跑在笔记本上的 Agent 一切正常，推到测试服务器后却开始报 ModuleNotFoundError；昨天还能用的流程，今天突然提示 CUDA 版本不匹配。这类问题几乎每个做自动化或智能体开发的团队都遇到过。Agent 的代码仓库通常可以做到严格版本控制，但运行环境却经常处于松散管理状态。依赖版本、系统包、驱动、环境变量、数据目录权限，任何一处不一致都可能改变 Agent 的行为。解决思路不是继续加强人工检查，而是用容器化与 IaC 将环境本身纳入代码管理。
一、环境漂移从哪里来：先看清 Agent 的依赖边界
环境不一致的麻烦在于它的隐蔽性。代码没有改动，但行为变了，排查时常常先怀疑模型输出、网络波动，最后才发现是某台机器上的 numpy 版本从 1.24 升到了 2.0，或者 libcuda.so 符号链接指向了不同的驱动版本。Agent 往往需要调用多种外部能力，比如 Python 解释器、系统命令、GPU 加速库、数据库驱动、浏览器内核，依赖链路比普通 Web 服务更长，漂移点也更多。
单靠 requirements.txt 或者 environment.yml 并不够。这类文件只声明顶层依赖，传递依赖的版本没有锁定，即使写上版本范围，也可能因为安装时间不同而得到不同结果。更不用说操作系统包、时区、locale、ulimit、内核参数这些经常被忽略的变量。下面这个对比就很典型：同一份代码在两台机器上 pip freeze 的结果不同，其中 numpy 的主版本都变了，API 兼容性被破坏。
# 机器 A numpy==1.24.4 requests==2.31.0 # 机器 B numpy==2.1.0 requests==2.32.3
因此，解决环境不一致不能只停留在“把依赖写清楚”，而是要把整个运行环境当成交付物的一部分。容器化负责把应用层的依赖、库、配置固化下来，IaC 则进一步管理宿主机和基础设施，让 Agent 所在的整条链路都可重建。
二、用容器化固定运行环境：从 Dockerfile 到镜像仓库
容器化的价值在于不可变基础设施思想：镜像构建完成后，在任意支持 Docker 的机器上启动的都是同一个文件系统快照。只要基础镜像 tag 明确、依赖锁定，Agent 看到的 Python 版本、动态库路径、环境变量都会完全一致。写 Dockerfile 的第一条原则就是不要使用 latest 标签，基础镜像必须指定精确版本，否则构建时间不同，底层系统就可能变化。
下面是一个面向 Agent 的 Dockerfile 示例。基础镜像选用 python:3.11.9-slim-bookworm，既锁定了 Python 版本，也锁定了 Debian 发行版。ENV 中设置 PYTHONDONTWRITEBYTECODE 和 PYTHONUNBUFFERED，能避免字节码缓存和输出缓冲造成的诡异差异。
FROM python:3.11.9-slim-bookworm
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "agent.py"]
如果 Agent 依赖 GPU，基础镜像需要换成 CUDA 官方镜像，例如 nvidia/cuda:12.4.0-cudnn-runtime-ubuntu22.04，并在启动时挂载 NVIDIA 驱动。不能只装 Python 的 CUDA 包，因为底层驱动和容器内的 CUDA 运行库不匹配会直接报错。镜像构建完成后推送到私有仓库，测试、生产都拉取同一个 digest，不回滚代码也能通过回滚镜像恢复环境。
多个服务配合时，不要用一条长长的 docker run 命令，docker compose 能把启动参数、网络、卷、环境变量都固化在 YAML 里。下面的编排示例让 Agent 依赖的 Redis 与主容器一起启动，减少手工操作。
services:
agent:
build: .
environment:
- REDIS_URL=redis://redis:6379/0
depends_on:
- redis
redis:
image: redis:7.2-alpine
三、IaC 管理宿主机与基础设施：把环境创建写进代码
容器化解决了应用层一致性，但容器运行在宿主机上，宿主机的 Docker 版本、NVIDIA 驱动、内核模块、网络策略不一致，同样会让 Agent 出问题。基础设施即代码的思路是用声明式或过程式脚本管理这些底层资源，避免手工敲命令。Terraform 适合云资源编排，Ansible 适合服务器配置管理，两者可以配合使用。
以 Ansible 为例，下面这个 playbook 会在所有 agent_nodes 上安装 Docker 并确保服务开机启动。Ansible 的模块是幂等的，重复执行不会产生副作用，即使某台机器漏配，也能通过再次执行收敛到目标状态。
- hosts: agent_nodes
become: yes
tasks:
- name: Install Docker
apt:
name: docker.io
state: present
update_cache: yes
- name: Ensure Docker service is running
service:
name: docker
state: started
enabled: yes
如果 Agent 节点运行在云上，还可以用 Terraform 定义 GPU 实例、安全组和启动脚本。这样新增一台 Agent 节点不需要人工登录配置，terraform apply 即可交付一台与现有节点相同的基础环境。下面示例创建了一台 g4dn.xlarge 实例，并通过 user_data 安装 Docker。
resource "aws_instance" "agent_node" {
ami = "ami-0c55b159cbfafe1f0"
instance_type = "g4dn.xlarge"
user_data = <<-EOF
#!/bin/bash
apt-get update
apt-get install -y docker.io
systemctl enable docker
systemctl start docker
EOF
tags = {
Name = "agent-node"
}
}
需要注意，IaC 管理的是“基座”，容器镜像管理的是“运行时”。两者职责不同，不能互相替代。只做容器化，宿主机驱动错乱仍然会导致挂载失败；只做 IaC，应用依赖仍然会漂移。真正的稳定来自两个层面的叠加。
四、把容器化与 IaC 接入 CI/CD 和 GitOps：让环境一致可验证
环境代码化之后，最大的好处是可以纳入版本控制和自动化流水线。镜像的 Dockerfile、compose 文件、Terraform 脚本、Ansible playbook 都放在同一个仓库或关联仓库中，任何变更都要经过 PR 审核。CI 流水线负责构建镜像、跑基础测试、扫描漏洞，再把镜像推送到私有仓库，标签使用 commit SHA 而不是 latest，这样每次发布都有唯一可追溯的环境。
下面是一段 GitHub Actions 的示例，每次推送到 main 分支时构建并推送 Agent 镜像。使用 GITHUB_SHA 作为标签，能保证镜像与代码版本一一对应，不会出现 latest 覆盖后无法回滚的问题。
name: build-agent-image
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build image
run: |
docker build -t registry.ipipp.com/agent:${GITHUB_SHA} .
docker push registry.ipipp.com/agent:${GITHUB_SHA}
在 CD 侧，可以先执行 terraform plan 查看基础设施变更，再执行 terraform apply，然后用 Ansible 或 docker compose 拉取新镜像滚动更新。这样整个环境的创建、变更、回滚过程都有记录。即使出现环境问题，也可以通过对比镜像 digest、基础设施状态文件来确定是哪一层发生了漂移。
归根结底，Agent 环境不一致不是某个工具单点能解决的，容器化与 IaC 是两种互补手段。把环境当作代码来管理，把运行依赖当作交付物来构建，团队才能从不断救火的状态中抽身，把精力放回 Agent 本身的能力迭代上。
Agent环境不一致容器化IaC修改时间：2026-09-21 00:24:28