use-sealos

使用 Sealos

Sealos 资源模型

Sealos Cloud 是一个多租户 Kubernetes 平台。用户拥有的所有内容都位于每个工作空间的一个命名空间（ns-xxx）中，并通过受限的 kubeconfig（~/.sealos/kubeconfig）访问。在该命名空间内：

• 应用是常规的 Deployment/StatefulSet + Service + Ingress，带有标签 cloud.sealos.io/app-deploy-manager: <app>，以便 Sealos「应用启动台」UI 管理它们。通过 <host>.<region-domain> 免费提供公共 HTTPS，并配有通配符证书。
• 数据库是由「数据库」UI 管理的 KubeBlocks Cluster CR。
• 模板商店托管 200 多个一键模板（sealos-api.py store-list）；已部署的模板会作为实例进行跟踪，并显示在 UI 中。
• 对象存储桶是 ObjectStorageBucket CR，凭据以 S3 兼容形式存储在托管密钥中。
• 区域由一个集群和一个域名组成（例如，国际区域为 usw-1.sealos.io，中国区域为 bja.sealos.run 等）。模板 API 位于 https://template.<region-domain>。

工具

请根据此技能所在目录解析 scripts/ 和 references/，而不是根据项目工作目录解析。

• scripts/sealos-api.py — 身份验证（status、login、workspaces、switch）和模板 API（deploy、store-list）。通过模板 API 部署（而非直接运行 kubectl apply）才能让资源在 Sealos UI 中显示为可删除的单元。
• 设置 KUBECONFIG=~/.sealos/kubeconfig 后使用 kubectl — 用于所有读取、调试和删除操作。kubeconfig 的范围限定为命名空间；你无法查看或操作其他租户。
• scripts/wait-app.sh — 部署后验证（工作负载就绪状态 + URL 探测 + 故障诊断）。
• docker buildx — 仅用于源码构建路径。

部署前检查

如果 SEALAI_DEPLOY_MODE 为 managed（由 Brain 管理的沙盒），请在此处停止并改为遵循 ../sealos-deploy/SKILL.md — 该模式禁止登录和交互式提示。以下内容均为本地交互式操作流程。

python3 scripts/sealos-api.py status

• authenticated: true → 继续；记下 namespace 和 region_domain。
• 未通过身份验证 → 在后台运行 python3 scripts/sealos-api.py login，并关注其 stderr；一旦显示登录 URL，立即转告用户（验证码会过期，切勿静默等待命令结束）。用户也可以从 Sealos Web 控制台（左上角头像 → kubeconfig）复制 kubeconfig，并粘贴到 ~/.sealos/kubeconfig。
• 区域不正确？运行 login --region <url>。工作空间不正确？运行 workspaces + switch <name>。

部署、创建数据库和创建存储都会消耗账户配额或余额 — 如果部署因配额错误被拒绝，请如实告知；不要悄悄改用更小的数值重试。

部署决策树（15 分钟快速路径）

当用户想要部署某项内容时，首先进行分类——选错路径会浪费全部时间：

1. 已知的可自托管产品（Uptime Kuma、Metabase、n8n 等）： python3 scripts/sealos-api.py store-list --search <name>。
   • 搜索到模板 → 部署该模板（deploy.md， 路径 A）。速度最快且经过实战验证；约 3 分钟即可完成。
   • 未搜索到模板 → 查看 recipes.md 中是否有 现成配方；否则使用官方 Docker 镜像并编写模板（deploy.md，路径 B）。只要存在官方镜像，就绝不要从源码构建产品。
2. 用户自己的项目（有源代码）：查找现有的 Dockerfile/compose 文件；如果没有，则生成一个，构建 linux/amd64 镜像， 推送，然后部署镜像（先看 build.md，再看 deploy.md 路径 B）。
3. 仅需数据库／存储桶：databases.md / platform.md 的对象存储部分——以最简模板部署。

