sealos-s3

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sealos S3

Identity and Discovery

身份与发现

Owner:
```
sealos-s3
```
(
```
/sealos-s3
```
and bucket, object, policy, credentials, presign, or quota requests).
Class:
```
cloud-local-mutation
```
through
```
sealos-cli s3
```
, with an optional redacted deployment handoff.

Canaries:

S3-PRIVATE-REUSE

S3-CONFIRM-PUBLIC

, and

S3-REDACT-OBJECT

所有者:
```
sealos-s3
```
（处理
```
/sealos-s3
```
以及桶、对象、策略、凭证、预签名或配额请求）。
类别: 通过
```
sealos-cli s3
```
实现的
```
cloud-local-mutation
```
，可选脱敏部署交接。

校验标识:

S3-PRIVATE-REUSE

、

S3-CONFIRM-PUBLIC

和

S3-REDACT-OBJECT

。

Scope and Boundaries

范围与边界

Accept a project path and object-storage intent. Analyze first, list existing buckets, create or reuse private storage, initialize credentials only when needed, and wire the smallest existing env-key set. Preserve local MinIO/Compose fallback; public policy, rotation, deletion, and destructive object changes remain gated.

接受项目路径和对象存储需求。先进行分析，列出现有桶，创建或复用私有存储，仅在需要时初始化凭证，并关联最小的现有环境密钥集合。保留本地 MinIO/Compose 回退方案；公共策略、凭证轮换、删除和破坏性对象变更仍受限制。

Risk and Confirmation

风险与确认

Keep buckets private by default. Ask before public policy, credential rotation for an active app, bucket/object deletion, or replacing storage configuration. Never print secret keys, full credential blocks, kubeconfig, auth files, or copied env values; parse JSON output rather than scraping secrets from tables.

默认保持桶私有。在设置公共策略、为活跃应用轮换凭证、删除桶/对象或替换存储配置前需询问用户。绝不要打印密钥、完整凭证块、kubeconfig、认证文件或复制的环境值；应解析 JSON 输出而非从表格中提取敏感信息。

Lifecycle Workflow

生命周期工作流

For each request, resolve the project, analyze storage need, confirm CLI/auth/region/workspace, list before create/reuse, wait for credential readiness, wire existing keys, prove an authenticated upload/read or presign path, clean temporary objects, and report policy state. Emit request-scoped

success

stopped

, or

error

; the existing private-first workflow remains the domain extension below. Workspace ambiguity, missing credential readiness, or a tracked env target stops the request before mutation.

针对每个请求，解析项目、分析存储需求、确认 CLI/认证/区域/工作区、在创建/复用前列出资源、等待凭证就绪、关联现有密钥、验证已认证的上传/读取或预签名路径、清理临时对象，并报告策略状态。输出请求范围内的

success

、

stopped

或

error

；以下是现有私有优先工作流的领域扩展。若工作区模糊、凭证未就绪或存在跟踪的环境目标，将在变更前终止请求。

Request Contract

请求契约

yaml

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

The ordered action is

analyze -> resolve account/workspace -> list -> create or reuse -> wait for secret -> wire -> object-flow -> cleanup

. Bucket identity, policy, namespace, and env mutation remain request-scoped.

yaml

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

执行顺序为

分析 -> 解析账户/工作区 -> 列出资源 -> 创建或复用 -> 等待密钥就绪 -> 关联环境 -> 对象流转 -> 清理

。桶身份、策略、命名空间和环境变更均属于请求范围。

Progressive Disclosure

渐进式披露

Load analyzer, bucket, policy, credential, object-flow, and cleanup procedures one level deep when their phase is reached. Keep private policy, confirmation, and redaction canaries visible before the CLI detail.

当进入对应阶段时，逐层加载分析器、桶、策略、凭证、对象流转和清理流程。在显示 CLI 详情前，保持私有策略、确认步骤和脱敏校验标识可见。

Output, Stop, and Error States

输出、终止与错误状态

