# Forgejo 部署与排障经验库

> 光湖语言世界代码仓库（guanghulab.com）从 CVM 迁移到广州轻量云服务器的完整踩坑记录。
> 换服务器或遇到类似问题时，先看这个文档，不用重新推演。

---

## 核心：一键部署脚本

优先使用仓库里的 `scripts/smart-deploy-forgejo.sh`。
这个脚本做了智能检测（Docker可用性、COS配置、已有Forgejo状态），一条命令跑完全部部署流程。
换服务器时的第一步。

---

## 二进制部署（Docker 不可用的替代方案）

当 Docker pull 失败（429限流或被墙）时，直接下载 Gitea 二进制：

```bash
# 下载 Gitea 1.23.7（Forgejo 的底层引擎）
wget -O /usr/local/bin/gitea https://dl.gitea.com/gitea/1.23.7/gitea-1.23.7-linux-amd64
chmod +x /usr/local/bin/gitea

# 创建专用用户
adduser --disabled-login --gecos "" git

# 目录结构
mkdir -p /opt/forgejo/custom/conf /opt/forgejo/data
chown -R git:git /opt/forgejo
```

### app.ini 配置

`/opt/forgejo/custom/conf/app.ini`：

```ini
APP_NAME = 光湖 · Forgejo
RUN_USER = git
RUN_MODE = prod

[database]
DB_TYPE = sqlite3
PATH = /opt/forgejo/data/forgejo.db

[server]
DOMAIN = guanghulab.com
HTTP_PORT = 3001
ROOT_URL = https://guanghulab.com/
HTTP_ADDR = 127.0.0.1
LANDING_PAGE = explore
OFFLINE_MODE = false

[service]
DISABLE_REGISTRATION = false
REQUIRE_SIGNIN_VIEW = false

[mailer]
ENABLED = false

[session]
PROVIDER = file

[log]
MODE = console
LEVEL = info
ROOT_PATH = /opt/forgejo/data/log
```

> **注意**：`ROOT_URL` 必须用 `https://`，否则克隆链接会显示 `http://`。

### systemd 服务

`/etc/systemd/system/forgejo.service`：

```ini
[Unit]
Description=Forgejo (Git with a cup of tea)
After=network.target

[Service]
ExecStart=/usr/local/bin/gitea web -c /opt/forgejo/custom/conf/app.ini --work-path /opt/forgejo
Restart=always
User=git
Group=git
WorkingDirectory=/opt/forgejo

[Install]
WantedBy=multi-user.target
```

```bash
systemctl daemon-reload
systemctl enable --now forgejo
systemctl status forgejo
```

---

## 常见问题与排查流程

### 1. Forgejo 拒绝以 root 运行

**现象**：启动报错 "Forgejo/Gitea refuses to run as root"

**原因**：Forgejo/Gitea 安全机制禁止 root 运行。

**解决**：
- 直接用 `sudo -u git /usr/local/bin/gitea ...` 启动
- 或者在 systemd 里设 `User=git`

---

### 2. Git 推送失败：HTTP 413 Request Entity Too Large

**现象**：

```
error: RPC failed; HTTP 413 curl 22 The requested URL returned error: 413
send-pack: unexpected disconnect while reading sideband packet
```

**排查流程**：
1. 确认 Nginx 配置中有 `client_max_body_size`：`cat /etc/nginx/sites-available/guanghulab`
2. 默认 Nginx 限制 1MB，Git 推送的 packfile 远超此值
3. 检查配置是否写在正确的 server block 里（certbot 可能创建了多个配置）

**解决**：

```bash
# 在 location / 块中添加 client_max_body_size
sudo sed -i '/location \/ {/a \        client_max_body_size 100M;' /etc/nginx/sites-available/guanghulab

# 重载 Nginx
sudo systemctl reload nginx
```

**验证**：`git push` 不再报 413 即为成功。

---

### 3. 仓库数据损坏：推送成功但网页不显示文件

**现象**：
- `git push` 返回成功（`[new branch] main -> main`）
- Forgejo 网页显示仓库名但看不到文件
- 再次推送报错：`Gitea: Internal Server Error Decoding Failed` + `pre-receive hook declined`
- 远程 HEAD 不一致：`git ls-remote` 显示的 hash 与本地不同

**根本原因**：从 COS 备份恢复旧 Gitea 数据时，Git 内部数据损坏或版本不兼容。

