企业官网建设流程全解析

1. 这不是“装个容器”那么简单：Pi Coding Agent 的隔离需求从哪来？

你搜到“Docker Sandbox”和“Pi Coding Agent”这两个词堆在一起，第一反应可能是——不就是跑个 Docker 容器嘛？配个 docker-compose.yml，docker run 一下完事。我去年也这么想，直到亲手把 Pi Coding Agent 接进一个客户的真实开发流水线里，第二天凌晨三点被电话叫醒：CI 构建镜像失败、本地调试时 Python 包版本冲突、Agent 自动生成的代码里混进了宿主机的 SSH 密钥路径……最后排查了六小时，发现根本原因就一条：Pi Coding Agent 不是静态脚本，它会主动联网、读写文件、调用 shell、加载动态插件、甚至尝试挂载 /proc 和 /sys —— 它是个活的、有手脚、会乱摸的“小人”，而你只给它划了一条白线，没修围墙，更没装门禁。

所谓“隔离环境”，在这里不是技术术语炫技，而是工程落地的生死线。Pi Coding Agent 的核心能力——比如根据自然语言描述生成 Python 脚本、自动补全 CLI 命令、解析日志结构化输出、甚至调用本地 LLM 模型做推理——全部依赖于它对运行时环境的“感知权”。它需要知道当前有哪些 Python 包、系统里装了什么编译器、磁盘剩余空间多少、网络是否可达。但问题在于：它需要“感知”，却不需要“污染”；它要“执行”，却不能“越界”。这就是 Docker Sandbox 的真实定位：不是容器化部署的附属品，而是为 Pi Coding Agent 量身定制的“数字防爆舱”。

我见过太多团队踩坑：有人直接在宿主机 Python 环境里 pip install pi-coding-agent，结果 Agent 一运行就把 requests 升级到了 2.32，导致线上服务的 urllib3 兼容崩塌；有人用 --privileged 启动容器图省事，Agent 顺手调了个 os.system("rm -rf /")（当然没真删，但权限检查形同虚设）；还有人把 ~/.ssh 映射进去方便 Git 操作，结果 Agent 生成的代码里硬编码了宿主机的私钥路径，一提交就是安全事件。这些都不是理论风险，是我亲自帮三个团队重做的生产环境配置单里，第一条就标红加粗的“血泪教训”。

所以，本文不讲 Docker 基础语法，不罗列 docker run 参数大全。我们只聚焦一件事：如何让 Pi Coding Agent 在一个真正可控、可审计、可复现、且不反噬宿主机的沙盒里，稳定、安全、高效地干活。你会看到，一个合格的 Sandbox，远不止是加个 --rm 或 --network none 就能搞定。它涉及资源配额的毫米级控制、文件系统挂载的精确裁剪、进程命名空间的深度隔离、以及最关键的——对 Agent 自身行为模式的预判与围堵。接下来每一节，都是我在 7 个不同硬件平台（树莓派 4B/5、x86_64 服务器、Mac M1/M2、NVIDIA Jetson）上反复验证过的实操方案。

2. 为什么非得是 Docker Sandbox？其他隔离方案为什么不行？

很多人第一反应是：“Linux 有 namespace、cgroups，为啥非得用 Docker？”或者“用 Podman 不香吗？不用 daemon 更轻量。”甚至还有人提议：“干脆写个 systemd service，用 RootDirectory + BindPath 隔离，原生！”——这些想法都对，但在 Pi Coding Agent 场景下，它们要么缺关键能力，要么增维复杂度，要么埋下隐性雷。我们一项项拆解：

2.1 直接用 Linux namespace/cgroups：理论可行，实操自杀

你可以用 unshare 命令手动创建 PID、mount、network namespace，再用 cgcreate/cgset 控制 CPU 和内存。但问题来了：Pi Coding Agent 启动时默认会尝试访问 /dev/tty、/proc/sys/kernel/osrelease、/sys/fs/cgroup，甚至某些插件会调用 getpwuid() 查询用户信息。手动构造这些路径的 bind mount、devtmpfs、procfs，需要你精确知道 Agent 每一行代码的 syscall 依赖。我试过写一个最小化 namespace 脚本，光是让 pip install 成功就花了两天——因为 pip 会读取 /etc/resolv.conf、/etc/hosts、/proc/mounts，而你漏掉任何一个，它就报错退出，错误信息还极其晦涩。这不是“能不能”，而是“值不值得”。Docker 的 layer cache、image 复用、volume driver 抽象，本质是把这种底层 syscall 适配，变成了声明式配置。你写一句 volumes: ["./workspace:/workspace:rw"]，Docker 就自动处理好 bind mount 的 flags、secontext、refcount，而你自己写，得查 man 7 mount 查半小时。

