# 生产容器镜像说明 ## 范围 DEPLOY-001 使用同一个锁定运行时构建三个独立镜像目标: | Target | 默认镜像名 | 入口 | 端口 | 镜像健康检查 | |---|---|---|---|---| | `api` | `enterprise-knowledge-api` | Uvicorn + API/Admin | `8000` | `GET /healthz` | | `mcp` | `enterprise-knowledge-mcp` | `ekp-mcp` | `8766` | PID 1 存活 | | `worker` | `enterprise-knowledge-worker` | `ekp-worker` | 无 | PID 1 存活 | 镜像没有内置数据库迁移、Helm、Ingress 或 Secret 对象;DEPLOY-002 已在独立 Chart 中提供这些 编排能力。API 镜像包含 Alembic 和 migrations,由一次性 Migration Job 覆盖命令后复用。详见 [`KUBERNETES_DEPLOYMENT.md`](KUBERNETES_DEPLOYMENT.md)。 ## 可重复构建基线 - Python 基础镜像固定为 `3.12.14-slim-bookworm`,uv 固定为 `0.12.5`,两者同时锁定 manifest digest; - Python 依赖只使用提交的 `uv.lock`,以 `uv sync --frozen --no-dev --no-editable` 安装; - 三个目标共享相同依赖层,不复制不同版本的业务运行时; - 进程均以固定 UID/GID `10001:10001` 运行,不具备 root 权限; - `.dockerignore` 排除 `.env`、Git、虚拟环境、缓存、本地存储、测试和开发产物; - Bake 计划同时声明 `linux/amd64` 与 `linux/arm64`,不下载或打包平台专属模型。 基础镜像 tag/digest 与应用依赖均已固定;镜像发布系统仍应保存本项目镜像的构建 digest,并让 Helm 按 digest 部署。本项目镜像 digest 由实际 Registry 发布产生,不把某个环境的 Registry 地址写入仓库。 ## 构建命令 先确认 Docker Buildx builder 支持两个目标平台: ```bash make images-print ``` 构建全部目标: ```bash IMAGE_REGISTRY=registry.example.internal/knowledge \ IMAGE_TAG= \ make images ``` 只有发布流水线才执行推送: ```bash IMAGE_REGISTRY=registry.example.internal/knowledge \ IMAGE_TAG= \ make images-push ``` 不要把 Registry 密码放入变量或命令行;构建节点应提前通过其凭据助手登录。禁止使用 `latest` 作为集群部署版本。 ## 运行时配置 镜像只内置以下非敏感进程默认值:`APP_ENV=production`、容器监听地址、静态页面绝对路径和 临时缓存目录。OceanBase、BOS、RabbitMQ、Embedding、Reranker 与 MCP Token 必须在容器启动 时由 Secret 注入。镜像构建参数、Layer、标签、健康检查和启动命令都不得包含这些值。 API 的 `/healthz` 只证明进程存活,不读取云端凭据或探测依赖。Kubernetes readiness、资源限制、 只读根文件系统所需临时卷及依赖就绪策略由 DEPLOY-002 Chart 配置。MCP endpoint 需要认证,Worker 没有 HTTP server,因此这两个镜像的 Docker 健康检查只验证主进程;业务可恢复性仍以持久化 Job/Attempt 和 DEPLOY-003 故障验收为准。 ## 本地单目标检查 需要加载到本地 Docker 时,可直接构建当前平台的一个 target: ```bash docker build --target api -f deploy/docker/Dockerfile -t ekp-api:test . docker build --target mcp -f deploy/docker/Dockerfile -t ekp-mcp:test . docker build --target worker -f deploy/docker/Dockerfile -t ekp-worker:test . ``` 启动时使用 `--env-file` 或编排系统的 Secret 引用,不在命令中展开敏感值。API/Admin smoke test 至少检查 `/healthz`、`/admin/upload` 和 `/api/v1/openapi.json`;MCP 与 Worker 的真实依赖启动 验收在具备 RabbitMQ 和目标 Provider 的受控环境执行。 ## DEPLOY-001 构建验收 2026-09-02 已使用 Buildx 分别构建并加载三个 `linux/arm64` target 和三个 `linux/amd64` target。API/Admin 以非 root 用户完成健康、静态页面和 OpenAPI smoke test;MCP/Worker 完成非 root 安装入口检查。构建历史与容器文件系统检查未发现 `.env`、Git、测试文件或敏感配置。 这次验收只生成本地 `deploy001-*` 测试 tag,没有登录或推送 Registry,因此不产生可供集群 引用的项目镜像 digest。DEPLOY-002 必须使用操作者指定的不可变 Registry tag/digest,不得把 本地测试 tag 当作发布版本。