sealos-database

Sealos 数据库

身份与发现

• 所有者：sealos-database（/sealos-database，以及数据库创建、连接、备份、日志或访问请求）。
• **类别：**通过 sealos-cli 执行 cloud-local-mutation，可选择将已脱敏的信息交接给部署流程。
• 金丝雀：DB-REUSE-ENV、DB-CONFIRM-PUBLIC 和 DB-REDACT-CONNECT。

范围与边界

接受项目路径和数据库需求。先分析并列出已有数据库，再创建或复用所选类型的数据库，并且只接入现有应用环境变量键。保留原有环境变量值和本地 Compose 回滚方案；默认使用私有访问。删除数据库、启用公开访问、删除备份、处理恢复冲突以及停用活跃访问均属于受控操作。

风险与确认

绝不输出密码、完整连接字符串、kubeconfig、认证文件或复制的环境变量值。启用公开访问或执行破坏性操作前必须征求确认，并说明私有访问这一替代方案。解析 CLI JSON 输出，并将所选工作区、命名空间、数据库和环境变量变更限定在当前请求范围内。

生命周期工作流

对于每个请求，解析项目，分析其数据库需求，确认 CLI、认证、区域和工作区；先列出现有数据库，再创建或复用；获取连接详情，接入现有环境变量键，并验证连接或迁移。输出限定于当前请求的 success、stopped 或 error 状态；现有的分析器优先工作流仍由下方的领域扩展负责。工作区不明确、凭据响应不可用或环境变量目标已纳入版本控制时，必须在变更前停止请求。

请求约定

input:
  project: local path or repository source
  intent: database type, purpose, and create-or-reuse preference
  access: private by default; public only after confirmation
preconditions:
  - analyzer evidence names the database signal and env key
  - sealos-cli/auth/region/workspace are resolved
  - the selected env file is ignored and the key is known

操作顺序为 analyze -> resolve account/workspace -> list -> create or reuse -> wait -> fetch -> wire -> verify。所选工作区、命名空间、数据库标识和环境变量变更均限定在当前请求范围内。

渐进式披露

在进入相应阶段时，逐层加载分析器、CLI、环境变量接入和连接性检查流程。即使详细命令位于自有脚本或参考资料中，也要在此处明确展示凭据处理规则以及公开访问或破坏性操作的确认要求。

输出、停止与错误状态

• success：数据库标识/状态、区域/工作区、环境变量文件和键名称、已脱敏的连接或迁移证据、确认状态，以及任何后续访问状态。
• stopped：工作区不明确、凭据尚未准备就绪、环境变量目标已纳入版本控制、涉及公开访问/破坏性操作的确认边界，或缺少前置条件；说明安全的后续操作，不得声称已执行任何受控变更。
• error：分析器、CLI、连接或环境变量写入步骤出错；提供已清理的诊断类别、受影响的构件和恢复操作，并对密码、URL、认证值和完整连接字符串进行脱敏。

交接

可选择交接给部署流程，交接时使用以下完整字段组。接收方会重新检查部署范围和运行时证据。

target: sealos-deploy
inputArtifact: redacted database identity, private-access status, approved env-key contract, and connectivity/migration evidence
allowedAction: consume approved Secret/env references within the selected deployment scope
failureReturn: sanitized analyzer, CLI, env, or connectivity diagnostic with the failed phase
responseOwner: sealos-database

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

验证

使用 analyze-project-database.mjs、sealos-cli JSON 输出、应用迁移/连接性证据，以及基准用例 database-positive-reuse-redacted-connectivity 和 database-violating-unconfirmed-public-or-destructive。验收成功前，验证环境变量保留情况和脱敏结果。

使用此技能，可在开发期间为项目配置真实的 Sealos Cloud 数据库。默认结果是：识别应用的数据库需求，使用 sealos-cli 创建或复用 Sealos 数据库，获取连接详情，只接入必要的本地环境变量，并验证应用能够连接。

安全规则

1. 最终回答中绝不输出数据库密码或完整连接字符串。
2. 未经确认或保留旧值，不要覆盖现有环境变量值。
3. 不要提交 .env、.env.local、连接字符串、密码、kubeconfig 或 Sealos 身份验证文件。
4. 启用数据库公共访问前先询问。当应用在 Sealos/Devbox 内运行时，优先使用私有连接。
5. 执行破坏性操作前先询问：database delete、backup-delete、恢复到可能重名的名称，或禁用活动应用所依赖的访问。
6. 默认使用 sealos-cli 的 JSON 输出并进行解析，不要从表格输出中抓取数据。

