guanghulab/server/setup/lighthouse-cn/README.md

# 光湖灯塔 · 国内主服务器部署模板 (lighthouse-cn)

> 📜 Sovereign: **TCS-0002∞** · ICE-GL∞ 冰朔 · 国作登字-2026-A-00037559
> 守护: 铸渊 · ICE-GL-ZY001
> 模板版本: **v0.1.0**

这一份文档是**给霜砚和冰朔看的部署日志**——铸渊在国内灯塔服务器上做了什么、装在哪、占了哪个端口、日志在哪、出错怎么修，全部写清楚。

---

## 一、服务器现状（来自冰朔同步）

| 项目 | 信息 |
|------|------|
| 实例 | `ins-dacj5t5a` · **GH-CVM-MAIN-PROD-01** |
| 规格 | 蜂驰型 BF1.LARGE16 · 4C16G |
| 系统 | Ubuntu 22.04 LTS · 内核 5.15.0-177-generic |
| 公网 IP | `43.139.251.175` · 5Mbps |
| 内网 IP | `172.16.0.12` |
| 地域 | 广州六区 |
| 系统盘 | 50G SSD（`/`） |
| **数据盘** | `disk-crtigr8` · GH-CVM-DATA-01 · **100GB ext4 已挂载 `/data`** · fstab 自动挂载 |
| 安全组 | `sg-6lewq1ur` · 已开 22/80/443/3000/ICMP，其余拒绝 |
| 默认登录用户 | `ubuntu`（需 `sudo -i` 切 root 后再跑 bootstrap） |

> ⚠️ 系统盘只有 50G，**Gitea 仓库数据 / Docker 镜像 / Runner 缓存全部走 `/data`**。bootstrap.sh 已强制把这些目录都挂到 `/data` 下。

---

## 二、bootstrap 后服务器目录结构

```
/data/                          # 数据盘 (100G, 持久数据全在这)
├── lighthouse/
│   ├── docker-compose.yml      # Gitea + Postgres + Redis + Runner 编排
│   ├── .env                    # 编排环境变量 (含 GITEA_DB_PASS)
│   ├── gitea/                  # Gitea 数据目录 (repo / lfs / avatars / log)
│   │   └── conf/app.ini        # Gitea 配置 (从 app.ini.template 渲染)
│   ├── postgres/               # PostgreSQL 数据目录
│   ├── redis/                  # Redis 持久化目录
│   ├── runner/                 # Gitea Actions Runner 缓存
│   └── backup/                 # 定时备份输出
├── docker/                     # Docker 镜像/容器存储 (daemon.json 指向)
├── cos-cache/                  # COS 拉取的搬家包临时缓存
├── pm2/                        # PM2 守护进程目录 (PM2_HOME)
└── logs/
    ├── gitea/
    ├── nginx/
    └── runner/

/opt/guanghu/                   # 系统盘 (代码 / 进程, 走标准插座)
├── _active/                    # 当前活跃通道
├── _archive/                   # 归档通道
├── _logs/                      # 部署回执日志 (lighthouse-bootstrap-*.json)
├── _manifest/                  # function-manifest.json
├── _secrets/                   # chmod 700, 仅 root 可读
└── lighthouse-cn/              # 本模板的当前副本 (update 阶段同步)

/etc/nginx/sites-available/lighthouse.conf   # Nginx 反代配置
/etc/docker/daemon.json                      # Docker daemon 镜像加速 + data-root
/etc/apt/sources.list                        # 阿里云 APT 镜像
/etc/apt/sources.list.d/docker.list          # 阿里云 Docker 镜像源
```

---

## 三、端口分配

