4.1 KiB
生产容器镜像说明
范围
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。
可重复构建基线
- 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 支持两个目标平台:
make images-print
构建全部目标:
IMAGE_REGISTRY=registry.example.internal/knowledge \
IMAGE_TAG=<immutable-release-tag> \
make images
只有发布流水线才执行推送:
IMAGE_REGISTRY=registry.example.internal/knowledge \
IMAGE_TAG=<immutable-release-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:
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 当作发布版本。