蓝湖 MCP 内网服务器打通方案

1. 目标和前提

目标：把 lanhu-mcp 从公网 Git 部署到内网服务器，并让 Claude/Codex 通过内网地址稳定调用。基于 lanhu.md 可确认的关键前提：

服务进程是 lanhu_mcp_server.py，默认监听 0.0.0.0:8000
客户端通过 HTTP MCP 接入：http://<host>:8000/mcp?role=...&name=...
依赖蓝湖 LANHU_COOKIE
服务运行目录需要可写 data/messages

2. 打通全链路（必须同时满足）

要真正"打通"，需要 4 条链路都通：

代码链路：GitHub -> 内网 Git
部署链路：内网 Git -> 内网服务器运行
访问链路：Claude/Codex 所在机器 -> 内网 MCP 服务
出网链路：MCP 服务 -> lanhuapp.com（蓝湖）

任何一条不通，都会表现为"已部署但不可用"。

3. 方案一览（推荐）

代码：在内网 GitLab/Gitea 建镜像仓库（mirror）
运行：内网 Linux 服务器使用 venv + systemd 常驻
入口：Nginx 反向代理统一暴露 https://lanhu-mcp.<corp>/mcp
鉴权：网关层加内网白名单 + BasicAuth/Token（至少二选一）
秘钥：LANHU_COOKIE 仅落服务器 .env，权限 600

4. 实施步骤

4.1 把 Git 仓库迁到内网

在可访问 GitHub 的跳板机执行一次镜像推送：

复制代码

git clone --mirror https://github.com/dsphper/lanhu-mcp.gitcd lanhu-mcp.gitgit remote set-url --push origin git@<内网Git域名>:mcp/lanhu-mcp.gitgit push --mirror

Bash

后续建议：

用 CI 定时同步（例如每晚一次）
生产环境固定 tag/commit，不直接跟 main

4.2 服务器部署（内网）

复制代码

export APP_DIR=/opt/lanhu-mcpsudo mkdir -p $APP_DIRsudo chown -R $USER:$USER $APP_DIR
git clone git@<内网Git域名>:mcp/lanhu-mcp.git $APP_DIRcd $APP_DIRcp .env.example .env

Bash

写入 .env：

复制代码

LANHU_COOKIE="从蓝湖浏览器抓到的完整Cookie"SERVER_PORT=8000

Plain Text

安装依赖（建议走内网源）：

复制代码

python3 -m venv venvsource venv/bin/activatepython -m pip install -U pip setuptoolspip install -r requirements.txtpython -m playwright install chromium

Bash

准备运行目录（避免 PermissionError）：

复制代码

mkdir -p /opt/lanhu-mcp-runtime/data/messages

Bash

4.3 用 systemd 托管

/etc/systemd/system/lanhu-mcp.service：

复制代码

[Unit]Description=Lanhu MCP ServiceAfter=network.target
[Service]Type=simpleUser=<运行用户>WorkingDirectory=/opt/lanhu-mcp-runtimeEnvironmentFile=/opt/lanhu-mcp/.envExecStart=/opt/lanhu-mcp/venv/bin/python /opt/lanhu-mcp/lanhu_mcp_server.pyRestart=alwaysRestartSec=5
[Install]WantedBy=multi-user.target

Plain Text

启动：

复制代码

sudo systemctl daemon-reloadsudo systemctl enable --now lanhu-mcpsudo systemctl status lanhu-mcpjournalctl -u lanhu-mcp -f

Bash

日志出现 Uvicorn running on http://0.0.0.0:8000 即服务启动成功。

4.4 入口网关（Nginx）

推荐统一暴露 HTTPS 域名，避免客户端直连 8000 端口。

复制代码

server {    listen 443 ssl;    server_name lanhu-mcp.<corp>;
    # 建议补充企业证书配置
    location /mcp {        proxy_pass http://127.0.0.1:8000/mcp;        proxy_http_version 1.1;        proxy_set_header Host $host;        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;        proxy_set_header X-Forwarded-Proto $scheme;
        # 可选：BasicAuth        # auth_basic "lanhu-mcp";        # auth_basic_user_file /etc/nginx/.htpasswd_lanhu_mcp;    }}

Plain Text

4.5 客户端接入（Claude/Codex）

把本地 localhost:8000 改成内网域名：

复制代码

# Claudeclaude mcp remove lanhu >/dev/null 2>&1 || trueclaude mcp add --transport http lanhu "https://lanhu-mcp.<corp>/mcp?role=测试&name=<你的名字>"
# Codexcodex mcp remove lanhu >/dev/null 2>&1 || truecodex mcp add lanhu --url "https://lanhu-mcp.<corp>/mcp?role=测试&name=<你的名字>"

Bash

5. 网络与安全最小检查清单

客户端机器可访问 https://lanhu-mcp.<corp>/mcp
服务器可访问蓝湖域名（至少 lanhuapp.com 相关接口）
.env 权限为 600，目录权限不暴露给其他用户
不使用 sudo 启动服务（避免 data/messages 归属异常）
生产固定版本（tag/commit），升级走灰度

6. 常见不通点与处理

点击小圆点，快速添加行或列


现象	根因	处理
客户端能配上但调用失败	只打通了内网入口，服务器无法访问蓝湖	放通服务器到蓝湖的出网策略或配置企业代理
`PermissionError: data/messages/...json`	运行目录不可写，或历史 sudo 污染	固定 `WorkingDirectory` ，修复目录归属后重启
`bind 0.0.0.0:8000 operation not permitted`	端口/安全策略限制	改用非受限端口，或通过 Nginx 反代
Python/依赖冲突	基础环境版本不一致	固定 Python 3.11，重建 venv
Playwright 安装失败	内网无法拉浏览器依赖	配置内网镜像/代理，或离线分发 Playwright 浏览器包

7. 验收命令（上线前）

复制代码

# 服务器侧systemctl status lanhu-mcp --no-pagercurl -I https://lanhu-mcp.<corp>/mcp
# 客户端侧claude mcp listcodex mcp list

Bash

再用一个真实蓝湖链接跑一次 lanhu_get_pages / lanhu_get_ai_analyze_page_result，成功即代表链路闭环完成。