Buxi/company-deploy-skills
2
0
Fork 0
Code Pull Requests Actions Packages Projects Releases Activity

docs(skill): rewrite deploy playbook — MCP first, never Dokploy UI

Browse Source
This commit is contained in:
Lon
2026-08-02 17:03:08 +08:00
parent 321d2e6165
commit 913588a369
2 changed files with 320 additions and 233 deletions
Download Patch File Download Diff File Expand all files Collapse all files

517
dokploy-gitea-deploy/SKILL.md
View File

@@ -1,91 +1,102 @@
--- ---
name: dokploy-gitea-deploy name: dokploy-gitea-deploy
description: > description: >
企业项目部署：默认走 company-deploy-mcp（飞书身份 + buxi_ Key → 推 Gitea → MCP 建库/多卷/PG·MySQL/域名/HTTPS → 轮询）。 企业 Dockerfile 项目部署（唯一默认路径：company-deploy-mcp）。
旧路径为直连 Dokploy API（.env.deploy），仅运维/无 MCP 时使用。触发词：部署、上线、Dokploy、Gitea、 飞书登录拿 buxi_ Key → 配置 MCP → whoami 联通 → ensure_repository + pushUrl 推代码
redeploy、MCP 部署、buxi_、company-deploy-mcp。Use when /dokploy-gitea-deploy。 → create/apply plan → 轮询 → 交付 HTTPS 链接。用户永不进 Dokploy/Gitea。
触发：部署、上线、重部署、redeploy、查项目、配额、buxi_、company-deploy、企业部署。
禁止引导用户打开 Dokploy 面板或索要 DOKPLOY_API_KEY。Use when /dokploy-gitea-deploy。
metadata: metadata:
short-description: "企业部署：优先 MCP，兼容 Dokploy 直连" short-description: "企业部署：MCP 全流程（用户不进 Dokploy）"
--- ---
# 安装（给用户 / Agent） # 企业部署 Skill（company-deploy-mcp）
## 0. 一句话
**用户只做两件事：① 连接中心飞书登录拿 `buxi_` Key 配到 Agent；② 说「部署」。**
其余（建库、推代码凭据、挂卷、数据库、域名、HTTPS、构建）全部由 **Agent + MCP** 完成。
| 正确 | 错误（禁止） |
|------|----------------|
| 调 MCP 工具部署 | 让用户打开 Dokploy 管理面板 |
| 401 → 引导连接中心重拿 Key | 说「权限配置无法通过，去找管理员要 Dokploy 权限」 |
| 交付 `https://buxi….loncode.site` | 索要 `DOKPLOY_API_KEY` / Gitea Token / 面板账号 |
| 环境变量靠 plan（`databases[]` 等）或代码默认 | 让用户去 Dokploy 改某个应用的 env |
**连接中心** `https://company-deploy-mcp.loncode.site/` = 飞书身份 + MCP 授权，**不是** Dokploy 面板。
**Dokploy** 只被控制面服务端调用，**业务用户与业务 Agent 默认不可见、不需要、不引导**。
---
## 1. 安装本 Skill（一次性）
```bash ```bash
# 内网一键（推荐）
curl -fsSL https://company-deploy-mcp.loncode.site/install-skill.sh | bash curl -fsSL https://company-deploy-mcp.loncode.site/install-skill.sh | bash
# 或
# 或 skills CLI
npx skills add http://git.loncode.site/Buxi/company-deploy-skills.git --skill dokploy-gitea-deploy -g -y npx skills add http://git.loncode.site/Buxi/company-deploy-skills.git --skill dokploy-gitea-deploy -g -y
``` ```
技能仓：http://git.loncode.site/Buxi/company-deploy-skills Skill 只定义流程；**没有配置 MCP + `buxi_` Key 则无法部署**。
连接中心（飞书 + MCP Key）：https://company-deploy-mcp.loncode.site/
Skill 只提供流程；真正部署还需配置 MCP `company-deploy`（`buxi_` Bearer）。
--- ---
# 企业部署编排（Gitea + Dokploy + company-deploy-mcp） ## 2. 联通性检测（每次部署前必做）
业务同学不碰平台细节。Agent 负责：可构建工程 → 推代码 → 调控制面 → 交付 **HTTPS 链接**。 按顺序，**先测再部署**。任一步失败：按 §6 处理，**禁止**改口去要 Dokploy。
**默认路径：company-deploy-mcp（必须优先）。** ### 2.1 MCP 是否挂上
直连 Dokploy API 为 **legacy / 运维例外**。
**产品范围（收口）：** 主路径是 **普通 Dockerfile 服务**（Python / Node / 静态站等）。 Agent 能否调用 `company-deploy` 的工具（至少 `whoami`）。
飞书 **妙搭 / `@lark-apaas/*` 模板不是主路径**——不承诺登录、权限、平台 API 与线上一致；控制面仅可能注入 **进程启动** 所需最小 env。详见 `references/stack-profiles.md` 支持矩阵。
参考： | 结果 | 含义 | 下一步 |
|------|------|--------|
| 工具列表里有 `whoami` / `apply_deployment_plan` | 已配置 MCP | → 2.2 |
| 没有这些工具 / 调用直接失败 | 未配置或 Key 错误 | → §3 鉴权 |
- `references/mcp-deploy.md` — **MCP 默认状态机**（工具参数、域名/卷/库） ### 2.2 身份
- `references/domain.md` — 域名与 HTTPS（Let’s Encrypt，无需通配符证书）
- `references/sequence.md` — 时序
- `references/env-deploy.example` — 仅 legacy 直连用
- `references/stack-profiles.md` — Dockerfile 约定 + **支持矩阵**
线上连接中心：`https://company-deploy-mcp.loncode.site/`
MCP endpoint：`https://company-deploy-mcp.loncode.site/mcp`
---
## 路径选择
| 条件 | 路径 |
|------|------|
| Agent 已配置 MCP `company-deploy`（`buxi_` Key） | **MCP 默认** |
| 用户已飞书登录拿过 Key | **MCP 默认** |
| 用户明确「不要 MCP / 运维直连 / 改 Dokploy 底层」 | legacy |
| 无 MCP 且无 `.env.deploy` | **先引导连 MCP**，不要伪造部署 |
**禁止**在可用 MCP 时仍让业务填写 `DOKPLOY_API_KEY` / Gitea Token。
---
## 架构（默认）
```text ```text
用户：「部署 / 上线」 whoami
→ Agent：Dockerfile + 本地验证
→ Agent：ensure_repository（MCP）→ 拿到 agentHint.pushUrl（机器人 Token）
→ Agent：git push <pushUrl>（禁止用用户 SSH；禁止向用户要密钥）
→ Agent：create_deployment_plan + apply_deployment_plan
MCP 内部：挂卷 → PG/MySQL（可选）→ domain（buxi+5位.根域 + LE HTTPS）→ deploy
→ Agent：get_deployment_status / list_projects 轮询
→ 交付：https://buxi*****.loncode.site + 脱敏说明
``` ```
- **飞书**：身份；**buxi_ Key**：调用 MCP 期望字段示例：`role`（`user`|`admin`）、`openId`、`name`、`isAdmin`。
- **Gitea**：源码（**gitea-robot** 建仓+推送；业务用户**不需要** Gitea 账号或 `~/.ssh`）
- **Dokploy**：构建运行（由 MCP 调用，不直暴露给业务） | 结果 | 处理 |
- **归属 / 配额 / 审计**：控制面 SQLite（`owner_open_id`、运行中数量） |------|------|
| 返回身份 JSON | 联通成功 |
| 401 / Unauthorized / invalid token | Key 无效 → §3 |
| 超时 / 连接失败 | 网络或控制面宕机 → 告之稍后重试，可 `curl -sS https://company-deploy-mcp.loncode.site/health` |
### 2.3 配额
```text
get_my_quota
```
看运行中项目数是否达上限。满了：先 `list_projects`，让用户停/删不用的，**不要**绕过 MCP。
### 2.4（可选）已有项目
```text
list_projects
```
重部署时记下已有 `repo` + `environment`（部署标签，默认多为 `default`），**必须沿用**，禁止擅自改成 `production`。
--- ---
## 前置条件 ## 3. 鉴权与获取授权
### MCP 路径（默认） ### 3.1 用户怎么拿 Key（业务同学）
1. 用户已在连接中心飞书登录，Agent 已配置： 1. 浏览器打开：**https://company-deploy-mcp.loncode.site/**
2. **飞书登录**
3. 复制页面上的 **`buxi_…` Key** 与 MCP 配置片段
4. 粘贴到 Agent 的 MCP 配置（见下）
5. 回到对话说「已配置」或直接「部署」
### 3.2 Agent / 客户端怎么配
```json ```json
{ {
@@ -93,240 +104,286 @@ MCP endpoint：`https://company-deploy-mcp.loncode.site/mcp`
"company-deploy": { "company-deploy": {
"url": "https://company-deploy-mcp.loncode.site/mcp", "url": "https://company-deploy-mcp.loncode.site/mcp",
"headers": { "headers": {
"Authorization": "Bearer buxi_..." "Authorization": "Bearer buxi_用户从连接中心复制的Key"
} }
} }
} }
} }
``` ```
2. 项目有可构建 **Dockerfile**（进程监听 `spec.port`，状态写 `/data` 等挂载点） - 前缀：`buxi_`（旧 `cdp_` 可能仍可用，新发一律 `buxi_`）
3. 本机有 `git` 即可；**推送凭据来自 `ensure_repository` 的 `agentHint.pushUrl`**，**不要**配置用户 SSH、**不要**加 `id_ed25519.pub` 到 Gitea - **禁止**把 Key 写进业务 Git 仓库
4. 企业侧已配：`*.DOMAIN_ROOT` DNS → Dokploy；80/443 可达（Let’s Encrypt） - **禁止**把 Key 完整打印在对用户的回复里（可确认「已配置」）
无 Key：引导打开连接中心登录，**不要**继续直连 Dokploy。 ### 3.3 权限模型（Agent 必须理解）
### Legacy 路径（运维） | 能力 | 谁有 | 说明 |
|------|------|------|
| 部署自己的项目 | 任意有效 `buxi_` | 首次 `apply` 建立归属 |
| 看自己的项目列表/状态 | 自己 | `list_projects` / `get_deployment_status` |
| 看别人的项目 | 仅 admin | `ADMIN_OPEN_IDS` 或平台 `MCP_AUTH_TOKEN` |
| 进 Dokploy 面板 | **不在本产品路径** | **禁止**当作用户解决办法 |
| 手改 Gitea 权限 / SSH | **不需要** | 推送只用 `ensure_repository` 的 `pushUrl` |
见文末；需 `.env.deploy` + `DEPLOY_AUTHORIZED=true`。 ### 3.4 鉴权失败怎么说（固定话术）
**401 / 未配置 MCP：**
> 还不能部署：需要先完成企业部署授权。
> 1. 打开 https://company-deploy-mcp.loncode.site/
> 2. 飞书登录，复制 `buxi_` Key
> 3. 按页面说明粘贴到当前 Agent 的 MCP 配置
> 4. 配置好后回复「已配置」，我再继续部署。
> （连接中心只负责身份和 MCP，不需要 Dokploy 账号。）
**403 看别人的项目：**
> 当前账号只能管理自己名下的项目。如需管理员视角，请联系平台管理员把你的飞书 open_id 加入白名单。
**禁止话术（截图类错误）：**
- ❌「你不能通过项目网页进入 Dokploy」
- ❌「向管理员索取 Dokploy 面板地址 / 登录账号 / 某应用环境变量编辑权限」
- ❌「企业部署连接中心不是 Dokploy，所以你没法配 env——去找管理员开 Dokploy」
- ❌ 凭空编造 Dokploy URL
若用户要的是 **业务应用自定义密钥**（如第三方 API Key），而 plan 又注入不了：
> 当前 MCP 会自动注入数据库连接（`databases[]`）和运行所需基础变量；
> **不提供**业务同学自助打开 Dokploy 改 env。
> 可选：① 非密钥配置进代码/配置文件；② 密钥由平台管理员走运维通道注入（不经过业务 Dokploy 账号）；③ 应用支持启动后自助配置页。
> **我不会让你去申请 Dokploy 面板权限。**
--- ---
## MCP 标准状态机（必须按序） ## 4. 部署操作流程（默认全链路）
细节与 JSON 示例见 `references/mcp-deploy.md`。 **前提：** §2 联通、§3 有有效 Key。工程为 **普通 Dockerfile** 服务（Python/Node/静态站等）。
妙搭/`@lark-apaas`：非主路径，见 `references/stack-profiles.md`；勿承诺与妙搭线上一致。
### 0. 身份
- 调用 `whoami`（可选）：确认 `role` / `openId`
- 调用 `get_my_quota`：看运行中数量是否达上限
### 1. 工程
- 识别栈；保证 Dockerfile；`.gitignore` 排除密钥
- 有状态：默认 `/data`；多目录用 `persistence[]`
- 需要库：`databases: [{ engine: "postgres"|"mysql", ... }]`
- **若依赖 `@lark-apaas/*` / 妙搭模板：**
- **先告知用户**：本平台不保证页面+接口可用；推荐 `lark-apps` 云端或业务去平台化
- **禁止**主动承诺「自托管后与妙搭一致」
- **禁止**在 skill 流程里大改登录/伪造网关/补 SPA 模板（那是业务仓责任，且非本 skill 范围）
- 用户书面坚持后，仅按普通 Dockerfile 部署，交付时标注 **实验性**
- **Node 多阶段硬规则**（详见 `stack-profiles.md`）：
- 禁止在 `npm ci`/`pnpm install` **之前** `ENV NODE_ENV=production`（否则 `nest`/`vite` not found）
- 大前端 Vite：`NODE_OPTIONS=--max-old-space-size=3072`
- runtime 用 `COPY --from=build` 串行，避免并行双 `npm ci` 把小机打爆
### 2. 仓库与推送（权限红线）
```text ```text
ensure_repository({ repo: "owner/name" 或 "name" }) ┌─────────────────────────────────────────────────────────────┐
→ 使用返回的 agentHint.pushUrl（含企业机器人 Token） │ A. 工程准备（本地） │
→ git add / commit │ B. ensure_repository → pushUrl 推送（Agent，禁止用户 SSH） │
→ git push --set-upstream "<pushUrl>" HEAD:<defaultBranch> │ C. create_deployment_plan │
→ 记录 commitSha │ D. apply_deployment_plan ← 卷/库/域名/构建全在这里 │
│ E. 轮询 get_deployment_status / list_projects │
│ F. 探活 URL → 按 §5 回复用户 │
└─────────────────────────────────────────────────────────────┘
``` ```
**硬规则：** 细节参数见 `references/mcp-deploy.md`；时序见 `references/sequence.md`。
1. **禁止**要求用户上传/配置 `~/.ssh/id_ed25519.pub` 或任何个人 SSH Key。 ### 4.1 工程准备（Agent）
2. **禁止**让用户自己去 Gitea 开权限、建仓、加 Collaborator。
3. **禁止**用未认证的 `cloneUrl` 去 `git push`（会 403 / Permission denied）。
4. **必须**用 `agentHint.pushUrl` 做一次推送；**不要**把 `pushUrl` 全文贴进对用户的回复。
5. 若仍 403：重新 `ensure_repository` 取新 hint，检查本机网络能否访问 `git.loncode.site`——**不要**改去配用户 SSH。
### 3. 计划与发布 - [ ] 有 `Dockerfile`，进程监听 **`0.0.0.0` + 容器端口**（与 plan `spec.port` 一致）
- [ ] 有状态写 **`/data`**（或 `persistence[]` 声明的路径）
- [ ] `.gitignore` 排除 `.env`、密钥、本地 db
- [ ] 需要 PG/MySQL → plan 里 `databases: [{ "engine": "postgres", "envVar": "DATABASE_URL" }]`
- [ ] Node 大前端：见 `stack-profiles.md`（禁止 install 前 `NODE_ENV=production`；堆内存；串行 multi-stage）
### 4.2 仓库与推送
```text
ensure_repository({ repo: "项目名" 或 "Buxi/项目名" })
→ 使用返回的 agentHint.pushUrl（内含企业机器人 Token）
→ git add / commit
→ git push --set-upstream "<pushUrl>" HEAD:<defaultBranch>
→ 记录 commitSha（git rev-parse HEAD）
```
| 硬规则 | |
|--------|--|
| 必须用 `pushUrl` 推 | 不要用无 Token 的 `origin` |
| 禁止要用户配 SSH / 加公钥到 Gitea | 失败则重取 `ensure_repository`，查网络 |
| 禁止把 `pushUrl` 全文贴给用户 | |
### 4.3 建计划
```text ```text
create_deployment_plan({ create_deployment_plan({
repo, commitSha, branch, repo,
# environment = 控制面「部署标签」，默认 default。禁止擅自 invent production/staging commitSha, # 已在 Gitea 上
# 除非用户明确说「再部署一套并行环境」。与 status/redeploy 必须同一标签；不确定 list_projects branch: "main",
environment: "default", environment: "default", # 除非用户明确要第二套并行环境
spec: { spec: {
buildType: "dockerfile", buildType: "dockerfile",
dockerfilePath: "Dockerfile", dockerfilePath: "Dockerfile",
buildPath: "/", buildPath: "/",
port: <容器端口>, port: <容器端口>,
healthcheckPath: "/", healthcheckPath: "/",
persistence: [ /* 可选多卷；缺省自动加 /data */ ],
databases: [ /* 可选 postgres|mysql */ ],
exposeWeb: true exposeWeb: true
# persistence / databases 按需
} }
}) })
→ apply_deployment_plan({ planId }) → 记下 planId
→ 使用返回的 url / domain / databases（密码已脱敏）
``` ```
**环境概念（易混）：** **部署标签 `environment`：** 控制面 mapping 键，**不是** Dokploy 的 preview/production 分组。
默认 **`default`**。禁止因用户说「上线/生产」就改成 `production`。
| 名称 | 是什么 | 谁决定 | ### 4.4 发布
|------|--------|--------|
| Dokploy Environment | 应用建在平台哪个分组（如 preview） | 控制面 `DOKPLOY_ENVIRONMENT_ID`（全站统一） |
| MCP `environment` | 部署标签，`repo+标签` 对应一套应用/域名 | Agent 参数，默认 `default`，全公司应统一 |
已有项目若当初用了非 default 标签，重部署/查状态必须继续传该标签，不要擅自改（否则会当成新项目）。
### 部署标签硬规则（Agent）
1. **默认且优先**：省略 `environment` 或显式 `"default"`。
2. **禁止**仅因用户说「上线 / 生产 / 正式」就改成 `production`——那只是业务话术，不是部署标签。
3. **仅当**用户明确要求「第二套环境 / staging / 并行预发」时，才用非 default 标签。
4. 重部署前 `list_projects`，沿用已有 `environment` 字段。
### 4. 轮询与交付
```text ```text
get_deployment_status / list_projects apply_deployment_plan({ planId })
Web：curl -skI "$url" 或健康路径（证书可能短暂签发中）
``` ```
对用户： 控制面内部（Agent **不要**再做）：挂卷 → 可选数据库 → 域名 `buxi`+5位+`DOMAIN_ROOT` + LE HTTPS → deploy。
- 给 **HTTPS 链接**（`apply` 的 `url`） 从返回中取：`url` / `domain` / `applicationId` / `isNewProject`（**勿回显**数据库密码）。
- 不提 Gitea/Dokploy/Token
- 配额满、无权：原文转述 MCP 错误
### 5. 域名与 HTTPS（控制面完成，Agent 勿重复 domain.create） ### 4.5 轮询与探活
- 默认 host：`buxi` + 5 位随机 `[a-z0-9]` + `.` + `DOMAIN_ROOT` ```text
例：`buxi3k9xa.loncode.site` 每 15–30s：get_deployment_status({ repo, environment }) 或 list_projects
- 首次分配后 **固定**（存在控制面 mapping） 终态：构建成功且运行中
- HTTPS：Dokploy Traefik + **Let’s Encrypt 按子域签证书**（**不需要**通配符证书） Web：curl -skI "$url"（证书首次可能 1–3 分钟）
- DNS：建议 `*.loncode.site` → 服务器（通配 **解析**，不是通配证书） 失败：get_sanitized_logs → 修代码/Dockerfile → 新 SHA → 新 plan → apply
- 证书失败：查 80/443、DNS；可暂 HTTP 仅当控制面 `DOMAIN_HTTPS=false` ```
Agent **不要**在 MCP 路径下再调 Dokploy `domain.create`（避免双绑/冲突）。 同一 `repo`+`environment` 重部署：**复用**域名与卷，**不占**新配额名额。
### 6. 卷与数据库 ### 4.6 工具速查
| 能力 | 行为 | | 工具 | 何时 |
|------|------| |------|------|
| 默认卷 | Docker named volume → `/data`（避免 bind 目录不存在导致 Swarm 0/1） | | `whoami` | 联通 / 身份 |
| bind 模式 | 可选；控制面 mkdir 宿主机路径，失败回退 volume | | `get_my_quota` | 部署前配额 |
| 多卷 | `spec.persistence[]`；缺 `/data` 仍自动补 | | `list_projects` | 我的项目、重部署标签 |
| Postgres / MySQL | `spec.databases[]` → Dokploy 建库 + 注入 `DATABASE_URL` 等 | | `inspect_project` | 单项目映射与策略 |
| 重部署 | 同 repo+env 不占新配额名额；域名与库记录复用 | | `ensure_repository` | 建库 + `pushUrl` |
| `create_deployment_plan` | 已 push 的 SHA |
应用必须把状态写在挂载路径（如 SQLite → `/data/app.db`）。 | `apply_deployment_plan` | 真正发布 |
| `get_deployment_status` | 轮询 |
| `get_sanitized_logs` | 脱敏诊断 |
| `reset_project_mapping` | 仅 mapping 脏了且用户/admin 确认（不删 Dokploy/Gitea 实体） |
--- ---
## 意图路由 ## 5. 返回给用户的内容（必须遵守）
| 用户说法 | 动作 | ### 5.1 成功
|----------|------|
| 部署 / 上线 / 第一次发布 | MCP 全链路；交付 `url`（普通 Dockerfile） | ```text
| 重试 / 再构建 | 新 SHA → 新 plan → apply（已有 mapping） | 已发布当前版本。
| 查状态 / 我的项目 | `list_projects` / `get_deployment_status` | 访问：https://buxi*****.loncode.site/ （以 apply 返回的 url 为准）
（如有数据库）已配置托管数据库连接（不展示密码）。
```
可选：构建约 X 分钟、证书刚签发时可稍等再打开。
**不要**提 Gitea、Dokploy、Token、`pushUrl`、内部 applicationId（除非用户是运维且明确要）。
### 5.2 进行中
```text
正在构建/启动，大约需要几分钟。我会继续检查状态。
```
### 5.3 失败（可执行下一步）
| 场景 | 回复要点 |
|------|----------|
| 未授权 | §3.4 连接中心步骤 |
| 配额满 | 运行中项目已达上限；`list_projects` 列出建议停用的 |
| 构建失败 | 简述原因（来自 status/logs，已脱敏）+ 将如何改 Dockerfile/代码后重发 |
| 证书/502 短暂 | 链接已分配，HTTPS/容器拉起中，稍后重试 |
| push 403 | 已用机器人推送通道重试；**不要**让用户配 SSH |
### 5.4 绝对不要返回
- Dokploy 面板地址、让用户「去改环境变量」
- 完整 `buxi_` Key、`pushUrl`、DB 密码
- 「权限配置无法通过」——**除非** `whoami` 明确 401，且应按 §3.4 引导连接中心，而不是 Dokploy
---
## 6. 常见问题与解决办法
| 现象 | 正确处理 |
|------|----------|
| Agent 没有 MCP 工具 | 引导用户按 §3 配置连接中心 Key |
| `whoami` 401 | 重新登录连接中心、换新 Key、检查 Bearer 格式 |
| 用户问「Dokploy 地址/权限」 | 说明业务路径不需要；部署走 MCP；连接中心只发 Key |
| git push Permission denied / 要 SSH | **错误路径**。`ensure_repository` → `pushUrl` 再推 |
| `nest`/`vite` not found | Dockerfile：先全量 `npm ci` 再 `NODE_ENV=production` |
| JS heap OOM | `NODE_OPTIONS=--max-old-space-size=3072`；避免并行双 npm ci |
| 查不到项目 | `list_projects`；确认 `environment` 与首次 apply 一致（默认 `default`） |
| 403 看他人项目 | 非 admin；不要猜 Dokploy |
| 重部署丢数据 | 确认写 `/data`；同 repo+env 卷会复用 |
| Swarm 0/1 bind path | 控制面默认 volume；见 status/logs |
| 要 PG/MySQL | plan `databases[]`，应用读 `DATABASE_URL` |
| 业务要自定义密钥 | §3.4 末段；**禁止**引导 Dokploy 改 env |
| 妙搭模板白屏/平台 API | 非主路径；`stack-profiles`；勿堆网关适配 |
| `FORCE_AUTHN_*` 启动失败 | apply 会注入 boot env；不等于业务可用 |
---
## 7. 意图路由（用户一句话 → 动作）
| 用户说法 | Agent 动作 |
|----------|------------|
| 部署 / 上线 / 发布 | §2 → §4 全链路 → §5 交付 URL |
| 再发一版 / 重试 | push 新 SHA → create+apply（同 environment）→ 轮询 |
| 我的项目 / 链接 | `list_projects` / `get_deployment_status` |
| 配额 | `get_my_quota` | | 配额 | `get_my_quota` |
| 只要链接 | `list_projects` 看 `url`；无则查 status | | 连不上 / 没权限 | **只**走 §2–§3（连接中心），**禁止** Dokploy |
| 运维直连 Dokploy | 仅明确要求时走 legacy | | 运维直连 Dokploy | 仅用户**明确**要求且本机有 `.env.deploy` → §8 |
| 妙搭应用 / `@lark-apaas` 上线 | **先边界说明**；优先 `lark-apps`；自托管仅实验、不承诺接口 | | 妙搭应用 | 先边界说明；优先 `lark-apps`；自托管实验见 stack-profiles |
| 修妙搭白屏 / 平台 API / 登录伪造 | **非本 skill**；说明需业务去平台化或妙搭云端，勿在控制面堆适配 |
--- ---
## 对用户话术 ## 8. Legacy：直连 Dokploy（运维例外 · 默认关闭）
**成功：** **仅当**同时满足：
- 已发布当前版本 1. 用户明确说「不要 MCP / 运维直连 Dokploy」；且
- 访问：`https://buxi….loncode.site/`（以 MCP 返回为准） 2. 本机有 `.env.deploy` + `DEPLOY_AUTHORIZED=true`
- 需要库时：说明已注入数据库连接（**不打印密码**）
- 若为妙搭实验部署：明确 **「仅容器/入口可能可用，登录与平台接口不保证」**
**失败：** 才可直连 Dokploy API。模板见 `references/env-deploy.example`。
- 配额满 / 未登录 Key / 构建失败 / 证书签发中 **有 MCP 时禁止向业务要 `DOKPLOY_API_KEY`。**
- 给可执行下一步，不暴露平台密钥 默认对话 **不要** 提 Dokploy 面板。
**拒绝加戏：**
- 不要为了「页面像妙搭」去改 skill 流程、伪造网关、承诺 runtime API
- 控制面 `SELF_HOST_*` 只是 boot 兜底，不是功能完整度保证
--- ---
## 安全红线 ## 9. 支持范围（产品收口）
1. 永不 commit / 回显：`buxi_` Key、`MCP_AUTH_TOKEN`、Dokploy/Gitea Token、`pushUrl`、数据库密码全文 | 栈 | 状态 |
2. `apply` 返回的 `connectionUrl` 已脱敏则保持；未脱敏则遮罩 |----|------|
3. 普通用户不可查他人项目（控制面会 403） | 普通 Python / Node / 静态站 + Dockerfile | **支持**（主路径） |
4. 生产破坏性操作仍受控制面策略约束 | 自管登录与 DB 的 API | **支持** |
5. **禁止**因 push 失败引导用户配置个人 SSH（那是错误路径） | 飞书妙搭 / `@lark-apaas/*` | **实验性**；不承诺登录/平台 API；见 `stack-profiles.md` |
主路径承诺：Dockerfile + 端口 + `/data` + 可选库 → **HTTPS 链接**。
不承诺：模拟妙搭网关、业务自定义 env 面板、用户进入 Dokploy。
--- ---
## Agent 检查清单（MCP） ## 10. 参考文件
- [ ] MCP 可用；`whoami` 正常 | 文件 | 内容 |
- [ ] Dockerfile + 数据写挂载点
- [ ] `ensure_repository` + push + `commitSha`
- [ ] plan 含正确 `port`；需要时 `persistence` / `databases`
- [ ] `apply` 拿到 `url`
- [ ] 轮询至终态；探活
- [ ] 未向用户索要 Dokploy/Gitea 地址或 Token
---
## Legacy：直连 Dokploy（运维例外）
**仅当**用户明确要求或 MCP 不可用且有 `.env.deploy`：
1. `set -a && source .env.deploy && set +a`，`DEPLOY_AUTHORIZED=true`
2. 按旧流程：Dockerfile → push → `application.*` / `mounts` / `domain.create` / deploy
3. 域名规则见 `references/domain.md` **Legacy** 段（与 MCP 的 `buxi+5` 规则不同，勿混用）
4. 模板：`references/env-deploy.example`
5. 仍禁止把密钥贴进聊天
**默认对话不要走这条。** 有 MCP 时禁止向业务索要 `DOKPLOY_API_KEY`。
---
## 与其它 skill 边界
| 场景 | 用 |
|------|-----|
| 企业 Dockerfile 部署（默认） | **本 skill → MCP** |
| 妙搭云端发布 / 平台能力迭代 | **`lark-apps`**（首选） |
| 妙搭模板硬上自托管 | 非主路径；见 `stack-profiles`；**不**在本 skill 做深度适配 |
| 无 MCP 的运维救火 | 本 skill → legacy |
---
## 故障速查（MCP）
| 现象 | 处理 |
|------|------| |------|------|
| 401 / 要 Feishu Key | 引导连接中心登录，配置 `buxi_` | | `references/mcp-deploy.md` | 工具参数、JSON 示例、apply 内部顺序 |
| git push 权限 / Permission denied / 要配 SSH | **错误路径**。改用 `ensure_repository` → `agentHint.pushUrl` 推送；禁止给用户配 SSH | | `references/sequence.md` | 时序图 |
| `nest: not found` / `vite: not found` | build 阶段在装依赖前设了 `NODE_ENV=production`；先全量 `npm ci` 再设 production | | `references/domain.md` | 域名与 HTTPS |
| `JavaScript heap out of memory` | Dockerfile build 加 `NODE_OPTIONS=--max-old-space-size=3072`；避免并行 npm ci；机器内存过小则升配 | | `references/stack-profiles.md` | Dockerfile 约定 + 支持矩阵 |
| `FORCE_AUTHN_INNERAPI_DOMAIN` / 平台模式需要基础域名 | 镜像仍带 PlatformModule 时缺 boot env；`apply` 会注入公网 URL；**不表示业务已可用** | | `references/env-deploy.example` | 仅 legacy |
| 妙搭项目：页面白屏 / `{{appId}}` / 接口 403·404 / JSON 解析 HTML | **预期内能力缺口**（非本 skill 必修）。引导去平台化或 `lark-apps`；勿在控制面加网关适配 |
| 运行中项目达上限 | `get_my_quota`；停/删旧应用后再部署 | 线上：
| Forbidden 看他人项目 | 非管理员；加 `ADMIN_OPEN_IDS` 或只查自己的 |
| 有部署无 HTTPS | 等 LE；查 DNS/80；控制面证书配置 | - 连接中心：https://company-deploy-mcp.loncode.site/
| 重部署丢数据 | 确认写 `/data`；控制面默认挂载是否开启 | - MCP：https://company-deploy-mcp.loncode.site/mcp
| Swarm 0/1 + bind path does not exist | 控制面已默认 volume + mkdir；旧应用可 `mkdir -p` 宿主机路径或删 bind 改 volume 后 redeploy | - 技能仓：http://git.loncode.site/Buxi/company-deploy-skills
| 要 PG/MySQL | plan 里带 `databases`，勿手建后不注入 env |
---
## 11. Agent 出发前检查清单
- [ ] 已 `whoami` 成功（不是假设有权限）
- [ ] 未要求用户打开 Dokploy / 提供面板账号
- [ ] 未索要 `DOKPLOY_API_KEY` / 用户 SSH
- [ ] Dockerfile + port + `/data`（及可选 databases）
- [ ] `ensure_repository` + **pushUrl** 推送 + `commitSha`
- [ ] `environment` 默认 `default` 或与历史一致
- [ ] `apply` 后轮询并交付 **HTTPS url**
- [ ] 回复符合 §5（无密钥、无 Dokploy 推诿）