```
success
```
: bucket identity/policy/readiness, workspace, env key names, authenticated object or presign proof, cleanup state, and redaction status.
```
stopped
```
: ambiguous workspace, unavailable credential readiness, tracked env target, public policy, rotation, replacement, or destructive confirmation boundary with the safe private/presign alternative; no gated operation is claimed.
```
error
```
: analyzer, CLI, policy, credential, object, or env-write step, sanitized diagnostic category, affected artifact, and recovery action with credentials, endpoints, and connection values redacted.

```
success
```
: 桶身份/策略/就绪状态、工作区、环境密钥名称、已认证对象或预签名验证结果、清理状态和脱敏状态。
```
stopped
```
: 工作区模糊、凭证未就绪、存在跟踪的环境目标、公共策略、凭证轮换、存储替换或破坏性操作确认边界（提供安全的私有/预签名替代方案）；未执行受限操作。
```
error
```
: 分析器、CLI、策略、凭证、对象或环境写入步骤出错，返回脱敏诊断类别、受影响工件和恢复操作（凭证、端点和连接值已脱敏）。

Handoffs

交接流程

An optional deployment handoff uses the complete tuple below. The receiver re-checks deployment scope and runtime evidence.

yaml

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

Direct S3 requests use

target: none

and keep the same evidence fields.

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

yaml

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

并保留相同证据字段。

Verification

验证

Use

analyze-project-s3.mjs

sealos-cli s3

JSON output, authenticated object-flow evidence, and baseline cases

s3-positive-private-round-trip

and

s3-violating-unconfirmed-public-or-rotation

. Verify private policy, env preservation, and redaction before success.

Use this skill to give a project real Sealos object storage through

sealos-cli s3

. The default outcome is: identify the app's object-storage need, create or reuse a bucket, initialize credentials only when needed, wire the smallest safe set of local env vars, and verify the project's upload/download or presigned URL path.

This skill is grounded in

zjy365/sealos-cli#28

, which registered the

s3

command and implemented bucket CRD operations plus S3-compatible object operations.

使用

analyze-project-s3.mjs

、

sealos-cli s3

JSON 输出、已认证对象流转证据，以及基准用例

s3-positive-private-round-trip

和

s3-violating-unconfirmed-public-or-rotation

。验证私有策略、环境保留和脱敏无误后再标记为成功。

使用此技能通过

sealos-cli s3

为项目配置真实的 Sealos 对象存储。默认结果为：识别应用的对象存储需求、创建或复用桶、仅在需要时初始化凭证、关联最小安全集的本地环境变量，并验证项目的上传/下载或预签名 URL 路径。

此技能基于

zjy365/sealos-cli#28

开发，该 PR 注册了

s3

命令并实现了桶 CRD 操作及兼容 S3 的对象操作。

Safety Rules

安全规则

Never print secret keys, full S3 credential blocks, or copied env values in the final answer.
Do not overwrite an existing env value without confirming or preserving the old value.
Do not commit
```
.env
```
,
```
.env.local
```
, S3 access keys, secret keys, kubeconfig, or Sealos auth files.
Ask before making a bucket public. Default bucket policy is
```
private
```
.
Ask before destructive operations:
```
s3 delete-bucket
```
,
```
s3 delete
```
, credential rotation for an active app, or replacing app storage configuration.
Use JSON output from
```
sealos-cli
```
by default and parse it instead of scraping table output.
Treat
```
s3 secret
```
output as sensitive even though the CLI can print it.

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

Workflow

工作流

1. Resolve the target project

1. 解析目标项目

Confirm the working directory with

pwd

git rev-parse --show-toplevel

Run the analyzer when a project directory is available:

bash

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

Use the analyzer result as a starting point, then inspect the real files it cites before editing anything. It intentionally avoids printing secret values.

通过

pwd

或

git rev-parse --show-toplevel

确认工作目录。

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

bash

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

以分析器结果为起点，在编辑任何内容前先检查它引用的真实文件。分析器会刻意避免打印敏感值。

2. Check

sealos-cli

2. 检查

sealos-cli

Prefer an existing

sealos-cli

binary:

bash

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

If it is not installed, use

npx -y sealos-cli@latest ...

for one-off commands. Ask before installing it globally.