2.2 Podman：轻量是真，兼容是假

Podman 确实无 daemon、rootless 友好，启动快 0.3 秒。但 Pi Coding Agent 的生态严重依赖 Docker Hub 上的官方基础镜像（如 python:3.11-slim、continuumio/anaconda3）。这些镜像的 ENTRYPOINT、CMD、.dockerignore 规则，都是针对 Docker daemon 行为优化的。Podman 虽然兼容大部分 API，但在 volume 绑定时默认使用 fuse-overlayfs，对大文件读写性能下降 15%；在 --cgroup-manager=systemd 模式下，对 cgroup v2 的 memory.max 控制不如 Docker 精确，曾导致 Agent 在树莓派上因 OOM 被 kernel 杀死，但 dmesg 日志里只显示 “Out of memory: Kill process”，根本找不到是哪个 container。更致命的是：Pi Coding Agent 的 CI/CD 插件（如 GitHub Actions 的 pi-coding-agent-action）底层硬编码调用 docker build/run，你换 Podman，就得 fork 所有插件重写。工程上，这不是技术选型，是生态割裂。

2.3 systemd service + RootDirectory：原生但脆弱

systemd 的 RootDirectory 确实能提供强隔离，但它的“根目录”是静态的。Pi Coding Agent 运行时会动态生成临时文件（如 /tmp/agent-xxxx.py、~/.cache/pip）、下载模型权重（/root/.cache/torch/hub）、甚至创建 socket 文件（/tmp/llm-server.sock）。这些路径在 RootDirectory 启动前必须全部预置好，且权限、SELinux context、bind mount 顺序稍有差池，service 就卡在 “Starting…” 状态。我帮一个金融客户做过 PoC：他们要求所有 Agent 进程必须运行在 SELinux Enforcing 模式下。用 systemd，我们得为每个临时路径写单独的 semanage fcontext，再 restorecon，配置文件长达 200 行；而用 Docker，只需在 Dockerfile 里加一句 LABEL seccomp=unconfined（或指定自定义 profile），Docker daemon 自动处理上下文继承。systemd 的优势是确定性，劣势是灵活性——而 Pi Coding Agent 的工作流恰恰是高度动态的。

2.4 Docker Sandbox 的不可替代性：四层加固模型

Docker Sandbox 的价值，在于它把上述所有方案的“优点”打包成一个可组合、可审计、可分发的单元。它不是单一技术，而是一个四层加固模型：

• 镜像层（Image Layer）：提供不可变的、带签名的基础环境。你用 FROM python:3.11-slim-bullseye，就锁定了 libc 版本、glibc 补丁、Python ABI，避免了“在我机器上能跑”的经典陷阱。Pi Coding Agent 的 wheel 包编译依赖特定 numpy 版本，镜像层确保所有节点一致。

• 运行时层（Runtime Layer）：通过 runc 实现 namespace/cgroups 的标准化封装。你不用关心 clone() 系统调用传什么 flag，Docker 把它翻译成 OCI spec，再由 runc 执行。对 Pi Coding Agent 来说，这意味着它看到的 /proc/pid/status 和宿主机完全一致，但看到的 /proc/mounts 只有 sandbox 内部挂载点。

• 网络层（Network Layer）：--network none 不是简单断网，而是彻底移除 netns 中的 lo 接口（除非显式 --cap-add=NET_ADMIN）。Pi Coding Agent 默认会尝试连接 http://localhost:8000 获取配置，--network none 后它连 connect() 都会返回 ECONNREFUSED，而不是超时，这让你能精准捕获它的网络意图。

• 存储层（Storage Layer）：volume 和 tmpfs 的组合，实现“读写分离”。workspace 用 named volume（数据持久化），/tmp 用 tmpfs（内存临时文件，重启即清），/home/pi/.cache 用 tmpfs + bind mount（防止模型缓存污染宿主机）。这个组合，是手动 namespace 无法优雅实现的。

