Skip to content

coolify-ops-skill 修复清单 #2

Closed
#3
Closed
coolify-ops-skill 修复清单#2
#3

Description

@hifizz
hifizz
opened on Jun 2, 2026

对齐基准:coollabsio/coolify-cli v1.6.2 源码 + coolify.io 官方文档(API Authorization)。
每条可独立贴成一个 Issue。标题用约定式前缀(与现有 commit 风格一致),正文中文,命令/flag 保持字面。
建议标签:P0 / P1、bug / docs / enhancement / security。

执行批次建议

P0

ISSUE #1 — fix(docs): "无法创建 app/service" 的能力描述已过时,CLI 实际支持

标签: P0 docs bug
影响文件: README.md、README.zh-CN.md(Capabilities 表)、SKILL.md(Known Capability Boundaries 段)

问题
README 能力表两个 ❌ 与 SKILL.md 的边界声明都说"从零创建应用/一键服务必须去 Web UI"。但 v1.6.2 源码里这些命令均已存在:

  • coolify app create 为完整父命令,子命令:public(公开 git)、github(GitHub App 私库)、deploy-key(SSH key 私库)、dockerfile、dockerimage;必填 --server-uuid --project-uuid --environment-name --build-pack --ports-exposes 等(见 cmd/application/create/)。
  • coolify service create <type> 存在,带 --list-types(枚举一键服务模板)与 --docker-compose(见 cmd/service/create.go)。
  • coolify project create 存在(见 cmd/project/create.go)。

改法

  1. 能力表把"Create an app from scratch""Create one-click services"两行从 ❌ 移到 ✅,补一句"需先有 server/project/environment 的 UUID"。
  2. SKILL.md "Known Capability Boundaries" 段重写:删除"app create 未暴露"的判断;改为新增一条决策路径 "F. 从零创建资源",列出 app create <source> / service create / project create 的最小必填参数,并强调先用 coolify project list / coolify server list 拿 UUID。
  3. 保留一句保守提醒:create 类命令参数较多且随版本变化,执行前 coolify app create <source> --help 核对。

验收

  • README/SKILL 不再出现"CLI 不能创建 app/service"的表述。
  • SKILL 含一条可走通的"从零创建"路径示例。

ISSUE #2 — fix(scripts): deploy-and-watch.sh 末尾状态汇报的 jq 过滤字段不存在,永远 silent 回退

标签: P0 bug
影响文件: scripts/deploy-and-watch.sh

问题
脚本结尾用 coolify deploy list --format=json 后按 .application_uuid / .resource_uuid 过滤。但 deploy list 的 model(internal/models/deployment.go)没有这两个字段,真实字段为:application_id(内部 int)、application_name、deployment_uuid、uuid、status、created_at。过滤恒不匹配 → 每次 silent 落到 coolify deploy list(table),"部署完自动汇报状态"实际是死代码。

改法(推荐:换用按 app 作用域的端点,绕开字段匹配)
用 coolify app deployments list <app-uuid>(cmd/application/deployments.go 的 list <app-uuid>),它本身就只返回该 app 的部署,无需按 uuid 过滤:

# 替换原有 deploy list | jq 过滤块
if command -v jq >/dev/null 2>&1; then
  coolify $CTX_FLAG app deployments list "$APP_UUID" --format=json 2>/dev/null \
    | jq -r 'sort_by(.created_at) | last
             | "  Status: \(.status // "unknown")  Deployment ID: \(.deployment_uuid // .uuid // "?")"' \
    2>/dev/null || coolify $CTX_FLAG app deployments list "$APP_UUID"
else
  coolify $CTX_FLAG app deployments list "$APP_UUID"
fi

改法(备选:若坚持用 deploy list)
按 name 部署时改成 select(.application_name==$n)(把解析到的 name 传进去),不要用 uuid;by-uuid 路径无可靠关联字段,直接取全局最新一条并提示"未按 app 过滤"。

验收

  • 在真实实例上 --format=json 跑通,确认 app deployments list 返回数组且含 status / created_at。
  • 部署结束能打印出真实最终状态,而非每次回退 table。

