sealos-deploy

Sealos Deploy

兼容性

部署需要 Sealos auth/workspace。仅当所选路径需要本地构建/推送时，才需要 Docker、buildx 和 gh CLI。从 GitHub URL 克隆或需要 Git 元数据时，需要 git。Node.js 18+ 和 Python 3.8+ 仍是可选的加速工具。

只需一条命令，即可将任何 GitHub 项目部署到 Sealos Cloud——从源代码到运行中的应用程序。

kubectl 安全规则（适用于所有阶段）

所有 kubectl 命令都必须使用 Sealos kubeconfig：

KUBECONFIG=~/.sealos/kubeconfig kubectl --insecure-skip-tls-verify

安装系统工具需要用户确认。如果缺少 docker、gh 或 kubectl，且此技能可为当前平台安装该工具，请先询问，只有用户明确回复 y 后才运行安装命令。

执行 kubectl delete 需要用户确认。 删除任何资源（deployment、service、ingress、PVC、database 等）之前，务必询问：

WARNING: About to delete <resource kind>/<resource name>. This data cannot be recovered. Confirm? (y/n)

只有用户确认后才能继续。即使流水线逻辑建议删除，也必须先询问。

清理 Template API 资源时必须包含 Instance CR。 通过 scripts/deploy-template.mjs 创建的部署，除 App/工作负载资源外，还会创建 instances.app.sealos.io/<app-name>。只有检查完 instances.app.sealos.io、apps.app.sealos.io、工作负载、Services、Ingresses、PVCs 和 Pods，清理才算完成。

清理 Template API 测试部署时，请使用此检查：

KUBECONFIG=~/.sealos/kubeconfig kubectl --insecure-skip-tls-verify -n "$NS" \
  get instances.app.sealos.io,app,statefulset,deployment,svc,ingress,pvc,pod | grep "$APP"

确认后按以下顺序删除：

KUBECONFIG=~/.sealos/kubeconfig kubectl --insecure-skip-tls-verify -n "$NS" delete instances.app.sealos.io "$APP" --ignore-not-found --wait=false
KUBECONFIG=~/.sealos/kubeconfig kubectl --insecure-skip-tls-verify -n "$NS" delete app "$APP" --ignore-not-found --wait=false
KUBECONFIG=~/.sealos/kubeconfig kubectl --insecure-skip-tls-verify -n "$NS" delete statefulset "$APP" --ignore-not-found --wait=false
KUBECONFIG=~/.sealos/kubeconfig kubectl --insecure-skip-tls-verify -n "$NS" delete deployment "$APP" --ignore-not-found --wait=false
KUBECONFIG=~/.sealos/kubeconfig kubectl --insecure-skip-tls-verify -n "$NS" delete ingress "$APP" --ignore-not-found --wait=false
KUBECONFIG=~/.sealos/kubeconfig kubectl --insecure-skip-tls-verify -n "$NS" delete svc "$APP" --ignore-not-found --wait=false
KUBECONFIG=~/.sealos/kubeconfig kubectl --insecure-skip-tls-verify -n "$NS" get pvc -o name | grep "$APP" | while read -r PVC; do
  KUBECONFIG=~/.sealos/kubeconfig kubectl --insecure-skip-tls-verify -n "$NS" delete "$PVC" --ignore-not-found --wait=false
done

反例：仅检查 app,statefulset,svc,ingress,pvc,pod 后，不要报告清理完成；这会遗漏 instances.app.sealos.io/<app-name>，导致 Sealos Instance 层残留。

用法

/sealos-deploy <github-url>
/sealos-deploy                    # deploy current project
/sealos-deploy <local-path>

快速开始

按顺序执行各模块：

1. modules/preflight.md — 环境检查和 Sealos 身份验证
2. modules/pipeline.md — 完整部署流水线（阶段 1–6）

日志记录

每次运行都必须在 ~/.sealos/logs/deploy-<YYYYMMDD-HHmmss>.log 创建日志文件。

执行开始时，只创建一次日志文件：

mkdir -p ~/.sealos/logs
LOG_FILE=~/.sealos/logs/deploy-$(date +%Y%m%d-%H%M%S).log
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Deploy started" > "$LOG_FILE"

