lanhu-mcp Docker 部署全指南：从 .env 配置到生产环境反向代理-平芜编程栈

MCP 服务
人工智能
AI 应用

【免费下载链接】lanhu-mcp

⚡ 需求分析效率提升 200%！全球首个为 AI 编程时代设计的团队协作 MCP 服务器，自动分析需求自动编写前后端代码，下载切图

项目地址：https://gitcode.com/gh_mirrors/la/lanhu-mcp

本指南围绕 lanhu-mcp 的容器化部署全流程展开，覆盖 Docker / Docker Compose 两种启动方式、环境变量配置、健康检查验证、AI 客户端接入（Cursor、Claude Desktop）、日常运维命令、故障排查、数据备份与生产环境加固。读完本文，你将能够独立完成 lanhu-mcp 从"拿一个 Cookie 起服务"到"反向代理 + HTTPS 上生产"的完整部署，并理解每个配置项在底层源码中的真实作用。

一、部署前准备

1.1 系统要求

按照 DEPLOY.md 的说明，部署前请确认本机满足以下最低条件：

项目	要求
Docker	20.10+
Docker Compose	2.0+
可用磁盘空间	至少 2GB（含 Playwright Chromium 浏览器、Python 依赖及截图缓存）

磁盘空间的占用来源主要有三块：python:3.12-slim-bookworm基础镜像与 Python 依赖、playwright install --with-deps chromium安装的 Chromium 浏览器（见 Dockerfile），以及运行后产生的data/（资源下载、截图缓存）与logs/（应用日志）目录。

1.2 确认配置：`.env`文件

lanhu-mcp 通过环境变量完成全部配置。仓库提供了模板文件 config.example.env，首次部署时先复制为.env再填写你的蓝湖 Cookie：

cp config.example.env .env

.env中各项配置的默认值与作用如下（均可直接对照源码 lanhu_mcp_server.py 中的os.getenv读取逻辑验证）：

变量	是否必需	默认值	说明
`LANHU_COOKIE`	必需	无	蓝湖登录 Cookie，所有请求蓝湖 API 的身份凭证。获取方法见 GET-COOKIE-TUTORIAL.md
`SERVER_HOST`	可选	`0.0.0.0`	服务监听地址，仅本地访问可改为`127.0.0.1`
`SERVER_PORT`	可选	`8000`	服务监听端口
`FEISHU_WEBHOOK_URL`	可选	空	飞书机器人 Webhook，用于团队协作通知与 @ 提醒，留空则禁用
`DATA_DIR`	可选	`./data`	数据存储目录（留言、设计资源、截图缓存）
`HTTP_TIMEOUT`	可选	`30`	对外 HTTP 请求超时秒数，网络慢时建议调大
`VIEWPORT_WIDTH`	可选	`1920`	浏览器视口宽度，影响页面初始渲染，不影响截图完整性
`VIEWPORT_HEIGHT`	可选	`1080`	浏览器视口高度，同上
`DEBUG`	可选	`false`	设为`"true"`输出更详细的调试日志

其中VIEWPORT_WIDTH/VIEWPORT_HEIGHT在源码中直接决定 Playwright 创建浏览器页面时的 viewport 尺寸（见 lanhu_mcp_server.py），而截图采用full_page=True全页模式，因此调整视口不会裁剪截图内容。LANHU_COOKIE在源码中通过COOKIE = os.getenv("LANHU_COOKIE", DEFAULT_COOKIE)（lanhu_mcp_server.py）读取，贯穿所有蓝湖 API 请求。

⚠️ 安全提示：.env内含真实 Cookie，务必加入.gitignore，不要提交到代码仓库。

二、快速部署

2.1 方式一：使用 Docker Compose（推荐）

仓库根目录已提供 docker-compose.yml，无需额外编写即可一键启动：

# 1. 构建并启动服务 docker-compose up -d # 2. 查看服务状态 docker-compose ps # 3. 查看实时日志 docker-compose logs -f lanhu-mcp # 4. 检查服务是否正常运行 curl http://localhost:8000/health

Compose 文件的核心编排逻辑（docker-compose.yml）：

