tranfu-coolify-ops

tranfu Coolify 部署运维

把 tranfu-labs/-app 端到端部署到公司 Coolify 实例。新项目 / 故障修复 / 临时改动全部走同一份 reconcile 流程——流程自己识别要做什么，整套幂等可重跑。

Token 纪律（硬约束，写在最前面）

$COOLIFY_API_TOKEN 是高敏感凭据。全 skill 范围遵守：

1. 校验脚本只输出 ✓ / ✗——长度、前缀都不打（见 assets/preflight.sh）
2. agent 给 Bash tool 的命令字符串里永远只引用 $COOLIFY_API_TOKEN 变量名——token 原文只在 shell 内展开，不进对话转录
3. 禁止 echo $COOLIFY_API_TOKEN 来"看一眼对不对"——校验只能通过 preflight.sh
4. gh secret 用 --body "$COOLIFY_API_TOKEN"，不写明文
5. curl 用 -H "Authorization: Bearer $COOLIFY_API_TOKEN"，不写明文
6. Coolify 返回的 env value 是明文——agent 拿来做 diff，不展示，hash 比较代替明文显示
7. 用户给的 .env 文件——读完直接打 API，不在对话里 echo 内容

这套纪律比"四件套合规"还硬——违反一次 token 就外泄。

心智模型（读一遍再开干）

