Buxi/company-deploy-skills

Fork 0

Files

Lon dcddd3c3f9 docs(skill): set_application_env for container secrets

2026-08-02 17:36:09 +08:00

12 KiB

Raw Blame History

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 配置示例（用户从连接中心复制，不要写进业务仓库）：

{
  "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

联通最小三步

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

标准调用顺序（必须）

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[]` 项

{
  "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[]` 项

{
  "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）

{
  "repo": "my-web-app",
  "commitSha": "a1b2c3d4e5f6...",
  "branch": "main",
  "environment": "default",
  "spec": {
    "buildType": "dockerfile",
    "dockerfilePath": "Dockerfile",
    "buildPath": "/",
    "port": 3000,
    "healthcheckPath": "/",
    "exposeWeb": true
  }
}

apply 成功后典型字段：

{
  "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 环境无关，且会导致查不到项目）。

{
  "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）

{
  "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 内按序完成：

配额：仅新建 mapping 时检查运行中数量
ensure Application（已有则复用）
ensureMounts：默认 /data（Docker volume，无需预建宿主机目录）+ persistence[]
ensureDatabases：postgres/mysql + 注入 env
ensureDomain：buxi+5 随机 + Let’s Encrypt（见 domain.md）
deploy 应用镜像

Agent 不要再直连 Dokploy 做 domain.create / mounts.create / 手建 DB（会双绑冲突）。

业务环境变量（容器 env）

项目 至少 apply 成功一次 后：

// 仅键名
{ "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 硬推。

轮询建议

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。

安全

永不 commit / 回显：buxi_、平台 Token、DB 密码全文、pushUrl
日志只用 get_sanitized_logs
.env / 密钥进 .gitignore
生产破坏操作受控制面策略约束；不要教用户绕过
不要把「去 Dokploy 改配置」当作排障步骤

12 KiB Raw Blame History Unescape Escape