build.context: .+dockerfile: Dockerfile：基于当前仓库目录构建镜像；
container_name: lanhu_mcp_service：固定容器名，便于管理；
restart: unless-stopped：容器异常退出时自动重启；
env_file: .env：从.env注入全部环境变量；
ports: "8000:8000"：宿主机 8000 端口映射到容器 8000 端口；
volumes：将./data、./logs挂载到容器内/app/data、/app/logs，实现数据持久化。

Compose 中的environment段会覆盖.env中的同名变量（注释也明确说明了这一点：docker-compose.yml），如非必要可删除这些行。

2.2 方式二：使用 Docker 命令

不依赖 Compose 时，可以手动构建并运行：

# 1. 构建镜像 docker build -t lanhu-mcp-server . # 2. 运行容器 docker run -d \ --name lanhu-mcp \ -p 8000:8000 \ --env-file .env \ -v $(pwd)/data:/app/data \ -v $(pwd)/logs:/app/logs \ --restart unless-stopped \ lanhu-mcp-server # 3. 查看日志 docker logs -f lanhu-mcp # 4. 检查服务状态 docker ps | grep lanhu-mcp

镜像构建过程由 Dockerfile 定义：基于python:3.12-slim-bookworm，安装pyproject.toml声明的lanhu-mcp-server分发包（控制台入口lanhu-mcp = "lanhu_mcp_server:main"，见 pyproject.toml），并执行playwright install --with-deps chromium预装 Chromium。容器启动命令为：

CMD ["lanhu-mcp", "--transport", "http", "--host", "0.0.0.0"]

对应源码入口 lanhu_mcp_server.py 的main()函数：--transport支持http/stdio两种传输模式（默认取环境变量MCP_TRANSPORT），--host与--port分别默认读取SERVER_HOST、SERVER_PORT。

三、验证部署

3.1 检查服务健康状态

curl http://localhost:8000/health # 预期响应: {"status": "ok"} 或类似的健康检查响应

3.2 访问 MCP 端点

MCP 服务的 HTTP 端点在源码中固定注册为路径/mcp（mcp.run(transport="http", path="/mcp", ...)，见 lanhu_mcp_server.py），通过 URL 查询参数传入协作身份：

curl "http://localhost:8000/mcp?role=Developer&name=TestUser"

role与name两个参数在服务端通过 FastMCP 的get_http_request()读取（lanhu_mcp_server.py），role还会经过normalize_role()归一化（lanhu_mcp_server.py），支持 "php后端"、"iOS开发" 等中文变体自动映射到标准角色。

3.3 查看日志确认

# Docker Compose docker-compose logs lanhu-mcp | grep "Server started" # 或 Docker docker logs lanhu-mcp | grep "Server started"

服务启动时，main()还会向终端打印一段可直接粘贴的 Cursor MCP 配置示例（lanhu_mcp_server.py），URL 中的端口会自动带上.env里配置的SERVER_PORT，非常便于快速接入客户端。

四、连接 AI 客户端

4.1 Cursor 配置

在 Cursor 的设置中添加 MCP 服务器配置。配置文件位置因操作系统而异：

macOS：~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows：%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Linux：~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

配置内容：

{ "mcpServers": { "lanhu": { "url": "http://localhost:8000/mcp?role=Backend&name=John" } } }

参数说明：

role：你的角色（Backend/Frontend/Tester/Product等），用于团队协作时的消息分组与 @ 提醒；
name：你的姓名，用于团队协作和 @ 提醒；
⚠️兼容性提示：部分 AI 开发工具不支持 URL 中文参数，建议使用英文（这也是 docker-compose.yml 注释中的官方建议）。

4.2 Claude Desktop 配置

编辑配置文件~/Library/Application Support/Claude/claude_desktop_config.json：

{ "mcpServers": { "lanhu": { "url": "http://localhost:8000/mcp?role=Developer&name=Jane" } } }

4.3 其他客户端与 stdio 模式

除 HTTP 传输外，源码入口还支持--transport stdio（或设置MCP_TRANSPORT=stdio），此时服务可由 MCP 客户端按需拉起，适合不支持 HTTP MCP 的客户端（lanhu_mcp_server.py）。需要说明的是，镜像默认以 HTTP 模式启动，stdio 模式通常用于本地非容器化运行场景。