**排查流程**：
1. `git ls-remote origin HEAD main` — 检查远程 HEAD 是否匹配本地
2. `curl -u user:token https://domain.com/api/v1/user/repos` — 查看仓库状态（empty、size）
3. 尝试推送观察具体错误信息

**解决**：

```bash
# 1. 通过 API 删除损坏仓库
curl -s -X DELETE -u "bingshuo:ACCESS_TOKEN" "https://guanghulab.com/api/v1/repos/bingshuo/guanghulab"

# 2. 创建新空仓库
curl -s -X POST -u "bingshuo:ACCESS_TOKEN" \
  "https://guanghulab.com/api/v1/user/repos" \
  -H "Content-Type: application/json" \
  -d '{"name":"guanghulab","description":"光湖代码仓库·国内镜像","private":false,"auto_init":false}'

# 3. 从本地推送完整代码
git push https://user:token@guanghulab.com/user/repo.git main
```

---

### 4. SSL 证书配置

```bash
# 申请证书
sudo certbot --nginx -d guanghulab.com

# 验证自动续期
sudo certbot renew --dry-run

# 证书位置
/etc/letsencrypt/live/guanghulab.com-0001/
```

certbot 会自动在 Nginx 配置中添加 `listen 443 ssl` 和 HTTP→HTTPS 重定向。

---

### 5. COS（腾讯云对象存储）备份恢复

```bash
# 安装 coscmd
pip3 install coscmd

# 配置
coscmd config -a {secret_id} -s {secret_key} -b {bucket_name} -r ap-guangzhou

# 列出文件
coscmd list

# 下载备份
coscmd download backups/guanghu-old-backup-20260512.tar.gz /root/forgejo-backup.tar.gz

# 恢复到 Forgejo 目录
tar -xzf /root/forgejo-backup.tar.gz -C /opt/forgejo/
chown -R git:git /opt/forgejo/
```

> **注意**：COS 存储桶名称：`zy-team-hub-1317346199`，区域：`ap-guangzhou`。
> 备份文件在 `backups/` 目录下。

---

### 6. 验证部署完整性

**确认服务运行**：

```bash
systemctl status forgejo           # 服务 active
curl -I http://127.0.0.1:3001      # 返回 200
curl -I https://guanghulab.com     # HTTPS 正常
```

**确认仓库状态**：
- Forgejo 网页登录 → 仓库列表有数据
- `git ls-remote https://guanghulab.com/bingshuo/guanghulab.git HEAD` → 返回正确 commit
- Forgejo API `GET /api/v1/user/repos` → 返回仓库列表

---

## 部署流程速查

从零开始部署的完整流程（假设已有 COS 备份）：

1. **执行 `scripts/smart-deploy-forgejo.sh`** 或手动部署二进制
2. **从 COS 下载备份并恢复**
3. **配置 Nginx 反向代理**（脚本已自动处理）
4. **申请 SSL 证书**（`certbot --nginx`）
5. **启动 Forgejo 并验证**
6. **如果仓库损坏** → 删除仓库，重建，重新推送
7. **如果推送报 413** → 配置 Nginx `client_max_body_size 100M`

---

## 注意事项

- **不要用 root 直接运行 Forgejo** — 必须用 git 用户
- **Nginx 配置改动后必须 reload** — `sudo systemctl reload nginx`
- **备份恢复后检查仓库完整性** — 用 `git ls-remote` 对比本地 hash
- **ROOT_URL 要写 https** — 否则克隆链接显示 http://
- **certbot 会修改 Nginx 配置** — 注意它创建的是独立的 server block

---

### 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 实测记录

本次迁移完整时间线：

| 时间 | 事件 | 结果 |
|------|------|------|
| 14:30 | 从 COS 下载 44MB 备份 | ✅ |
| 14:45 | 解压恢复 forgejo.db + 仓库 | ✅ |
| 15:00 | 下载 Gitea 1.23.7 二进制 | ✅ |
| 15:20 | Nginx 反向代理 + SSL 证书 | ✅ |
| 15:50 | 域名解析切换到广州服务器 | ✅ |
| 16:37 | 推送代码到新仓库 | ⚠️ 推送成功但网页不显示 |
| 16:50 | 发现仓库数据损坏 | ❌ Internal Server Error |
| 16:52 | 删除损坏仓库，重建 | ✅ |
| 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. MCP Server 迁移关键：access key 路径、Nginx rewrite、location 不能嵌套
4. PM2 进程迁移后要清理冲突的 errored 实例
5. 经验要沉淀到仓库里，不能只留在本地终端