Buxi/company-deploy-skills

Fork 0

Files

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

2026-08-02 17:03:08 +08:00

15 KiB

Raw Blame History

name, description, metadata

name

description

metadata

dokploy-gitea-deploy

企业 Dockerfile 项目部署（唯一默认路径：company-deploy-mcp）。飞书登录拿 buxi_ Key → 配置 MCP → whoami 联通 → ensure_repository + pushUrl 推代码 → create/apply plan → 轮询 → 交付 HTTPS 链接。用户永不进 Dokploy/Gitea。触发：部署、上线、重部署、redeploy、查项目、配额、buxi_、company-deploy、企业部署。禁止引导用户打开 Dokploy 面板或索要 DOKPLOY_API_KEY。Use when /dokploy-gitea-deploy。

short-description
企业部署：MCP 全流程（用户不进 Dokploy）

企业部署 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（一次性）

curl -fsSL https://company-deploy-mcp.loncode.site/install-skill.sh | bash
# 或
npx skills add http://git.loncode.site/Buxi/company-deploy-skills.git --skill dokploy-gitea-deploy -g -y

Skill 只定义流程；没有配置 MCP + buxi_ Key 则无法部署。

2. 联通性检测（每次部署前必做）

按顺序，先测再部署。任一步失败：按 §6 处理，禁止改口去要 Dokploy。

2.1 MCP 是否挂上

Agent 能否调用 company-deploy 的工具（至少 whoami）。

结果	含义	下一步
工具列表里有 `whoami` / `apply_deployment_plan`	已配置 MCP	→ 2.2
没有这些工具 / 调用直接失败	未配置或 Key 错误	→ §3 鉴权

2.2 身份

whoami

期望字段示例：role（user|admin）、openId、name、isAdmin。

结果	处理
返回身份 JSON	联通成功
401 / Unauthorized / invalid token	Key 无效 → §3
超时 / 连接失败	网络或控制面宕机 → 告之稍后重试，可 `curl -sS https://company-deploy-mcp.loncode.site/health`

2.3 配额

get_my_quota

看运行中项目数是否达上限。满了：先 list_projects，让用户停/删不用的，不要绕过 MCP。

2.4（可选）已有项目

list_projects

重部署时记下已有 repo + environment（部署标签，默认多为 default），必须沿用，禁止擅自改成 production。

3. 鉴权与获取授权

3.1 用户怎么拿 Key（业务同学）

浏览器打开：https://company-deploy-mcp.loncode.site/
飞书登录
复制页面上的 buxi_… Key 与 MCP 配置片段
粘贴到 Agent 的 MCP 配置（见下）
回到对话说「已配置」或直接「部署」

3.2 Agent / 客户端怎么配

{
  "mcpServers": {
    "company-deploy": {
      "url": "https://company-deploy-mcp.loncode.site/mcp",
      "headers": {
        "Authorization": "Bearer buxi_用户从连接中心复制的Key"
      }
    }
  }
}

前缀：buxi_（旧 cdp_ 可能仍可用，新发一律 buxi_）
禁止把 Key 写进业务 Git 仓库
禁止把 Key 完整打印在对用户的回复里（可确认「已配置」）

3.3 权限模型（Agent 必须理解）

能力	谁有	说明
部署自己的项目	任意有效 `buxi_`	首次 `apply` 建立归属
看自己的项目列表/状态	自己	`list_projects` / `get_deployment_status`
看别人的项目	仅 admin	`ADMIN_OPEN_IDS` 或平台 `MCP_AUTH_TOKEN`
进 Dokploy 面板	不在本产品路径	禁止当作用户解决办法
手改 Gitea 权限 / SSH	不需要	推送只用 `ensure_repository` 的 `pushUrl`

3.4 鉴权失败怎么说（固定话术）

401 / 未配置 MCP：

还不能部署：需要先完成企业部署授权。

打开 https://company-deploy-mcp.loncode.site/

飞书登录，复制 buxi_ Key

按页面说明粘贴到当前 Agent 的 MCP 配置

配置好后回复「已配置」，我再继续部署。
（连接中心只负责身份和 MCP，不需要 Dokploy 账号。）

403 看别人的项目：

当前账号只能管理自己名下的项目。如需管理员视角，请联系平台管理员把你的飞书 open_id 加入白名单。

禁止话术（截图类错误）：

❌「你不能通过项目网页进入 Dokploy」
❌「向管理员索取 Dokploy 面板地址 / 登录账号 / 某应用环境变量编辑权限」
❌「企业部署连接中心不是 Dokploy，所以你没法配 env——去找管理员开 Dokploy」
❌ 凭空编造 Dokploy URL

若用户要的是 业务应用自定义密钥（如第三方 API Key），而 plan 又注入不了：

当前 MCP 会自动注入数据库连接（databases[]）和运行所需基础变量；
不提供业务同学自助打开 Dokploy 改 env。
可选：① 非密钥配置进代码/配置文件；② 密钥由平台管理员走运维通道注入（不经过业务 Dokploy 账号）；③ 应用支持启动后自助配置页。
我不会让你去申请 Dokploy 面板权限。

4. 部署操作流程（默认全链路）

前提： §2 联通、§3 有有效 Key。工程为 普通 Dockerfile 服务（Python/Node/静态站等）。
妙搭/@lark-apaas：非主路径，见 references/stack-profiles.md；勿承诺与妙搭线上一致。

