技术栈构建约定（Agent 改 Dockerfile 时遵循）

通用

基础镜像：Docker Hub（python:* / node:* / nginx:*），避免默认 ghcr.io。
多阶段或「依赖层 → 代码层」拆分。
BuildKit：--mount=type=cache 缓存包管理器目录。
生产 CMD/ENTRYPOINT 明确；进程监听 spec.port（与 plan 一致）。
健康检查：实现 /healthz 或约定路径，写入 spec.healthcheckPath。
Dokploy 不要每次 cleanCache。
有状态数据写挂载路径（见下），不要只写容器可写层。

持久化与 `/data`（MCP 默认）

控制面默认为每个应用挂载 容器内 /data（可配置，见 inspect_project → policy.storage）。

约定	说明
SQLite / 本地文件	路径放在 `/data/...`，例如 `/data/app.db`
上传目录	额外 `persistence`：`{ "name": "uploads", "mountPath": "/var/uploads" }`
日志	ephemeral 可写容器内；需保留则挂卷
多卷	`spec.persistence[]`；若未包含 `/data`，控制面仍自动补默认卷

示例环境变量（应用代码侧）：

DATA_DIR=/data
DATABASE_PATH=/data/app.db

禁止假设宿主机路径；只认容器内 mountPath。

托管数据库（Postgres / MySQL）

plan 中声明 spec.databases[] 后，控制面注入连接串环境变量（默认名 DATABASE_URL）。

应用应：

启动时读取 process.env.DATABASE_URL（或自定义 envVar）
不要在镜像里写死密码
迁移在启动脚本或独立 job 中执行（注意并发与锁）

示例（Node）：

const url = process.env.DATABASE_URL;
if (!url) throw new Error("DATABASE_URL is required");

示例（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。

推荐结构：

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 运行）：

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（可提交或构建时注入）：

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

5.2 KiB Raw Blame History Unescape Escape