阿里云控制台                        PlaySandbox 平台
┌─────────────────┐                ┌─────────────────────┐
│ 1. 创建 OSS Bucket │                │ 3. 注册 Credential   │
│ 2. 创建 RAM 子账号  │── AK/SK ──→  │    (POST /credentials) │
│    签发 AK/SK      │                │ 4. 沙箱挂载 OSS       │
└─────────────────┘                └─────────────────────┘

一、创建 OSS Bucket

1.1 进入 OSS 控制台

登录阿里云控制台 → 左侧菜单对象存储 OSS → Bucket 列表→ 点击创建 Bucket

1.2 关键参数

参数	推荐值	说明
Bucket 名称	my-sandbox-data	全局唯一，小写字母+数字+连字符，创建后不可改
地域 (Region)	华东1（杭州）cn-hangzhou	选择离沙箱集群最近的地域，必须用内网 endpoint
存储类型	标准存储	频繁访问选标准；归档/低频访问成本更低但读取有延迟
读写权限	私有	强烈建议私有，通过 AK/SK 授权访问
服务端加密	OSS 完全托管 (SSE-OSS)	可选，对数据静态加密
实时日志查询	关闭	按需开启

地域选择要点：PlaySandbox 沙箱集群通常部署在阿里云 VPC 内，Bucket 与沙箱在同一地域可通过内网 endpoint 免流量费访问。跨地域走公网会有延迟和流量费用。

1.3 创建完成

创建后可以看到 Bucket 的Endpoint信息，例如：

外网 Endpoint:  oss-cn-hangzhou.aliyuncs.com
内网 Endpoint:  oss-cn-hangzhou-internal.aliyuncs.com  ← 使用这个

内网 Endpoint是关键，PlaySandbox 沙箱通过 VPC 内网访问 OSS，既快又省流量。记住这个内网 endpoint，后面注册 credential 和 kconf 配置都要用。

二、创建 RAM 子账号并签发 AK/SK

安全原则：绝不使用主账号 AK/SK。通过 RAM 创建子账号，授予最小权限（仅限目标 Bucket 的读写），降低泄漏风险。

2.1 进入 RAM 控制台

阿里云控制台 → 访问控制 (RAM) → 用户 → 创建用户

2.2 创建子账号

参数	推荐值
登录名称	sandbox-oss-access
显示名称	PlaySandbox OSS Access
访问方式	勾选编程访问（OpenAPI / CLI / SDK 方式），不勾选控制台访问

创建成功后，页面会显示：

AccessKey ID（AK）：类似LTAI5tXXXXXXXXXXXX
AccessKey Secret（SK）：类似XXXXXXXXXXXXXXXXXXXXXXXX

⚠️SK 只在创建时显示一次，请立即复制保存到安全位置（密码管理器等）。关闭页面后无法再查看，只能重新创建。

2.3 授予最小权限策略

创建用户后 → 点击添加权限 → 选择自定义策略 → 创建策略，输入如下 JSON：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:GetObject",
        "oss:PutObject",
        "oss:DeleteObject",
        "oss:ListObjects",
        "oss:GetBucketInfo",
        "oss:AbortMultipartUpload",
        "oss:ListParts",
        "oss:CopyObject",
        "oss:GetObjectMeta"
      ],
      "Resource": [
        "acs:oss:*:*:my-sandbox-data",
        "acs:oss:*:*:my-sandbox-data/*"
      ]
    }
  ]
}

将my-sandbox-data替换为你实际的 Bucket 名称。Resource里第一行授权 Bucket 级操作（如 ListObjects），第二行授权 Object 级操作（读写/删除文件）。

策略命名：AliyunOSSMySandboxDataAccess，创建后回到用户页面，将该策略授权给子账号。

2.4 验证 AK/SK 可用性

使用ossutil或 Python SDK 快速验证：

# 安装 ossutil（如未安装）
curl -o /usr/local/bin/ossutil https://gosspublic.alicdn.com/ossutil/1.7.18/ossutil64
chmod +x /usr/local/bin/ossutil

# 配置凭证
ossutil config -i LTAI5tXXXXXXXXXXXX -k XXXXXXXXXXXXXXXXXXXXXXXX -e oss-cn-hangzhou-internal.aliyuncs.com

# 测试列举文件
ossutil ls oss://my-sandbox-data

如果返回空列表（Bucket 刚创建还没有文件）且无报错，说明 AK/SK 权限正常。

三、在 PlaySandbox 注册 Credential

拿到 AK/SK 后，需要在 PlaySandbox 平台注册一个Volume Credential，后续沙箱挂载 OSS 时通过 credential ID 引用。

3.1 通过 API 创建

