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

chore: init company-deploy-skills with dokploy-gitea-deploy

Browse Source
This commit is contained in:
deploy-bot
2026-07-31 09:47:16 +08:00
commit 7b56a16fbc
7 changed files with 1125 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
dokploy-gitea-deploy/references/domain.md Normal file
View File

@@ -0,0 +1,142 @@
# 域名与 HTTPS
## 默认路径：company-deploy-mcp（优先）
业务部署 **不要** 手写 Dokploy `domain.create`。
控制面在 `apply_deployment_plan` 内自动绑定域名并启用 HTTPS。
### 主机名规则
| 项 | 值 |
|----|-----|
| 格式 | `{prefix}{random}.{DOMAIN_ROOT}` |
| 默认 prefix | `buxi` |
| 默认 random | 5 位 `[a-z0-9]` |
| 默认根域 | `loncode.site`（以控制面 `DOMAIN_ROOT` 为准） |
| 示例 | `buxi3k9xa.loncode.site` |
- **首次** `apply` 且 `exposeWeb !== false` 时分配
- 分配后写入项目 mapping，**同 repo+environment 永久复用**
- 可用 `spec.domainHost` 指定固定 host（需 DNS 已解析到 Dokploy；一般业务勿用）
- `exposeWeb: false`：不绑公网域（Worker / 长连接机器人）
### HTTPS / 证书
| 项 | 说明 |
|----|------|
| 默认 | `DOMAIN_HTTPS=true`，`certificateType=letsencrypt` |
| 实现 | Dokploy Traefik 按**具体子域**申请 Let’s Encrypt |
| **不需要** | 通配符证书（`*.loncode.site` 的 cert） |
| **需要** | DNS 把子域指到 Dokploy；**80/443** 公网可达（HTTP-01） |
推荐 DNS（一次配好，所有项目共用）：
```text
*.loncode.site → A/AAAA → Dokploy 服务器 IP
```
这是通配 **解析**，不是通配证书。每个 `buxi*****.loncode.site` 各自签 LE。
### 交付链接
| 来源 | 字段 |
|------|------|
| `apply_deployment_plan` | `url`、`domain.host`、`domain.url` |
| `list_projects` | 每项 `url` / `domainHost` |
| `get_deployment_status` | 结合应用状态与 mapping |
格式：`https://<host>/`（控制面 `DOMAIN_HTTPS=false` 时才是 `http://`）。
Agent 探活：
```bash
curl -skI "https://buxiXXXXX.loncode.site/"
# 或健康路径
curl -skI "https://buxiXXXXX.loncode.site/healthz"
```
首次可能短暂 404 / TLS 握手失败：等 1–3 分钟 LE；仍失败查 DNS 与 80/443。
### Agent 红线（MCP 路径）
1. **不要**再调 Dokploy `domain.create`（双绑/冲突）
2. **不要**要求业务用户填 `DOKPLOY_DOMAIN`
3. **不要**把错误的宿主机端口（如别人的 `:8080`）当成产品链接
4. 证书失败：查基础设施，不要改业务代码「硬编码域名」进 Git
细节与 plan 参数见 `mcp-deploy.md`。
---
## Legacy 路径：直连 Dokploy（运维例外）
仅当用户明确要求不走 MCP，且存在项目 `.env.deploy` 时使用。
### 配置写在哪？
| 位置 | 用途 |
|------|------|
| **项目根 `.env.deploy`** | Agent 读取；必须 gitignore |
| `env-deploy.example` | 模板 |
| Dokploy 面板 Domains | 人工补绑 |
| 域名注册商 DNS | 用户/运维配置 |
### 方式 A：写死完整域名
```bash
DOKPLOY_EXPOSE_WEB=true
DOKPLOY_DOMAIN=crm.loncode.site
DOKPLOY_DOMAIN_HTTPS=true
DOKPLOY_DNS_READY=true
DOKPLOY_PORT=3000
```
### 方式 B：根域 + slug
```bash
DOKPLOY_EXPOSE_WEB=true
DOKPLOY_DOMAIN_ROOT=loncode.site
DOKPLOY_DOMAIN_PREFIX=
# DOKPLOY_DOMAIN 留空 → {PREFIX}{slug}.{ROOT}
```
与控制面 `buxi+5` 规则**不同**（legacy 多为 app 名 slug）。
企业统一对外仍推荐 **MCP 的 buxi+5**，避免与连接中心体验分裂。
### 方式 C：非 Web
```bash
DOKPLOY_EXPOSE_WEB=false
```
### Legacy API 示例
```bash
curl -sS -X POST \
-H "x-api-key: $DOKPLOY_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"host\": \"${DOKPLOY_DOMAIN}\",
\"applicationId\": \"${DOKPLOY_APPLICATION_ID}\",
\"https\": true,
\"certificateType\": \"letsencrypt\",
\"port\": ${DOKPLOY_PORT},
\"path\": \"/\",
\"domainType\": \"application\"
}" \
"${DOKPLOY_URL}/api/domain.create"
```
`host` **不要**带协议。证书同样依赖 DNS + 80/443。
---
## 故障速查
| 现象 | 处理 |
|------|------|
| 有 host 无 HTTPS | 等 LE；查 80 是否被占用/防火墙 |
| DNS NXDOMAIN | 配 `*.DOMAIN_ROOT` 或单条 A 记录 |
| 证书反复失败 | 确认公网能访问该 host 的 80 |
| 打开了错误站点 | 是否绑到了别的 applicationId |
| MCP 与 legacy 双绑 | 停掉一侧；优先只走 MCP |

