Back to Details

zeabur-object-storage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Zeabur Object Storage Deployment & Integration

Zeabur 对象存储部署与集成

Always use 
npx zeabur@latest
to invoke Zeabur CLI. Never use 
zeabur
directly or any other installation method. If 
npx
is not available, install Node.js first.
请始终使用 
npx zeabur@latest
调用Zeabur CLI。 切勿直接使用 
zeabur
或其他任何安装方式。若未安装
npx
，请先安装Node.js。

Deploy Object Storage

部署对象存储

Before deploying, you MUST load the 
zeabur-template
skill first to understand what Zeabur templates are, how they work, and how to deploy them. This skill only covers object storage-specific integration — all template knowledge lives in 
zeabur-template
.
Search for a storage template:
bash
npx zeabur@latest template search minio -i=false --json
Pick the template with the highest deployment count.
  • Default to MinIO if the user doesn't specify — most widely supported, built-in web console, auto-creates a default bucket.
  • Recommend RustFS if the user wants lightweight/minimal or mentions RustFS specifically.
部署前，必须先加载 
zeabur-template
技能，了解Zeabur模板是什么、工作原理以及如何部署。本技能仅涵盖对象存储特定的集成内容——所有模板相关知识都在 
zeabur-template
中。
搜索存储模板：
bash
npx zeabur@latest template search minio -i=false --json
选择部署次数最多的模板。
  • 如果用户未指定，默认使用MinIO——支持最广泛，内置Web控制台，会自动创建默认存储桶。
  • 如果用户需要轻量级/极简方案或明确提到RustFS，推荐使用RustFS。

After Deployment: How to Connect

部署后：如何连接

For object storage, you need: S3 API endpoint (how to connect), access key + secret key (how to authenticate), and a bucket name.
对于对象存储，你需要：S3 API端点（连接方式）、访问密钥+密钥密码（认证方式）以及存储桶名称。

How to connect — 
service network

连接方式 —— 
service network

bash
npx zeabur@latest service network --id <storage-service-id> -i=false
This shows:
  • Private Networking — internal 
    hostname:port
    for the S3 API (e.g., 
    minio.zeabur.internal:9000
    )
  • Public Networking — for HTTP ports, it will indicate you need to bind a domain to access externally
MinIO and RustFS ports are HTTP type, so public access is via domain binding, not port forwarding. Bind a domain to the API port via the Dashboard to get an external S3 endpoint (e.g., 
https://minio-api.zeabur.app
).
bash
npx zeabur@latest service network --id <storage-service-id> -i=false
该命令会显示：
  • 私有网络：S3 API的内部 
    hostname:port
    （例如 
    minio.zeabur.internal:9000
    ）
  • 公网：对于HTTP端口，会提示你需要绑定域名才能外部访问
MinIO和RustFS的端口为HTTP类型，因此公网访问需通过域名绑定，而非端口转发。通过控制台将域名绑定到API端口，即可获取外部S3端点（例如 
https://minio-api.zeabur.app
）。

How to authenticate — 
variable list

认证方式 —— 
variable list

bash
npx zeabur@latest variable list --id <storage-service-id> -i=false
This lists the access key, secret key, and other credentials.
bash
npx zeabur@latest variable list --id <storage-service-id> -i=false
该命令会列出访问密钥、密钥密码及其他凭证信息。

MinIO

MinIO

Credentials (from 
variable list
)

凭证信息（来自 
variable list
）

VariableDescription
MINIO_USERNAME
Access Key ID (default: 
minio
)
MINIO_PASSWORD
Secret Access Key (auto-generated)
MINIO_DEFAULT_BUCKET
Default bucket name (default: 
zeabur
)
MINIO_CONSOLE_URL
Web console URL
变量名描述
MINIO_USERNAME
访问密钥ID（默认值：
minio
）
MINIO_PASSWORD
密钥密码（自动生成）
MINIO_DEFAULT_BUCKET
默认存储桶名称（默认值：
zeabur
）
MINIO_CONSOLE_URL
Web控制台地址

Connect from app (same project)

从同项目应用连接

Set these env vars on your app service:
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
The S3 endpoint is not exposed as a variable — you must hardcode it using the internal hostname from 
service network
.
在你的应用服务中设置以下环境变量：
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
中的内部主机名硬编码。

Connect from local machine

从本地机器连接

Bind a domain to the API port, then use that domain as endpoint:
bash
undefined
将域名绑定到API端口，然后使用该域名作为端点：
bash
undefined

MinIO Client (mc)

MinIO 客户端 (mc)

mc alias set zeabur https://MINIO_API_DOMAIN MINIO_USERNAME MINIO_PASSWORD mc ls zeabur/ mc cp local-file.txt zeabur/zeabur/
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 CLI