ISSUE #3 — feat(security): 引入 API token 最小权限模型(read/write/deploy/root/read:sensitive)

标签: P0 security docs
影响文件: SKILL.md(First-Time Setup)、references/safety-rules.md、README.md / README.zh-CN.md(Requirements)

问题
skill 面向"别人安装、对着自己的生产 Coolify",但完全没提 token 权限模型——而这才是限制"Agent 跑飞能造成多大破坏"的根本控制。官方(Laravel Sanctum)abilities 为:read / write / deploy / read:sensitive / root;root 绕过所有检查、可开关 API 本身;权限不足返回 403 并附缺失 permission 列表;API 还支持 Allowed IPs;token 为 team-scoped。

改法

  1. 建 token 引导(setup): 按最小权限建议——日常运维 read + deploy;改配置/创建资源才加 write;永不使用 root。
  2. read:sensitive 与脱敏挂钩: 说明不授予 read:sensitive 时,服务端直接脱敏密码/密钥/compose,比"Agent 自觉不打印"更硬;-s/--show-sensitive 仅在 token 具备该 ability 时才有内容。
  3. Allowed IPs: 提示在 Coolify API 设置里限制来源 IP(留空/0.0.0.0 = 全开,生产不推荐)。
  4. team scoping: token 只能看本 team 资源,跨 team 需分别建 token。
  5. safety-rules 的 403 行升级为"读 403 返回体的 missing permissions,直接定位缺哪个 ability"。

验收

  • setup 段含"最小权限 token"建议与各 ability 含义。
  • safety-rules 含 read:sensitive、Allowed IPs、team scoping 三点。

ISSUE #4 — fix(docs): env sync 的 build-time/runtime 语义与"密钥不进 build 层"建议冲突

标签: P0 docs bug
影响文件: references/deploy-patterns.md、references/cli-cheatsheet.md(Env 段)、SKILL.md(D. 环境变量)

问题
cmd/application/env/sync.go 中 --build-time 与 --runtime 注册默认值均为 true,但代码仅在用户显式传入(cmd.Flags().Changed(...))时才下发,否则交服务端默认。两个后果:

  1. Agent 被要求 trust --help,而 --help 显示 --build-time (default: true),会误以为"裸 sync 即全部 build-time",与真实行为(没传则不下发)不符。
  2. deploy-patterns 现写"想让密钥不进 build 层就 sync 时不加 --build-time"——但默认是 true,要真正排除 build 层必须显式 --build-time=false;且 env sync 整个文件共用一套 flag,无法一次区分。还有个未文档化的 --runtime。

改法

  1. deploy-patterns "Next.js" 与 "环境变量分层"两处:把"不加 --build-time"改为"敏感那遍显式 --build-time=false",并明确 sync 是"全文件一套 flag",敏感与非敏感需分两遍同步。
  2. cheatsheet Env 段补 --runtime(默认 true),并加一句显著警告:--help 的 default 显示与"未显式传则不下发"的真实行为不一致,需要某个布尔时请显式 --flag=true|false。
  3. SKILL.md D 段补:涉及密钥的 .env 同步,默认行为可能把变量带入 build 层,需 --build-time=false 显式排除。

验收

  • 文档不再暗示"裸 sync 可把密钥挡在 build 层外"。
  • --runtime 已收录;build-time 显式赋值的注意事项已写明。

ISSUE #05 — fix(docs): database backup create 的 flag 名错误并补齐缺失项

标签: P0 docs bug
影响文件: references/cli-cheatsheet.md(Database/backup 段)、SKILL.md(E. 数据库与备份)

问题
对照 cmd/database/backup/create.go:

  • ❌ --retention-days-local → ✅ --retention-days-locally
  • ❌ --retention-amount-local → ✅ --retention-amount-locally
  • ❌ --databases → ✅ --databases-to-backup
  • --save-s3 / --s3-storage-uuid 确实存在(当前被标 ⚠️ unverified,可去掉标记)
  • 未收录:--dump-all、--retention-max-storage-locally、--retention-amount-s3 / --retention-days-s3 / --retention-max-storage-s3、--timeout、--disable-local-backup