每次部署后，都要先验证再报告：

bash scripts/wait-app.sh -u https://<host>.<region-domain> deployment/<name> [cluster/<name>-pg ...]

在 *.sealos.io 区域，本地部署也会在脚本中认领一个 Brain Project； 如果 brain_adoption.ok 为 false，或者验证后 warnings 中仍列有 incompleteResourceSet，则运行 sealos-api.py adopt <instance>—— 绝不要重新部署。在 *.sealos.run 上会跳过此步骤 （brain_adoption.reason: not-sealos-io）。请参阅 deploy.md。

快速操作

export KUBECONFIG=~/.sealos/kubeconfig
kubectl get deploy,sts,pods                                   # what's running
kubectl get clusters.apps.kubeblocks.io                       # databases
kubectl get ingress -o custom-columns='NAME:.metadata.name,HOST:.spec.rules[0].host'  # public URLs
kubectl logs deploy/<name> --tail=100                         # app logs
kubectl describe pod <pod>                                    # scheduling/pull issues
kubectl get events --field-selector type=Warning --sort-by=.lastTimestamp | tail -20
kubectl scale deploy/<name> --replicas=2                      # scale
python3 scripts/sealos-api.py store-list --search <query>     # template store

路由

意图	参考文档
部署任何内容（模板、镜像或构建产物）	deploy.md
为用户源码编写 Dockerfile／构建镜像／推送到镜像仓库	build.md
配置或连接 PostgreSQL/MySQL/MongoDB/Redis/Kafka	databases.md
编写模板 YAML 时的清单规则（标签、Ingress、存储、配额阶梯、对象存储）	platform.md
状态、日志、调试、扩缩容、删除、成本管理	operate.md
常见可自托管软件的应用配方	recipes.md
Brain 托管沙箱（SEALAI_DEPLOY_MODE=managed）	../sealos-deploy/SKILL.md

只加载任务所需的内容——通常只需一个参考文档，最多两个。

执行规则

1. 没有证据，绝不要报告部署成功：wait-app.sh 以 0 退出，且公共 URL 返回真实页面（2xx/3xx；对于 SSR 应用， 响应正文不能是错误页面）。如果验证失败，通过 operate.md 进行排查——不要盲目重新部署。
2. 生产镜像必须构建并推送为 linux/amd64（docker buildx build --platform linux/amd64）。Apple Silicon 的默认设置会生成 arm64 镜像，在 Sealos 上会因 exec format error 而反复崩溃重启。
3. 资源请求和限制应遵循平台阶梯 （platform.md）；请求值根据限制值计算，内存始终使用 Mi 单位。
4. 通过 Template API 部署。仅在调试单个资源时才回退到 kubectl apply，并记住 kubectl apply 不接受带有 volumeClaimTemplates 的 Deployment（应使用 StatefulSet）。
5. 破坏性操作（删除应用、数据库、存储桶；在共享机器上切换 工作区）必须事先获得用户明确确认。
6. 绝不打印密钥值。将其读入 shell 变量或通过管道传递； 只向用户展示名称以及获取值的方法。
7. 执行变更后，先读取状态（kubectl get ...），再进行说明。
8. 每个应用名称一次只能部署一个实例；共享命名空间中的名称冲突 会破坏选择器。随机后缀（-a1b2c3d4）有其用途——请保留。
9. 如果 Agent 沙箱阻止对工作区之外的路径进行写入，则应提升文件 访问权限，以便写入 ~/.sealos/kubeconfig、使用 Docker 套接字，以及执行任何 必须读取该 kubeconfig 的命令。

响应格式

每次操作后报告：已部署/更改的内容（名称 + 命名空间）、 公共 URL（如有）、验证证据（就绪状态、HTTP 状态码）以及 凭据位置（Secret 名称，绝不包含值）。失败时：报告故障资源、关键日志/事件行，以及 你将采取的下一步操作。