77
dokploy-gitea-deploy/references/env-deploy.example Normal file
View File

@@ -0,0 +1,77 @@
# ═══ LEGACY ONLY ═══
# 默认部署请走 company-deploy-mcp（飞书 + buxi_ Key），不要业务项目填本文件。
# 仅运维 / 明确直连 Dokploy 时使用。
#
# 复制到目标项目根目录：
# cp ~/.grok/skills/dokploy-gitea-deploy/references/env-deploy.example .env.deploy
# 填好后：set -a && source .env.deploy && set +a
# 必须 gitignore：.env.deploy
# ── 授权 ──
DEPLOY_AUTHORIZED=false
ALLOW_SYNC_APP_ENV_TO_DOKPLOY=true
DO_GIT_PUSH=true
DO_DOKPLOY_DEPLOY=true
DO_HEALTHCHECK=true
FIX_DOCKERFILE=true
PROJECT_DIR=.
APP_ENV_FILE=.env
# ── Gitea ──
GITEA_URL=https://git.example.com
GITEA_USER=
GITEA_ORG=
GITEA_REPO=
GITEA_REPO_VISIBILITY=private
GITEA_REPO_EXISTS=false
GITEA_TOKEN=
GIT_PUSH_METHOD=https
GIT_BRANCH=main
GITEA_CLONE_URL=
# ── Dokploy ──
DOKPLOY_URL=https://dokploy.example.com
DOKPLOY_API_KEY=
DOKPLOY_PROJECT_NAME=
DOKPLOY_APP_NAME=
DOKPLOY_APPLICATION_ID=
DOKPLOY_BUILD_TYPE=dockerfile
DOKPLOY_DOCKERFILE_PATH=Dockerfile
DOKPLOY_PORT=8080
DOKPLOY_REPLICAS=1
DOKPLOY_VOLUME_MOUNT=
DOKPLOY_HEALTHCHECK_PATH=/healthz
DOKPLOY_GIT_AUTH_METHOD=gitea_provider
DOKPLOY_GITEA_LINKED=false
# 首次部署后勿默认 true，除非依赖变了或缓存损坏
DOKPLOY_CLEAN_CACHE=false
# ── 域名 / 可访问链接（Web 页面必看）──
# 是否对外提供网页链接：true=部署成功后必须绑 Domain 并交付 https URL
# false=Worker/飞书长连接等，域名可选
DOKPLOY_EXPOSE_WEB=true
# 方式 A：完整主机名（优先）。不要写 https://
# DOKPLOY_DOMAIN=crm.loncode.site
# 方式 B：根域自动生成子域（DOKPLOY_DOMAIN 留空时生效）
# 最终 host = {DOKPLOY_DOMAIN_PREFIX}{slug}.{DOKPLOY_DOMAIN_ROOT}
# slug 默认取 DOKPLOY_APP_NAME 或 GITEA_REPO（小写，非法字符变 -）
# 建议 DNS 配：*.loncode.site → Dokploy 服务器 IP
DOKPLOY_DOMAIN=
DOKPLOY_DOMAIN_ROOT=
DOKPLOY_DOMAIN_PREFIX=
# HTTPS / 证书（公网建议 true + letsencrypt）
DOKPLOY_DOMAIN_HTTPS=true
DOKPLOY_CERTIFICATE_TYPE=letsencrypt
# DNS 是否已指向 Dokploy（true 时 Agent 会强调证书应能签发并做探活）
DOKPLOY_DNS_READY=false
# ── 包源（构建）──
# Python / uv
PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
# Node（可选，写入构建环境或 .npmrc）
# NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