五、常用管理命令

日常运维中最常用的命令一览（Compose 与裸 Docker 两种语法等价）：

# 查看服务状态 docker-compose ps # 或 docker ps | grep lanhu-mcp # 查看实时日志 docker-compose logs -f lanhu-mcp # 最近100行日志 docker-compose logs --tail=100 lanhu-mcp # 或 docker logs --tail=100 lanhu-mcp # 重启服务 docker-compose restart lanhu-mcp # 或 docker restart lanhu-mcp # 停止服务 docker-compose stop lanhu-mcp # 或 docker stop lanhu-mcp # 停止并删除容器 docker-compose down # 或 docker rm -f lanhu-mcp # 重新构建并启动 docker-compose up -d --build # 或分步操作 docker-compose build docker-compose up -d # 进入容器调试 docker-compose exec lanhu-mcp /bin/bash # 或 docker exec -it lanhu-mcp /bin/bash

注意：docker-compose down会删除容器，但不会删除挂载的data/与logs/卷目录，因此数据不会丢失；docker rm -f同理，如需彻底清理数据请手动处理宿主机上的挂载目录。

六、故障排查

6.1 容器无法启动

检查日志：

docker-compose logs lanhu-mcp

常见原因：

Cookie 格式错误：LANHU_COOKIE缺失或格式不正确，导致启动后所有蓝湖 API 请求鉴权失败；
端口被占用：修改.env中的SERVER_PORT（或调整 Compose 端口映射）后重启；
系统资源不足：构建或运行阶段内存/磁盘不足，Docker 会直接报错退出。

6.2 Cookie 失效

症状：请求返回 401 或 403 错误。

解决方法：

重新登录蓝湖网页版；
获取新的 Cookie（步骤详见 GET-COOKIE-TUTORIAL.md）；
更新.env文件；
重启服务：

docker-compose restart lanhu-mcp

6.3 端口冲突

8000 端口被占用时有两种改法：

方式一：修改.env文件

SERVER_PORT=8001

方式二：修改 docker-compose.yml

ports: - "8001:8000" # 宿主机8001端口映射到容器8000端口

方式二只改宿主机映射端口，容器内部仍是 8000，与 Dockerfile 的EXPOSE 8000保持一致。无论哪种方式，改完后都要同步更新 AI 客户端配置中的连接 URL。

6.4 Playwright 浏览器问题

截图功能异常时，通常是容器内 Chromium 缺失或依赖损坏：

# 进入容器 docker-compose exec lanhu-mcp /bin/bash # 重新安装浏览器 playwright install chromium playwright install-deps chromium # 退出并重启 exit docker-compose restart lanhu-mcp

正常情况下 Chromium 在镜像构建阶段已通过playwright install --with-deps chromium安装完成（Dockerfile），并固定安装到/opt/playwright（由环境变量PLAYWRIGHT_BROWSERS_PATH指定，Dockerfile），无需重复安装。

6.5 数据持久化问题

确认数据目录挂载正确：

# 检查挂载 docker-compose exec lanhu-mcp ls -la /app/data # 检查宿主机目录权限 ls -la ./data ls -la ./logs # 如果权限有问题 chmod -R 755 ./data ./logs

从源码看，DATA_DIR下主要存放三类数据：团队留言记录data/messages/（lanhu_mcp_server.py）、Axure 资源与截图data/axure_extract_*（lanhu_mcp_server.py）、设计资源data/lanhu_designs/（lanhu_mcp_server.py）。这些目录在镜像构建时已由 Dockerfile 创建（mkdir -p /app/data /app/logs，Dockerfile），挂载后数据不会因容器重启而丢失。

七、数据备份

7.1 备份数据

# 备份数据目录（留言、设计资源、截图缓存） tar -czf lanhu-mcp-backup-$(date +%Y%m%d).tar.gz data/ logs/ # 只备份留言数据 tar -czf lanhu-messages-backup-$(date +%Y%m%d).tar.gz data/messages/

7.2 恢复数据

# 停止服务 docker-compose stop lanhu-mcp # 恢复数据（将备份解压回 data/、logs/ 对应位置） tar -xzf lanhu-mcp-backup-20241217.tar.gz # 启动服务 docker-compose start lanhu-mcp

