用 Docker Compose 搭一套本地 AI Agent 调试环境

背景

在做一个基于大模型的 Agent 项目时，最麻烦的往往不是模型调用本身，而是本地环境：Python 版本、向量库、缓存、网关代理，每换一台机器就要重来一遍。这篇文章记录我用 Docker Compose 把整套调试栈固化下来的过程，启动一条命令，环境可复制。

整体结构

最小可用栈包含四个组件：

• `agent-app`：业务代码，FastAPI 暴露 8000 端口

• `redis`：会话上下文与限流计数

• `qdrant`：向量检索，做知识库召回

• `nginx`：统一入口，顺手做请求日志

compose 文件

services:
  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes
    volumes: [redis-data:/data]
  qdrant:
    image: qdrant/qdrant:latest
    volumes: [qdrant-data:/qdrant/storage]
  agent-app:
    build: .
    environment:
      REDIS_URL: redis://redis:6379/0
      QDRANT_URL: http://qdrant:6333
    depends_on: [redis, qdrant]
  nginx:
    image: nginx:alpine
    ports: ["8080:80"]
    volumes: [./nginx.conf:/etc/nginx/conf.d/default.conf:ro]
    depends_on: [agent-app]
volumes:
  redis-data:
  qdrant-data:

几个踩过的坑

**1. 容器内 DNS 解析慢**：Agent 里要访问外部模型 API，容器默认 DNS 偶尔会卡 5 秒。显式在 service 上加 `dns: 223.5.5.5` 后请求耗时从 5.2s 降到 0.3s。

**2. 向量库首次写入慢**：qdrant 冷启动后第一次 upsert 会建索引，建议在健康检查里等 `/readyz` 返回 200 再让应用启动，否则会拿到 503。

**3. 日志混在一起看不清**：给每个服务加 `logging: driver: json-file, options: max-size: 10m`，再用 `docker compose logs -f agent-app` 单独盯业务日志，排查效率高很多。

效果

原来新同事配环境平均 40 分钟，现在 `docker compose up -d` 之后 90 秒内就能跑通一次完整对话。镜像分层缓存之后，二次构建只要 8 秒左右。

小结

本地调试环境值得当成基础设施来做。Compose 不是生产部署方案，但作为「一键复现」的载体非常合适，尤其是团队里模型、应用、数据三条线并行开发的时候。