knowledge-platform/docs/development/CONTAINER_IMAGES.md
2026-09-03 12:21:54 +08:00

4.1 KiB
Raw Blame History

生产容器镜像说明

范围

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 当作发布版本。