恢复时务必先停服务再解压，避免容器运行中写入造成文件冲突；data/messages/是团队协作留言的核心数据，建议单独纳入备份策略。

八、安全建议

Cookie 安全
- 定期更换 Cookie（建议每月一次）；
- 确保.env文件不被提交到 Git（仓库已在 config.example.env 和 docker-compose.yml 中多次强调）；
- 设置严格的文件权限：chmod 600 .env。
网络安全
- 如果只需本地访问，将SERVER_HOST改为127.0.0.1（仅本机可连）；
- 生产环境建议配置反向代理（Nginx）并启用 HTTPS；
- 使用防火墙限制访问来源（仅放行内网/白名单 IP）。
数据安全
- 定期备份data/messages/目录；
- 敏感项目数据不要保留太久；
- 定期清理缓存：rm -rf data/lanhu_designs/* data/axure_extract_*。

注：SERVER_HOST、SERVER_PORT在源码中通过--host/--port参数读取环境变量生效（lanhu_mcp_server.py），改配置后必须重启容器才生效。

九、更新服务与回滚

9.1 更新到最新版本

# 1. 停止服务 docker-compose down # 2. 拉取最新代码 git pull origin main # 3. 重新构建并启动 docker-compose up -d --build # 4. 查看日志确认 docker-compose logs -f lanhu-mcp

更新前建议先备份data/与logs/（见第七章），版本演进信息可参考仓库根目录的 CHANGELOG.md 与各版本 RELEASE_NOTES 文件。

9.2 回滚到旧版本

# 1. 停止服务 docker-compose down # 2. 切换到指定版本 git checkout v1.0.0 # 替换为实际版本号 # 3. 重新构建并启动 docker-compose up -d --build

回滚前同样建议备份数据目录；回滚后可用docker-compose logs -f lanhu-mcp观察是否出现数据格式不兼容等异常。

十、性能优化

10.1 调整资源限制

在 docker-compose.yml 中添加资源限制，防止服务占用过多宿主资源：

services: lanhu-mcp: # ... 其他配置 deploy: resources: limits: cpus: '2' memory: 2G reservations: cpus: '1' memory: 1G

截图类工具由 Playwright 驱动 Chromium，内存占用波动较大，memory: 2G的上限对常规团队使用较为稳妥。

10.2 清理缓存

# 清理超过30天未修改的旧截图缓存 docker-compose exec lanhu-mcp find /app/data/lanhu_designs -type f -mtime +30 -delete # 清理超过30天未修改的 Axure 资源缓存 docker-compose exec lanhu-mcp find /app/data/axure_extract_* -type f -mtime +30 -delete

10.3 查看资源使用情况

# 查看容器实时资源使用 docker stats lanhu-mcp # 查看磁盘占用明细 du -sh data/* logs/*

十一、生产环境部署建议

11.1 使用 Nginx 反向代理

nginx.conf示例：

server { listen 80; server_name your-domain.com; location / { proxy_pass http://localhost:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 增加超时时间（用于长时间的截图操作） proxy_read_timeout 300s; proxy_connect_timeout 75s; } }

截图与 Axure 页面分析属于耗时操作，因此proxy_read_timeout建议放宽到 300s，否则 Nginx 会在服务端完成截图前就断开连接。

11.2 启用 HTTPS

使用 Let's Encrypt 免费证书：

# 安装 certbot sudo apt-get install certbot python3-certbot-nginx # 获取证书 sudo certbot --nginx -d your-domain.com # 自动续期 sudo certbot renew --dry-run

启用 HTTPS 后，AI 客户端的 MCP URL 需同步改为https://your-domain.com/mcp?role=...&name=...。

11.3 配置日志轮转

创建/etc/logrotate.d/lanhu-mcp：

/path/to/lanhu-mcp/logs/*.log { daily rotate 7 compress delaycompress missingok notifempty create 0640 root root }

logs/目录由服务持续写入，长期不轮转会持续膨胀；配合 Docker 挂载卷（./logs:/app/logs），宿主机侧用 logrotate 即可完成清理。

十二、使用技巧

12.1 多环境部署

复制并修改配置文件，用--env-file指定不同环境的配置：

# 开发环境 cp .env .env.dev # 生产环境 cp .env .env.prod # 使用指定配置启动 docker-compose --env-file .env.dev up -d

12.2 查看 MCP 工具列表

curl "http://localhost:8000/mcp?role=Developer&name=Test" | jq '.tools[].name'

返回的 tools 列表即服务暴露给 AI 客户端的全部能力（设计稿解析、切图下载、Axure 页面提取、需求留言等），可用jq快速确认接入是否成功。

12.3 监控服务健康

创建简单的健康检查脚本health-check.sh：

#!/bin/bash STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/mcp) if [ $STATUS -eq 200 ]; then echo "✅ Service is healthy" exit 0 else echo "❌ Service is down (HTTP $STATUS)" exit 1 fi

配置 crontab 定时检查：

# 每5分钟检查一次，失败自动重启服务 */5 * * * * /path/to/health-check.sh || docker-compose restart lanhu-mcp

