From 3b8fea51c5d5ba0a917330e42f1f912c2e6ff2d3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=86=B0=E6=9C=94?= <565183519@qq.com>
Date: Sat, 16 May 2026 17:29:08 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85MCP=20Server=E8=BF=81?=
 =?UTF-8?q?=E7=A7=BB=E7=BB=8F=E9=AA=8C=E5=88=B0=E9=83=A8=E7=BD=B2=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/ops/forgejo-deployment-experience.md | 51 ++++++++++++++++++++++-
 1 file changed, 50 insertions(+), 1 deletion(-)

diff --git a/docs/ops/forgejo-deployment-experience.md b/docs/ops/forgejo-deployment-experience.md
index 0f0d4ff..a5191f0 100644
--- a/docs/ops/forgejo-deployment-experience.md
+++ b/docs/ops/forgejo-deployment-experience.md
@@ -255,6 +255,47 @@ curl -I https://guanghulab.com     # HTTPS 正常
 
 ---
 
+### MCP Server 配置
+
+MCP Server 迁移到新服务器后需要手动启动：
+
+```nginx
+# Nginx location block（放在 location / 前面）
+location /mcp {
+    proxy_pass http://127.0.0.1:8083;
+    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;
+}
+
+location /repo-mcp {
+    rewrite ^/repo-mcp$ /mcp break;
+    proxy_pass http://127.0.0.1:3903;
+    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;
+}
+```
+
+**启动步骤**：
+1. 克隆仓库：`cd /opt && git clone https://user:token@guanghulab.com/bingshuo/guanghulab.git repo-name`
+2. 启动 guanghulab-mcp-server（端口 8083）：
+   - `cd /opt/repo-name/server/mcp-server && npm install`
+   - 创建密钥：`echo "TOKEN" > /data/guanghulab/mcp-server/.access-key`
+   - `pm2 start ecosystem.config.js`
+3. 启动 repo-mcp-server（端口 3903）：
+   - `cd /opt/repo-name/mcp-servers/repo-mcp-server && npm install`
+   - `REPO_MCP_PORT=3903 REPO_MCP_SECRET=SECRET pm2 start index.js --name repo-mcp-server`
+4. 验证：`curl -X POST -H "Authorization: Bearer TOKEN" https://guanghulab.com/mcp`
+
+**常见问题**：
+- **Nginx location 嵌套**：sed 拼接容易把 location 块塞进其他 block 里，直接 cat 覆盖最稳
+- **路径重写**：repo-mcp-server 后端路由是 `/mcp`，但对外暴露 `/repo-mcp`，Nginx 需要 `rewrite ^/repo-mcp$ /mcp break;`
+- **access key 路径**：`ecosystem.config.js` 写死了 `/data/guanghulab/mcp-server/.access-key`，需检查是否存在
+- **PM2 进程冲突**：多次启动同一进程名会创建重复实例，用 `pm2 delete ID` 清除 errored 的
+
 ## 2026-05-16 实测记录
 
 本次迁移完整时间线：
@@ -272,8 +313,16 @@ curl -I https://guanghulab.com     # HTTPS 正常
 | 16:55 | 再次推送 → HTTP 413 | ❌ |
 | 16:58 | 排查 Nginx 配置 → 缺 client_max_body_size | ✅ 修复 |
 | 17:02 | 重载 Nginx，第三次推送 | ✅ 成功 |
+| 17:12 | MCP Server 迁移 | ❌ Invalid CSRF token / SSE 404 |
+| 17:15 | Nginx 配置修复（location 嵌套错误） | ❌ Nginx 配置乱 |
+| 17:17 | cat 覆盖完整 Nginx 配置 | ✅ 配置正常 |
+| 17:20 | MCP Server 启动（access key 路径问题） | ❌ 403 认证失败 |
+| 17:25 | 创建 /data/guanghulab/mcp-server/.access-key | ✅ 认证通过 |
+| 17:26 | repo-mcp-server 路由重写 `/repo-mcp` → `/mcp` | ✅ 全链路通过 |
 
 **教训总结**：
 1. COS 备份恢复后，仓库数据可能损坏——先 `git ls-remote` 验证
 2. Nginx 默认 1MB body 限制——Git 推送必超，需显式设置
-3. 经验要沉淀到仓库里，不能只留在本地终端
+3. MCP Server 迁移关键：access key 路径、Nginx rewrite、location 不能嵌套
+4. PM2 进程迁移后要清理冲突的 errored 实例
+5. 经验要沉淀到仓库里，不能只留在本地终端