sealos-s3

Sealos S3

身份与发现

• 所有者： sealos-s3（/sealos-s3，以及 bucket、object、policy、credentials、presign 或 quota 请求）。
• 类别： 通过 sealos-cli s3 执行 cloud-local-mutation，可选进行脱敏部署交接。
• 哨兵用例： S3-PRIVATE-REUSE、S3-CONFIRM-PUBLIC 和 S3-REDACT-OBJECT。

范围与边界

接受项目路径和对象存储意图。先进行分析、列出现有 bucket、创建或复用私有存储、仅在需要时初始化凭据，并接入最小范围的现有 env 键集。保留本地 MinIO/Compose 回退方案；公共 policy、轮换、删除和破坏性 object 更改仍需经过确认。

风险与确认

默认保持 bucket 为私有。更改为公共 policy、轮换活动应用的凭据、删除 bucket/object，或替换存储配置前，必须先征求确认。绝不打印密钥、完整凭据块、kubeconfig、认证文件或复制的 env 值；解析 JSON 输出，不要从表格中抓取密钥。

生命周期工作流

对于每个请求，解析项目、分析存储需求、确认 CLI/认证/区域/工作区、先列出再创建或复用、等待凭据就绪、接入现有键、验证经过认证的上传/读取或 presign 流程、清理临时 object，并报告 policy 状态。按请求输出 success、stopped 或 error；现有的私有优先工作流仍是下文中的领域扩展。工作区不明确、凭据未就绪或 env 目标已纳入版本控制时，必须在执行变更前停止请求。

请求约定

input:
  project: local path or repository source
  intent: bucket purpose, object path, and sharing requirement
  policy: private by default; publicRead/publicReadwrite only after confirmation
preconditions:
  - analyzer evidence identifies the storage adapter and env keys
  - sealos-cli/auth/region/workspace are resolved
  - bucket list and credential status are available

操作顺序为 analyze -> resolve account/workspace -> list -> create or reuse -> wait for secret -> wire -> object-flow -> cleanup。bucket 身份、policy、namespace 和 env 变更均限定在当前请求范围内。

渐进式披露

在进入相应阶段时，按一层深度加载 analyzer、bucket、policy、凭据、object 流程和清理步骤。在展示 CLI 细节前，确保私有 policy、确认要求和脱敏哨兵用例清晰可见。

输出、停止与错误状态

• success：bucket 身份/policy/就绪状态、工作区、env 键名称、经过认证的 object 或 presign 证明、清理状态和脱敏状态。
• stopped：工作区不明确、凭据未就绪、env 目标已纳入版本控制、公共 policy、轮换、替换或破坏性操作需要确认；同时说明安全的私有/presign 替代方案；不得声称已执行任何受限制的操作。
• error：analyzer、CLI、policy、凭据、object 或 env 写入步骤出错时，提供经清理的诊断类别、受影响的产物，以及恢复操作，并对凭据、端点和连接值进行脱敏。

交接

可选的部署交接使用以下完整元组。接收方会重新检查部署范围和运行时证据。

target: sealos-deploy
inputArtifact: private bucket identity, policy, approved env-key contract, credential-readiness state, and object-flow proof
allowedAction: consume approved ObjectStorageBucket/Secret wiring within the selected deployment scope
failureReturn: sanitized analyzer, CLI, policy, credential, object, or env diagnostic with the failed phase
responseOwner: sealos-s3

直接 S3 请求使用 target: none，并保留相同的证据字段。

验证

使用 analyze-project-s3.mjs、sealos-cli s3 JSON 输出、经过认证的 object 流程证据，以及基线用例 s3-positive-private-round-trip 和 s3-violating-unconfirmed-public-or-rotation。在报告成功前，验证私有 policy、env 保留情况和脱敏状态。

使用此 skill，通过 sealos-cli s3 为项目配置真正的 Sealos 对象存储。默认结果是：识别应用的对象存储需求、创建或复用 bucket、仅在需要时初始化凭据、接入最小范围的安全本地 env 变量集，并验证项目的上传/下载或预签名 URL 流程。

此 skill 基于 zjy365/sealos-cli#28，该 PR 注册了 s3 命令，并实现了 bucket CRD 操作和兼容 S3 的 object 操作。

安全规则

1. 切勿在最终答复中打印密钥、完整的 S3 凭证块或复制的环境变量值。
2. 未经确认或保留原值，不得覆盖现有环境变量值。
3. 不得提交 .env、.env.local、S3 访问密钥、密钥、kubeconfig 或 Sealos 身份验证文件。
4. 将存储桶设为公开前必须先询问。默认存储桶策略为 private。
5. 执行破坏性操作前必须先询问：s3 delete-bucket、s3 delete、为正在运行的应用轮换凭证，或替换应用存储配置。
6. 默认使用 sealos-cli 的 JSON 输出并解析，不要从表格输出中抓取内容。
7. 即使 CLI 会打印 s3 secret 的输出，也必须将其视为敏感信息。