301
dokploy-gitea-deploy/references/mcp-deploy.md Normal file
View File

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

104
dokploy-gitea-deploy/references/sequence.md Normal file
View File

@@ -0,0 +1,104 @@
# 时序
## 默认：MCP 全链路（业务部署）
```text
用户 Agent company-deploy-mcp Gitea Dokploy
│ │ │ │ │
│ 部署/上线 │ │ │ │
│─────────────────►│ │ │ │
│ │ whoami / get_my_quota │ │ │
│ │────────────────────────►│ │ │
│ │ Dockerfile + 本地校验 │ │ │
│ │ ensure_repository │ │ │
│ │────────────────────────►│──建库(可选)─────►│ │
│ │◄────────────────────────│◄─────────────────│ │
│ │ git push（企业凭据） │ │ │
│ │───────────────────────────────────────────►│ │
│ │ create_deployment_plan │ │ │
│ │────────────────────────►│ │ │
│ │ apply_deployment_plan │ │ │
│ │────────────────────────►│ │ │
│ │ │ ensure app │ │
│ │ │ mounts (/data+) │ │
│ │ │ postgres/mysql? │ │
│ │ │ domain buxi+5+LE │ │
│ │ │ deploy ──────────┼──────────────►│
│ │ │ │ clone/build │
│ │ get_deployment_status │ │ run │
│ │────────────────────────►│──status──────────┼──────────────►│
│ │ 探活 https://buxi…. │ │ │
│ 交付 HTTPS 链接 │ │ │ │
│◄─────────────────│ │ │ │
```
要点：
- **建库 / 挂卷 / PG·MySQL / 域名 / deploy** 全在 MCP `apply` 内
- **push** 只在 Agent 本机
- 业务用户不接触 Gitea / Dokploy / Token
参数与示例：`mcp-deploy.md`。域名与证书：`domain.md`。
---
## 日常二次发布（MCP）
```text
用户 → Agent → git push → create_deployment_plan(新 SHA)
→ apply_deployment_plan
→ 复用 mapping（域名、卷、库、配额名额）
→ 轮询 + 探活
```
- 同一 `repo` + `environment`：**不新建** Dokploy 应用名额
- 域名 host **不变**
- 数据卷 **不变**（应用须写在挂载路径）
- plan 一次性；每次发布新建 plan
---
## Legacy：直连 Dokploy（运维例外）
```text
用户 Agent Gitea Dokploy
│ │ │ │
│ 明确要求直连 │ │ │
│───────────────────►│ source .env.deploy │ │
│ │ Dockerfile │ │
│ │ 建仓+git push │ │
│ │────────────────────►│ │
│ │ application.* │ │
│ │ mounts / domain │ │
│ │ application.deploy │ │
│ │──────────────────────────────────────────►│
│ │ 轮询 + 探活 │ │
│◄───────────────────│ │ │
```
仅当 MCP 不可用且有 `.env.deploy` + `DEPLOY_AUTHORIZED=true`。
默认对话 **不要** 走这条。
---
## 责任边界
| 角色 | MCP 路径 | Legacy 路径 |
|------|----------|-------------|
| 用户 | 飞书登录拿 `buxi_`；说「部署」 | 提供/保管 `.env.deploy`（运维） |
| Agent | 工程 + push + 调 MCP 工具 + 交付 URL | 工程 + push + 直调 Dokploy API |
| company-deploy-mcp | 身份/配额/审计/Gitea 建库/Dokploy 编排 | — |
| Gitea | 源码 | 源码 |
| Dokploy | 构建运行/卷/库/Traefik+LE | 同左（Agent 直调） |
---
## 异步语义
| 动作 | 含义 |
|------|------|
| `apply_deployment_plan` 返回 200 | 已受理编排与 deploy 请求 |
| `deploymentRequested: true` | 不等于用户已可稳定访问 |
| 上线完成 | Dokploy 部署终态成功 +（Web）HTTPS 探活通过 |
构建失败：`get_deployment_status` / `get_sanitized_logs`，修代码或 Dockerfile 后新 SHA 再 plan+apply。

