Docker一键部署lanhu-mcp:团队共享MCP服务的完整指南
Docker一键部署lanhu-mcp:团队共享MCP服务的完整指南
lanhu-mcp 是一款蓝湖 MCP 服务器,让 Cursor、Claude 等 AI 编程助手直接读取蓝湖需求文档、自动编写前后端代码并下载切图。本文带你用 Docker 一键部署共享 MCP 服务,5 分钟完成团队环境搭建,告别重复安装和配置。
1. 为什么选择 Docker 部署共享 MCP 服务?🐳
个人本地运行 lanhu-mcp 已经能提升效率,但团队场景下更好的玩法是:一台服务器跑一个共享 MCP 服务,全员的 AI 助手连接同一个服务。
- 🧠 知识共享:打破 AI IDE 孤岛,A 开发 AI 分析过的需求,B 开发的 AI 可以直接查询复用
- 📦 环境统一:镜像内置 Python 3.12、Playwright 浏览器等全部依赖,无需本地装环境
- 📥 资源持久化:切图、截图、缓存统一存到服务器,谁连接都能用
- ⚡ 免维护:配置
restart: unless-stopped,服务挂掉自动拉起
部署配置集中在 docker-compose.yml 和 Dockerfile 两个文件中,构建时会自动安装设计模块和 Chromium 浏览器,开箱即用。
2. 部署前准备:3 件事缺一不可
2.1 检查系统要求
| 项目 | 最低要求 |
|---|---|
| Docker | 20.10+ |
| Docker Compose | 2.0+ |
| 磁盘空间 | 2GB 可用 |
2.2 获取蓝湖 Cookie
这是唯一必需的凭据。登录蓝湖网页版后,打开浏览器开发者工具,从请求头中复制 Cookie。详细步骤见 GET-COOKIE-TUTORIAL.md。
2.3 准备配置文件
仓库提供了带注释的配置模板 config.example.env,只需把 LANHU_COOKIE 填入真实值即可,其余配置(端口、视口、超时等)都有合理默认值。
3. 一键部署步骤:5 分钟上线 MCP 服务
第 1 步:获取代码
git clone https://gitcode.com/gh_mirrors/la/lanhu-mcp
cd lanhu-mcp
第 2 步:初始化配置
cp config.example.env .env
# 编辑 .env,填入 LANHU_COOKIE
第 3 步:构建并启动
docker-compose up -d
第 4 步:确认服务状态
docker-compose ps
docker-compose logs -f lanhu-mcp
看到服务启动日志后,部署就完成了 ✅
docker-compose.yml 中已经帮你预设好以下配置,一般无需改动:
| 配置项 | 值 | 作用 |
|---|---|---|
| 端口映射 | 8000:8000 |
AI 客户端通过 8000 端口连接 |
| 数据卷 | ./data:/app/data |
持久化切图、截图与缓存 |
| 日志卷 | ./logs:/app/logs |
日志落盘,容器重建不丢失 |
| 重启策略 | unless-stopped |
异常退出自动拉起 |
4. 验证部署成功:健康检查与端点测试
健康检查:
curl http://localhost:8000/health
返回 {"status": "ok"} 说明服务正常。
访问 MCP 端点(带角色参数):
curl "http://localhost:8000/mcp?role=Developer&name=TestUser"
能返回工具列表,说明 MCP 协议通道已打通。完整验证与排障流程参考官方文档 DEPLOY.md。
5. 团队接入:让每个人的 AI 共享同一服务
团队成员在 AI 工具的 MCP 配置中填入服务地址即可接入,一台服务器、全员共享:
{
"mcpServers": {
"lanhu": {
"url": "http://服务器IP:8000/mcp?role=Backend&name=John"
}
}
}
URL 支持两个团队参数:
role:角色,如Frontend、Backend、Tester、Productname:姓名,用于留言板 @提醒和协作追踪
⚠️ 小提醒:部分 AI 开发工具不支持 URL 中文参数,建议 role 和 name 使用英文。Cursor、Claude Desktop 等客户端的具体配置位置,DEPLOY.md 中有分系统说明。
6. 日常运维:MCP 服务常用管理命令清单
| 操作 | 命令 |
|---|---|
| 查看实时日志 | docker-compose logs -f lanhu-mcp |
| 重启服务 | docker-compose restart lanhu-mcp |
| 停止服务 | docker-compose down |
| 重新构建 | docker-compose up -d --build |
| 进入容器调试 | docker-compose exec lanhu-mcp /bin/bash |
| 查看资源占用 | docker stats lanhu-mcp |
更新到最新版本只需三步:docker-compose down → git pull → docker-compose up -d --build。
7. 故障排查:Docker 部署最常见的 4 个问题
① Cookie 失效(返回 401/403)
重新登录蓝湖获取新 Cookie → 更新 .env → docker-compose restart lanhu-mcp。建议每月定期更换 Cookie。
② 8000 端口被占用
修改映射为 "8001:8000" 后重启,并同步更新各客户端的连接 URL。
③ 截图功能异常(Playwright 浏览器问题)
进入容器执行 playwright install chromium 后重启服务。
④ 数据丢失疑虑
确认 ./data 与 ./logs 目录挂载正确。数据目录已持久化,容器重启不会丢切图和缓存。
8. 安全建议:上线前必看的 3 条
- 🔒 确保
.env已加入.gitignore,绝不把真实 Cookie 提交到代码仓库 - 🛡️ 仅本机使用时,将
SERVER_HOST改为127.0.0.1;对外服务建议加 Nginx 反向代理并启用 HTTPS - 🧹 定期清理设计缓存与过期数据,备份
data/messages/留言数据
9. 获取支持:加入 lanhu-mcp 交流群
部署和使用过程中遇到问题,可以扫码加入蓝湖 MCP 交流群,和官方维护者及社区伙伴一起交流:
核心文件速查:部署入口 docker-compose.yml | 镜像定义 Dockerfile | 配置模板 config.example.env | 部署文档 DEPLOY.md | Cookie 教程 GET-COOKIE-TUTORIAL.md。按本文步骤操作,你的团队共享 MCP 服务已经上线,让所有 AI 助手一起读蓝湖、写代码吧 🚀
