蓝湖 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 条链路都通：

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

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.git
cd lanhu-mcp.git
git remote set-url –push origin git@<内网Git域名>:mcp/lanhu-mcp.git
git push –mirror

后续建议：

• 用 CI 定时同步（例如每晚一次）

• 生产环境固定 tag/commit，不直接跟 main

4.2 服务器部署（内网）

export APP_DIR=/opt/lanhu-mcp
sudo mkdir -p $APP_DIR
sudo chown -R $USER:$USER $APP_DIR

git clone git@<内网Git域名>:mcp/lanhu-mcp.git $APP_DIR
cd $APP_DIR
cp .env.example .env

写入 .env：

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

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

python3 -m venv venv
source venv/bin/activate
python -m pip install -U pip setuptools
pip install -r requirements.txt
python -m playwright install chromium

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

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

4.3 用 systemd 托管

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

[Unit]
Description=Lanhu MCP Service
After=network.target

[Service]
Type=simple
User=<运行用户>
WorkingDirectory=/opt/lanhu-mcp-runtime
EnvironmentFile=/opt/lanhu-mcp/.env
ExecStart=/opt/lanhu-mcp/venv/bin/python /opt/lanhu-mcp/lanhu_mcp_server.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

启动：

sudo systemctl daemon-reload
sudo systemctl enable –now lanhu-mcp
sudo systemctl status lanhu-mcp
journalctl -u lanhu-mcp -f

日志出现 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;
}
}

4.5 客户端接入（Claude/Codex）

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

# Claude
claude mcp remove lanhu >/dev/null 2>&1 || true
claude mcp add –transport http lanhu "https://lanhu-mcp.<corp>/mcp?role=测试&name=<你的名字>"

# Codex
codex mcp remove lanhu >/dev/null 2>&1 || true
codex mcp add lanhu –url "https://lanhu-mcp.<corp>/mcp?role=测试&name=<你的名字>"

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

• 客户端机器可访问 https://lanhu-mcp.<corp>/mcp

• 服务器可访问蓝湖域名（至少 lanhuapp.com 相关接口）

• .env 权限为 600，目录权限不暴露给其他用户

• 不使用 sudo 启动服务（避免 data/messages 归属异常）

• 生产固定版本（tag/commit），升级走灰度

6. 常见不通点与处理

7. 验收命令（上线前）

# 服务器侧
systemctl status lanhu-mcp –no-pager
curl -I https://lanhu-mcp.<corp>/mcp

# 客户端侧
claude mcp list
codex mcp list

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