183
dokploy-gitea-deploy/references/stack-profiles.md Normal file
View File

@@ -0,0 +1,183 @@
# 技术栈构建约定（Agent 改 Dockerfile 时遵循）
## 通用
1. 基础镜像：Docker Hub（`python:*` / `node:*` / `nginx:*`），避免默认 `ghcr.io`。
2. 多阶段或「依赖层 → 代码层」拆分。
3. BuildKit：`--mount=type=cache` 缓存包管理器目录。
4. 生产 `CMD`/`ENTRYPOINT` 明确；进程监听 **`spec.port`**（与 plan 一致）。
5. 健康检查：实现 `/healthz` 或约定路径，写入 `spec.healthcheckPath`。
6. Dokploy **不要每次 cleanCache**。
7. **有状态数据写挂载路径**（见下），不要只写容器可写层。
---
## 持久化与 `/data`（MCP 默认）
控制面默认为每个应用挂载 **容器内 `/data`**（可配置，见 `inspect_project` → `policy.storage`）。
| 约定 | 说明 |
|------|------|
| SQLite / 本地文件 | 路径放在 `/data/...`，例如 `/data/app.db` |
| 上传目录 | 额外 `persistence`：`{ "name": "uploads", "mountPath": "/var/uploads" }` |
| 日志 | ephemeral 可写容器内；需保留则挂卷 |
| 多卷 | `spec.persistence[]`；若未包含 `/data`，控制面仍自动补默认卷 |
示例环境变量（应用代码侧）：
```text
DATA_DIR=/data
DATABASE_PATH=/data/app.db
```
**禁止**假设宿主机路径；只认容器内 `mountPath`。
---
## 托管数据库（Postgres / MySQL）
plan 中声明 `spec.databases[]` 后，控制面注入连接串环境变量（默认名 `DATABASE_URL`）。
应用应：
1. 启动时读取 `process.env.DATABASE_URL`（或自定义 `envVar`）
2. **不要**在镜像里写死密码
3. 迁移在启动脚本或独立 job 中执行（注意并发与锁）
示例（Node）：
```js
const url = process.env.DATABASE_URL;
if (!url) throw new Error("DATABASE_URL is required");
```
示例（Python）：
```python
import os
url = os.environ.get("DATABASE_URL")
if not url:
raise RuntimeError("DATABASE_URL is required")
```
Docker 内网 host 由 Dokploy 管理；应用只消费完整 URL。
---
## Python（uv 优先）
检测：`pyproject.toml` + `uv.lock`，或 `requirements.txt`。
推荐结构：
```dockerfile
FROM python:3.12-slim-bookworm
WORKDIR /app
ENV UV_LINK_MODE=copy \
UV_CONCURRENT_DOWNLOADS=16 \
UV_HTTP_TIMEOUT=120 \
PYTHONUNBUFFERED=1
ARG PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
ENV UV_DEFAULT_INDEX=${PIP_INDEX_URL} \
UV_INDEX_URL=${PIP_INDEX_URL} \
PIP_INDEX_URL=${PIP_INDEX_URL}
RUN --mount=type=cache,target=/root/.cache/pip \
pip install --no-cache-dir "uv>=0.6.0"
COPY pyproject.toml uv.lock README.md ./
RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --frozen --no-dev --no-install-project
COPY src ./src
# …其它源码…
RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --frozen --no-dev
# 监听 0.0.0.0，端口与 plan.spec.port 一致
ENV DATA_DIR=/data
EXPOSE 8000
CMD ["uv", "run", "your-entrypoint"]
```
说明：
- 慢点通常是 **PyPI 下包**，不是 `pip install uv` 本身。
- 主机 `~/.pip/pip.conf` **不会**自动进容器；必须 Dockerfile/build-arg。
- 飞书长连接类：`replicas=1` + 状态进 `/data`；`exposeWeb: false` 若无需公网页。
---
## Node（pnpm / npm）
检测：`package.json`，优先 `pnpm-lock.yaml` → `package-lock.json` → `yarn.lock`。
推荐结构（standalone / 需 `node` 运行）：
```dockerfile
FROM node:22-bookworm-slim AS deps
WORKDIR /app
RUN corepack enable
COPY package.json pnpm-lock.yaml ./
# 可选：COPY .npmrc ./
RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
pnpm install --frozen-lockfile
FROM node:22-bookworm-slim AS build
WORKDIR /app
RUN corepack enable
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN pnpm run build
FROM node:22-bookworm-slim AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV DATA_DIR=/data
COPY --from=build /app/dist ./dist
COPY --from=build /app/package.json ./
COPY --from=deps /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/index.js"]
```
静态前端（Vite 等）可用 `nginx:stable-alpine` 拷 `dist`；`spec.port` 多为 `80`。
Registry 加速示例 `.npmrc`（可提交或构建时注入）：
```ini
registry=https://registry.npmmirror.com
```
---
## Docker Compose
- 当前 MCP MVP **仅** `buildType: dockerfile` 单应用。
- 多服务 Compose：legacy / 运维在 Dokploy 选 Compose 类型，或拆成多个 MCP 应用 + 托管 DB。
- 生产注意：DB 密码走 `databases[]` 注入；卷走 `persistence[]`。
---
## 构建耗时预期（经验）
| 场景 | 预期 |
|------|------|
| 首次全量（弱网 + 下包） | 10–40 分钟可能 |
| 依赖层已缓存，只改代码 | 数分钟内 |
| 仅拉预构建业务镜像 | 通常更短 |
若日志出现 `Prepared N packages in 30m`：换源 + 分层缓存 + 禁止 cleanCache；长期用私有镜像仓库。
---
## 与 plan.spec 对齐检查
部署前 Agent 自检：
- [ ] 容器监听 `0.0.0.0:$PORT`，且 `spec.port` 一致
- [ ] 有状态路径落在 `/data` 或其它 `persistence.mountPath`
- [ ] 需要 PG/MySQL 时 plan 带 `databases`，代码读对应 env
- [ ] Web 服务 `exposeWeb: true`（默认）；Worker 显式 `false`
- [ ] `.gitignore` 排除 `.env`、密钥、本地 db