curl -X POST https://<your-sandbox-api>/sandbox/commercial/api/credentials \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "name": "oss-hangzhou-prod",
    "backend": "oss",
    "accessKeyID": "LTAI5tXXXXXXXXXXXX",
    "secretAccessKey": "XXXXXXXXXXXXXXXXXXXXXXXX",
    "region": "cn-hangzhou"
  }'

字段说明：

字段	说明
name	凭证名称，同一 Team 下唯一。建议命名规则：oss-<地域>-<用途>
backend	固定oss
accessKeyID	第二步获取的 AK
secretAccessKey	第二步获取的 SK，API 返回时不回显此字段
region	OSS 地域，如cn-hangzhou。可留空（挂载时由 endpoint 推导）

创建成功后返回：

{
  "credentialID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "oss-hangzhou-prod",
  "backend": "oss",
  "accessKeyID": "LTAI5tXXXXXXXXXXXX",
  "region": "cn-hangzhou",
  "createdAt": "2026-09-09T20:00:00Z"
}

🔑 记住返回的credentialID，后续创建沙箱挂载 OSS 时需要用到它。

3.2 通过 Admin Console 创建

如果用户有 admin-console 访问权限：

进入Team Detail页面
找到Volume Credentials区域
点击新建 Credential
填写 name / backend(oss) / accessKeyID / secretAccessKey / region
保存

3.3 查看已有 Credential

curl -X GET https://<your-sandbox-api>/sandbox/commercial/api/credentials \
  -H "Authorization: Bearer <your-token>"

四、在沙箱中挂载 OSS

4.1 内联挂载（推荐，无需预注册 Volume）

创建沙箱时在volumeMounts中直接指定 OSS 挂载：

{
  "volumeMounts": [
    {
      "name": "my-oss-data",
      "type": "oss",
      "credentialId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "bucket": "my-sandbox-data",
      "endpoint": "oss-cn-hangzhou-internal.aliyuncs.com",
      "region": "cn-hangzhou",
      "mountPath": "/data/oss"
    }
  ]
}

字段说明：

字段	必填	说明
name	✅	挂载名称，同一沙箱内唯一
type	✅	固定oss（内联挂载模式）
credentialId	✅	第三步注册 credential 返回的 UUID
bucket	✅	第一步创建的 Bucket 名称
endpoint	❌	OSS 内网 endpoint。可省略——省略时依次回退：kconfcommercial_oss_defaults.endpoint→ 环境变量COMMERCIAL_OSS_DEFAULTS。全部为空则报 400
region	❌	OSS 地域。省略时回退到 credential 注册时的 region。仍为空时 geesefs 从 endpoint 自动推导
mountPath	✅	沙箱内挂载路径，如/data/oss

4.2 Endpoint 优先级

请求 body 中的 endpoint
    ↓ (为空则)
kconf commercial_oss_defaults.endpoint
    ↓ (为空则)
环境变量 COMMERCIAL_OSS_DEFAULTS
    ↓ (全部为空)
返回 400，拒绝挂载

如果用户的环境已在 kconf 中配置了commercial_oss_defaults.endpoint，创建沙箱时可以省略endpoint字段。

4.3 在沙箱内验证

沙箱启动后，进入终端：

# 查看挂载
ls /data/oss

# 写入测试文件
echo "hello oss" > /data/oss/test.txt

# 读取
cat /data/oss/test.txt
# hello oss

# 同步到阿里云控制台查看
# 进入 OSS 控制台 → Bucket my-sandbox-data → 文件管理
# 应能看到 test.txt

五、kconf 全局默认配置（可选，管理员操作）

如果用户是环境管理员，可以在 kconf 中配置全局 OSS 默认 endpoint，这样所有商业化租户创建沙箱时都不必传endpoint字段。

在 kconf 的kwaisandbox配置 key 中添加：

{
  "commercial_oss_defaults": {
    "endpoint": "oss-cn-hangzhou-internal.aliyuncs.com"
  }
}

此字段仅对商业化路径（tenantID 非空）生效。内部路径的 OSS 挂载继续走volume_credentials表里各自的 endpoint 列。

六、安全最佳实践

原则	做法
不使用主账号 AK/SK	通过 RAM 子账号签发，授予最小权限
Bucket 私有读写	读写都走 AK/SK 鉴权，不暴露公开
SK 仅创建时可见	立即存入密码管理器，不要明文记录
定期轮转 AK/SK	建议每 90 天在 RAM 中创建新 AK，更新 PlaySandbox credential，删除旧 AK
内网 endpoint	沙箱与 Bucket 同地域走内网，避免公网流量费
按 Bucket 授权	RAM 策略 Resource 限定到具体 Bucket，不使用oss:*全局权限