# 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. 生产破坏操作受控制面策略约束；不要教用户绕过