# 技术栈构建约定（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