sealos-s3

Sealos S3 技能用于通过 sealos-cli 的 s3 命令为项目提供真实的 Sealos 对象存储能力。其默认目标是：识别应用的对象存储需求，创建或复用存储桶，仅在需要时初始化凭证，写入最小安全集合的本地环境变量，并验证项目的上传/下载或预签名 URL 路径。

该技能基于 zjy365/sealos-cli#28，该 PR 注册了 s3 命令并实现了存储桶 CRD 操作以及 S3 兼容的对象操作。

安全规则

• 绝不在最终答案中打印密钥、完整的 S3 凭证块或复制的环境变量值。
• 未经确认或保留旧值，不得覆盖现有环境变量值。
• 不得提交 .env、.env.local、S3 访问密钥、密钥、kubeconfig 或 Sealos 认证文件。
• 将存储桶设为公开前需先询问。默认存储桶策略为私有。
• 执行破坏性操作前需先询问：s3 delete-bucket、s3 delete、对活跃应用进行凭证轮换，或替换应用存储配置。
• 默认使用 sealos-cli 的 JSON 输出并解析它，而不是抓取表格输出。
• 即使 CLI 可以打印 s3 secret 输出，也应将其视为敏感信息。

工作流程

1. 确定目标项目

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

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

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

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

1. 检查 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 命名空间派生对象存储用户，因此错误的工作区意味着错误的存储桶和凭证。

1. 选择创建或复用

首先列出已有存储桶：

sealos-cli s3 buckets -o json

当现有存储桶的用途和策略匹配时复用。当项目没有合适的存储桶或用户要求新建时创建新桶：

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

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

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

对于应用环境变量接线或对象操作，获取凭证：

sealos-cli s3 secret -o json

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

当前命令契约和响应处理请参阅 references/sealos-cli-s3.md。

1. 接线开发环境

仅映射项目已使用的键。常见目标：

项目信号 | 首选环境变量键 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。

1. 验证应用存储行为

运行最小的真实项目路径以证明对象存储正常工作：

如果可用，运行仓库中上传和读取对象的脚本或测试。

否则使用 sealos-cli s3 upload 上传一个小型本地测试文件，列出它，下载到临时路径，然后删除测试对象。

对于预签名 URL 功能，运行 sealos-cli s3 presign <bucket> <key> --expires 3600 -o json，并仅在该 URL 是请求工作流的一部分时验证它。

仅当连接到非 Sealos 的 S3 兼容端点时，才同时使用 --endpoint、--access-key 和 --secret-key。不要混合部分覆盖。

1. 报告结果

总结：

• 存储桶名称、策略、区域/工作区及就绪状态。
• 更新的环境变量文件和键，不透露密钥值。
• 验证命令和结果。
• 任何公开策略、凭证轮换或清理后续事项。

常见任务

将现有项目连接到 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 环境变量键映射。