十三、相关文档

README.md - 项目概述和功能介绍
GET-COOKIE-TUTORIAL.md - 蓝湖 Cookie 获取图文教程
config.example.env - 环境变量配置模板与逐项说明
docker-compose.yml - Compose 编排文件（含完整使用说明注释）
Dockerfile - 镜像构建定义
lanhu_mcp_server.py - 服务入口与核心实现
CHANGELOG.md - 更新日志
CONTRIBUTING.md - 贡献指南

如遇文档未能覆盖的问题，建议按以下顺序排查：先docker-compose logs -f lanhu-mcp查看实时日志，再对照本文档的故障排查章节逐项核对，最后可在仓库的 Issue 区提交问题（附上相关日志片段有助于快速定位）。

MCP 服务
人工智能
AI 应用

【免费下载链接】lanhu-mcp

⚡ 需求分析效率提升 200%！全球首个为 AI 编程时代设计的团队协作 MCP 服务器，自动分析需求自动编写前后端代码，下载切图

项目地址：https://gitcode.com/gh_mirrors/la/lanhu-mcp

点击查看免费下载

【免费下载链接】lanhu-mcp

一、部署前准备

1.1 系统要求

1.2 确认配置：.env文件

二、快速部署

2.1 方式一：使用 Docker Compose（推荐）

2.2 方式二：使用 Docker 命令

三、验证部署

3.1 检查服务健康状态

3.2 访问 MCP 端点

3.3 查看日志确认

四、连接 AI 客户端

4.1 Cursor 配置

4.2 Claude Desktop 配置

4.3 其他客户端与 stdio 模式

五、常用管理命令

六、故障排查

6.1 容器无法启动

6.2 Cookie 失效

6.3 端口冲突

6.4 Playwright 浏览器问题

6.5 数据持久化问题

七、数据备份

7.1 备份数据

7.2 恢复数据

八、安全建议

九、更新服务与回滚

9.1 更新到最新版本

9.2 回滚到旧版本

十、性能优化

10.1 调整资源限制

10.2 清理缓存

10.3 查看资源使用情况

十一、生产环境部署建议

11.1 使用 Nginx 反向代理

11.2 启用 HTTPS

11.3 配置日志轮转

十二、使用技巧

12.1 多环境部署

12.2 查看 MCP 工具列表

12.3 监控服务健康

十三、相关文档

【免费下载链接】lanhu-mcp

相关推荐

3步免费让老Mac运行最新macOS

如何使用Nginx反向代理部署WebSSH：生产环境完整配置指南

MindIE/stable_diffusion_v1.5批量生成教程：如何高效处理1000+图像任务

告别冗长UUID：Nano ID如何让游戏实体标识性能提升400%？

Nano ID边缘计算：物联网设备上的高效实现

Nano ID非安全模式详解：何时该用nanoid/non-secure

第1章：开发环境搭建，在 Windows 中安装 Git

循环神经网络RNN零基础入门：用生活例子理解记忆与序列处理

NodeSource Node.js 二进制发行版完全指南：基于 .deb 与 .rpm 的安装、手动配置与常见问题排障

1.2 确认配置：`.env`文件