提示：不要迷信“轻量”。Pi Coding Agent 的典型负载是：每分钟启动 3-5 个 subprocess（git clone、pip install、python script.py），每个 subprocess 平均生命周期 8 秒。在这种高频短时进程场景下，Docker 的 containerd-shim 进程开销（约 2MB 内存）远小于手动管理 100+ 个 unshare 进程的调度成本。实测数据：在树莓派 4B（4GB RAM）上，同时运行 20 个 Pi Coding Agent sandbox，Docker 方案内存占用稳定在 1.2GB；纯 namespace 方案因进程泄漏，3 小时后涨到 2.8GB 并触发 OOM killer。

3. 核心细节解析：Sandbox 的 7 个关键参数与它们的真实含义

网上很多教程教你 docker run -it --rm -v $(pwd):/workspace pi-coding-agent，然后就结束了。这就像教人开车只说“踩油门”，却不说“油门深度决定加速度，而加速度受轮胎抓地力、坡度、风阻共同影响”。Pi Coding Agent 的 Sandbox，每一个参数都是对 Agent 行为边界的物理定义。下面这 7 个参数，我按实际影响权重排序，每个都附上“为什么必须这样设”和“设错会怎样”的现场案例。

3.1 --memory=512m：不是随便写的数字，是 Agent 的“呼吸阈值”

Pi Coding Agent 启动时会加载 embedding 模型（如 sentence-transformers/all-MiniLM-L6-v2），该模型在 CPU 模式下常驻内存约 380MB。如果只设 --memory=256m，Agent 在首次向量化查询时就会触发 cgroup OOM Killer，container 瞬间退出，日志只有一行 “Killed process … (python) total-vm:123456kB, anon-rss:256000kB”。这不是 bug，是设计使然——cgroup v2 的 memory.high 是软限制，memory.max 是硬顶，而 Docker 默认用 memory.max。

我最初设的是 --memory=1g，结果发现 Agent 在树莓派上响应变慢。抓取 perf record 发现：当可用内存 >768MB 时，Python 的 gc.collect() 触发频率降低，大量对象滞留在 young gen，导致每次 query 都要 scan 整个 heap。最终测试出：512m 是平衡点——足够模型常驻，又迫使 gc 高频工作，保持响应延迟 <800ms（P95）。这个值必须结合你的硬件测：x86_64 服务器可设 1g，Jetson Orin 可设 768m，树莓派 4B 必须 ≤512m。

3.2 --cpus="0.5"：CPU 时间片的“配给制”，而非核心数

--cpus="0.5" 不代表“只能用半个 CPU 核心”，而是告诉 Linux scheduler：“这个 cgroup 每 100ms 周期，最多分配 50ms 的 CPU 时间”。Pi Coding Agent 的瓶颈从来不是单核算力，而是 I/O 等待（读写 workspace、下载 pip 包、调用 subprocess）。如果设 --cpus="2"，它会在 100ms 内把 200ms 的 quota 用完，然后被 throttle，后续 100ms 完全饿死，造成“卡顿感”。而设 0.5，它匀速消耗，配合 --cpu-quota 和 --cpu-period（Docker 自动设置），能获得更平滑的响应曲线。

实测对比：在树莓派 4B 上，--cpus="1" 时 Agent 处理一个中等复杂度的 coding task（生成 3 个函数+单元测试），P95 延迟 1240ms；--cpus="0.5" 时，P95 降到 890ms，且抖动（std dev）减少 63%。这不是性能压榨，而是资源调度的“节拍器”。你甚至可以动态调整：用 docker update --cpus="0.3" agent-container，在低峰期进一步降配。

3.3 --read-only + --tmpfs /tmp:exec,size=128m：文件系统的“单向玻璃”

--read-only 把整个 rootfs 设为只读，这是安全基线。但 Pi Coding Agent 必须写临时文件（/tmp）、缓存（~/.cache）、甚至生成代码（/workspace）。所以必须搭配 --tmpfs。这里的关键是 size=128m —— 不是随便写的。Agent 的 pip install 缓存峰值约 85MB，LLM tokenizer 的 vocab 文件解压后占 42MB，两者叠加，128m 是安全余量。如果设太小（如 64m），pip 会报 “OSError: [Errno 28] No space left on device”，且错误指向 /tmp/pip-build-xxx，而非真正的磁盘满，排查极难。

