蓝湖 MCP（lanhu-mcp）本地部署排障经验总结

日期：2026-08-06
环境：Windows 10+ / Docker Desktop 29.6.1 / lanhu-mcp（dsphper/lanhu-mcp）
参考文档：uni-agent 使用蓝湖 MCP 实现设计稿转代码

---

一、背景

在 HBuilderX / uni-agent 中使用「蓝湖设计稿转代码」功能，需要本地部署社区版 MCP 服务 lanhu-mcp。按官方文档操作后，.env 已配置 Cookie，但 docker compose up -d 服务起不来。

最终结论：两个坑叠加导致失败——① .env 中 Cookie 含 $ 符号被 Docker Compose 变量插值破坏；② 国内网络构建镜像卡死（apt/pip/Playwright 官方源不可用）。

最终成果： 只要让AI用sse连接 http://localhost:8000/mcp?role=Developer&name=me，就能查看蓝湖的图，注意蓝湖的图要按标准设计才能正确识别，不然还是乖乖下载图片，让AI精准取色，绘制可以不动手

---

二、前置条件

依赖	说明
Git	克隆项目
Docker Desktop	含 Docker Compose
蓝湖账号 Cookie	登录 蓝湖 → F12 → Network 过滤 /api/ → 复制完整 Cookie

---

三、部署步骤（从下载开始）

1. 克隆项目

git clone https://github.com/dsphper/lanhu-mcp.git
cd lanhu-mcp

2. 配置 .env

# Windows
setup-env.bat
# 或手动复制模板
copy config.example.env .env

关键变量：

LANHU_COOKIE="粘贴你的蓝湖Cookie"   # 必需
SERVER_HOST="0.0.0.0"
SERVER_PORT=8000
FEISHU_WEBHOOK_URL=""               # 可选

3. 启动服务

docker compose up -d --build

---

四、踩坑记录（核心）

坑 1：Cookie 含 $ 符号导致服务起不来 ⚠️ 最大坑

现象

• docker compose up -d 刷屏大量警告：

  The "o3" variable is not set. Defaulting to a blank string.
  The "g1" variable is not set. Defaulting to a blank string.
  The "t1752823316" variable is not set. Defaulting to a blank string.
  

• 服务启动失败 / 即使起来 Cookie 也是坏的，访问蓝湖鉴权失败。

根因

蓝湖 Cookie 里的 _ga_80BGNFFJQN=GS2.1.s1752823300$o3$g1$t1752823316$j44$l0$h0 这类 Google Analytics 参数自带 $ 符号。而 Docker Compose 会先对 .env 文件做 变量插值，把 $xxx 当成变量引用：

• $o3 → 未定义变量 → 替换为空字符串 + 刷警告
• Cookie 被静默破坏

排查方法

# 检查 .env 中是否含 $ 符号
Select-String -Path .env -Pattern '\$'

解决方案

把 .env 中所有 $ 替换为 $$（Docker Compose 转义规则，容器内会还原为单个 $）：

# 先备份
Copy-Item .env .env.bak
# 替换（注意用 -Raw 读取避免换行符被破坏）
$text = [System.IO.File]::ReadAllText("D:\mcp\lanhu-mcp\lanhu-mcp\.env")
$fixed = $text.Replace('$', '$$')
[System.IO.File]::WriteAllText("D:\mcp\lanhu-mcp\lanhu-mcp\.env", $fixed, (New-Object System.Text.UTF8Encoding $false))

💡 通用教训：凡是 .env 中的密码、Token、Cookie 等含 $、${}、\ 等特殊字符，要么用 $$ 转义，要么改用 docker run -e 传参，要么在容器内直接读文件。

---

坑 2：国内网络构建镜像卡死

现象

• docker compose up -d --build 在以下位置长时间无进展：
  1. apt-get update 卡在 Get:4 http://deb.debian.org/debian trixie/main amd64 Packages [9673 kB]（9.6MB 索引下载极慢/挂起）
  2. pip install 走 PyPI 官方源慢
  3. playwright install chromium 卡在 0% of 184.3 MiB（cdn.playwright.dev 被墙）

解决方案：使用国内镜像源构建

创建加速版 Dockerfile.tuna（保留原文件不动）：

FROM python:3.10-slim

WORKDIR /app

ARG HTTP_PROXY
ARG HTTPS_PROXY

ENV HTTP_PROXY=${HTTP_PROXY}
ENV HTTPS_PROXY=${HTTPS_PROXY}
ENV PYTHONUNBUFFERED=1