If auth is missing or expired, run:

bash

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

Use the workspace the user expects. If multiple workspaces exist and the target is ambiguous, ask before provisioning.

sealos-cli s3

derives the object-storage user from the active kubeconfig namespace, so a wrong workspace means wrong buckets and credentials.

优先使用已有的

sealos-cli

二进制文件：

bash

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

若未安装，可使用

npx -y sealos-cli@latest ...

执行一次性命令。全局安装前需询问用户。

若认证缺失或过期，运行：

bash

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

使用用户期望的工作区。若存在多个工作区且目标不明确，配置前需询问用户。

sealos-cli s3

从活跃 kubeconfig 命名空间派生对象存储用户，因此错误的工作区会导致错误的桶和凭证。

3. Choose create or reuse

3. 选择创建或复用

List existing buckets first:

bash

sealos-cli s3 buckets -o json

Reuse an existing bucket when its purpose and policy match. Create a new one when the project has no suitable bucket or the user asks for a fresh bucket:

bash

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

Use

private

unless the user explicitly needs public reads or writes. Bucket policies accepted by the PR are

private

publicRead

, and

publicReadwrite

; aliases such as

public-read

normalize to

publicRead

, but use canonical values in instructions and scripts.

先列出现有桶：

bash

sealos-cli s3 buckets -o json

当现有桶的用途和策略匹配时复用。若项目无合适桶或用户要求新桶，则创建新桶：

bash

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

除非用户明确需要公共读取或写入权限，否则使用

private

策略。PR 支持的桶策略为

private

、

publicRead

和

publicReadwrite

；

public-read

等别名会标准化为

publicRead

，但在指令和脚本中需使用规范值。

4. Initialize credentials only when needed

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

For app env wiring or object operations, fetch credentials:

bash

sealos-cli s3 secret -o json

The command creates the

ObjectStorageUser

if it does not exist, then waits briefly for status. If credentials are not ready, retry after a few seconds instead of creating raw CRDs by hand.

Use

references/sealos-cli-s3.md

for the current command contract and response handling.

为应用环境关联或对象操作获取凭证：

bash

sealos-cli s3 secret -o json

若

ObjectStorageUser

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

参考

references/sealos-cli-s3.md

获取当前命令契约和响应处理方式。

5. Wire the development environment

5. 关联开发环境

Map only the keys the project already uses. Common targets:

Project signal	Preferred env keys
AWS SDK / S3 generic	`S3_ENDPOINT` , `S3_ACCESS_KEY_ID` , `S3_SECRET_ACCESS_KEY` , `S3_BUCKET`
AWS-style config	`AWS_ACCESS_KEY_ID` , `AWS_SECRET_ACCESS_KEY` , `AWS_REGION` , `S3_BUCKET`
MinIO replacement	existing `MINIO_*` keys or migrate to existing S3 keys only if the app supports them
Upload libraries	the keys read by the adapter/config file

Use endpoint from

secret.external

for local laptop development. Use

secret.internal

only when the app runs inside Sealos/Devbox and the runtime can reach the internal endpoint.

Read

references/env-integration.md

before editing env files.

仅映射项目已在使用的密钥。常见目标：

项目标识	首选环境密钥
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. Verify application storage behavior

6. 验证应用存储行为

Run the smallest real project path that proves object storage works:

Run a repo script or test that uploads and reads an object if available.
Otherwise upload a small local test file with
```
sealos-cli s3 upload
```
, list it, download it to a temp path, and delete the test object.
For presigned URL features, run
```
sealos-cli s3 presign <bucket> <key> --expires 3600 -o json
```
and verify the URL only when that is part of the requested workflow.

Use

--endpoint

--access-key

, and

--secret-key

together only when connecting to a non-Sealos S3-compatible endpoint. Do not mix partial overrides.

运行最小化的真实项目路径以验证对象存储可用：

若存在，运行仓库脚本或测试来上传并读取对象。
否则使用
```
sealos-cli s3 upload
```
上传小型本地测试文件，列出文件，下载到临时路径，然后删除测试对象。
若涉及预签名 URL 功能，运行
```
sealos-cli s3 presign <bucket> <key> --expires 3600 -o json
```
并仅在请求的工作流包含此步骤时验证 URL。