36
dokploy-gitea-deploy/references/mcp-deploy.md
View File

@@ -1,5 +1,23 @@
# company-deploy-mcp 默认部署路径 # company-deploy-mcp 默认部署路径
> **完整操作手册（联通 → 鉴权 → 部署 → 返回话术）见上级 `SKILL.md`。**
> 本文是工具参数与 JSON 细节；若与 SKILL 冲突，以 **SKILL.md** 为准。
## Agent 禁止话术（高频翻车）
| 禁止 | 正确 |
|------|------|
| 让用户打开 Dokploy 面板 / 要面板地址 | 业务路径 **永不** 需要 Dokploy UI |
| 要 Dokploy 账号、某应用「环境变量编辑权限」 | 库用 `databases[]`；自定义密钥见 SKILL §3.4，不导向 Dokploy |
| 「权限配置无法通过」却未调用 `whoami` | 先 `whoami`；401 才引导 **连接中心** 重拿 `buxi_` |
| 索要 `DOKPLOY_API_KEY` / Gitea Token / 用户 SSH | 只用 MCP + `ensure_repository.pushUrl` |
| 编造 Dokploy URL | 不要猜 |
**连接中心** = 飞书身份 + 发 `buxi_` Key。
**不是** Dokploy 管理面板；也 **不能** 用来替代 MCP 部署。
---
**连接中心（飞书登录 + 拿 Key）：** **连接中心（飞书登录 + 拿 Key）：**
`https://company-deploy-mcp.loncode.site/` `https://company-deploy-mcp.loncode.site/`
@@ -25,6 +43,14 @@ Agent 配置示例（用户从连接中心复制，**不要**写进业务仓库
- 身份：飞书 `open_id` 绑定到 Key；管理员另见 `ADMIN_OPEN_IDS` / 平台 `MCP_AUTH_TOKEN` - 身份：飞书 `open_id` 绑定到 Key；管理员另见 `ADMIN_OPEN_IDS` / 平台 `MCP_AUTH_TOKEN`
- **禁止**在 MCP 可用时向业务用户索要 Dokploy / Gitea Token - **禁止**在 MCP 可用时向业务用户索要 Dokploy / Gitea Token
### 联通最小三步
```text
1. whoami → 必须成功
2. get_my_quota → 未满再部署
3. list_projects → 重部署时沿用 environment
```
--- ---
## 工具一览 ## 工具一览
@@ -289,18 +315,22 @@ apply 返回后：
| 场景 | 说法 | | 场景 | 说法 |
|------|------| |------|------|
| 成功 | 已发布当前版本；访问：`https://…` | | 成功 | 已发布当前版本；访问：`https://…`（apply 的 url） |
| 有数据库 | 已配置托管数据库连接（不打印密码） | | 有数据库 | 已配置托管数据库连接（不打印密码） |
| 配额满 | 运行中项目已达上限，请先停用不用的服务 | | 配额满 | 运行中项目已达上限，请先停用不用的服务 |
| 未登录 | 打开连接中心飞书登录，把配置贴到 Agent | | 未登录 / 401 | 打开连接中心飞书登录，把 `buxi_` 配到 Agent（**不要**提 Dokploy） |
| 构建中 | 正在构建，稍后自动检查 | | 构建中 | 正在构建，稍后自动检查 |
| 证书中 | 链接已分配，HTTPS 证书签发中，稍后再开 | | 证书中 | 链接已分配，HTTPS 证书签发中，稍后再开 |
| 用户要 Dokploy 权限 | 业务部署不需要；用连接中心 + 本 MCP 即可 |
完整模板见 **SKILL.md §5**。
--- ---
## 安全 ## 安全
1. 永不 commit / 回显：`buxi_`、平台 Token、DB 密码全文 1. 永不 commit / 回显：`buxi_`、平台 Token、DB 密码全文、`pushUrl`
2. 日志只用 `get_sanitized_logs` 2. 日志只用 `get_sanitized_logs`
3. `.env` / 密钥进 `.gitignore` 3. `.env` / 密钥进 `.gitignore`
4. 生产破坏操作受控制面策略约束；不要教用户绕过 4. 生产破坏操作受控制面策略约束；不要教用户绕过
5. 不要把「去 Dokploy 改配置」当作排障步骤