S3 Docs

Telegram S3 兼容存储文档

使用标准 S3 SDK 与 Telegram 存储交互的完整指南，涵盖凭证配置、端点信息、支持的操作和示例代码。

进入控制台

端点

https://您的域名/api/s3

区域

telegram-s3

存储桶

telegram-s3-bucket

兼容性说明

Telegram S3 实现了 Amazon S3 的核心 API，覆盖常用读写与分片上传流程。受 Telegram 限制，部分高级功能可能不可用或行为略有不同。

推荐使用 Path Style + v4 签名

Credentials

配置 S3 凭证

访问密钥 ID: S3 配置页面设置的 Access Key

秘密访问密钥: S3 配置页面设置的 Secret

区域: telegram-s3

端点: https://您的域名/api/s3

安全建议

妥善保管 Access Key 与 Secret，避免写入公共仓库。
建议定期轮换密钥，在 S3 配置页面重置即可。
API Key 与 JWT 管理员登录可配合使用。

Endpoints

端点与配置

S3 API

https://您的域名/api/s3

统一 API 入口，兼容常用 S3 SDK。

Bucket

telegram-s3-bucket

默认桶名称，建议保持一致。

s3ForcePathStyle: 强制使用路径样式访问，建议 true

signatureVersion: 采用 v4 签名

Operations

支持的 S3 操作

ListObjects / ListObjectsV2完全支持

列出存储桶中的对象

GetObject完全支持

获取对象内容

PutObject完全支持

上传对象

DeleteObject完全支持

删除对象

CreateMultipartUpload支持

初始化分片上传

UploadPart支持

上传分片

CompleteMultipartUpload支持

完成分片上传

AbortMultipartUpload支持

中止分片上传

ListParts支持

列出已上传的分片

Examples

代码示例

JavaScript (AWS SDK v3)

import { S3Client, ListObjectsCommand, PutObjectCommand } from "@aws-sdk/client-s3";

const s3Client = new S3Client({
  region: "telegram-s3",
  endpoint: "https://您的域名/api/s3",
  credentials: {
    accessKeyId: "您的访问密钥ID",
    secretAccessKey: "您的秘密访问密钥"
  },
  forcePathStyle: true
});

async function listObjects() {
  const command = new ListObjectsCommand({
    Bucket: "telegram-s3-bucket"
  });
  const response = await s3Client.send(command);
  console.log(response.Contents);
}

async function uploadObject() {
  const command = new PutObjectCommand({
    Bucket: "telegram-s3-bucket",
    Key: "example.txt",
    Body: "Hello, Telegram S3!"
  });
  const response = await s3Client.send(command);
  console.log(response);
}

Python (Boto3)

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://您的域名/api/s3",
    aws_access_key_id="您的访问密钥ID",
    aws_secret_access_key="您的秘密访问密钥",
    region_name="telegram-s3",
    config=boto3.session.Config(
        signature_version="s3v4",
        s3={"addressing_style": "path"}
    )
)

response = s3.list_objects(Bucket="telegram-s3-bucket")
for obj in response.get("Contents", []):
    print(obj["Key"], obj["Size"])

s3.put_object(
    Bucket="telegram-s3-bucket",
    Key="example.txt",
    Body="Hello, Telegram S3!"
)

response = s3.get_object(
    Bucket="telegram-s3-bucket",
    Key="example.txt"
)
data = response["Body"].read().decode("utf-8")
print(data)

大文件分片上传

import boto3
import os

s3 = boto3.client(
    "s3",
    endpoint_url="https://您的域名/api/s3",
    aws_access_key_id="您的访问密钥ID",
    aws_secret_access_key="您的秘密访问密钥",
    region_name="telegram-s3"
)

file_path = "large_file.mp4"
file_name = os.path.basename(file_path)
bucket = "telegram-s3-bucket"

response = s3.create_multipart_upload(
    Bucket=bucket,
    Key=file_name
)
upload_id = response["UploadId"]

chunk_size = 20 * 1024 * 1024
file_size = os.path.getsize(file_path)
part_count = (file_size + chunk_size - 1) // chunk_size
parts = []

with open(file_path, "rb") as file:
    for i in range(part_count):
        offset = chunk_size * i
        bytes_to_read = min(chunk_size, file_size - offset)
        file.seek(offset)
        data = file.read(bytes_to_read)
        response = s3.upload_part(
            Bucket=bucket,
            Key=file_name,
            PartNumber=i + 1,
            UploadId=upload_id,
            Body=data
        )
        parts.append({
            "PartNumber": i + 1,
            "ETag": response["ETag"]
        })
        print(f"上传分片 {i + 1}/{part_count}")

s3.complete_multipart_upload(
    Bucket=bucket,
    Key=file_name,
    UploadId=upload_id,
    MultipartUpload={"Parts": parts}
)

print(f"文件 {file_name} 上传完成")