仅当连接到非 Sealos 的兼容 S3 端点时，才同时使用

--endpoint

、

--access-key

和

--secret-key

。不要混合使用部分覆盖参数。

7. Report the result

7. 报告结果

Summarize:

Bucket name, policy, region/workspace, and readiness.
Env file and keys updated, without revealing secret values.
Verification command and outcome.
Any public policy, credential rotation, or cleanup follow-up.

总结内容：

桶名称、策略、区域/工作区和就绪状态。
更新的环境文件和密钥（不泄露敏感值）。
验证命令和结果。
任何公共策略、凭证轮换或清理后续操作。

Common Tasks

常见任务

Connect an existing project to Sealos object storage

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

Run the analyzer.
Inspect the env/config files it cites.
List existing buckets.
Create or reuse the matching bucket.
Fetch credentials with
```
s3 secret
```
.
Write only the env keys the app reads.
Verify the app's storage path.

运行分析器。
检查它引用的环境/配置文件。
列出现有桶。
创建或复用匹配的桶。
使用
```
s3 secret
```
获取凭证。
仅写入应用读取的环境密钥。
验证应用的存储路径。

Replace local MinIO for development

替换本地 MinIO 用于开发

Identify the app service env vars that point at MinIO or an S3-compatible service.
Create or reuse a private Sealos bucket.
Update only the app's local env file, not the compose file, unless the user asks to remove MinIO.
Keep local Compose rollback simple: the original MinIO service remains available.

识别指向 MinIO 或兼容 S3 服务的应用服务环境变量。
创建或复用私有 Sealos 桶。
仅更新应用的本地环境文件，而非 compose 文件，除非用户要求移除 MinIO。
保持本地 Compose 回退简单：保留原始 MinIO 服务可用。

Upload or share project assets

上传或共享项目资产

Confirm the target bucket and object key prefix.

Upload with

sealos-cli s3 upload <bucket> <file> --key <key> -o json

Use
```
presign
```
for temporary sharing instead of public bucket policy when possible.
Delete temporary test objects after verification.

确认目标桶和对象键前缀。

使用

sealos-cli s3 upload <bucket> <file> --key <key> -o json

上传。

尽可能使用
```
presign
```
进行临时共享，而非设置公共桶策略。
验证后删除临时测试对象。

References

参考资料

```
scripts/analyze-project-s3.mjs
```
- read-only project object-storage intent analyzer.

references/sealos-cli-s3.md

- PR #28

sealos-cli s3

command contract.

```
references/env-integration.md
```
- safe env-file editing and S3 env-key mapping.

```
scripts/analyze-project-s3.mjs
```
- 只读项目对象存储需求分析器。

references/sealos-cli-s3.md

- PR #28 的

sealos-cli s3

命令契约。

```
references/env-integration.md
```
- 安全的环境文件编辑和 S3 环境密钥映射指南。

sealos-s3

Original

Translation

Sealos S3

Sealos S3

Identity and Discovery

身份与发现

Scope and Boundaries

范围与边界

Risk and Confirmation

风险与确认

Lifecycle Workflow

生命周期工作流

Request Contract

请求契约

Progressive Disclosure

渐进式披露

Output, Stop, and Error States

输出、终止与错误状态

Handoffs

交接流程

Verification

验证

Safety Rules

安全规则

Workflow

工作流

1. Resolve the target project

1. 解析目标项目

2. Check sealos-cli

2. 检查sealos-cli

3. Choose create or reuse

3. 选择创建或复用

4. Initialize credentials only when needed

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

5. Wire the development environment

5. 关联开发环境

6. Verify application storage behavior

6. 验证应用存储行为

7. Report the result

7. 报告结果

Common Tasks

常见任务

Connect an existing project to Sealos object storage

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

Replace local MinIO for development

替换本地 MinIO 用于开发

Upload or share project assets

上传或共享项目资产

References

参考资料

2. Check
`sealos-cli`

2. 检查
`sealos-cli`