重要：仅在开始时创建一次日志文件。此后所有写入都必须使用 >> 追加到同一个 $LOG_FILE。不要创建第二个日志文件。

每个阶段结束时，使用 Bash >> 向同一文件追加日志条目：

[2026-03-05 14:30:01] === Phase 0: Preflight ===
[2026-03-05 14:30:01] Docker: ✓ 27.5.1
[2026-03-05 14:30:01] Node.js: ✓ 22.12.0
[2026-03-05 14:30:02] Sealos auth: ✓ (region: <REGION from config.json>)
[2026-03-05 14:30:02] Project: /Users/dev/myapp (github: https://github.com/owner/repo)

[2026-03-05 14:30:03] === Phase 1: Assess ===
[2026-03-05 14:30:03] Score: 9/12 (good)
[2026-03-05 14:30:03] Language: python, Framework: fastapi, Port: 8000
[2026-03-05 14:30:03] Decision: CONTINUE

[2026-03-05 14:30:04] === Phase 2: Detect Image ===
[2026-03-05 14:30:05] Docker Hub: owner/repo:latest (arm64 only, no amd64)
[2026-03-05 14:30:05] GHCR: not found
[2026-03-05 14:30:05] Decision: no amd64 image → continue to Phase 3

[2026-03-05 14:30:06] === Phase 3: Dockerfile ===
[2026-03-05 14:30:06] Existing Dockerfile: none
[2026-03-05 14:30:07] Generated: python-fastapi template, port 8000

[2026-03-05 14:30:08] === Phase 4: Build & Push ===
[2026-03-05 14:30:08] Registry: ghcr (auto-detected via gh CLI)
[2026-03-05 14:30:30] Build: ✓ ghcr.io/zhujingyang/repo:20260305-143022
[2026-03-05 14:30:32] GHCR pullability: private package detected — deploy will auto-create image pull Secret from gh CLI
[2026-03-05 14:30:33] IMAGE_REF=ghcr.io/zhujingyang/repo:20260305-143022

[2026-03-05 14:30:34] === Phase 5: Template ===
[2026-03-05 14:30:35] Output: .sealos/template/index.yaml

[2026-03-05 14:30:36] === Phase 6: Deploy ===
[2026-03-05 14:30:36] Deploy URL: https://template.gzg.sealos.run/api/v2alpha/templates/raw
[2026-03-05 14:30:38] Status: 201 — deployed successfully
[2026-03-05 14:30:38] === DONE ===

发生错误时，请在停止前记录错误详情：

[2026-03-05 14:30:10] === ERROR ===
[2026-03-05 14:30:10] Phase: 4 (Build & Push)
[2026-03-05 14:30:10] Error: docker buildx build failed — "npm ERR! Missing script: build"
[2026-03-05 14:30:10] Retry: 1/3

全部完成后，告知用户日志所在位置：

Log saved to: ~/.sealos/logs/deploy-20260305-143001.log

脚本

位于此技能目录下的 scripts/（<SKILL_DIR>/scripts/）：

脚本	用法	用途
score-model.mjs	node score-model.mjs <repo-dir>	确定性就绪度评分（0-12）
validate-artifacts.mjs	node validate-artifacts.mjs --dir <work-dir>	根据强制执行的架构验证 .sealos JSON 构件
detect-image.mjs	node detect-image.mjs <github-url> [work-dir] 或 node detect-image.mjs <work-dir>	检测现有的 Docker/GHCR 镜像
build-push.mjs	node build-push.mjs <work-dir> <repo> [--registry ghcr|dockerhub] [--user <user>]	构建 amd64 镜像并推送到选定的注册表（Docker Hub 路径假定部署时镜像是公开的；省略 --registry 会保留自动检测行为）
ensure-image-pull-secret.mjs	node ensure-image-pull-secret.mjs <namespace> <secret-name> <image-ref> [deployment-name]	创建/更新应用专用的 GHCR 拉取 Secret，并可选择为现有 Deployment 打补丁以引用该 Secret
gh-refresh-scopes.mjs	node gh-refresh-scopes.mjs write:packages	在当前 TTY 中刷新 GHCR 软件包访问权限；在此工作流中，write:packages 足以用于推送和私有拉取
deploy-template.mjs	node deploy-template.mjs <template-path> [--dry-run] [--args-json '{"KEY":"value"}'|--args-file <file>]	从 ~/.sealos/auth.json 解析当前区域，构建正确的 Template API URL，并提交本地模板 YAML
sealos-footprint.mjs	node sealos-footprint.mjs --namespace <ns> --app <app>	只读清点 Instance/App/工作负载/Jobs/KubeBlocks/PVC，用于部署调试和清理规划
sealos-live-smoke.mjs	node sealos-live-smoke.mjs --url <url> [--captcha-path <path>] [--login-path <path>] [--username <user>] [--password <pass>] [--auth-path <path>]	对真实 Sealos App 入口 URL 进行只读或使用凭据的 HTTP 冒烟测试
sealos-auth.mjs	node sealos-auth.mjs check|login|list|switch	Sealos Cloud 身份验证和工作区切换

所有脚本都输出 JSON。通过 Bash 运行并解析结果。

内部技能依赖

此技能会引用同一安装环境中的内部技能知识文件。这些文件不面向用户，会在特定阶段按需加载。

<SKILL_DIR> 指包含此 SKILL.md 的目录。同级技能位于 <SKILL_DIR>/../：

<SKILL_DIR>/../
├── sealos-deploy/           ← this skill (user entry point) = <SKILL_DIR>
├── dockerfile-skill/        ← Phase 3: Dockerfile generation knowledge
├── cloud-native-readiness/  ← Phase 1: assessment criteria
└── docker-to-sealos/       ← Phase 5: Sealos template rules

pipeline.md 中使用的路径遵循以下模式：

<SKILL_DIR>/../dockerfile-skill/knowledge/error-patterns.md
<SKILL_DIR>/../dockerfile-skill/templates/<lang>.dockerfile
<SKILL_DIR>/../docker-to-sealos/references/sealos-specs.md

阶段概览

阶段	操作	跳过条件
0 — 预检	能力扫描、特定路径警告、Sealos 身份验证	初始阻碍已解决
1 — 评估	克隆仓库（或使用当前项目），分析可部署性	评分过低 → 停止
2 — 检测	查找现有镜像（Docker Hub / GHCR / README）	找到 → 跳转到阶段 5
3 — Dockerfile	缺少 Dockerfile 时生成	已有 → 跳过
4 — 构建并推送	docker buildx → GHCR（通过 gh CLI 自动处理）或 Docker Hub（备用）	—
5 — 模板	生成 Sealos 应用模板	—
5.5 — 配置	指导用户设置应用环境变量和输入项	无需输入
6 — 部署	将模板部署到 Sealos Cloud	—
6.5 — 运行时核验	验证实际的 Sealos 运行时、日志、App URL、登录路径和资源占用情况	用户明确要求仅输出部署结果

决策流程

Input (GitHub URL / local path)
  │
  ▼
[Phase 0] Preflight ── fail → guide user to fix and STOP
  │ pass
  ▼
[Phase 1] Assess ── not suitable → STOP with reason
  │ suitable
  ▼
[Phase 2] Detect existing image
  │
  ├── found (amd64) ────────────────────┐
  │                                     │
  ▼                                     │
[Phase 3] Dockerfile (generate/reuse)   │
  │                                     │
  ▼                                     │
[Phase 4] Build & Push to registry      │
  │                                     │
  ◄─────────────────────────────────────┘
  │
  ▼
[Phase 5] Generate Sealos Template
  │
  ▼
[Phase 5.5] Configure ── present env vars → ask user for inputs → confirm
  │
  ▼
[Phase 6] Deploy to Sealos Cloud ── 401 → re-auth
│                                  409 → instance exists
▼
[Phase 6.5] Runtime Truth Pass ── runtime/log/login issue → debug template or runtime config
│
▼
Done — app deployed ✓

执行规则： 阶段 0 仍有未解决的入口阻碍时，绝不能启动阶段 1。必须尽早报告 Docker、gh、构建器和注册表故障，但只有当运行流程随后需要本地构建/推送时，它们才会成为硬性阻碍。