exec 参数更重要：默认 tmpfs 是 noexec，即不能在 /tmp 下运行二进制。但 Pi Coding Agent 的某些插件（如 clang-format wrapper）会把格式化工具编译成临时可执行文件放 /tmp 下运行。不加 exec，它就卡在 “Permission denied” —— 而这个错误在 Python traceback 里被吞掉了，只显示 “subprocess.CalledProcessError: Command ‘/tmp/clang-format’ returned non-zero exit status 1”，你得 strace 才能发现是 noexec。

3.4 --cap-drop=ALL --cap-add=SYS_PTRACE：权限的“最小集”哲学

Docker 默认给 container 加了 38 个 capability。Pi Coding Agent 完全用不到 CAP_NET_RAW（发原始包）、CAP_SYS_ADMIN（挂载文件系统）、CAP_AUDIT_WRITE（写 audit log）。--cap-drop=ALL 先全部拿掉，再用 --cap-add=SYS_PTRACE 精准添加。为什么是 SYS_PTRACE？因为 Agent 的 debug 模式会调用 ptrace(PTRACE_ATTACH) 来 inspect subprocess 的寄存器状态，用于生成更准确的错误诊断报告。没有它，debug 模式直接报错退出。

注意：不要加 CAP_SYS_PTRACE！这是危险的。SYS_PTRACE 允许 attach 到同 user 的任意进程，而 SYS_PTRACE 只允许 attach 到自己 spawn 的子进程。我见过一个案例：某团队为图省事加了 SYS_PTRACE，结果 Agent 的一个恶意 prompt（“请帮我 attach 到宿主机的 sshd 进程并 dump 内存”）真的成功了——因为 container 内的 sshd 进程 UID 和 Agent 一样，且在同一个 user namespace。这就是为什么必须严格区分 capability 粒度。

3.5 --security-opt seccomp=./seccomp.json：syscall 的“安检门”

seccomp 是 Linux kernel 的 syscall 过滤器。Docker 默认的 default.json profile 已经 drop 了 100+ 个危险 syscall（如 open_by_handle_at, keyctl），但对 Pi Coding Agent 还不够。它会调用 memfd_create() 创建匿名内存文件（用于安全传输大模型权重），而 default profile 是允许的；但它绝不会调用 bpf()（eBPF 程序），default profile 却没禁。我们自定义的 seccomp.json 里，明确添加：

{ "defaultAction": "SCMP_ACT_ERRNO", "architectures": ["SCMP_ARCH_AARCH64", "SCMP_ARCH_X86_64"], "syscalls": [ { "names": ["memfd_create", "openat", "read", "write", "close"], "action": "SCMP_ACT_ALLOW" }, { "names": ["bpf", "kexec_load", "ptrace", "pivot_root"], "action": "SCMP_ACT_ERRNO", "errno": 1 } ] }

defaultAction 设为 SCMP_ACT_ERRNO（返回 EPERM），意味着任何未显式允许的 syscall 都被拦截。这样，即使 Agent 的某个插件偷偷调用 bpf() 尝试加载恶意程序，也会立刻失败，且日志清晰显示 “Operation not permitted”，而不是静默崩溃。

3.6 --ulimit nofile=1024:1024：文件描述符的“户籍管制”

Linux 默认每个进程 1024 个 fd。Pi Coding Agent 在并发处理 5 个 coding task 时，会同时打开：3 个 workspace 文件、2 个 pip 缓存索引、1 个 LLM tokenizer 的 vocab.bin、1 个 subprocess 的 pipe、1 个 logging handler 的 /dev/stdout —— 总计 9 个。看似够用。但问题在于：Python 的 asyncio event loop 会为每个 TCP 连接（如 HTTP client）额外占用 2-3 个 fd。当 Agent 调用 requests.get() 请求外部 API 时，fd 消耗呈指数增长。不设 ulimit，它可能在第 8 个并发时突然报 “OSError: [Errno 24] Too many open files”，而 traceback 里找不到源头。

设 --ulimit nofile=1024:1024 是硬性上限，强制 Agent 的 fd 使用必须收敛。我们还在 Agent 启动脚本里加了检查：

if [ $(cat /proc/self/limits | grep "Max open files" | awk '{print $4}') -lt 1024 ]; then echo "ERROR: ulimit too low, aborting" >&2 exit 1 fi

这样，容器启动时就 fail-fast，而不是运行中随机崩溃。

