从一次 Docker 部署踩坑说起：多智能体项目落地时最容易忽略的三件事

背景

最近在华为云 AI 开发者空间里跑通了几个多智能体（Multi-Agent）开源项目，包括 EduSwarm 智慧课堂工作台、面试官天团这类「Leader + 多个专职 Agent」的编排式应用。整体感受是：模型本身不是瓶颈，工程细节才是。同一个 compose 文件，在本地笔记本上一条命令就起来，换到云主机上却会在三个地方反复卡住。

下面按我实际排查的顺序记录，每个坑位都给出可以直接复制运行的检查命令。

坑位一：容器拿到的不是「你以为的那个地址」

多智能体项目普遍是「教师端 / 学生端双入口」的形态。前端拿到后端地址后拼出给学生用的链接，如果容器内用 localhost 或容器自身 IP 去拼，教师在宿主机上打开页面一切正常，学生从另一台机器点链接就会一直转圈。

典型表现是：教师端功能完好，学生「输课堂码加入」超时。这时候很容易误判成 WebSocket 端口没放行，去翻安全组，白花半小时。

EduSwarm 的 compose 文件里其实留了出口，只是默认是注释状态：

environment:
  # - EDU_FRONTEND_URL=http://<服务器IP>:5173
  # - EDU_BACKEND_URL=http://<服务器IP>:19200

只要学生端需要跨机器访问，这两行就必须显式打开，填宿主机的真实 IP，而不是 127.0.0.1。

自查思路是先确认「容器以为自己是谁」，再确认「浏览器实际访问谁」：

docker exec -it <容器名> hostname -I
docker exec -it <容器名> env | grep -iE 'URL|HOST|PORT'

如果容器返回的 IP 是 172.x 这类内网地址，而你在浏览器里敲的是公网或宿主机 IP，那这个不一致基本就是问题源头。

坑位二：数据卷名字差一个前缀，教学数据就「消失」了

这是我在 EduSwarm 上花时间最久的一处。compose 里如果只写

volumes:
  - eduswarm-data:/data

Compose 会自动加上项目名前缀，实际创建的卷叫 项目名_eduswarm-data。但项目里可能有多个历史遗留的空卷（eduswarm-data、eduswarm_eduswarm-data），你改一行挂载名，容器照样能起来，健康检查也过，只是进到页面发现班级、课件、学情全是空的——因为它挂到了一个全新创建的空卷上。

正确做法是显式指定卷名，把「用哪个卷」这件事钉死：

volumes:
  eduswarm_clean-data:
    name: eduswarm_clean-data   # 显式指定，避免自动加项目名前缀

排查时先列一下机器上到底有哪些卷、各自多大：

docker volume ls
docker system df -v | grep -i eduswarm

有数据的那一个体积不会是 0。挂载点确认用：

docker inspect <容器名> --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{println}}{{end}}'

坑位三：docker.sock 挂载是一把双刃剑

不少 Agent 项目需要「在容器里再起容器」——比如学生实训沙箱、一键安装 3D 资产库。实现方式是挂载宿主机的 /var/run/docker.sock。挂上之后功能确实通了，但同时意味着：容器内进程拥有了宿主机 root 级的 docker 权限。

这件事在单机、内网、学校机房里可以接受；一旦拿去做多租户公网托管，就是明确的越权面。EduSwarm 的 compose 注释里已经写明了这条安全边界，值得所有同类项目照抄一句。

自查沙箱服务是否真的起来了（很多时候容器 Up 但沙箱没起，学生一开实训就转圈）：

docker exec <容器名> tail -8 /tmp/sandbox-server.log
# 期望看到 Uvicorn running on http://127.0.0.1:8080

如果没有 docker.sock 挂载，或者宿主机 docker 版本不匹配，这行日志就是空的或报 ModuleNotFoundError。

一张自查清单

把上面三点压缩成部署后立刻要跑的四条命令：

# 1) 关键挂载是否到位
docker inspect <容器名> --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{println}}{{end}}' | grep -E 'docker.sock|assets'

# 2) 数据卷是否挂在有数据的那个
docker system df -v | grep -i <项目名>

# 3) 访问地址是否指向宿主机
docker exec <容器名> env | grep -iE 'FRONTEND|BACKEND'

# 4) 沙箱服务是否真的起来
docker exec <容器名> tail -8 /tmp/sandbox-server.log

这四条都过了，再去看业务逻辑。反过来，如果这四条里有一条不过，后面所有的「Agent 不响应」「页面空白」大概率都是它的下游症状。

小结

多智能体项目的门槛正在从「会不会写 Agent」转移到「会不会把一堆容器和端口摆对」。模型能力在快速拉平，工程细节的差异反而更明显地决定了项目能不能真正跑起来。对开发者来说，把这类部署期的坑位沉淀成可执行的检查清单，比反复读文档更省时间。

如果要把这套东西长期用下去，建议在 CI 或启动脚本里就把上面四条检查固化进去，让问题在启动阶段暴露，而不是等到有人真的来用的时候。