feat: 数据库对外访问文档 + 安全加固 + 仓库工程化

.github/workflows/shellcheck.yml

@@ -0,0 +1,22 @@
+name: shellcheck
+
+on:
+  push:
+    paths:
+      - 'scripts/**.sh'
+      - '.github/workflows/shellcheck.yml'
+  pull_request:
+    paths:
+      - 'scripts/**.sh'
+      - '.github/workflows/shellcheck.yml'
+
+jobs:
+  shellcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run ShellCheck
+        uses: ludeeus/action-shellcheck@master
+        with:
+          severity: warning
+          scandir: ./scripts

.gitignore

@@ -0,0 +1,15 @@
+# macOS
+.DS_Store
+
+# Logs
+*.log
+
+# Env / secrets — 绝不提交真实凭据
+.env
+.env.*
+!.env.example
+
+# Editors
+.vscode/
+.idea/
+*.swp

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hifizz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,9 +1,24 @@
 # coolify-ops
 
+> **兼容性**：Tested against coolify-cli vX.X.X / Coolify vX.X.X（请填入你实测的版本）。CLI 在持续演进，flag 以 `coolify <cmd> --help` 的实际输出为准。
+
 一个让 Claude Code / Codex 通过官方 `coolify` CLI 远程操控自托管 Coolify 实例的 Agent Skill。
 
 针对场景：本地 macOS + 远端 VPS（已装 Coolify），部署/运维 Node、Next.js、Docker 类服务。
 
+## 能力边界（能做 / 不能做）
+
+| ✅ 能做 | ❌ 不能做（需 Web UI） |
+|---|---|
+| 已有应用/服务的部署、重新部署 | **从零创建应用**（绑 Git 仓库、设构建命令）—— CLI 未完整支持 |
+| 运维与排障（看运行时/部署日志、查状态） | **一键服务的创建**（模板服务）—— 需在 Web UI 选模板 |
+| 环境变量同步（`env sync` 批量增改） | |
+| 数据库创建与备份 | |
+| 生命周期管理（start / stop / restart） | |
+| 数据库对外访问决策（内网/隧道/公网加固，见 `references/database-access.md`） | |
+
+惯例：在 Web UI 把"骨架"建好（新 app / 一键服务），CLI 接管后续的配置、部署与运维。
+
 ## 安装
 
 放到 Claude Code 的 skills 目录即可自动加载：
@@ -43,6 +58,7 @@ coolify-ops/
 ├── references/
 │   ├── cli-cheatsheet.md       # 全量命令速查 + jq 配方 + 排障表
 │   ├── deploy-patterns.md      # Node/Next/Docker/静态站部署模板 + env 分层 + magic vars
+│   ├── database-access.md      # 数据库对外访问：协议认知 + 内网/隧道/公网加固 + 域名连库
 │   └── safety-rules.md         # 危险操作红线与确认清单
 └── scripts/
     ├── install-cli.sh          # 跨平台安装 CLI

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coolify-ops
-description: 通过官方 coolify CLI 远程操控 Coolify 实例，完成应用/服务/数据库的部署、运维、排障。Use this skill whenever the user wants to deploy, restart, redeploy, check logs, sync environment variables, manage databases, or troubleshoot any resource on a Coolify instance — including phrases like "部署到 Coolify"、"重启那个服务"、"看下部署日志"、"同步环境变量到线上"、"Coolify 上那个 app 挂了"，or when they mention a Coolify app/service/database UUID and want an operation performed. Also trigger when the user wants to set up the coolify CLI for the first time or add a new Coolify context.
+description: 通过官方 coolify CLI 远程操控 Coolify 实例，完成应用/服务/数据库的部署、运维、排障。Use this skill whenever the user wants to deploy, restart, redeploy, roll back, check logs or deployment status, scale or adjust resources, bind a domain, add/change/sync environment variables, create or back up databases, expose a database port, or troubleshoot any resource on a Coolify instance — including phrases like "部署到 Coolify"、"重启那个服务"、"看下部署日志"、"查部署状态"、"同步环境变量到线上"、"加个环境变量"、"给它绑个域名"、"扩容/调一下资源"、"备份数据库"、"回滚到上一个版本"、"把数据库端口暴露出去"、"Coolify 上那个 app 挂了"，or when they mention a Coolify app/service/database UUID and want an operation performed. Also trigger when the user wants to set up the coolify CLI for the first time or add a new Coolify context.
 ---
 
 # Coolify Ops
@@ -106,6 +106,8 @@ coolify database backup trigger <db-uuid> <backup-uuid>   # 立即备份
 支持类型：postgresql / mysql / mariadb / mongodb / redis / keydb / clickhouse / dragonfly。
 **删库前**务必走安全规则里的检查清单。
 