# ① apt 换清华 TUNA 源（Debian 12+ 是 debian.sources 格式）
RUN sed -i 's|deb.debian.org|mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list.d/debian.sources \
    && apt-get update && apt-get install -y \
    curl wget gnupg ca-certificates fonts-liberation \
    libasound2 libatk-bridge2.0-0 libatk1.0-0 libatspi2.0-0 \
    libcups2 libdbus-1-3 libdrm2 libgbm1 libgtk-3-0 \
    libnspr4 libnss3 libwayland-client0 libxcomposite1 \
    libxdamage1 libxfixes3 libxkbcommon0 libxrandr2 xdg-utils \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .

# ② pip 换清华 PyPI 源
RUN pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

# ③ Playwright 浏览器换 npmmirror 国内镜像
ENV PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/
RUN playwright install chromium
RUN playwright install-deps chromium

COPY lanhu_mcp_server.py .

RUN mkdir -p /app/data /app/logs

ENV HTTP_PROXY=
ENV HTTPS_PROXY=

EXPOSE 8000

CMD ["python", "lanhu_mcp_server.py"]

创建加速版 docker-compose.tuna.yml：

version: '3.8'

services:
  lanhu-mcp:
    build:
      context: .
      dockerfile: Dockerfile.tuna
    container_name: lanhu_mcp_service
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "8000:8000"
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    environment:
      - SERVER_HOST=0.0.0.0
      - SERVER_PORT=8000

启动命令：

docker compose -f docker-compose.tuna.yml up -d --build

加速效果实测：

阶段	官方源	国内镜像
apt 安装 200+ 包	卡死（数分钟无进展）	~3 分钟完成
pip 依赖	慢	6.7 MB/s，68 秒
Chromium 184MB	0% 卡死	37 秒下载完成

---

坑 3：curl 访问 /mcp 报 406 —— 不是故障！

现象

curl http://localhost:8000/mcp
# {"jsonrpc":"2.0","id":"server-error","error":{"code":-32600,
#  "message":"Not Acceptable: Client must accept text/event-stream"}}

解释：这是 FastMCP 服务器的正常响应。MCP 走 SSE 流协议，普通 curl 不带 Accept: text/event-stream 头会被拒绝。服务是活的，只是 curl 不是 MCP 客户端。

正确验证方式（MCP initialize 握手）：

curl -X POST "http://localhost:8000/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

正常返回：

{"jsonrpc":"2.0","id":1,"result":{
  "protocolVersion":"2025-03-26",
  "capabilities":{...},
  "serverInfo":{"name":"Lanhu Axure Extractor","version":"3.4.6"}
}}

---

五、集成到 uni-agent（HBuilderX）

在 uni-agent 配置中加入（全局 config.json 的 mcp 节点）：

{
  "mcp": {
    "lanhu": {
      "type": "remote",
      "url": "http://localhost:8000/mcp?role=Developer&name=me",
      "enabled": true
    }
  }
}

⚠️ URL 参数不要用中文；role 可选 Developer/Frontend/Backend/Tester/Product。

重启 HBuilderX，询问 uni-agent：「蓝湖 MCP 可用吗？」

---

六、日常使用命令速查

# 启动（注意用 tuna 配置）
docker compose -f docker-compose.tuna.yml up -d

# 查看日志
docker logs -f lanhu_mcp_service

# 更新 Cookie 后重启
docker compose -f docker-compose.tuna.yml restart

# 停止
docker compose -f docker-compose.tuna.yml down

# 重新构建（改了 Dockerfile 后）
docker compose -f docker-compose.tuna.yml up -d --build

---

七、维护要点

1. Cookie 有效期：蓝湖 Cookie 会过期，表现为 MCP 调用返回鉴权错误。重新登录蓝湖 → F12 复制新 Cookie → 更新 .env（记得 $ 要写 $$）→ docker compose -f docker-compose.tuna.yml restart
2. 端口占用：8000 被占用时改 docker-compose.tuna.yml 的 ports: "8001:8000"，同步改 uni-agent URL
3. 数据持久化：./data（缓存/截图）、./logs 已挂载，容器重启不丢
4. 安全：.env 含真实凭据，勿提交 git、勿外传

---

八、关键教训总结

1. 先看报错再动手：The "xxx" variable is not set 这种警告不是噪音，是变量插值在破坏你的配置——排查 .env 特殊字符是第一优先级。
2. 国内 Docker 构建三件套：apt 源（deb.debian.org → 清华）、pip 源（pypi → 清华）、Playwright 下载源（cdn.playwright.dev → npmmirror），一次配齐省一天。
3. 不要改原文件：新增 Dockerfile.tuna / docker-compose.tuna.yml，原配置保留，升级项目时直接对比即可。
4. 406 / 401 不一定是错误：对协议型服务（MCP/Registry），先用正确协议验证再下结论——curl 握手请求是最快验证手段。
5. 修改 .env 后必须重启容器：restart 不是 down+up，但改了环境变量要确认容器真的重建了。