zeabur-object-storage

Zeabur 对象存储部署与集成

**始终使用 npx zeabur@latest 调用 Zeabur CLI。**切勿直接使用 zeabur 或采用其他安装方式。如果没有 npx，请先安装 Node.js。

部署对象存储

部署前，必须先加载 zeabur-template 技能，了解 Zeabur 模板是什么、如何运作以及如何部署。本技能仅涵盖对象存储相关集成；所有模板知识均由 zeabur-template 提供。

搜索存储模板：

npx zeabur@latest template search minio -i=false --json

选择部署次数最多的模板。

• 默认使用 MinIO，除非用户另有说明——它的支持最广泛，内置 Web 控制台，并会自动创建默认存储桶。
• 如果用户想要轻量/精简方案，或特别提到 RustFS，则推荐 RustFS。

---

部署后：如何连接

使用对象存储需要：S3 API 端点（如何连接）、访问密钥 + 密钥（如何进行身份验证）以及存储桶名称。

如何连接——service network

npx zeabur@latest service network --id <storage-service-id> -i=false

此命令会显示：

• Private Networking——S3 API 的内部 hostname:port（例如，minio.zeabur.internal:9000）
• Public Networking——对于 HTTP 端口，会提示你需要绑定域名才能从外部访问

MinIO 和 RustFS 的端口类型为 HTTP，因此需通过绑定域名来进行公网访问，而不是端口转发。通过 Dashboard 将域名绑定到 API 端口，即可获取外部 S3 端点（例如，https://minio-api.zeabur.app）。

如何进行身份验证——variable list

npx zeabur@latest variable list --id <storage-service-id> -i=false

此命令会列出访问密钥、密钥以及其他凭据。

---

MinIO

凭据（来自 variable list）

变量	说明
MINIO_USERNAME	访问密钥 ID（默认值：minio）
MINIO_PASSWORD	秘密访问密钥（自动生成）
MINIO_DEFAULT_BUCKET	默认存储桶名称（默认值：zeabur）
MINIO_CONSOLE_URL	Web 控制台 URL

从应用连接（同一项目）

在应用服务上设置以下环境变量：

S3_ENDPOINT=http://minio.zeabur.internal:9000
S3_ACCESS_KEY=${MINIO_USERNAME}
S3_SECRET_KEY=${MINIO_PASSWORD}
S3_BUCKET=zeabur
S3_REGION=us-east-1
S3_FORCE_PATH_STYLE=true

S3 端点不会作为变量公开——你必须使用 service network 中的内部主机名将其硬编码。

从本地计算机连接

将域名绑定到 API 端口，然后将该域名用作端点：

# MinIO Client (mc)
mc alias set zeabur https://MINIO_API_DOMAIN MINIO_USERNAME MINIO_PASSWORD
mc ls zeabur/
mc cp local-file.txt zeabur/zeabur/

# AWS CLI
aws --endpoint-url https://MINIO_API_DOMAIN s3 ls

Web 控制台

在浏览器中打开 MINIO_CONSOLE_URL，使用 MINIO_USERNAME / MINIO_PASSWORD 登录。MinIO 会在首次启动时自动创建 zeabur 存储桶。

---

RustFS

凭据（来自 variable list）

变量	说明
RUSTFS_USERNAME	访问密钥 ID（默认值：rustfs）
RUSTFS_PASSWORD	秘密访问密钥（自动生成）

从应用连接（同一项目）

在应用服务上设置以下环境变量：

S3_ENDPOINT=http://rustfs.zeabur.internal:9000
S3_ACCESS_KEY=${RUSTFS_USERNAME}
S3_SECRET_KEY=${RUSTFS_PASSWORD}
S3_BUCKET=my-bucket
S3_REGION=us-east-1
S3_FORCE_PATH_STYLE=true

S3 端点不会作为变量公开——你必须使用 service network 中的内部主机名将其硬编码。此外，请通过 service list 检查确切的服务名称（可能是 RustFS，而不是 rustfs）。

你必须先创建存储桶——与 MinIO 不同，RustFS 启动时不会包含任何存储桶。

从本地计算机连接

将域名绑定到 API 端口，然后：

mc alias set zeabur https://RUSTFS_API_DOMAIN RUSTFS_USERNAME RUSTFS_PASSWORD
mc mb zeabur/my-bucket
mc ls zeabur/

Web 控制台

在浏览器中打开绑定到端口 9001 的域名，使用 RUSTFS_USERNAME / RUSTFS_PASSWORD 登录。在应用上传文件之前，请先创建存储桶。

---

SDK 示例

所有兼容 S3 的 SDK 都需要：端点、访问密钥、秘密密钥、区域以及 forcePathStyle: true。

// Node.js (AWS SDK v3)
const { S3Client } = require("@aws-sdk/client-s3");
const s3 = new S3Client({
  endpoint: process.env.S3_ENDPOINT,
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY,
    secretAccessKey: process.env.S3_SECRET_KEY,
  },
  region: "us-east-1",
  forcePathStyle: true,
});

# Python (boto3)
import boto3, os
s3 = boto3.client(
    "s3",
    endpoint_url=os.environ["S3_ENDPOINT"],
    aws_access_key_id=os.environ["S3_ACCESS_KEY"],
    aws_secret_access_key=os.environ["S3_SECRET_KEY"],
    region_name="us-east-1",
)

// Go (aws-sdk-go-v2)
cfg, _ := config.LoadDefaultConfig(ctx,
    config.WithRegion("us-east-1"),
    config.WithCredentialsProvider(
        credentials.NewStaticCredentialsProvider(accessKey, secretKey, ""),
    ),
)
client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.BaseEndpoint = aws.String(endpoint)
    o.UsePathStyle = true
})

---

注意事项

1. 必须启用 forcePathStyle — 否则，S3 SDK 会使用虚拟主机式 URL（http://bucket.host:9000/key），导致无法解析。这是导致“找不到存储桶”错误的首要原因。
2. 上传前先创建存储桶（RustFS） — MinIO 会自动创建 zeabur 存储桶；RustFS 不会。请通过控制台或 mc mb 创建一个存储桶。
3. S3 端点不是模板变量 — 使用 service network 中的主机名（内部）或绑定的域名（外部）将其硬编码。
4. 变量引用 — Zeabur 使用扁平命名空间。请通过 Zeabur Dashboard 设置 ${MINIO_USERNAME} 等变量 — CLI 在 ${} 展开方面有一个已知错误。
5. 控制台与 API 端口 — MinIO：API 为 9000，控制台为 9090。RustFS：API 为 9000，控制台为 9001。应用连接到 API 端口。