374 lines
12 KiB
Markdown
374 lines
12 KiB
Markdown
# company-deploy-mcp 默认部署路径
|
||
|
||
> **完整操作手册（联通 → 鉴权 → 部署 → 返回话术）见上级 `SKILL.md`。**
|
||
> 本文是工具参数与 JSON 细节；若与 SKILL 冲突，以 **SKILL.md** 为准。
|
||
|
||
## Agent 禁止话术（高频翻车）
|
||
|
||
| 禁止 | 正确 |
|
||
|------|------|
|
||
| 让用户打开 Dokploy 面板 / 要面板地址 | 业务路径 **永不** 需要 Dokploy UI |
|
||
| 要 Dokploy 账号、「环境变量编辑权限」 | 库用 `databases[]`；业务密钥用 **`set_application_env`** |
|
||
| 把 `.env` 推进企业 Git | 密钥用 `set_application_env` 写容器 env；`.gitignore` 排除 `.env` |
|
||
| 「权限配置无法通过」却未调用 `whoami` | 先 `whoami`；401 才引导 **连接中心** 重拿 `buxi_` |
|
||
| 索要 `DOKPLOY_API_KEY` / Gitea Token / 用户 SSH | 只用 MCP + `ensure_repository.pushUrl` |
|
||
| 编造 Dokploy URL | 不要猜 |
|
||
|
||
**连接中心** = 飞书身份 + 发 `buxi_` Key。
|
||
**不是** Dokploy 管理面板；也 **不能** 用来替代 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
|
||
|
||
### 联通最小三步
|
||
|
||
```text
|
||
1. whoami → 必须成功
|
||
2. get_my_quota → 未满再部署
|
||
3. list_projects → 重部署时沿用 environment
|
||
```
|
||
|
||
---
|
||
|
||
## 工具一览
|
||
|
||
| 工具 | 读写 | 作用 |
|
||
|------|------|------|
|
||
| `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` | 读 | 脱敏诊断摘要 |
|
||
| `list_application_env_keys` | 读 | 容器/应用 env **键名**列表（永不返回值） |
|
||
| `set_application_env` | 写 | 合并/删除业务 env → 容器环境变量；可选 `redeploy` |
|
||
|
||
`repo` 格式：
|
||
|
||
- `Owner/name` 完整路径
|
||
- 或仅 `name` → 控制面补默认 `GITEA_ORG`
|
||
|
||
---
|
||
|
||
## 标准调用顺序（必须）
|
||
|
||
```text
|
||
0. whoami / get_my_quota # 可选但推荐；配额满先处理
|
||
1. 本地：Dockerfile + 数据写 /data + .gitignore
|
||
2. ensure_repository({ repo })
|
||
→ 响应含 agentHint.pushUrl（oauth2:机器人Token@gitea/...）
|
||
3. git commit
|
||
git push --set-upstream "<pushUrl>" HEAD:<defaultBranch>
|
||
# 禁止：git push origin（若 origin 无 Token）
|
||
# 禁止：要求用户配置 ~/.ssh/id_ed25519
|
||
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 在服务器上读不到用户工作区未提交文件。
|
||
**凭据**：仅用 `ensure_repository` 返回的 `pushUrl`（企业 `gitea-robot`），用户无 Gitea 账号/SSH 也能部署。
|
||
|
||
---
|
||
|
||
## 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（会双绑冲突）。
|
||
|
||
---
|
||
|
||
## 业务环境变量（容器 env）
|
||
|
||
项目 **至少 apply 成功一次** 后：
|
||
|
||
```json
|
||
// 仅键名
|
||
{ "repo": "my-app", "environment": "default" }
|
||
// → list_application_env_keys
|
||
|
||
// 写入 / 覆盖 / 删除
|
||
{
|
||
"repo": "my-app",
|
||
"environment": "default",
|
||
"vars": {
|
||
"FEISHU_APP_ID": "cli_xxx",
|
||
"FEISHU_APP_SECRET": "secret"
|
||
},
|
||
"removeKeys": [],
|
||
"redeploy": true
|
||
}
|
||
// → set_application_env
|
||
```
|
||
|
||
| 规则 | |
|
||
|------|--|
|
||
| 落点 | Dokploy 应用 env → **容器进程环境变量** |
|
||
| 不进 Git | 禁止 commit `.env` |
|
||
| 响应 | 只含 `updatedKeys` / `keys` 等名称；**永不回显 value** |
|
||
| 受保护键（非 admin） | `DATABASE_URL`、`SUDA_DATABASE_URL`、`SERVER_*`、`PORT`、`FORCE_*`、`COMPANY_DEPLOY_SELF_HOST` |
|
||
| `redeploy: true` | 建议；否则旧容器可能仍用旧 env |
|
||
| 权限 | 项目 owner 或 admin |
|
||
|
||
---
|
||
|
||
## 配额与归属
|
||
|
||
| 概念 | 行为 |
|
||
|------|------|
|
||
| 归属 | 首次成功 `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://…`（apply 的 url） |
|
||
| 有数据库 | 已配置托管数据库连接（不打印密码） |
|
||
| 配额满 | 运行中项目已达上限，请先停用不用的服务 |
|
||
| 未登录 / 401 | 打开连接中心飞书登录，把 `buxi_` 配到 Agent（**不要**提 Dokploy） |
|
||
| 构建中 | 正在构建，稍后自动检查 |
|
||
| 证书中 | 链接已分配，HTTPS 证书签发中，稍后再开 |
|
||
| 用户要 Dokploy 权限 | 业务部署不需要；用连接中心 + 本 MCP 即可 |
|
||
|
||
完整模板见 **SKILL.md §5**。
|
||
|
||
---
|
||
|
||
## 安全
|
||
|
||
1. 永不 commit / 回显：`buxi_`、平台 Token、DB 密码全文、`pushUrl`
|
||
2. 日志只用 `get_sanitized_logs`
|
||
3. `.env` / 密钥进 `.gitignore`
|
||
4. 生产破坏操作受控制面策略约束；不要教用户绕过
|
||
5. 不要把「去 Dokploy 改配置」当作排障步骤
|