┌─────────────────────────────────────────────────────────────┐
│  A. 工程准备（本地）                                          │
│  B. ensure_repository → pushUrl 推送（Agent，禁止用户 SSH）     │
│  C. create_deployment_plan                                    │
│  D. apply_deployment_plan   ← 卷/库/域名/构建全在这里          │
│  E. 轮询 get_deployment_status / list_projects                 │
│  F. 探活 URL → 按 §5 回复用户                                  │
└─────────────────────────────────────────────────────────────┘

细节参数见 references/mcp-deploy.md；时序见 references/sequence.md。

4.1 工程准备（Agent）

有 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 仓库与推送

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 建计划

create_deployment_plan({
  repo,
  commitSha,          # 已在 Gitea 上
  branch: "main",
  environment: "default",   # 除非用户明确要第二套并行环境
  spec: {
    buildType: "dockerfile",
    dockerfilePath: "Dockerfile",
    buildPath: "/",
    port: <容器端口>,
    healthcheckPath: "/",
    exposeWeb: true
    # persistence / databases 按需
  }
})
→ 记下 planId

部署标签 environment： 控制面 mapping 键，不是 Dokploy 的 preview/production 分组。
默认 default。禁止因用户说「上线/生产」就改成 production。

4.4 发布

apply_deployment_plan({ planId })

控制面内部（Agent 不要再做）：挂卷 → 可选数据库 → 域名 buxi+5位+DOMAIN_ROOT + LE HTTPS → deploy。

从返回中取：url / domain / applicationId / isNewProject（勿回显数据库密码）。

4.5 轮询与探活

每 15–30s：get_deployment_status({ repo, environment }) 或 list_projects
终态：构建成功且运行中
Web：curl -skI "$url"（证书首次可能 1–3 分钟）
失败：get_sanitized_logs → 修代码/Dockerfile → 新 SHA → 新 plan → apply

同一 repo+environment 重部署：复用域名与卷，不占新配额名额。

4.6 工具速查

工具	何时
`whoami`	联通 / 身份
`get_my_quota`	部署前配额
`list_projects`	我的项目、重部署标签
`inspect_project`	单项目映射与策略
`ensure_repository`	建库 + `pushUrl`
`create_deployment_plan`	已 push 的 SHA
`apply_deployment_plan`	真正发布
`get_deployment_status`	轮询
`get_sanitized_logs`	脱敏诊断
`reset_project_mapping`	仅 mapping 脏了且用户/admin 确认（不删 Dokploy/Gitea 实体）

5. 返回给用户的内容（必须遵守）

5.1 成功

已发布当前版本。
访问：https://buxi*****.loncode.site/   （以 apply 返回的 url 为准）
（如有数据库）已配置托管数据库连接（不展示密码）。

可选：构建约 X 分钟、证书刚签发时可稍等再打开。
不要提 Gitea、Dokploy、Token、pushUrl、内部 applicationId（除非用户是运维且明确要）。

5.2 进行中

正在构建/启动，大约需要几分钟。我会继续检查状态。

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`
连不上 / 没权限	只走 §2–§3（连接中心），禁止 Dokploy
运维直连 Dokploy	仅用户明确要求且本机有 `.env.deploy` → §8
妙搭应用	先边界说明；优先 `lark-apps`；自托管实验见 stack-profiles

8. Legacy：直连 Dokploy（运维例外 · 默认关闭）

仅当同时满足：

用户明确说「不要 MCP / 运维直连 Dokploy」；且
本机有 .env.deploy + DEPLOY_AUTHORIZED=true

才可直连 Dokploy API。模板见 references/env-deploy.example。

有 MCP 时禁止向业务要 DOKPLOY_API_KEY。
默认对话不要提 Dokploy 面板。

9. 支持范围（产品收口）

栈	状态
普通 Python / Node / 静态站 + Dockerfile	支持（主路径）
自管登录与 DB 的 API	支持
飞书妙搭 / `@lark-apaas/*`	实验性；不承诺登录/平台 API；见 `stack-profiles.md`

主路径承诺：Dockerfile + 端口 + /data + 可选库 → HTTPS 链接。
不承诺：模拟妙搭网关、业务自定义 env 面板、用户进入 Dokploy。

10. 参考文件

文件	内容
`references/mcp-deploy.md`	工具参数、JSON 示例、apply 内部顺序
`references/sequence.md`	时序图
`references/domain.md`	域名与 HTTPS
`references/stack-profiles.md`	Dockerfile 约定 + 支持矩阵
`references/env-deploy.example`	仅 legacy

线上：

连接中心：https://company-deploy-mcp.loncode.site/
MCP：https://company-deploy-mcp.loncode.site/mcp
技能仓：http://git.loncode.site/Buxi/company-deploy-skills

11. Agent 出发前检查清单

已 whoami 成功（不是假设有权限）
未要求用户打开 Dokploy / 提供面板账号
未索要 DOKPLOY_API_KEY / 用户 SSH
Dockerfile + port + /data（及可选 databases）
ensure_repository + pushUrl 推送 + commitSha
environment 默认 default 或与历史一致
apply 后轮询并交付 HTTPS url
回复符合 §5（无密钥、无 Dokploy 推诿）

15 KiB Raw Blame History Unescape Escape