chore: init company-deploy-skills with dokploy-gitea-deploy

2026-07-31 09:47:16 +08:00
commit 7b56a16fbc
7 changed files with 1125 additions and 0 deletions
--- a/dokploy-gitea-deploy/references/mcp-deploy.md
+++ b/dokploy-gitea-deploy/references/mcp-deploy.md
@@ -0,0 +1,301 @@
+# company-deploy-mcp 默认部署路径
+
+**连接中心（飞书登录 + 拿 Key）：**  
+`https://company-deploy-mcp.loncode.site/`
+
+**MCP endpoint：**  
+`https://company-deploy-mcp.loncode.site/mcp`
+
+Agent 配置示例（用户从连接中心复制，**不要**写进业务仓库）：
+
+```json
+{
+  "mcpServers": {
+    "company-deploy": {
+      "url": "https://company-deploy-mcp.loncode.site/mcp",
+      "headers": {
+        "Authorization": "Bearer buxi_..."
+      }
+    }
+  }
+}
+```
+
+- Key 前缀：`buxi_`（旧 `cdp_` 若仍存在可兼容，新发一律 `buxi_`）  
+- 身份：飞书 `open_id` 绑定到 Key；管理员另见 `ADMIN_OPEN_IDS` / 平台 `MCP_AUTH_TOKEN`  
+- **禁止**在 MCP 可用时向业务用户索要 Dokploy / Gitea Token
+
+---
+
+## 工具一览
+
+| 工具 | 读写 | 作用 |
+|------|------|------|
+| `whoami` | 读 | 当前身份、`role`（user/admin）、`openId` |
+| `get_my_quota` | 读 | 运行中项目数 / 上限 / 剩余 |
+| `list_projects` | 读 | 用户仅自己的；admin 全部 + Dokploy 运行态 |
+| `inspect_project` | 读 | 某 repo+env 映射与策略（含存储策略说明） |
+| `ensure_repository` | 写 | Gitea 建库（缺省组织私有库） |
+| `create_deployment_plan` | 写 | 针对**已 push** 的 commit SHA 建计划 |
+| `apply_deployment_plan` | 写 | 挂卷 → PG/MySQL → 域名/HTTPS → deploy |
+| `get_deployment_status` | 读 | 应用与部署摘要（脱敏） |
+| `get_sanitized_logs` | 读 | 脱敏诊断摘要 |
+
+`repo` 格式：
+
+- `Owner/name` 完整路径  
+- 或仅 `name` → 控制面补默认 `GITEA_ORG`
+
+---
+
+## 标准调用顺序（必须）
+
+```text
+0. whoami / get_my_quota          # 可选但推荐；配额满先处理
+1. 本地：Dockerfile + 数据写 /data + .gitignore
+2. ensure_repository({ repo })
+3. git remote add/set-url + commit + push   # Agent 本机企业凭据
+4. create_deployment_plan({ repo, commitSha, branch, environment, spec })
+5. apply_deployment_plan({ planId })
+6. get_deployment_status / list_projects 轮询
+7. curl 探活 apply 返回的 url（证书可能短暂签发中）
+```
+
+**Push 必须在 Agent 侧做**：MCP 在服务器上读不到用户工作区未提交文件。
+
+---
+
+## create_deployment_plan 参数
+
+| 字段 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `repo` | string | 必填 | 见上 |
+| `commitSha` | string | 必填 | 7–64 位 hex，**已在 Gitea 上** |
+| `branch` | string | `main` | 分支名 |
+| `environment` | string | 控制面 `DEFAULT_DEPLOY_ENVIRONMENT`（常为 `default`） | **部署标签**（非 Dokploy preview/production）；与 repo 组成唯一映射。查状态/重部署必须与首次 apply 相同 |
+| `spec` | object | 必填 | 见下 |
+
+### `spec` 字段
+
+| 字段 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `buildType` | `"dockerfile"` | 必填 | MVP 仅 Dockerfile |
+| `dockerfilePath` | string | `Dockerfile` | 路径须以 `Dockerfile` 结尾 |
+| `buildPath` | string | `/` | 构建上下文 |
+| `port` | number | 必填 | **容器内**监听端口（Traefik 转到这里） |
+| `healthcheckPath` | string | `/` | 以 `/` 开头 |
+| `persistence` | array | `[]` | 多卷；**缺 `/data` 时控制面自动补** |
+| `databases` | array | `[]` | 托管 PG/MySQL，可选 |
+| `exposeWeb` | boolean | `true` | `false` 则不绑公网域名（Worker 等） |
+| `domainHost` | string | 省略 | 可选固定 host；省略则 `buxi`+5 随机 |
+
+### `persistence[]` 项
+
+```json
+{
+  "name": "data",
+  "mountPath": "/data",
+  "hostPath": "/optional/host/path"
+}
+```
+
+- `name`：逻辑名（命名 volume / 主机子目录用）  
+- `mountPath`：容器内绝对路径  
+- `hostPath`：可选；bind 模式下省略则控制面生成  
+  `{HOST_DATA_ROOT}/{appSlug}/{name}`  
+
+**应用约定：** 有状态数据必须写在挂载路径（如 SQLite → `/data/app.db`）。  
+重部署同 `repo`+`environment` **不重新占配额**，卷与域名复用。
+
+### `databases[]` 项
+
+```json
+{
+  "engine": "postgres",
+  "name": "main",
+  "databaseName": "app",
+  "databaseUser": "app",
+  "envVar": "DATABASE_URL"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `engine` | `postgres` 或 `mysql` |
+| `name` | 逻辑名（多库区分）；默认 `main` |
+| `databaseName` / `databaseUser` | 可选覆盖 |
+| `envVar` | 注入应用的环境变量名，默认 `DATABASE_URL` |
+
+`apply` 时：Dokploy 建库服务 → deploy 库 → 把连接串写入应用 env → 再构建应用。  
+**勿**在聊天中打印完整 `connectionUrl`（返回侧会尽量脱敏）。
+
+---
+
+## 最小示例：纯 Web（自动域名 + 默认 /data）
+
+```json
+{
+  "repo": "my-web-app",
+  "commitSha": "a1b2c3d4e5f6...",
+  "branch": "main",
+  "environment": "default",
+  "spec": {
+    "buildType": "dockerfile",
+    "dockerfilePath": "Dockerfile",
+    "buildPath": "/",
+    "port": 3000,
+    "healthcheckPath": "/",
+    "exposeWeb": true
+  }
+}
+```
+
+`apply` 成功后典型字段：
+
+```json
+{
+  "planId": "...",
+  "applicationId": "...",
+  "isNewProject": true,
+  "url": "https://buxi3k9xa.loncode.site",
+  "domain": {
+    "host": "buxi3k9xa.loncode.site",
+    "url": "https://buxi3k9xa.loncode.site",
+    "https": true
+  },
+  "mounts": [{ "name": "data", "mountPath": "/data" }],
+  "databases": [],
+  "dataPathHint": {
+    "container": "/data",
+    "note": "Write application state under mounted paths..."
+  }
+}
+```
+
+对用户只说：**已发布，访问 `https://buxi….loncode.site/`**（以实际返回为准）。
+
+---
+
+## 示例：多卷 + Postgres
+
+**部署标签必须用默认 `default`（或省略），除非用户明确要求并行第二套环境。**  
+禁止因「上线/生产」等话术擅自改成 `production`（与 Dokploy 的 production 环境无关，且会导致查不到项目）。
+
+```json
+{
+  "repo": "Buxi/order-api",
+  "commitSha": "deadbeefcafebabe...",
+  "branch": "main",
+  "environment": "default",
+  "spec": {
+    "buildType": "dockerfile",
+    "dockerfilePath": "Dockerfile",
+    "buildPath": "/",
+    "port": 8080,
+    "healthcheckPath": "/healthz",
+    "exposeWeb": true,
+    "persistence": [
+      { "name": "data", "mountPath": "/data" },
+      { "name": "uploads", "mountPath": "/var/uploads" }
+    ],
+    "databases": [
+      {
+        "engine": "postgres",
+        "name": "main",
+        "envVar": "DATABASE_URL"
+      }
+    ]
+  }
+}
+```
+
+应用启动时读 `process.env.DATABASE_URL`（或所选 `envVar`）。  
+若还要 MySQL 第二实例，再 push 一条 `{ "engine": "mysql", "name": "legacy", "envVar": "MYSQL_URL" }`。
+
+---
+
+## 示例：Worker（不暴露 Web）
+
+```json
+{
+  "repo": "job-worker",
+  "commitSha": "...",
+  "branch": "main",
+  "environment": "default",
+  "spec": {
+    "buildType": "dockerfile",
+    "dockerfilePath": "Dockerfile",
+    "buildPath": "/",
+    "port": 8080,
+    "healthcheckPath": "/healthz",
+    "exposeWeb": false
+  }
+}
+```
+
+`url` / `domain` 可能为 null；用 `get_deployment_status` 看 Dokploy 运行态即可。
+
+---
+
+## apply 内部顺序（Agent 勿重复）
+
+控制面在 `apply_deployment_plan` 内按序完成：
+
+1. **配额**：仅**新建** mapping 时检查运行中数量  
+2. **ensure Application**（已有则复用）  
+3. **ensureMounts**：默认 `/data`（Docker volume，无需预建宿主机目录）+ `persistence[]`  
+4. **ensureDatabases**：postgres/mysql + 注入 env  
+5. **ensureDomain**：`buxi`+5 随机 + Let’s Encrypt（见 `domain.md`）  
+6. **deploy** 应用镜像  
+
+Agent **不要**再直连 Dokploy 做 `domain.create` / `mounts.create` / 手建 DB（会双绑冲突）。
+
+---
+
+## 配额与归属
+
+| 概念 | 行为 |
+|------|------|
+| 归属 | 首次成功 `apply` 的 `owner_open_id` |
+| 配额 | 该用户 **Dokploy 运行中** 应用数 ≤ `MAX_RUNNING_PROJECTS_PER_USER`（常见 5） |
+| 重部署 | 同 repo+env **不占新名额** |
+| 可见性 | 普通用户只能 list/status 自己的；admin 看全部 |
+
+配额满错误：引导用户停掉旧应用或找管理员，**不要**绕过 MCP 硬推。
+
+---
+
+## 轮询建议
+
+```text
+apply 返回后：
+  每 15–30s：get_deployment_status(repo, environment)
+  或 list_projects 看 applicationStatus / running / url
+  终态：构建成功且容器 running/done
+  Web：curl -skI "$url" 或健康路径
+  证书：首次 LE 可能需 1–3 分钟；DNS/80 未通会失败
+```
+
+`create` 的 plan **只能 apply 一次**；失败或新版本 → 新 SHA 再 `create_deployment_plan`。
+
+---
+
+## 对用户话术（摘要）
+
+| 场景 | 说法 |
+|------|------|
+| 成功 | 已发布当前版本；访问：`https://…` |
+| 有数据库 | 已配置托管数据库连接（不打印密码） |
+| 配额满 | 运行中项目已达上限，请先停用不用的服务 |
+| 未登录 | 打开连接中心飞书登录，把配置贴到 Agent |
+| 构建中 | 正在构建，稍后自动检查 |
+| 证书中 | 链接已分配，HTTPS 证书签发中，稍后再开 |
+
+---
+
+## 安全
+
+1. 永不 commit / 回显：`buxi_`、平台 Token、DB 密码全文  
+2. 日志只用 `get_sanitized_logs`  
+3. `.env` / 密钥进 `.gitignore`  
+4. 生产破坏操作受控制面策略约束；不要教用户绕过