工作流

1. 确定目标项目

使用 pwd 或 git rev-parse --show-toplevel 确认工作目录。

项目目录可用时运行分析器：

node <SKILL_DIR>/scripts/analyze-project-s3.mjs <project-dir>

将分析器结果作为起点，然后在编辑任何内容前检查它引用的实际文件。分析器会有意避免打印机密值。

2. 检查 sealos-cli

优先使用已有的 sealos-cli 二进制文件：

sealos-cli --version
sealos-cli s3 --help
sealos-cli whoami

如果尚未安装，请使用 npx -y sealos-cli@latest ... 执行一次性命令。全局安装前必须先询问。

如果身份验证缺失或已过期，请运行：

sealos-cli login <region>
sealos-cli workspace list
sealos-cli workspace current

使用用户期望的工作区。如果存在多个工作区且目标不明确，请先询问再配置资源。sealos-cli s3 会根据当前 kubeconfig 命名空间确定对象存储用户，因此工作区选错会导致存储桶和凭证错误。

3. 选择创建或复用

先列出现有存储桶：

sealos-cli s3 buckets -o json

当现有存储桶的用途和策略符合要求时，优先复用。若项目没有合适的存储桶，或用户要求新建存储桶，则创建一个：

sealos-cli s3 create-bucket <bucket-name> --policy private -o json

除非用户明确需要公开读取或写入，否则使用 private。该 PR 接受的存储桶策略为 private、publicRead 和 publicReadwrite；public-read 等别名会规范化为 publicRead，但在说明和脚本中请使用规范值。

4. 仅在需要时初始化凭证

配置应用环境变量或执行对象操作时，获取凭证：

sealos-cli s3 secret -o json

如果 ObjectStorageUser 不存在，该命令会创建它，然后短暂等待状态更新。如果凭证尚未就绪，请等待几秒后重试，不要手动创建原始 CRD。

有关当前命令约定和响应处理方式，请参阅 references/sealos-cli-s3.md。

5. 配置开发环境

只映射项目已使用的键。常见目标如下：

项目信号	首选环境变量键
AWS SDK / 通用 S3	S3_ENDPOINT、S3_ACCESS_KEY_ID、S3_SECRET_ACCESS_KEY、S3_BUCKET
AWS 风格配置	AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_REGION、S3_BUCKET
替换 MinIO	使用现有的 MINIO_* 键；只有在应用支持时，才迁移为现有 S3 键
上传库	适配器/配置文件读取的键

本地笔记本电脑开发时，使用 secret.external 中的端点。只有当应用在 Sealos/Devbox 内运行且运行环境能够访问内部端点时，才使用 secret.internal。

编辑环境变量文件前，请先阅读 references/env-integration.md。

6. 验证应用存储行为

运行能够证明对象存储正常工作的最小真实项目流程：

1. 如果有可用的仓库脚本或测试，运行它来上传和读取对象。
2. 否则，使用 sealos-cli s3 upload 上传一个小型本地测试文件，列出对象，将其下载到临时路径，然后删除测试对象。
3. 对于预签名 URL 功能，运行 sealos-cli s3 presign <bucket> <key> --expires 3600 -o json，并仅在该功能属于请求的工作流时验证 URL。

只有连接到非 Sealos 的 S3 兼容端点时，才同时使用 --endpoint、--access-key 和 --secret-key。不要只覆盖其中一部分。

7. 报告结果

总结：

1. 桶名称、策略、区域/工作区和就绪状态。
2. 更新的环境文件和键，不要泄露密钥值。
3. 验证命令和结果。
4. 任何公开策略、凭据轮换或清理后续事项。

常见任务

将现有项目连接到 Sealos 对象存储

1. 运行分析器。
2. 检查分析器提到的环境/配置文件。
3. 列出已有桶。
4. 创建或复用匹配的桶。
5. 使用 s3 secret 获取凭据。
6. 只写入应用会读取的环境变量键。
7. 验证应用的存储路径。

在开发环境中替换本地 MinIO

1. 找出指向 MinIO 或兼容 S3 的服务的应用服务环境变量。
2. 创建或复用私有的 Sealos 桶。
3. 只更新应用的本地环境文件，除非用户要求移除 MinIO，否则不要修改 compose 文件。
4. 保持本地 Compose 回滚简单：原有的 MinIO 服务仍可用。

上传或分享项目资源

1. 确认目标桶和对象键前缀。
2. 使用 sealos-cli s3 upload <bucket> <file> --key <key> -o json 上传。
3. 尽可能使用 presign 临时分享，而不是设置公开桶策略。
4. 验证后删除临时测试对象。

参考资料

• scripts/analyze-project-s3.mjs - 只读的项目对象存储意图分析器。
• references/sealos-cli-s3.md - PR #28 sealos-cli s3 命令约定。
• references/env-integration.md - 安全编辑环境文件和 S3 环境变量键映射。