工作流

1. 确定目标项目

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

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

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

将分析器结果作为起点，然后在编辑任何内容之前检查其提及的实际文件。分析器会刻意避免输出机密值。

2. 检查 sealos-cli

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

sealos-cli --version
sealos-cli database --help
sealos-cli whoami

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

如果缺少身份验证信息或身份验证已过期，运行：

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

使用用户预期的工作区。如果存在多个工作区且目标不明确，请在配置资源前先询问。

3. 选择新建或复用

先列出现有数据库：

sealos-cli database list -o json

如果名称、类型和用途相符，则复用现有数据库。如果项目没有合适的数据库，或用户要求新建开发数据库，则创建一个。

除非项目明确需要更高配置，否则使用保守的开发环境默认值：

sealos-cli database create postgresql --name <app-dev-db> --cpu 1 --memory 1 --storage 3 --replicas 1 -o json

如果版本选择很重要，则在创建前检查支持的版本：

sealos-cli database versions --type postgresql -o json

CLI 支持的数据库类型包括 postgresql、mongodb、mysql、apecloud-mysql、redis、kafka、qdrant、nebula、weaviate、milvus、pulsar 和 clickhouse。使用从项目中检测到的类型；仅当项目没有数据库类型相关信号时，才默认使用 postgresql。

4. 等待就绪并获取连接数据

轮询详情，直到数据库正在运行或连接数据已就绪：

sealos-cli database get <name> -o json
sealos-cli database connection <name> -o json

阅读 references/sealos-cli-database.md，了解当前命令约定和响应处理方式。

5. 配置开发环境

将连接信息映射到项目已使用的环境变量：

项目信号	首选环境变量名
Prisma、Drizzle、TypeORM、通用 Postgres	DATABASE_URL
使用现有 MySQL 专用配置的 MySQL 应用	DATABASE_URL 或现有的 MYSQL_URL
MongoDB 应用	MONGODB_URI
Redis 缓存/队列	REDIS_URL

遵循现有的本地环境变量约定：

1. 对于 Next.js 和与前端相关的项目，优先使用 .env.local。
2. 仅当仓库已将 .env 用于本地开发且该文件已加入 Git 忽略列表时，才优先使用 .env。
3. 将 .env.example 仅用作文档；绝不要在其中写入真实机密。
4. 保留注释和无关的键。

如果返回的连接字符串格式不符合所需格式，则使用 sealos-cli database connection 返回的 host、port、username 和 password 字段进行组合。

6. 验证应用连接

运行项目的常规验证流程，而不只是 CLI 命令：

1. 如果项目有明确的迁移或内省命令（prisma migrate、drizzle-kit migrate、db:migrate、db:push），则运行该命令。
2. 启动应用，或运行能够建立数据库连接的最小测试。
3. 如果应用在 Sealos 外部运行且无法连接私有端点，则在启用公共访问前先询问：

sealos-cli database enable-public <name> -o json
sealos-cli database connection <name> -o json

测试后如果不再需要公共访问，请将其禁用：

sealos-cli database disable-public <name> -o json

7. 报告结果

总结：

1. 数据库名称、类型、区域/工作区和状态。
2. 已更新的环境变量文件和键，不要透露机密值。
3. 验证命令及结果。
4. 公共访问状态和后续操作。

常见任务

将现有项目连接到 Sealos 数据库

1. 运行分析器。
2. 检查分析器引用的 env/config 文件。
3. 列出现有的 Sealos 数据库。
4. 创建或复用匹配的数据库。
5. 获取连接详情。
6. 写入预期的 env 键。
7. 运行应用的数据库验证。

在开发环境中替换本地 Compose 数据库

1. 找出应用服务的 env 变量，它们指向 postgres、mysql、mongo 或 redis Compose 服务。
2. 创建对应的 Sealos 数据库。
3. 只更新应用的本地 env 文件，不要修改 compose 文件，除非用户要求移除本地服务。
4. 让本地 Compose 回滚保持简单：保留原有的 compose 服务，以便继续使用。

将数据库添加到 Devbox 工作流

1. 如果 Devbox 在同一个 Sealos 工作区中运行，请使用私有数据库连接详情。
2. 将 env 变量写入仓库所需的 Devbox/应用环境。
3. 只有在设置好 env 变量后，才重启或重新加载 Devbox 进程。

参考资料

• scripts/analyze-project-database.mjs - 只读的项目数据库意图分析器。
• references/sealos-cli-database.md - sealos-cli database 命令约定。
• references/env-integration.md - 安全编辑 env 文件及连接字符串映射。