spaces

Spaces 技能

为 App Platform 应用提供兼容 S3 的对象存储。

工具分工（重要）

┌─────────────────────────────────────────────────────────────────┐
│  doctl: KEYS ONLY          │  aws CLI: EVERYTHING ELSE          │
│  • doctl spaces keys create│  • Bucket create/delete            │
│  • doctl spaces keys list  │  • Object upload/download          │
│  • doctl spaces keys delete│  • CORS, logging, lifecycle        │
└─────────────────────────────────────────────────────────────────┘

为什么？ doctl 对 Spaces 的支持仅限于密钥管理。存储桶操作需要使用兼容 S3 的工具。

---

快速决策

┌─────────────────────────────────────────────────────────────────┐
│              What do you need to do with Spaces?                 │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
   Create key            Create bucket         Upload/download
   or rotate             set CORS/logging      objects
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│    doctl      │    │   aws CLI     │    │   aws CLI     │
│ spaces keys   │    │   s3api       │    │   s3 cp/sync  │
└───────────────┘    └───────────────┘    └───────────────┘

---

前提条件

doctl auth init          # One-time DO API auth
aws --version            # AWS CLI v2
jq --version             # JSON processor

---

快速开始

1. 设置环境

# Choose region matching your App Platform app (see shared/regions.yaml)
export DO_SPACES_REGION="syd1"
export DO_SPACES_ENDPOINT="https://${DO_SPACES_REGION}.digitaloceanspaces.com"
export APP_NAME="myapp"
export BUCKET="${APP_NAME}-uploads"
export DO_SPACES_KEY_NAME="${APP_NAME}-spaces-key"

2. 创建密钥（doctl）

KEY_JSON=$(doctl spaces keys create "${DO_SPACES_KEY_NAME}" --output json)
export AWS_ACCESS_KEY_ID=$(echo "$KEY_JSON" | jq -r '.[0].access_key')
export AWS_SECRET_ACCESS_KEY=$(echo "$KEY_JSON" | jq -r '.[0].secret_key')

# IMPORTANT: Secret shown only once - save it now!

3. 创建存储桶（aws CLI）

aws --endpoint-url "$DO_SPACES_ENDPOINT" s3api create-bucket --bucket "$BUCKET"

4. App 规格

services:
  - name: api
    envs:
      - key: SPACES_BUCKET
        value: myapp-uploads
      - key: SPACES_REGION
        value: ${SPACES_REGION}           # Your bucket's region
      - key: SPACES_ENDPOINT
        value: ${SPACES_ENDPOINT}         # e.g., https://syd1.digitaloceanspaces.com
      - key: SPACES_ACCESS_KEY
        scope: RUN_TIME
        type: SECRET
        value: ${SPACES_ACCESS_KEY}
      - key: SPACES_SECRET_KEY
        scope: RUN_TIME
        type: SECRET
        value: ${SPACES_SECRET_KEY}

将 SPACES_ACCESS_KEY 和 SPACES_SECRET_KEY 存储在 GitHub Secrets 中。

---

区域

Spaces 使用的 slug 与 App Platform 不同。请参阅 shared/regions.yaml。

App Platform	Spaces	端点
nyc	nyc3	https://nyc3.digitaloceanspaces.com
sfo	sfo3	https://sfo3.digitaloceanspaces.com
ams	ams3	https://ams3.digitaloceanspaces.com
lon	lon1	https://lon1.digitaloceanspaces.com
fra	fra1	https://fra1.digitaloceanspaces.com
tor	tor1	https://tor1.digitaloceanspaces.com
sgp	sgp1	https://sgp1.digitaloceanspaces.com
blr	blr1	https://blr1.digitaloceanspaces.com
syd	syd1	https://syd1.digitaloceanspaces.com
atl	atl1	https://atl1.digitaloceanspaces.com

---

常见操作

doctl（仅密钥）

doctl spaces keys list
doctl spaces keys create "myapp-key" --output json
doctl spaces keys delete <key-id>

aws CLI（存储桶和对象）

EP="--endpoint-url https://syd1.digitaloceanspaces.com"

# Buckets
aws $EP s3 ls
aws $EP s3api create-bucket --bucket myapp-uploads
aws $EP s3 rb s3://myapp-uploads

# Objects
aws $EP s3 cp ./file.txt s3://myapp-uploads/path/file.txt
aws $EP s3 cp s3://myapp-uploads/path/file.txt ./file.txt
aws $EP s3 ls s3://myapp-uploads/ --recursive
aws $EP s3 sync ./local-dir/ s3://myapp-uploads/prefix/

---

脚本（适合 AI 使用）

脚本	用途
scripts/bootstrap_app_spaces.sh	完整设置：密钥、存储桶和日志记录
scripts/enable_bucket_logging.sh	启用/验证日志记录（幂等）
scripts/view_access_logs.sh	列出/下载访问日志
scripts/rotate_spaces_key.sh	安全轮换凭据

# Set env vars then run
./scripts/bootstrap_app_spaces.sh

---

参考文件

文件	内容
aws-cli-operations.md	完整的 aws CLI 参考
key-management.md	按应用配置密钥、轮换工作流
access-logging.md	存储桶日志记录设置
sdk-configuration.md	Node.js、Python、Go SDK 设置
troubleshooting.md	常见错误及修复方法

---

URL 格式

类型	格式
标准	https://<bucket>.<region>.digitaloceanspaces.com/<key>
CDN	https://<bucket>.<region>.cdn.digitaloceanspaces.com/<key>

---

快速故障排除

错误	修复方法
BucketAlreadyExists (409)	使用唯一前缀：mycompany-myapp-uploads
Access Denied (403)	验证密钥，并检查端点是否与存储桶区域匹配
CORS error	通过 aws s3api put-bucket-cors 配置
SignatureDoesNotMatch	使用 https:// 前缀，不要添加尾部斜杠

详情请参阅 troubleshooting.md。

---

集成

• → designer：设计应用时包含 Spaces 环境变量
• → deployment：凭据存储在 GitHub Secrets 中
• → devcontainers：MinIO 提供本地 Spaces 兼容环境