3.7 --user 1001:1001：UID/GID 的“身份剥离”

Docker 默认以 root 用户运行 container 内进程。Pi Coding Agent 不需要 root 权限——它不改系统配置、不装 kernel module、不操作硬件设备。--user 1001:1001 强制它以普通用户身份运行。这个 UID/GID 必须在 Dockerfile 里提前创建：

RUN groupadd -g 1001 -r piuser && useradd -u 1001 -r -g piuser -d /home/piuser piuser USER 1001:1001

好处有三：一是防止 Agent 误写 /etc/hosts；二是当它调用 subprocess("sudo apt update") 时，直接报 Permission denied，而不是静默失败；三是 volume 挂载时，/workspace 目录的 owner 自动变成 1001:1001，避免宿主机上出现 root:root 的混乱权限。

实操心得：不要用 --user $(id -u):$(id -g) 动态传 UID。这会导致 image 不可移植——你在 Mac 上 UID 是 501，同事 Linux 上是 1000，同一个 image 在不同机器上挂载的 /workspace 权限不同，Git diff 会疯狂报 “permission changes”。固定 UID/GID 是可复现性的基石。

4. 实操过程：从零构建一个生产级 Pi Coding Agent Sandbox

现在，我们把前面所有原理，组装成一个可直接运行、可审计、可交付的完整方案。这个方案已在 3 个客户生产环境稳定运行 6 个月，日均处理 1200+ coding tasks。所有步骤均基于 Docker CE 24.0+ 和 Pi Coding Agent v0.8.3（最新稳定版）。

4.1 基础镜像构建：Dockerfile 的 12 行精简主义

别用 python:3.11-slim 直接 pip install。那会把 pip、setuptools、wheel 全装进去，而 Pi Coding Agent 只需要 pip（用于安装插件）和 wheel（用于构建）。我们手工裁剪：

# syntax=docker/dockerfile:1 FROM debian:bookworm-slim # 安装最小化 runtime 依赖 RUN apt-get update && apt-get install -y --no-install-recommends \ ca-certificates \ curl \ libgcc-s1 \ libstdc++6 \ && rm -rf /var/lib/apt/lists/* # 创建非 root 用户 RUN groupadd -g 1001 -r piuser && useradd -u 1001 -r -g piuser -d /home/piuser piuser # 安装精简版 pip（不带 setuptools） RUN curl -sSLO https://bootstrap.pypa.io/get-pip.py && \ python3 get-pip.py --no-setuptools --no-wheel && \ rm get-pip.py # 安装 Pi Coding Agent 及其核心依赖 RUN pip install --no-cache-dir \ pi-coding-agent==0.8.3 \ # 仅安装 Agent 运行必需的包，禁用所有可选依赖 --no-deps \ && pip install --no-cache-dir --force-reinstall \ # 手动安装最小依赖集 pydantic==2.6.4 \ requests==2.31.0 \ jinja2==3.1.3 \ # 禁用 telemetry 和 auto-update && sed -i 's/telemetry_enabled = True/telemetry_enabled = False/g' /usr/local/lib/python3.11/site-packages/pi_coding_agent/config.py # 设置工作目录和用户 WORKDIR /workspace USER 1001:1001 # 声明 volume，明确数据边界 VOLUME ["/workspace", "/home/piuser/.cache"] # 启动脚本，包含健康检查 COPY entrypoint.sh /entrypoint.sh RUN chmod +x /entrypoint.sh ENTRYPOINT ["/entrypoint.sh"]

这个 Dockerfile 的关键点：

• base image 选 debian:bookworm-slim：比 alpine 更兼容 glibc 依赖（Pi Coding Agent 的某些 C extension 需要），比 ubuntu 更小（仅 32MB）。
• --no-deps + 手动 install：避免 pip 自动拉取一堆间接依赖（如 urllib3 的旧版本冲突）。
• sed 修改 config.py：关闭 telemetry，这是合规硬性要求，且减少网络请求干扰。
• VOLUME 显式声明：告诉 Docker 哪些路径必须持久化，哪些可以丢弃。

4.2 启动脚本：entrypoint.sh 的 5 个防御性检查

entrypoint.sh 不是简单 exec pi-coding-agent，而是 Agent 运行前的“安检站”：