aws --endpoint-url https://MINIO_API_DOMAIN s3 ls
undefined
aws --endpoint-url https://MINIO_API_DOMAIN s3 ls
undefined

Web Console

Web控制台

Open 
MINIO_CONSOLE_URL
in a browser, login with 
MINIO_USERNAME
/ 
MINIO_PASSWORD
. MinIO auto-creates a 
zeabur
bucket on first boot.
在浏览器中打开 
MINIO_CONSOLE_URL
，使用 
MINIO_USERNAME
/ 
MINIO_PASSWORD
登录。MinIO会在首次启动时自动创建 
zeabur
存储桶。

RustFS

RustFS

Credentials (from 
variable list
)

凭证信息（来自 
variable list
）

VariableDescription
RUSTFS_USERNAME
Access Key ID (default: 
rustfs
)
RUSTFS_PASSWORD
Secret Access Key (auto-generated)
变量名描述
RUSTFS_USERNAME
访问密钥ID（默认值：
rustfs
）
RUSTFS_PASSWORD
密钥密码（自动生成）

Connect from app (same project)

从同项目应用连接

Set these env vars on your app service:
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
The S3 endpoint is not exposed as a variable — you must hardcode it using the internal hostname from 
service network
. Also check 
service list
for the exact service name (may be 
RustFS
not 
rustfs
).
You must create a bucket first — unlike MinIO, RustFS starts with zero buckets.
在你的应用服务中设置以下环境变量：
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启动时没有任何存储桶。

Connect from local machine

从本地机器连接

Bind a domain to the API port, then:
bash
mc alias set zeabur https://RUSTFS_API_DOMAIN RUSTFS_USERNAME RUSTFS_PASSWORD
mc mb zeabur/my-bucket
mc ls zeabur/
将域名绑定到API端口，然后执行：
bash
mc alias set zeabur https://RUSTFS_API_DOMAIN RUSTFS_USERNAME RUSTFS_PASSWORD
mc mb zeabur/my-bucket
mc ls zeabur/

Web Console

Web控制台

Open the domain bound to port 
9001
in a browser, login with 
RUSTFS_USERNAME
/ 
RUSTFS_PASSWORD
. Create a bucket before your app can upload files.
在浏览器中打开绑定到 
9001
端口的域名，使用 
RUSTFS_USERNAME
/ 
RUSTFS_PASSWORD
登录。在应用上传文件前，请先创建存储桶。

SDK Examples

SDK 示例

All S3-compatible SDKs need: endpoint, access key, secret key, region, and 
forcePathStyle: true
.
javascript
// 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
undefined
所有兼容S3的SDK都需要：端点、访问密钥、密钥密码、区域，以及 
forcePathStyle: true
。
javascript
// 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
undefined

Python (boto3)

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
// 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
})
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
// 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
})

Caveats

注意事项

  1. forcePathStyle
    is required     — Without it, S3 SDKs use virtual-hosted-style URLs (
    http://bucket.host:9000/key
    ) which won't resolve. This is the #1 cause of "bucket not found" errors.
  2. Create bucket before uploading (RustFS) — MinIO auto-creates a 
    zeabur
    bucket; RustFS does not. Create one via the console or 
    mc mb
    .
  3. S3 endpoint is not a template variable — Hardcode it using the hostname from 
    service network
    (internal) or the bound domain (external).
  4. Variable references — Zeabur uses a flat namespace. Set 
    ${MINIO_USERNAME}
    etc. via the Zeabur Dashboard — the CLI has a known bug with 
    ${}
    expansion.
  5. Console vs API ports — MinIO: API 
    9000
    , console 
    9090
    . RustFS: API 
    9000
    , console 
    9001
    . Apps connect to the API port.
  1. 必须设置 
    forcePathStyle
    ——如果不设置，S3 SDK会使用虚拟主机样式的URL（
    http://bucket.host:9000/key
    ），无法解析。这是“存储桶未找到”错误的头号原因。
  2. 上传前创建存储桶（RustFS）——MinIO会自动创建 
    zeabur
    存储桶；RustFS不会。请通过控制台或 
    mc mb
    命令创建。
  3. S3端点不是模板变量——使用 
    service network
    中的主机名（内部）或绑定的域名（外部）硬编码。
  4. 变量引用——Zeabur使用扁平命名空间。请通过Zeabur控制台设置 
    ${MINIO_USERNAME}
    等变量——CLI在 
    ${}
    展开方面存在已知Bug。
  5. 控制台与API端口——MinIO：API端口 
    9000
    ，控制台端口 
    9090
    。RustFS：API端口 
    9000
    ，控制台端口 
    9001
    。应用连接到API端口。