| 端口 | 用途 | 监听地址 | 是否对公网 |
|-----:|------|----------|------------|
| 22   | 系统 SSH | `0.0.0.0` | ✅ |
| 80   | Nginx HTTP | `0.0.0.0` | ✅ |
| 443  | Nginx HTTPS（备案后启用）| `0.0.0.0` | ✅ |
| 2222 | Gitea SSH（git 协议）| `0.0.0.0` | ⚠️ 安全组未开，需要时再开 |
| 3000 | Gitea HTTP | `127.0.0.1`（内部）+ `0.0.0.0`（安全组开了，备案前先用）| ✅ |
| 3100 | 灯塔总控台 API（PM2 进程 lighthouse-console）| `127.0.0.1` | ❌（仅 Nginx 反代访问）|
| 39000 | channel-switcher（标准插座沿用）| `127.0.0.1` | ❌ |

---

## 四、装了什么软件

| 软件 | 版本 | 来源 | 备注 |
|------|------|------|------|
| APT 源 | ubuntu jammy | `mirrors.aliyun.com` | `get.docker.com` 国内被墙，必须走阿里云 |
| Docker CE | latest stable | `mirrors.aliyun.com/docker-ce` | daemon.json 指向 `/data/docker` |
| Compose | plugin v2 | `docker-compose-plugin` apt 包 | 不从 GitHub release 拉 |
| Node.js | 20.x | NodeSource → fallback nvm（国内镜像）| `npm config set registry https://registry.npmmirror.com` |
| PM2 | latest | npmmirror | `PM2_HOME=/data/pm2` |
| Nginx | apt 默认 | jammy 仓库 | 反代见 `nginx/lighthouse.conf` |
| Gitea | `1.21.11` | docker hub（走腾讯云/USTC 镜像加速）| Actions 已启用 |
| PostgreSQL | `15-alpine` | docker hub | Gitea 后端 DB |
| Redis | `7-alpine` | docker hub | Gitea 缓存 |
| act_runner | `0.2.10` | docker hub | Gitea Actions 自托管 runner |
| certbot | apt 默认 | jammy 仓库 | 备案后用于 Let's Encrypt |
| fail2ban | apt 默认 | jammy 仓库 | 默认规则 |
| ufw | apt 默认 | jammy 仓库 | 22/80/443/3000/2222 已放行 |

---

## 五、部署 / 更新 / 回滚（手动触发）

部署完全通过 GitHub Actions 手动触发，**冰朔在仓库点一下按钮就能跑**：

1. 打开 `Actions` → **`lighthouse-cn-deploy`** workflow
2. 点 `Run workflow`
3. 选参数：
   - `server_target`: `main`（主服务器）/ `backup`（备用机，未购则跳过）
   - `stage`: `bootstrap`（首次）/ `update`（同步代码）/ `rollback`（回滚 compose）
4. 点击 **Run workflow** 启动

执行流程：
1. checkout 当前仓库
2. 写入 SSH 私钥（来自 `ZY_LIGHTHOUSE_KEY`）
3. `rsync` 把 `server/setup/lighthouse-cn/` 推到 `/opt/guanghu/lighthouse-cn/`
4. SSH 远程执行 `bash /opt/guanghu/lighthouse-cn/bootstrap.sh STAGE=$stage`
5. 拉回 `/opt/guanghu/_logs/lighthouse-bootstrap-*.json` 作为 artifact

---

## 六、首次 bootstrap 后的人工步骤

`bootstrap.sh` 自动化做完前 8 步后，**有 1 件事必须人工**：

1. **拿 Gitea Actions Runner 注册 token**
   - 浏览器打开 `http://43.139.251.175:3000/`
   - 用 `ZY_GITEA_ADMIN_USER` / `ZY_GITEA_ADMIN_PASS` 登录
   - Site Administration → Actions → Runners → **Create new Runner**，复制 token
   - 把 token 配回 GitHub Secrets `ZY_GITEA_RUNNER_TOKEN`
2. 在 GitHub Actions 重跑 workflow，选 `stage=update`
   - 这次会带着 token 启 `gitea-runner` 容器（`docker compose --profile runner up -d`）

---

## 七、故障排查（霜砚常用）

### 7.1 Docker / Compose