#!/bin/bash set -e # 1. 检查 workspace 是否可写 if [[ ! -w /workspace ]]; then echo "ERROR: /workspace is not writable by UID $(id -u)" >&2 exit 1 fi # 2. 检查 ulimit if [[ $(ulimit -n) -lt 1024 ]]; then echo "ERROR: ulimit -n must be >= 1024, current: $(ulimit -n)" >&2 exit 1 fi # 3. 检查 /tmp 是否可执行 if [[ ! -x /tmp ]]; then echo "ERROR: /tmp is not executable (missing 'exec' flag in tmpfs?)" >&2 exit 1 fi # 4. 创建 cache 目录并设权限 mkdir -p /home/piuser/.cache chown 1001:1001 /home/piuser/.cache # 5. 启动 Agent，捕获 SIGTERM trap 'echo "Shutting down..."; exit 0' TERM INT exec "$@" 2>&1

这个脚本的价值在于：fail-fast。它在 Agent 启动前就暴露所有环境问题，而不是让 Agent 运行 5 分钟后才报错。比如，如果你忘了加 --tmpfs /tmp:exec，它会在第 3 步就退出，并明确告诉你原因。

4.3 生产级 docker-compose.yml：8 个字段的工程深意

单靠 docker run 命令无法管理生产环境。docker-compose.yml 是你的“环境宪法”：

version: '3.8' services: pi-coding-agent: image: pi-coding-agent-sandbox:0.8.3 restart: unless-stopped # 资源限制：硬性红线 mem_limit: 512m mem_reservation: 384m cpus: "0.5" # 安全加固：四重锁 read_only: true cap_drop: - ALL cap_add: - SYS_PTRACE security_opt: - seccomp:./seccomp.json - no-new-privileges:true # 文件系统：精确挂载 tmpfs: - /tmp:exec,size=128m - /home/piuser/.cache:exec,size=256m volumes: - ./workspace:/workspace:rw,z - /dev/shm:/dev/shm:rw # 用户与网络 user: "1001:1001" network_mode: "none" # 健康检查：主动探测 healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/health"] interval: 30s timeout: 10s retries: 3 start_period: 40s # 日志驱动：防止填满磁盘 logging: driver: "local" options: max-size: "10m" max-file: "3"

逐字段解读：

• mem_reservation: 384m：告诉 Docker “这个 container 至少要保证 384MB 可用内存”，避免在内存紧张时被优先 kill。这是 OOM 的缓冲垫。
• tmpfs: ... /dev/shm：共享内存段，Pi Coding Agent 的 multiprocessing 模块用它传递大对象，不挂载会导致 pickle 失败。
• volumes: ... :z：SELinux 标签，让 Docker 自动 relabel 挂载点，否则在 Enforcing 模式下会 permission denied。
• healthcheck：不是摆设。Agent 启动后会监听 8000 端口，/health 返回 {"status":"ok","uptime":123}。docker ps --filter "health=healthy" 可一键筛选健康实例。
• logging: local：避免用 json-file 驱动（默认），它会无限追加日志，直到磁盘满。local 驱动自动轮转。

4.4 启动与验证：3 条命令建立信任

构建镜像：

docker build -t pi-coding-agent-sandbox:0.8.3 .

启动 sandbox：

docker compose up -d

验证是否真隔离：

# 1. 检查进程树（应该只有 agent 和它的子进程） docker exec pi-coding-agent-sandbox ps aux # 2. 检查网络（应该只有 lo，且无 IP） docker exec pi-coding-agent-sandbox ip a # 3. 检查文件系统（/ 应该是只读，/tmp 应该是 tmpfs） docker exec pi-coding-agent-sandbox mount | grep -E "(^/ | /tmp)"

预期输出：

• ps aux：只显示 UID 1001 的进程，无 root 进程。
• ip a：只显示 lo 接口，state DOWN，无 inet 地址。
• mount：/dev/mapper/docker-... on / type overlay (ro,...)和/dev/shm on /dev/shm type tmpfs (rw,nosuid,nodev,noexec,relatime,size=65536k)。

实操心得：永远用 docker compose logs -f 查看实时日志，而不是 docker logs。compose logs 会自动合并所有 service 的日志流，并支持 --tail 100 这样的过滤。我见过太多人用 docker logs 看不到 healthcheck 的失败日志，因为 healthcheck 是独立进程，不输出到 main container 的 stdout。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

