Gemini MCP Server Docker 部署与使用指南

项目概述

Gemini MCP Server 是一个基于 Docker 容器化的 AI 服务中间件，它通过 MCP (Model Control Protocol) 协议为客户端提供统一的多模型 AI 服务接口。该项目支持 Gemini、OpenAI、xAI 等多种 AI 模型的 API 接入，采用容器化部署方式，具有轻量、安全、易扩展等特点。

环境准备

基础要求

• 已安装 Docker 引擎 (推荐最新稳定版)
• 至少配置一个 AI 服务的 API 密钥 (Gemini/OpenAI/xAI 等)
• 系统资源建议: 2GB 以上内存，10GB 以上磁盘空间

操作系统兼容性

• Linux (推荐 Ubuntu 20.04+)
• macOS (Intel/Apple Silicon)
• Windows 10/11 (需 WSL2 支持)

部署流程

1. 获取项目配置

# 复制环境变量模板文件
cp .env.example .env

2. 配置 API 密钥

使用文本编辑器打开 .env 文件，至少配置以下一项 API 密钥：

GEMINI_API_KEY=your_gemini_key_here
OPENAI_API_KEY=your_openai_key_here
XAI_API_KEY=your_xai_key_here

3. 构建 Docker 镜像

提供多种构建方式：

# 标准构建命令
docker build -t zen-mcp-server:latest .

# 使用构建脚本 (Bash)
chmod +x docker/scripts/build.sh
./docker/scripts/build.sh

# PowerShell 构建脚本
docker/scripts/build.ps1

运行方式

推荐方式：直接运行容器

# 使用环境变量文件运行
docker run --rm -i --env-file .env \
  -v $(pwd)/logs:/app/logs \
  zen-mcp-server:latest

# 使用命令行参数指定环境变量
docker run --rm -i \
  -e GEMINI_API_KEY="your_key_here" \
  -e LOG_LEVEL=INFO \
  -v $(pwd)/logs:/app/logs \
  zen-mcp-server:latest

开发模式：使用 Docker Compose

# 部署服务
chmod +x docker/scripts/deploy.sh
./docker/scripts/deploy.sh

# 或使用 PowerShell
docker/scripts/deploy.ps1

# 进入交互模式
docker-compose exec zen-mcp python server.py

服务管理

容器监控

# 查看运行中的容器
docker ps

# 查看容器日志
docker logs <container_id>

# 停止所有服务容器
docker stop $(docker ps -q --filter "ancestor=zen-mcp-server:latest")

使用 Docker Compose 管理

# 实时查看日志
docker-compose logs -f zen-mcp

# 服务状态检查
docker-compose ps

# 重启服务
docker-compose restart zen-mcp

# 完全停止服务
docker-compose down

数据持久化

Gemini MCP Server 通过以下方式确保数据持久性：

1. 日志目录：将容器内的 /app/logs 挂载到主机的 ./logs 目录
2. 配置存储：使用 Docker 命名卷 zen-mcp-config 持久化配置
3. 时区同步：只读挂载主机的 /etc/localtime 确保时间一致

安全特性

• 以非 root 用户 zenuser 运行
• 只读文件系统，临时文件使用 tmpfs
• 不暴露网络端口，仅通过标准输入输出通信
• 敏感信息通过环境变量管理，不写入镜像

故障排查

常见问题处理

容器启动失败：

# 测试镜像是否存在
docker images zen-mcp-server

# 交互式测试容器
docker run --rm -it --env-file .env zen-mcp-server:latest bash

API 连接问题：

# 测试 API 密钥是否加载
docker run --rm --env-file .env zen-mcp-server:latest python -c "import os; print('GEMINI_API_KEY:', bool(os.getenv('GEMINI_API_KEY')))"

权限问题：

# 修复日志目录权限 (Linux/macOS)
sudo chown -R $USER:$USER logs/
chmod 755 logs/

性能优化建议

1. 资源限制：为容器设置内存限制

   docker run --rm -i --memory="512m" --env-file .env zen-mcp-server:latest
   

2. 日志轮转：配置日志文件大小限制和轮转策略

3. 健康检查：利用内置的健康检查机制监控服务状态

功能工具集

Gemini MCP Server 提供丰富的 AI 功能工具：

工具名称	功能描述
chat	通用 AI 对话和协作
thinkdeep	多阶段深度推理和分析
planner	交互式任务规划
consensus	多模型共识工作流
codereview	全面的代码审查
debug	根本原因分析和调试
refactor	代码重构建议
secaudit	安全审计工作流
testgen	测试用例生成（含边界情况）

性能指标

• 镜像大小：约 293MB (优化后的多阶段构建)
• 内存占用：基础约 256MB + 模型开销
• 启动时间：容器初始化约 2-3 秒
• API 响应：根据模型和复杂度不同 (1-30 秒)

最佳实践

1. 密钥管理：为不同环境使用独立的 API 密钥
2. 资源监控：定期检查容器资源使用情况
3. 日志分析：建立日志分析机制识别异常
4. 版本控制：为生产环境使用固定版本标签

通过本指南，您可以快速部署和使用 Gemini MCP Server，享受统一的多模型 AI 服务体验。如需进一步定制，可参考项目文档中的高级配置选项。