改法

  1. 修正上述错误 flag 名(cheatsheet 与 SKILL E 段示例同步)。
  2. 去掉 --save-s3、--s3-storage-uuid 的 ⚠️。
  3. 补全缺失 flag,给一行最小示例(本地保留 + S3 各一条)。

验收

  • 文档内的 backup flag 与 coolify database backup create --help 完全一致。
  • 不再保留与本命令相关的 ⚠️ unverified 标记。

P1

ISSUE #06 — feat(setup): 用 coolify docs 生成版本精确命令参考喂 Agent(治本 anti-drift)

标签: P1 enhancement
影响文件: 新增 scripts/gen-reference.sh(或并入 scripts/install-cli.sh)、SKILL.md、references/cli-cheatsheet.md

问题
手维护的 cheatsheet 会持续 drift(本轮已发现 #2/#4/#05 多处)。CLI 自带 coolify docs 命令(cmd/docs.go),支持 man / markdown / llms,其中 llms 官方描述即"Generate llms.txt and llms-full.txt for AI agents"。

改法

  1. setup 时跑一次 coolify docs markdown(或 llms)生成当前版本完整参考,落到 skill 目录(如 references/_generated/),让 Agent 以生成内容为准。
  2. SKILL.md 在 Core Principles 增加:flag 真实值以"--help 或生成参考"为准,cheatsheet 仅作高频速查 + jq 配方 + 故障表。
  3. cheatsheet 顶部注明"权威来源为生成参考,本表只是速查"。

验收

  • 提供一键生成参考的脚本/步骤。
  • SKILL 明确"生成参考 > 手写 cheatsheet"的优先级。

ISSUE #07 — docs(cheatsheet): 补齐缺失的命令组

标签: P1 docs
影响文件: references/cli-cheatsheet.md、SKILL.md

问题
以下命令组在 skill 中完全缺失:

  • coolify github(list/repo/branches/create/get/update/delete)—— app create github 依赖其 app-uuid。
  • coolify privatekeys(create/list/delete)
  • coolify {app,database,service} storage(持久卷 create/list/update/delete)—— 有状态服务核心。
  • coolify app previews(预览部署清理)
  • coolify server add / remove / domain(当前只写了 list/get/validate)
  • coolify database env(数据库也有 env;SKILL 现说 env 仅 app/service 有)
  • coolify teams(list/get/current/members)—— 与 token team scoping 相关。

改法
在 cheatsheet 增设对应小节(命令 + 关键 flag + 一行示例);SKILL.md 修正"env 仅 app/service"的说法。

验收

  • 上述命令组在 cheatsheet 均有最小可用条目。

ISSUE #08 — fix(docs): 修正 "never SSH" 绝对化表述,并正确标注 init/firewall 为 [ALPHA] v5

标签: P1 docs
影响文件: SKILL.md(Core Principles #1)、README.md / README.zh-CN.md

问题
SKILL 开头"The CLI is an HTTP API client, not SSH"对日常运维(app/service/database/deploy/env)成立,但 init(WireGuard mesh + Podman 引导)与 firewall(COOLIFY-ALLOW iptables 链、跨主机容器规则)是 [ALPHA]、面向尚未 GA 的 Coolify v5、基于 SSH + root 的命令。

改法

  1. 把该原则改为"日常资源运维经 REST API,与 SSH 无关;少数 v5 实验命令(init/firewall/common sshmesh)走 SSH,属例外"。
  2. 若在文档提及 init/firewall,显著标注 [ALPHA] / Coolify v5 / 需 root,不要当作稳定功能;明确"限制公网 DB 端口源 IP 仍用 ufw/云安全组,与 CLI 的 firewall(管 mesh 容器)不是一回事"。

验收

  • SKILL 不再绝对化"never SSH"。
  • init/firewall 若出现则带 ALPHA/v5 标注,且不与 database-access 的边界防火墙建议混淆。

ISSUE #09 — fix(security): 澄清 token 落盘位置与轮换,纠正"绝不写 token 进文件"

标签: P1 security docs
影响文件: references/safety-rules.md

问题
safety-rules 现写"不把 token 写进任何文件",与 CLI 自身行为矛盾:CLI 合法持久化 token 于 ~/.config/coolify/config.json(文件 0600、目录 0750,见 internal/config/loader.go)。

改法

  1. 改为:token 由 CLI 持久化于 ~/.config/coolify/config.json(0600),这是合法存储;Agent 不应 cat 该文件、不回显其内容、不复制到别处。
  2. 补轮换建议:coolify context set-token <name> <new-token>;并提示该文件具备本地读取风险,主机被入侵时应及时在 Web UI 吊销并轮换。

验收

  • safety-rules 不再出现与 CLI 行为矛盾的"绝不写文件"绝对表述。
  • 含 config.json 位置/权限说明与轮换命令。

ISSUE #10 — fix(docs): 澄清 -f 在 env sync 中是 --file 而非 --force

标签: P1 docs
影响文件: references/safety-rules.md、references/cli-cheatsheet.md

问题
safety-rules 反复强调"绝不加 -f",但 coolify app env sync 用 -f 作为 --file 的 short(cmd/application/env/sync.go:StringP("file","f",...)),与全局 --force 同字母,易致 Agent 连 -f .env 都回避。

改法

  1. safety-rules:把"绝不加 -f"改为"绝不加全局 --force(跳过破坏性确认)";明确 env sync 的 -f 含义为 --file。
  2. cheatsheet:在 Env 段与全局 flag 段各加一句区分。

验收

  • 文档明确两类 -f 的区别,不再误导。

ISSUE #11 — feat(scripts): install 脚本加 brew / go install 回退并填真实版本

标签: P1 enhancement docs
影响文件: scripts/install-cli.sh、README.md / README.zh-CN.md(vX.X.X 占位)

问题
install-cli.sh 仅有 curl … install.sh | bash 一条路径,网络受限时无兜底;README 兼容性写着 vX.X.X 占位。官方另支持 brew install coollabsio/coolify-cli/coolify-cli 与 go install github.com/coollabsio/coolify-cli/coolify@latest。

改法

  1. install-cli.sh:curl 失败时按平台提示/尝试 brew(有 brew 时)或 go install(有 go 时)兜底;失败信息更明确。
  2. README 把 vX.X.X 填为实际验证版本:CLI v1.6.2;Coolify backend 版本由 coolify context version 取得后填入。

验收

  • 安装至少两条可用路径;README 无占位版本号。

ISSUE #12 — docs(cheatsheet): app logs 补充 -f/-n

标签: P1 docs
影响文件: references/cli-cheatsheet.md(App 段)

问题
cmd/application/logs.go 中 app logs 支持 -n/--lines(默认 100)与 -f/--follow,cheatsheet 只写了 coolify app logs <uuid>。

改法
补 coolify app logs <uuid> -f / -n 100;与 deployments logs 的 follow/lines 行为对齐说明(后者另有 --debuglogs)。

验收

  • App 运行时日志条目含 follow/lines 用法。

ISSUE #13 — feat(scripts): 新增 doctor / preflight 脚本

标签: P1 enhancement
影响文件: 新增 scripts/doctor.sh、SKILL.md(Scripts 段)

问题
缺少"装上先自检"的入口,环境问题(CLI 太旧、context 没连、token 权限不足、缺 jq)往往在操作中途才暴露。

改法
新增 doctor.sh,检查:① coolify --version 是否 ≥ 已验证版本;② coolify context verify 连通;③ token ability 是否够用(可用一个只读探测 + 一个需要 deploy 的 dry 探测,捕获 403 的 missing permissions 提示);④ jq 是否安装。SKILL Scripts 段加入"首次/排障先跑 doctor"。

验收

  • doctor 能一屏给出版本/连通/权限/依赖四项结论与下一步提示。

基准版本:coolify-cli v1.6.2。后续 CLI 升级后,优先以 ISSUE #06 生成的参考为准重新核对 flag。

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions