92 lines
4.1 KiB
Markdown
92 lines
4.1 KiB
Markdown
# 生产容器镜像说明
|
||
|
||
## 范围
|
||
|
||
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=<immutable-release-tag> \
|
||
make images
|
||
```
|
||
|
||
只有发布流水线才执行推送:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```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 当作发布版本。
|