+**对外访问分支**：当请求涉及"让数据库对外 / 被其他机器 / 被 Vercel 访问"，或"用域名连库""暴露数据库端口"时，**先读 `references/database-access.md`**，按其推荐顺序（**内网 > 隧道 > 公网加固**）与用户确认，**不要直接 `--is-public`**。要点：数据库说 TCP 协议、不走 HTTP（`https://db.example.com` 连不上）；连库方与库同机走内网、在能常驻进程的外部机器走隧道、**Vercel 等 serverless 走 HTTP 层（裸 TCP 隧道对它走不通）**；确需公网先走 `safety-rules.md` 的 `--is-public` 标准流程并提醒默认无 TLS。
+
 ## 已知能力边界
 
 - **从零创建应用**（绑 Git 仓库、设构建命令）目前 CLI 支持不完整：`app update` 能改字段，但完整的 `app create` 尚未公开。第一次创建新应用通常仍需在 Web UI 完成，CLI 接管后续运维。遇到"创建新 app"请求时，明确告诉用户这一限制，引导他在 UI 建好骨架后再用 CLI 配置和部署。
@@ -116,6 +118,7 @@ coolify database backup trigger <db-uuid> <backup-uuid>   # 立即备份
 - `references/cli-cheatsheet.md` — 全量命令速查 + 排障表 + 输出格式与全局 flag。需要查具体命令语法时读它。
 - `references/deploy-patterns.md` — Node / Next.js / Docker / 静态站四类项目的部署配置模板、env 分层惯例、Coolify magic variables（SERVICE_URL_* / SERVICE_PASSWORD_*）。部署或排构建问题时读它。
 - `references/safety-rules.md` — 危险操作红线与确认清单。执行任何 delete/stop/强制操作前读它。
+- `references/database-access.md` — 如何从外部访问 Coolify 上的数据库：协议认知、内网/隧道/公网加固四级方案、用域名连库（Cloudflare 灰云）、TLS 警告。涉及"让数据库对外访问/暴露端口/用域名连库"时读它。
 
 ## 脚本
 

references/cli-cheatsheet.md

@@ -88,6 +88,8 @@ coolify deploy get <deployment-uuid>      # 单个部署详情
 coolify deploy cancel <deployment-uuid>   # 取消进行中的部署
 ```
 
+> ⚠️ **`deploy list --format=json` 的字段名未实测**：`deploy-and-watch.sh` 按 `application_uuid` / `resource_uuid` / `deployment_uuid` / `status` 过滤来定位最近一次部署，但这些字段名是基于通用约定推断的。首次使用请先跑 `coolify deploy list --format=json` 看真实结构，再决定按哪个字段过滤。
+
 ## 环境变量 Env
 
 > app 和 service 的 env 子命令完全一致，下面以 app 为例。
@@ -127,12 +129,14 @@ coolify database delete <uuid>   # 危险，需确认
 coolify database backup list <db-uuid>
 coolify database backup create <db-uuid> \
   --frequency "0 2 * * *" --enabled \
-  [--save-s3 --s3-storage-uuid <uuid>] \
-  [--retention-days-local 7] [--retention-amount-local 5]
+  [--save-s3 --s3-storage-uuid <uuid>] \           # ⚠️ 未实测，以 --help 为准
+  [--retention-days-local 7] [--retention-amount-local 5]   # --retention-amount-local ⚠️ 未实测，以 --help 为准
 coolify database backup trigger <db-uuid> <backup-uuid>       # 立即备份
 coolify database backup executions <db-uuid> <backup-uuid>    # 备份执行记录
 ```
 
+> ⚠️ **以下 backup flag 未在真实 CLI 上验证**，是基于通用约定推断的：`--save-s3`、`--s3-storage-uuid`、`--retention-amount-local`。使用前先 `coolify database backup create --help` 核对真实 flag 名与语义；`--retention-days-local` 同样以 --help 为准。
+
 cron 速记：`"0 2 * * *"` = 每天 02:00；`"0 */6 * * *"` = 每 6 小时。
 
 ## 服务 Service
@@ -187,7 +191,7 @@ coolify resources list --format=json | jq -r '.[] | select(.status!="running") |
 | `connection refused` / 超时 | URL 错；VPS 防火墙没放行；Coolify 没起来 | 先 `curl -I <url>` 测 Web 入口；检查 VPS 防火墙端口 |
 | `401 Unauthorized` | Token 错或被删 | Web UI 重新生成 token，`coolify context set-token` 更新 |
 | `403 Forbidden` | Token 权限不足 | 检查该 token 在 Coolify 里的权限范围 |
-| `certificate verify failed` | HTTPS 证书没配好 | 临时用 http://，或先在 Coolify 配好 TLS |
+| `certificate verify failed` | HTTPS 证书没配好 | **优先**在 Coolify 配好 TLS 再连。⚠️ 降级到 `http://` 会让 Bearer Token 明文上链路，仅限可信内网/临时排查，且事后应轮换 token |
 | 命令找不到资源 | UUID 过期/记错 | 重新 `<resource> list --format=json` 拿 UUID |
 | 不确定 flag | CLI 版本差异 | `coolify <cmd> --help` 看当前版本实际 flag |
 | 想看请求细节 | — | 任意命令前加 `--debug` |