现象

这次排查的是一个 AI Agent 工具环境。Agent 页面本身可以正常对话，但一接 MCP 工具，问题就分散开了：

Git 工具能看到仓库名，读 diff 时 permission denied
Playwright MCP 容器启动慢，偶尔卡在依赖下载
数据库工具能连上，但账号权限过大
Agent 能写文件，但工作区边界不清楚
日志散在 Agent 应用、MCP Server 和工具容器里

这类问题不要只按“模型效果不好”处理。Agent 接入 MCP 以后，排查重点要从模型层扩展到工具调用和运行边界。

适合落地的 Agent 场景

先说明一下这类环境为什么值得搭。AI Agent 接入工具后，适合处理的是“需要上下文 + 需要动作”的工作，而不只是普通问答。

常见场景：

场景	Agent 可以做什么	需要接入的工具
代码仓库巡检	看 diff、整理影响范围、生成变更摘要	Git MCP、文件工具
PR 辅助	生成测试建议、检查配置变更	Git MCP、知识库
Web 测试巡检	打开测试环境、截图、收集报错	Playwright MCP
数据排查	查询只读库、整理异常指标	DB MCP
运维 runbook	按步骤查服务状态和日志	Shell MCP、容器日志
内部知识库	结合文档、工单和代码回答问题	文档检索、Git 工具

这些场景的收益是减少重复整理和跨系统切换。也因为 Agent 会真实调用工具，所以后面必须把依赖、目录、权限和日志排清楚。

我这次按这个顺序排：

依赖检查 -> Compose 启动 -> 工作区挂载 -> 工具权限 -> 日志和回滚

1. 先把不同来源的依赖拆开

MCP 工具服务经常不止一个依赖。GitHub MCP Server、浏览器工具、Postgres、Redis 可能来自不同制品源。如果直接 docker compose up -d，失败时不容易判断是哪个环节卡住。

先拆关键依赖：

docker pull ghcr.1ms.run/github/github-mcp-server
docker pull mcr.1ms.run/playwright/mcp
docker pull docker.1ms.run/postgres:16-alpine
docker pull docker.1ms.run/redis:7-alpine
docker pull docker.1ms.run/python:3.12-slim

这里的目标不是“优化所有问题”，只是先确认这些工具依赖能进入当前环境。依赖层能启动，再继续看权限和沙箱。

2. Compose 先把应用和工具拆开

下面是我会保留的最小 compose 结构。真实环境里替换 token、依赖版本和启动命令即可。

services:
  agent-api:
    image: docker.1ms.run/python:3.12-slim
    container_name: agent-api
    working_dir: /app
    command: ["python", "server.py"]
    env_file:
      - .env.agent
    volumes:
      - ./app:/app:ro
      - ./workspace:/workspace
    depends_on:
      - mcp-github
      - mcp-browser
      - postgres
      - redis

  mcp-github:
    image: ghcr.1ms.run/github/github-mcp-server
    container_name: mcp-github
    env_file:
      - .env.github.readonly
    read_only: true
    cap_drop:
      - ALL

  mcp-browser:
    image: mcr.1ms.run/playwright/mcp
    container_name: mcp-browser
    shm_size: "1gb"
    cap_drop:
      - ALL

  postgres:
    image: docker.1ms.run/postgres:16-alpine
    environment:
      POSTGRES_DB: agent
      POSTGRES_USER: agent_readonly
      POSTGRES_PASSWORD: change_me
    volumes:
      - ./data/postgres:/var/lib/postgresql/data

  redis:
    image: docker.1ms.run/redis:7-alpine

这里有几个有用的边界：

• agent-api 和 MCP 工具服务分开，出问题能单独看日志。
• /app 只读，避免 Agent 修改应用代码。
• /workspace 单独可写，用来放输出文件。
• GitHub MCP 使用只读 token。
• Browser MCP 单独限制能力和资源。

3. 启动以后不要只看 running

docker compose pull
docker compose up -d
docker compose ps

很多时候 ps 看着正常，但工具调用还是失败。继续看日志：

docker compose logs --tail=120 agent-api
docker compose logs --tail=120 mcp-github
docker compose logs --tail=120 mcp-browser

再检查目录边界：

docker exec agent-api test -w /workspace
docker exec agent-api test ! -w /app

预期结果是：/workspace 可写，/app 不可写。如果 /app 也可写，说明 compose 挂载需要调整。

4. 文件工具不要碰宿主机大目录

我不建议这样挂：

/
/root
/home
/var/run/docker.sock

尤其是 /var/run/docker.sock。Agent 如果能控制宿主机 Docker，很多容器隔离就没有意义了。

如果 Agent 需要读某个仓库，可以单独挂载只读目录：

volumes:
  - ./repo:/repo:ro
  - ./workspace:/workspace

这样 Agent 可以读代码，也能把分析结果写到工作区，但不能顺手改掉代码目录。

5. 数据库和 Git 权限先从只读开始

数据库账号可以先这样处理：

CREATE USER agent_readonly WITH PASSWORD 'change_me';
GRANT CONNECT ON DATABASE agent TO agent_readonly;
GRANT USAGE ON SCHEMA public TO agent_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO agent_readonly;

Git token 也一样，先只读，再按任务需要逐步开放。不要为了 Demo 方便，把个人全权限 token 塞进 MCP Server。

6. 常见错误怎么分

context deadline exceeded

先判断是不是依赖启动层：

docker pull ghcr.1ms.run/github/github-mcp-server

依赖能拉，再看 MCP Server 访问外部服务是否超时。

permission denied

先看容器用户和目录：

docker compose exec agent-api id
ls -lah ./workspace

如果是 Git 工具报错，再看 token 权限和仓库范围。

工具调用成功但没人能复盘

至少要记录：

Agent 会话 ID
工具名称
参数摘要
执行结果
错误原因
对应容器日志

7. 最后保留一张检查单

工具依赖来源明确，可单独验证
Agent 应用和 MCP 工具服务分开
应用目录只读
工作区单独挂载
不挂 Docker socket
Git token 只读起步
数据库账号只读起步
工具调用有日志
Agent 和 MCP Server 可独立回滚

总结

AI Agent 的价值在于把代码、测试、数据、运维和知识库这些动作串起来，减少重复整理和来回切系统的成本。接入 MCP 工具后，部署排查不能只看模型和提示词。工具服务能不能启动、Agent 能访问哪些目录、token 权限多大、数据库是否只读、日志能不能追到调用链，这些才是上线前最容易出问题的地方。

依赖检查只解决第一层：让 Git 工具、浏览器工具、数据库和缓存先进入可启动状态。后面的目录、权限、网络、Secret 和审计，仍然要逐层确认。