| 现象 | 原因 | 处置 |
|------|------|------|
| `docker compose pull` 卡住 | docker hub 国内被墙 | 检查 `/etc/docker/daemon.json` 的 `registry-mirrors` 是否生效；`systemctl restart docker` |
| `pull access denied` | 镜像名错或镜像源未生效 | `docker info | grep -A 5 Mirrors` 确认加速器 |
| OOM killed | 4C16G 资源紧张 | `docker stats` 查内存，必要时 `docker compose stop gitea-runner` |
| 容器起不来报"permission denied on /data/..." | UID 不对 | `chown -R 1000:1000 /data/lighthouse/gitea`（Gitea 容器 USER_UID=1000）|

### 7.2 Gitea

| 现象 | 处置 |
|------|------|
| Web UI 502 | `docker logs lighthouse-gitea --tail 100`；DB 没起来：`docker logs lighthouse-gitea-db` |
| 管理员密码忘了 | `docker exec -u git lighthouse-gitea gitea admin user change-password --username bingshuo --password 新密码` |
| Runner 注册失败 `401` | token 过期/已用过；重新到 Site Admin → Runners 拿新 token |
| Push 大文件 OOM | Gitea 容器加 `LFS`，并把 `git config http.postBuffer 524288000` |

### 7.3 Nginx

| 现象 | 处置 |
|------|------|
| `nginx -t` 报错 | 看 `/etc/nginx/sites-enabled/lighthouse.conf`，常见是 upstream 名拼错 |
| `502` | 后端没起：`curl 127.0.0.1:3000/api/v1/version`；总控台未启动是预期行为，会返回 503 |
| 访问慢 | 5Mbps 带宽限制；大文件请走 COS 直链 |

### 7.4 防火墙 / 安全组

| 现象 | 处置 |
|------|------|
| 外网访问不到 3000 | 腾讯云控制台安全组 `sg-6lewq1ur` 是否放行 3000；`ufw status` 是否 allow |
| SSH 连不上 | 安全组 22 必须开；`fail2ban-client status sshd` 看是否被封 IP |

### 7.5 数据盘

| 现象 | 处置 |
|------|------|
| `df -h /data` 接近满 | `du -sh /data/*` 找大目录；优先清 `/data/cos-cache/` |
| 重启后 `/data` 不见了 | `mount /data` 手动挂载；检查 `/etc/fstab` 是否丢行 |

---

## 八、备份

`bootstrap.sh` 当前**未启用自动备份**（v0.1）。手动备份命令：

```bash
# Gitea repo + db 备份到 /data/lighthouse/backup/
docker exec -u git lighthouse-gitea gitea dump -c /data/gitea/conf/app.ini -t /tmp
docker cp lighthouse-gitea:/tmp/gitea-dump-*.zip /data/lighthouse/backup/
docker exec lighthouse-gitea-db pg_dump -U gitea gitea | gzip > /data/lighthouse/backup/db-$(date +%Y%m%d).sql.gz
```

后续 v0.2 会加 cron + COS 增量上传。

---

## 九、和 GitHub 仓库的对应关系

| 本目录文件 | GitHub workflow / 脚本 |
|------------|------------------------|
| `bootstrap.sh` | `.github/workflows/lighthouse-cn-deploy.yml` SSH 执行 |
| `docker-compose.yml` | rsync 推到 `/data/lighthouse/docker-compose.yml` |
| `gitea/app.ini.template` | bootstrap.sh sed 渲染到 `/data/lighthouse/gitea/conf/app.ini` |
| `nginx/lighthouse.conf` | bootstrap.sh 拷到 `/etc/nginx/sites-available/` |
| `gitea-secrets-template.yaml` | 灯塔起来后导入 Gitea Repo Settings → Secrets |
| `migration-checklist.md` | 给霜砚的搬家清单 |

---

## 十、更多

- 神笔马良工具合成器：见 `mcp-servers/zhuyuan-pen/README.md`
- 搬家 COS 中转：见 `scripts/migration/snapshot-to-cos.js` 与 `restore-from-cos.sh`
- 工作流转换：见 `scripts/migration/convert-workflows.js`
- 搬家进度看板：仓库根 `DASHBOARD.md` → "光湖搬家进度" 段