上个月，我被分配了一个从没碰过的任务：把部门里跑了两周的VeADK Agent 项目从开发机搬到测试服务器，并且要做到"一键容器化部署"。之前大家的习惯是手动建虚拟环境、配systemd、逐个装依赖，每次环境不一样，光一个Python 版本对不上就能折腾一整天。这次我选择了 Docker 作为突破口，从写第一个 Dockerfile 到最终用 Docker Compose 拉起整套 Agent 服务，中间踩了不少坑，也把 VeADK Agent 的并发、会话状态、优雅退出这些问题挨个理了一遍。这篇文章我会把整套部署思路、关键配置文件、排查链路和压测数据都放出来，希望对正在做 Agent 容器化部署的同学有实际参考价值。
1. 为什么 VeADK Agent 非要容器化：裸进程部署的三个硬伤
先别急着写 Dockerfile。如果没想清楚"为什么要容器化"，后面每个决策都会犹豫。我一开始也觉得 systemd + 虚拟环境勉强能用，直到三个问题同时砸过来。
1.1 环境漂移才是排障噩梦的根源
我们有三台测试机，一台 Ubuntu 20.04，两台 CentOS 7.9。VeADK Agent 依赖的底层 C 扩展库（比如 tokenizer 相关的分词库、音频工具链里的 libsndfile）在三个环境里安装路径、动态链接库版本都不一样。第一周，问题清单里有一半是"A 机器上跑通，B 机器上报找不到 libffi.so.7"。每次排查都要先在服务器上敲一堆 ldconfig、which python3、pip list，浪费的时间比写业务代码还多。
容器化的核心价值就是保证"构建一次，到处运行"。镜像把 Python 解释器、系统库、依赖包全部锁死在同一个文件系统里，宿主机上有什么根本无所谓。我后来把这句话写进了团队部署文档：环境漂移不是运维问题，而是工程债。
1.2 Agent 的依赖洁癖比普通 Web 服务更严重
普通 Web 服务依赖的库相对集中，顶多是 Flask/Django 那套。VeADK Agent 不一样，它内部有意图识别、工具调用编排、大模型 API 交互、向量检索等多个模块，需要的依赖横跨 NLP、网络、并发调度三个方向。
我在准备虚拟环境时发现，光 requirements.txt 就有 80 多个包，而且版本兼容关系非常脆弱。比如某个版本的 pydantic 和 langchain 类工具库不兼容，装完后 import 阶段直接报 ValidationError；某个加密库需要系统编译工具链，没有 gcc 时 pip install 会原地卡死。这些依赖如果在宿主机上直接装，会把测试机弄成一团乱麻；但如果做进镜像里，所有版本关系都可以在构建日志里复现，出了问题顶多重打一遍镜像。
1.3 任务队列的波峰波谷需要快速扩缩容
VeADK Agent 承接的业务有明显的潮汐特征：白天高峰期每分钟会涌入大量会话请求，凌晨基本没有流量。裸进程部署时，要扩容只能手动复制整套环境再起一个 systemd 服务，等高峰期过了再手动杀掉，操作繁琐不说，还容易漏掉资源清理。
容器化之后，扩容就是 docker compose up -d --scale worker=3 一行命令的事，缩容同理。这个能力在 Agent 场景里尤其重要，因为 Agent 任务不像普通 HTTP 请求那么轻，每个会话可能持续几十秒甚至几分钟，背着的并发太高容易打爆上游大模型 API 的限流配额。容器让"按需扩容"真正变成了可能。
2. 部署方案选型：基础镜像、编排工具与进程模型
确定要做容器化之后，接下来是选型。这一步我走了不少弯路，最深的体会是：选型要结合 Agent 的运行特征，不能照搬 Web 项目的部署方案。
2.1 基础镜像选择：slim 胜过 alpine
VeADK Agent 的核心依赖里有大量 Python C 扩展和部分需要 glibc 的二进制库。一开始我图镜像体积小，选了 python:3.11-alpine，结果在构建到某个音频处理库时直接报错——alpine 用的是 musl libc，很多预编译的 wheel 包不兼容，强制编译又需要额外的 build-base，反而更痛苦。
后来换成了 python:3.11-slim，它是 Debian 底子，兼容性比 alpine 好得多。slim 镜像虽然比 alpine 大几十 MB，但省去了一堆"缺头文件""缺动态库"的坑，构建一次能省一个小时。如果你也碰到类似情况，我的建议是：除非明确知道所有依赖都有 musl 版本，否则别碰 alpine。
2.2 编排工具：单机 Compose，集群再上 K8s
我们首批部署目标是两台测试机，副本数量不会超过 10 个，这时候上 Kubernetes 纯属给自己找麻烦。Docker Compose 足够覆盖单机多容器的编排需求，而且学习成本低，一条 docker compose up -d 就能把整套环境拉起来。
后续如果要上生产集群，Compose 文件可以直接转换成 Kubernetes 的 Deployment YAML 思路，只是把 restart、scale 这些语义换成 K8s 的字段。所以我建议中小团队从 Compose 起步，先把"一键部署"跑通，再考虑编排平台的事。
2.3 Agent 进程模型决定了容器数量
VeADK Agent 的逻辑分三层：对外提供 HTTP 接口的 api 服务、消费任务队列的 worker 进程、以及存储会话状态的状态层。最开始我想把所有功能塞进一个容器，省事；但实测下来，api 服务和 worker 的资源需求差异很大——api 服务吃内存但 CPU 压力小，worker 在做工具调用和大模型推理时 CPU 冲得很高。
所以我最终拆成两个容器：api 和 worker。共享同一个镜像，用不同的启动命令区分角色。这样调优时可以单独给 worker 配 CPU 上限，给 api 配内存上限，互不干扰。
3. 镜像构建：Dockerfile 的完整写法和镜像瘦身记录
这是整篇里实操密度最高的一节。我把最终版本的 Dockerfile 贴出来，然后逐段解释为什么这么写。
3.1 多阶段构建把编译期依赖和运行期依赖分开
VeADK Agent 里有几个依赖包需要编译安装，比如 pydantic-core、orjson 这类 Rust 扩展。如果所有编译工具都留在最终镜像里，镜像体积会膨胀到 1.2GB 以上。
多阶段构建的核心思想是：第一阶段装齐全套编译工具，把 wheel 包编译出来；第二阶段只拷贝编译好的 wheel 和运行期依赖，不保留编译器。这样最终镜像干净，也不用担心 gcc 带来的安全风险。
# 阶段一：构建 wheel FROM python:3.11-slim AS builder ENV PIP_NO_CACHE_DIR=1 \ PIP_DISABLE_PIP_VERSION_CHECK=1 RUN apt-get update && apt-get install -y --no-install-recommends \ build-essential \ libffi-dev \ libssl-dev \ && rm -rf /var/lib/apt/lists/* WORKDIR /build COPY requirements.txt . RUN pip wheel --wheel-dir /wheels -r requirements.txt # 阶段二：运行时镜像 FROM python:3.11-slim AS runtime RUN apt-get update && apt-get install -y --no-install-recommends \ curl \ ca-certificates \ && rm -rf /var/lib/apt/lists/* RUN groupadd -r veadk && useradd -r -g veadk veadk WORKDIR /app COPY --from=builder /wheels /wheels RUN pip install --no-cache-dir /wheels/*.whl && rm -rf /wheels COPY --chown=veadk:veadk . /app USER veadk EXPOSE 8000 ENTRYPOINT ["/usr/local/bin/tini", "--", "python", "-m", "veadk"]注意几个关键点：
- tini 作为 init 进程：容器里 PID 1 必须是能妥善转发信号的进程，否则 docker stop 时 Agent 收不到 SIGTERM，会直接强杀，导致会话状态写了一半丢失。tini 是最轻量的方案。
- USER veadk：以非 root 运行是基本安全要求，避免容器被攻破后直接拿到宿主机的 root 权限。
- COPY 顺序：先把 requirements.txt 复制进去装依赖，再复制源码。这样只要依赖没变，Docker 就会命中缓存层，迭代代码时不需要重新装依赖。
3.2 BuildKit 缓存让构建提速三倍
第一次用默认构建方式，每次改一行代码都要重新 pip install 几十个包，一次构建六七分钟，人直接麻了。后来开启 BuildKit 的依赖缓存，构建时间降到了两分钟以内。
在构建前加一行环境变量：
export DOCKER_BUILDKIT=1然后在 Dockerfile 里把 pip 安装依赖的步骤改成挂载缓存：
RUN --mount=type=cache,target=/root/.cache/pip \ pip install --no-cache-dir /wheels/*.whl && rm -rf /wheels这样 pip 的缓存目录会被持久化到构建缓存里，二次构建时下载过的包直接复用，不再重复拉取。实测下来这个改动是投入产出比最高的优化，强烈建议所有基于 Python 的 Docker 镜像构建都这么改。
3.3 镜像体积从 1.2GB 瘦到 480MB
构建完第一版镜像，docker images 一看 1.2GB，吓一跳。瘦身我做了三件事：
第一，去掉构建阶段的编译工具。上面多阶段构建已经做了，这一步直接抹掉了近 500MB。 第二，清理运行时不需要的系统包。运行时只保留 curl 用于健康检查，连 vim、iputils 都没装。 第三，用 pip install 的 --no-cache-dir 去掉 pip 缓存。
最终体积 480MB，虽然比不上那些几百 KB 的 Go 镜像，但在 Python 生态里已经算很能打了。
| 优化项 | 体积变化 | 说明 |
|---|---|---|
| 单阶段构建 | 1.2GB | 编译工具全部留在镜像里 |
| 多阶段构建 | 520MB | 编译期依赖进 builder 阶段 |
| 清理系统包 + pip 缓存 | 480MB | 只留健康检查所需工具 |
4. 编排部署：一份可以直接抄的 Compose 配置
镜像构建完成，接下来是编排。我用 Docker Compose 把 api、worker、Redis（会话状态外部化）、以及日志采集容器串起来。这一节给出完整配置并逐段解释。
4.1 Compose 文件逐段解析
version: "3.8" services: redis: image: redis:7-alpine restart: unless-stopped command: redis-server --appendonly yes --maxmemory 512mb --maxmemory-policy allkeys-lru volumes: - veadk-redis-data:/data healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 10s timeout: 5s retries: 5 api: image: registry.internal/veadk-agent:1.4.2 restart: unless-stopped command: ["python", "-m", "veadk.api", "--workers", "4"] env_file: - .env depends_on: redis: condition: service_healthy ports: - "8000:8000" volumes: - veadk-sessions:/data/sessions - veadk-logs:/data/logs healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/healthz"] interval: 15s timeout: 5s retries: 3 start_period: 20s worker: image: registry.internal/veadk-agent:1.4.2 restart: unless-stopped command: ["python", "-m", "veadk.worker", "--concurrency", "8"] env_file: - .env depends_on: redis: condition: service_healthy volumes: - veadk-sessions:/data/sessions - veadk-logs:/data/logs deploy: resources: limits: cpus: "4.0" memory: 4g healthcheck: test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:9100/status')"] interval: 15s timeout: 5s retries: 3 start_period: 30s volumes: veadk-redis-data: veadk-sessions: veadk-logs:几个需要重点说明的设计：
redis 的 appendonly yes 和 maxmemory 策略。VeADK Agent 的会话状态需要持久化，Redis 开了 AOF 之后重启不丢数据；maxmemory 限制了 Redis 不会把宿主机内存吃满，allkeys-lru 保证了状态过期自动淘汰。这套配置用来做会话状态层已经足够稳。
depends_on 的 condition: service_healthy。不加这个条件时，api 和 worker 会在 redis 还没就绪时就启动，连接池疯狂报错。加上健康检查后，Compose 会等 redis 健康了才启动下游服务。这个是我踩了好几次坑后才加上的。
api 和 worker 共享镜像、不同 command。两者用同一份代码构建，但启动的角色不同。api 进程只处理 HTTP 请求，worker 进程消费任务队列。资源限制在 worker 上单独设置，因为我实测 worker 比 api 更吃 CPU。
4.2 密钥管理：API Key 绝不写进镜像
VeADK Agent 要调用大模型 API，密钥必须处理。最开始的版本我把 API Key 直接写进了环境变量构建进镜像，结果有同事把镜像 push 到内部仓库后，密钥等于裸奔了。
正确做法是 Compose 里引用 env_file，镜像只留占位变量。.env 文件不进 git，只在宿主机上维护：
LLM_API_KEY=sk-xxxx REDIS_URL=redis://redis:6379/0 SESSION_STORAGE=redis LOG_LEVEL=info启动时用 docker compose --env-file .env up -d 加载。这样镜像本身是"无状态"的，任何拿到镜像的人看不到密钥。
4.3 健康检查和启动顺序是稳定性地基
健康检查这块我吃了不少苦头。VeADK Agent 的启动过程比较重——它要加载意图识别模型、初始化工具调度器、连大模型 API 做一次连通性测试，这些加起来要 5 到 15 秒。
如果健康检查的 start_period 设置太短，容器会被反复标记为 unhealthy，接着被重启，形成一个死循环。我最后给 api 设了 start_period: 20s，worker 因为要加载更多模型，设了 30s。一个原则：start_period 的长度必须大于进程最慢的冷启动时间。
健康检查还有个隐藏好处：Docker 的负载均衡和上层调度器会依据健康状态摘除有问题实例。我在压测时故意杀掉一个 worker，流量自动切到了健康实例上，整个过程没有人工干预。
5. Agent 运行时的特殊问题：状态保持、优雅退出与日志追踪
普通 Web 服务容器化只要考虑无状态就行，Agent 最大的不同在于它是有状态的。会话可能在中间某一步暂停，等大模型返回，再继续执行工具调用。这给容器部署带来三个额外要求。
5.1 有状态会话如何映射到容器文件系统
VeADK Agent 默认把会话数据存在本地 SQLite 文件里。容器化之后，容器随时可能被销毁重建，本地文件不持久化的话，用户会话一旦中断就找不回来。
我的方案是：会话数据挂到宿主机命名卷。compose 文件里的 veadk-sessions 卷会持久化到宿主机 Docker 数据目录，容器重建后数据还在。同时，为了支持未来横向扩容，我把"活跃会话索引"放在了 Redis 里，SQLite 只存完整的历史快照。这样多个 worker 实例可以通过 Redis 共享会话锁，避免同一个会话被两个 worker 同时处理。
如果会话量进一步涨，建议把 SQLite 换成 PostgreSQL 或者对象存储，我们的数据量目前还没到那一步，但架构上已经预留了切换空间。
5.2 优雅停机：让 Agent 把手头的活儿干完
普通进程 kill 掉重来就完了，Agent 不行。worker 可能在某个会话里已经执行了工具调用，就差最后一步写回结果，这时候把它杀了，用户的请求就永远卡住了。
我在三个层面上做了优雅停机：
- Dockerfile 里用 tini 做 init，SIGTERM 能正确转发到 Python 进程。
- VeADK Agent 的 worker 模块里注册了 SIGTERM 信号处理函数。收到信号后停止拉取新任务，但已经在执行的任务会继续跑完，最多等待 30 秒（可在环境变量里调）。
- Compose 里设置 stop_grace_period: 60s。如果 30 秒内任务没跑完，Docker 也不会立刻强杀，会等到 60 秒超时才开始 SIGKILL。
这套组合下来，我用 docker compose stop 做过实验：所有正在处理的会话都正常结束，没有一条半截记录。Agent 的优雅退出，本质上就是给正在处理的请求留够时间。
5.3 日志规范：单条会话全链路追踪
Agent 的日志比普通服务更难排查，因为一个用户请求会经过 api 转发、worker 调度、多次工具调用、大模型 API 往返。如果没有统一的会话 ID，日志看起来就是一锅粥。
我在 VeADK Agent 的日志层做了两件事：
第一，所有业务日志都带上 veadk_session_id 字段。这个 ID 在 api 收到请求时生成，通过消息队列传给 worker，工具调用时继续透传。排查问题时，只需要在日志系统里按 session_id 搜索，整条链路就出来了。
第二，日志格式统一为结构化 JSON，方便采集和分析。
{ "time": "2025-05-12T10:24:11.003Z", "level": "INFO", "logger": "veadk.worker", "session_id": "abc123", "event": "tool_call", "tool": "web_search", "duration_ms": 823, "queue_wait_ms": 12 }容器里日志打到 stdout，让 Docker 自动接管。后面接 filebeat 或 Promtail 就能直接送到日志平台，不需要在容器里再装 agent。
6. 上线实测：三个让我熬夜的坑和完整排查链路
部署方案看着没问题，真到实测环节还是连续翻车。我把最典型的三个问题写出来，每个都从现象、排查到根因给出完整链路，希望能帮你少走点弯路。
6.1 坑一：容器正常启动，Agent 进程几秒后消失
现象是 docker ps 显示容器处于运行状态，但 docker logs 只输出几行就没了。一开始我以为是代码问题，后来发现是健康检查失败了——compose 会不断重启容器，但 Docker 不告诉你重启原因。
排查链路：
- docker ps -a 看到 api 容器的 STATUS 是 "Restarting (137) 3 seconds ago"。
- 退出码 137 是 128 + 9，表示被 SIGKILL。
- docker inspect 看 OOMKilled 字段，发现是 true。
根因：我用 start_period 设了 20s，但 api 冷启动要 15 秒左右，而资源限制只给了 512MB 内存。VeADK Agent 加载意图识别模型时内存突增到 700MB，直接触发 OOM Killer。
解决：内存上限调到 2GB，start_period 加长的同时，把模型文件做成懒加载，启动时只建索引，第一次请求才载入模型。这样冷启动内存能降到 300MB 以下，容器稳定运行。
6.2 坑二：并发一上来，大模型 API 调用大量超时
压测跑到第 5 分钟，日志里刷屏出现 429 和 timeout 错误。我第一反应是 Redis 连接池太小，查了半天发现根本不是。
排查链路：
- 看 Redis 监控，连接数正常，QPS 没到瓶颈。
- 看 worker 日志，发现 timeouts 全部发生在调用上游大模型 API 的阶段。
- 查 Compose 配置，worker 的并发数设了 8，但上游大模型 API 的账号限流是每分钟 50 次请求。
根因：worker 并发数超过了上游 API 配额，请求被限流。
解决：在 VeADK Agent 里加了一层令牌桶限流器，把调用大模型 API 的速率控制在每分钟 45 次；同时增加重试机制，对 429 响应做指数退避。改完后压测稳定通过，超时率从 12% 降到了 0.3%。
这个坑给我的教训是：Agent 的并发瓶颈往往不在自己的服务，而在上游 API 的配额。
6.3 坑三：镜像层缓存失效，每次构建都全量重来
这是最让人抓狂的一个问题。明明只改了一行代码，构建却要等三分钟重新下载所有依赖。
排查链路：
- docker buildx build 带 --progress=plain 看每一层的执行状态。
- 发现 RUN pip install 之前的 COPY requirements.txt 这层显示 cache busted。
- 用 diff 对比宿主机上的 requirements.txt 与构建上下文里的 requirements.txt，内容完全一致。
根因：BuildKit 在计算缓存 hash 时，会把整个构建上下文加进去。我的 .dockerignore 没写全，把 .git 目录和本地虚拟环境 .venv 都打进了上下文，导致任何文件变动都会让依赖层的缓存失效。
解决：补齐 .dockerignore：
.git .venv __pycache__ *.pyc test/ docs/ .env加上之后，改业务代码时依赖层稳定命中缓存，构建时间从三分钟降到四十几秒。BuildKit 缓存失效，九成是 .dockerignore 写得不够干净。
7. 压测与调优：VeADK Agent 并发承载能力实测
排完坑，我做了两轮压测，目的是搞清楚"这套容器化部署到底能扛多少并发"，顺便把资源限制调到一个合理区间。
7.1 单容器并发压测数据
压测环境：两台 8C16G 的测试机，api 容器限制 2C4G，worker 容器限制 4C8G，Redis 单独跑在宿主机上。
第一轮压测：同时开启 50 个会话请求，每个会话平均需要调用 2 次工具、1 次大模型推理。结果如下：
| 指标 | 数值 |
|---|---|
| 会话成功率 | 99.2% |
| 平均响应时间 | 4.8s |
| P99 响应时间 | 12.6s |
| worker CPU 使用率 | 稳定在 72% |
| 大模型 API 超时率 | 0.3% |
第二轮把并发提高到 100 个会话，api 和 worker 都没崩，但大模型 API 的超时率爬到了 4%。说明瓶颈在上游，不在容器本身。
7.2 资源限制的合理阈值
实测后我把资源限制确定成了下面这组参数：
| 服务 | CPU | 内存 | 说明 |
|---|---|---|---|
| api | 1.0 | 1GB | 吃内存少，CPU 限制太狠反而增加排队 |
| worker | 4.0 | 6GB | 工具调用和大模型推理是 CPU 大户 |
| redis | 0.5 | 512MB | 加上 maxmemory 限制，防止膨胀 |
有个细节：worker 内存上限 6GB 比实际常驻内存 4GB 多预留了 50%，原因是 Agent 在极端情况下会有多个会话同时执行任务，内存会瞬时冲高。压测时如果只给 4GB，OOM Killer 会准时出现。
7.3 横向扩容后的一致性处理
单容器再优化也有上限，高峰期我把 worker 扩到了 3 个副本：
docker compose up -d --scale worker=3 --scale api=2扩容本身没问题，但很快发现一个问题：会话锁在 Redis 里是全局的，三个 worker 同时消费队列时，可能出现同一个会话被两个 worker 拉到的竞态。我的解决方式是给队列消费加了一条分布式锁，用 Redis 的 SETNX 实现，锁超时时间设 10 秒。实测扩容到 3 个 worker 后，会话冲突率为 0。
另外一个一致性问题是：会话快照存的是宿主机命名卷，多个副本共享同一份数据没问题；但如果后续拆到多台机器，这份快照就必须挪到 Redis 或对象存储。目前在单机多副本阶段，命名卷方案还够用。
8. 从这套方案里沉淀下来的几点体会
部署做完之后我回头总结，发现 VeADK Agent 容器化这件事，真正的难点不在 Docker 语法，而在"怎么理解 Agent 的运行特征"。
容器化的本质是把运行环境固化，让"这里能跑""那里也能跑"；而 Agent 的本质是有状态、长耗时、依赖外部 API 的异步任务。这两者结合，意味着不能拿无状态 Web 服务的部署思维来套。
几个我觉得最值得记住的点：
第一，镜像层优先把依赖锁死，环境漂移问题一次性清零。多阶段构建加上 BuildKit 缓存，能让迭代成本降到最低，这钱花得值。
第二，Compose 里健康检查、启动顺序、优雅退出缺一不可。Agent 冷启动慢、任务周期长，任何一步没做好，线上表现就是"容器明明活着，事情却没办成"。
第三，Agent 的扩容要考虑会话一致性和上游 API 配额。先把 Redis 上的会话锁做好，再谈横向扩多个 worker，否则并发一上去全是坑。
最后再分享一个小技巧：我在所有容器里统一加了 veadk.version 标签，发布时照着版本号滚动升级。以后排查问题，先看容器跑的哪个版本，再看日志里的 session_id，基本五分钟之内能定位到问题根因。这套方案现在跑了两周，零故障，团队里再也没人跟我抱怨"环境又对不上了"。
