Agent 本地部署排错手册：Docker + Ollama + MCP 完整避坑指南

本地部署 Agent 的三大优势

1. 数据不出本机——适合处理敏感数据
2. 无 API 费用——Ollama 运行本地模型免费
3. 低延迟——无网络往返，响应更快

但本地部署的坑也最多。以下是 12 个最常见的排错场景。

坑 1：Ollama 模型找不到

# ❌ 错误：模型不存在
ollama run llama3
# Error: model llama3 not found

# ✅ 修复：先拉取模型
ollama pull llama3
ollama run llama3

坑 2：GPU 内存不足

# 检查 GPU 使用情况
nvidia-smi

# 使用量化模型减少显存占用
ollama pull llama3:8b-q4_0

# 或设置 Ollama 使用 CPU
OLLAMA_LLM_LIBRARY=cpu ollama serve

坑 3：Docker 内无法访问 Ollama

# ❌ 错误：容器内访问 localhost:11434 失败
# ✅ 修复：使用 host.docker.internal
services:
  agent:
    environment:
      - OLLAMA_URL=http://host.docker.internal:11434

坑 4：MCP Server 启动超时

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["server.py"],
      "timeout": 30000
    }
  }
}

坑 5：Python 版本不兼容

# 使用 uv 管理多版本 Python
uv python install 3.12
uv venv --python 3.12
source .venv/bin/activate

坑 6：Node.js 版本过低

# MCP Server 通常需要 Node.js >= 18
nvm install 18
nvm use 18
node --version

坑 7：端口冲突

# 查找占用端口的进程
lsof -i :18800
kill -9 <PID>

# 或使用不同端口
MCP_PORT=18801 python server.py

坑 8：环境变量未加载

# 检查 .env 是否被加载
python -c "import os; print(os.environ.get('MY_KEY', 'NOT SET'))"

# 确保使用 python-dotenv
pip install python-dotenv

坑 9：SSL 证书问题

# 本地开发临时禁用 SSL 验证
export PYTHONHTTPSVERIFY=0
export NODE_TLS_REJECT_UNAUTHORIZED=0

坑 10：Ollama 推理速度慢

# 启用 Flash Attention
OLLAMA_FLASH_ATTENTION=1 ollama serve

# 调整并发数
OLLAMA_NUM_PARALLEL=4 ollama serve

# 使用更小的上下文窗口
OLLAMA_NUM_CTX=2048 ollama serve

坑 11：Docker 磁盘空间不足

# 清理 Docker 缓存
docker system prune -a
docker volume prune

坑 12：MCP Server 日志看不到

# 使用 MCP Inspector 调试
npx @modelcontextprotocol/inspector python server.py

# 或手动添加日志
import logging
logging.basicConfig(level=logging.DEBUG)

排错通用清单

1. 检查版本兼容性（Node >= 18, Python >= 3.10）
2. 检查端口是否被占用
3. 检查环境变量是否正确加载
4. 查看进程日志而非只看错误码
5. 从最简单的配置开始，逐步添加复杂度