• GitHub repo name == Coolify project name == intended Application name——从 GitHub URL 初始化/同名探测时三者同名是硬约束。给一个 https://github.com/tranfu-labs/markdown-kits-app，立刻派生 REPO_NAME = PROJECT_NAME = APP_NAME = markdown-kits-app，全 skill 围绕这一个锚点定位资源，不扫描其他 project / 不让用户从列表里挑。但若入口是 Coolify UI URL / 已知 Application UUID，Coolify 返回的 name 可能是派生显示名（如 <repo>:<branch>-<uuid>），此时不要用 name == repo 判失败；以 git_repository / git_branch / build_pack / github_app_uuid / project_uuid / docker_compose_location / docker_compose_domains 等绑定字段判定 0.8 形态。
• Application 创建/GHA 成功后仍 unhealthy 要继续排障到可观测结论——先读 deployment 记录和容器日志；常见根因是运行时 env 缺失（例如应用启动直接抛 missing env）。如果 coolify app logs <uuid> --lines N 因 Application is not running 拿不到运行日志，可用只读 docker ps -a --filter name=<app_uuid> + docker logs --tail N <container> 取退出容器日志；注意 Coolify CLI 的 app logs 参数是 --lines/-n，不是 --tail。补 env 时不展示值，补完立即 POST /deploy?force=false 并验证 running:healthy + 公网 2xx/3xx。细节见 references/application-onboard-runtime-env-pitfalls.md；数据引导类失败案例见 references/session-2026-07-02-college-fit-app-data-bootstrap-notes.md。
• 用户在聊天里贴出的 secret 不要硬编码进脚本/JSON 字面量——Hermes/Feishu/日志脱敏层可能把值改写成占位符，导致 Coolify env 写入假的 masked value；也会扩大泄露面。优先让用户/运维在 UI 或终端手动录入，或使用不会把明文写入生成代码/日志的安全通道；若无法保证，就输出可复制模板而不是代执行。写完只验证 key/HTTP 状态，不打印 value；若怀疑写入被脱敏，明确要求人工覆盖并轮换。案例见 references/session-2026-07-03-offerpilot-env-redaction-pitfall.md。
• Coolify 全量只读盘点是部署 reconcile 的例外入口——当用户明确要求遍历 project/resources/deployments、输出域名/首次成功部署日期/状态清单时，可以跨 project 做只读 inventory；不得执行 PATCH/POST deploy/env/delete/start/stop/restart。使用 projects/{uuid} 建 environment→project 映射、/api/v1/resources 取资源归属和域名、deployment 历史取最早 finished/success。详见 references/coolify-read-only-inventory.md。
• GHA success + Coolify deployment finished 不等于应用可用——deployment finished 只说明部署流程结束，Application 可能随后从 restarting:unknown 落到 exited:unhealthy，公网返回 503 no available server。收尾必须继续查 coolify app get 运行状态 + 公网/health route；若运行日志因 Application is not running 取不到，先读 deployment logs，再按 reversible-ops 只读规则取一次性容器日志。案例和命令见 references/session-2026-07-02-college-fit-app-finished-but-unhealthy.md。
• 503 no available server 的多服务 Application 排障顺序——先确认目标 Application status；若为 exited:unhealthy / restarting:unknown，不要只重启或只看 GHA success。读取最近 deployment logs，定位具体 unhealthy service（例如 dependency failed to start: container asr-... is unhealthy）；若 coolify app logs 返回 Application is not running，这是预期限制，不代表无日志，改查 coolify app deployments list/logs。多服务 compose 中 depends_on: condition: service_healthy 会让一个子服务 unhealthy 拖垮整组，即使其他服务 healthy。恢复后必须同时验证 coolify app get == running:healthy 和公网 /、关键 health route 返回 2xx。
• env 重复 key 是风险信号但不自动清理——Coolify env API 可能已有重复 IMAGE_REF / 业务配置 key，排障时只输出 key/count/hash/长度，不展示值；若当前恢复不依赖删除重复项，不要自动 DELETE。删除重复 env 属于有风险清理，应单独列出受影响 key、保留候选和值哈希差异后再请求确认。
• GHA success 也可能只是 build-only success——如果仓库 workflow 使用旧变量名/条件（如 COOLIFY_APPLICATION_UUID、COOLIFY_API_URL、webhook token），Update Coolify IMAGE_REF / Deploy to Coolify 可能被 skip 但整条 run 仍 success。用户说 workflow 成功后，仍要打开实际 workflow 或 run job summary 确认 deploy step 没被跳过；social-media-analytics-app 细节见 references/session-2026-07-03-social-media-analytics-app-onboard-notes.md。
• 资源类型: Application (private-github-app) + build_pack=dockercompose——POST /api/v1/applications/private-github-app 创建, GET/PATCH/DELETE 走 /api/v1/applications/{uuid}。不用 Service / Compose Empty namespace (那是 0.7 旧形态)。详见 references/service-vs-application.md
• Application 身份确认要多锚点——不要只靠 git_repository 或 name 选目标；重复 Application、project_uuid=null、旧 unhealthy 实例都可能存在。写 env / deploy 前用生产域名、已验证 UUID、status、deployment URL/path 等交叉确认；重复 env key 只列 key/hash，不自动删或覆盖。详见 references/application-identity-and-env-duplicates.md
• GHA deploy template must contain executable auth headers, not log-masked placeholders——assets/deploy.yml.template and generated workflows must use -H "Authorization: Bearer $TOKEN" inside run steps. Never commit copied log-redaction text like Bearer ***; it produces invalid shell/YAML and deploy calls fail silently or at curl parse time. After generating or editing workflow files, run a static check for: no ***, Update Coolify IMAGE_REF, Trigger Coolify deploy, Bearer $TOKEN, no old variable names, and YAML parse success. When patching repeated YAML header lines, do not use broad fuzzy replace; patch with surrounding step context or rewrite the full file then read back the relevant section.
• GitHub App integration 是 Coolify 实例级一次性配置——GET /api/v1/github-apps 找 organization=tranfu-labs 的那一条, preflight 校验存在并 export $GITHUB_APP_UUID。skill 永不接管创建 (要上传 private key / installation id, 一次性手工配置, 所有 tranfu-labs 项目复用同一个)。不存在 → preflight 终止 + 给 UI 入口
• Auto Deploy on Push 永远关闭——is_auto_deploy_enabled: false. Coolify 收到 GitHub push 不部署, 部署只能由 GHA build 完后 POST /api/v1/deploy 触发。4I.4 GET 必须校验这个字段；接管/更新已有 Application 时也必须确认 UI 的 Deployment → Auto Deploy 已关闭，不要只看 GHA 链路或默认假设。若 API 返回 null/缺字段/不确定，按未确认处理，明确提醒用户到 UI 关掉或给出可恢复的 PATCH/设置命令模板，不能在报告里声称已关闭。
• 镜像链路: GHA → GHCR → IMAGE_REF → Coolify pull——compose 里主 service 只写 image: ${IMAGE_REF:-ghcr.io/${REPO}:latest} + pull_policy: always，不写 build:。GHA build/push 成功后先 PATCH/POST Coolify app env IMAGE_REF=ghcr.io/${REPO}:sha-<commit>，再 POST /api/v1/deploy；Coolify 读取不可变 sha tag 拉镜像。latest 只是 fallback/滚动标签，不是生产版本真相。回滚 = 改 IMAGE_REF 回上一个 sha tag + redeploy，不需要改 git 或重 build。若更新旧仓库从 IMAGE_TAG/latest 迁到 IMAGE_REF，注意验证 workflow 先写 IMAGE_REF 再 deploy，并检查是否已有重复 IMAGE_REF env（只报告，不自动删除）。详见 references/file-generation-rules.md、references/application-ghcr-node-deploy-quirks.md 和 references/session-2026-07-01-agentreach-image-ref-notes.md
• 生成 workflow 时避免 Bearer header 被脱敏破坏——在 Hermes/ops 会话里写 .github/workflows/deploy.yml 时，形如 Authorization: Bearer $TOKEN 的文本可能被安全脱敏层改写成 ***，导致文件或 patch 变成无效 shell/YAML。模板和手写修复优先用 curl --oauth2-bearer "$TOKEN" 携带 Coolify token，或在最终文件中显式静态校验“不含 *** 且含 --oauth2-bearer "$TOKEN"”。详见 references/hermes-bearer-header-redaction.md
• 一个 Application + dockercompose = 一份 compose + 内嵌 sub-applications 数组——compose 里有 N 个 service, sub-applications 数组就有 N 条, 每条有独立 uuid + fqdn
• 改域名走 docker_compose_domains 字段（不是 domains、不是 urls、不是 compose 里 SERVICE_FQDN_*）——详见 references/urls-vs-docker-compose-domains.md
• SERVICE_FQDN_* 是 Coolify → 容器的 output, 不是 user → Coolify 的 input——compose 里写 '' 即可, 写真值无效。详见 references/service-fqdn-trap.md
• 改 compose 走 git push, 不走 PATCH docker_compose_raw——0.7 Service 形态 compose 存在 Coolify 里 (base64), 改了要 PATCH; 0.8 Application 形态 compose 存在 git repo 里, 改完 push 即可, Coolify 下次 deploy 自动读最新 commit
• 部署链路: GHA push GHCR → curl $BASE/api/v1/deploy?uuid=$APP_UUID → Coolify pull 重启。详见 commands/deploy-trigger.md
• 同名 Service 残留 (0.7 历史) skill 不接管——Step 1 探测到同名 Service 而无 Application 时, 终止并告知用户手动 DELETE 旧 service 后重跑；legacy Service 可能 project_uuid=null，不能只按 name + project_uuid 查，需额外 name-only/null-project fallback（见 references/session-2026-07-02-offerpilot-legacy-service-null-project.md）
• Application identity 不只看 git_repository——Coolify 里可能存在同 repo/同名的重复 Application，或 API 返回 project_uuid=null 导致 Step 1 的 name + project_uuid filter 漏掉真实线上实例；写 env / deploy 前必须用 domain、已验证 UUID、status、deployment URL 等多锚点确认目标。详见 references/application-identity-and-env-duplicates.md