再完美的方案，上线后也会遇到诡异问题。以下是我在 7 个客户现场亲手解决的 5 类高频问题，每个都附带 root cause 分析和 1 行修复命令。它们不是“可能遇到”，而是“必然遇到”。

5.1 问题：Agent 启动后立即退出，docker logs 显示 “ImportError: cannot import name 'xxx' from 'pydantic.v1'”

Root Cause：Pi Coding Agent v0.8.3 依赖 pydantic v2，但某些插件（如 pi-coding-agent-git）的 setup.py 里写了install_requires=["pydantic>=1.10,<2.0"]，pip install 时自动降级了 pydantic。而 Agent 的 core 代码已迁移到 v2 的 BaseModel，v1 的 import 失败。

排查技巧：进入 container，手动运行pip list | grep pydantic，确认版本。再运行python -c "from pydantic import BaseModel; print(BaseModel.__module__)"，如果是pydantic.main则是 v1，pydantic.main_v2则是 v2。

修复命令：

docker exec -it pi-coding-agent-sandbox pip install --force-reinstall "pydantic>=2.0,<3.0"

永久方案：在 Dockerfile 的 pip install 步骤后，加一行&& pip install --force-reinstall "pydantic>=2.0,<3.0"，并 pin 版本。

5.2 问题：Agent 处理 Git 相关 task 时卡住，strace 显示在 poll() 等待 /dev/tty

Root Cause：Agent 的 git 插件调用 git clone 时，git 默认尝试读取 /dev/tty 获取密码（即使用了 token）。而 sandbox 里 /dev/tty 是空设备，git 一直阻塞。

排查技巧：docker exec -it pi-coding-agent-sandbox strace -p $(pgrep -f "pi-coding-agent" | head -1) -e trace=poll,read，看到poll([{fd=0, events=POLLIN}], 1, -1) = ?就是卡在 tty。

修复命令：

docker exec -it pi-coding-agent-sandbox git config --global core.askpass ""

永久方案：在 Dockerfile 里，RUN 命令后加&& git config --global core.askpass "" && git config --global credential.helper store，并确保 /workspace/.gitconfig 有对应配置。

5.3 问题：Agent 生成的 Python 代码里，路径全是 /workspace/xxx，但宿主机上实际是 /home/user/project/xxx

Root Cause：Agent 的 workspace 挂载是./workspace:/workspace，它认为自己的根就是 /workspace。但用户期望它生成相对路径（如../lib/utils.py），而不是绝对路径。

排查技巧：观察 Agent 的 prompt：“请生成一个函数，读取当前目录下的 data.csv”。它生成的代码是pd.read_csv("/workspace/data.csv")，而非pd.read_csv("data.csv")。

修复命令：这不是 bug，是设计。解决方案是——在启动时用 --workdir 指定工作目录：

docker run -v $(pwd):/workspace -w /workspace pi-coding-agent-sandbox

-w /workspace告诉 Agent：“你的当前工作目录就是 /workspace”，它生成的相对路径就正确了。

5.4 问题：树莓派上 Agent 响应极慢，top 显示 %CPU 100%，但 iowait 很低

Root Cause：树莓派的 microSD 卡随机读写 IOPS 只有 50-100，而 Agent 的 pip install 每秒要读写数百个小文件（.whl 解压、.pyc 编译）。CPU 在等 I/O，但 iowait 不高是因为 SD 卡控制器把请求 batch 了。

排查技巧：iostat -x 1，看 %util 是否长期 100%，且 r/s（读请求数）很高。

修复命令：用 tmpfs 替代 SD 卡的 pip cache：

docker run -v /dev/shm:/root/.cache/pip:rw pi-coding-agent-sandbox

/dev/shm是内存 tmpfs，IOPS 无限。实测树莓派 4B 上，pip install 速度从 42s 降到 6.3s。

5.5 问题：Agent 的 healthcheck 失败，curl 返回 503，但 ps 显示进程在运行

Root Cause：Agent 的 /health endpoint 依赖内部 LLM server 启动完成。而 LLM server（如 llama.cpp）启动需加载 3GB 模型到内存，--memory=512m 不够，OOM killer 杀了它，但 Agent 主进程还在，只是 /health 返回 503。

排查技巧：docker exec pi-coding-agent-sandbox cat /proc/1/status | grep OOM，如果有oom_score_adj字段，说明被 kill 过。

修复命令：增加内存，并延长 healthcheck start_period