shuangyan-notebook/第五域 · Fifth Domain/⚒️ 铸渊·协作指令｜GitHub ↔ Notion 桥接协议/铸渊指令｜全仓库服务器配置模板统一化 · 测试服务器已就绪 · 代码侧旧路径清理 · ZY-SVR- 0d70252ae1a14aa8bdeb1412d642c6fd.md

---
belongs_to:
  - "[[INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]"
---
# 铸渊指令｜全仓库服务器配置模板统一化 · 测试服务器已就绪 · 代码侧旧路径清理 · ZY-SVR-TPL-2026-0426-001 · 霜砚签发 · 冰朔授权

```
HLDP://zy-svr-tpl-2026-0426-001/root
├── meta
│   ├── id: ZY-SVR-TPL-2026-0426-001
│   ├── type: 铸渊指令 · 全仓库配置统一化
│   ├── issued_by: 霜砚（AG-SY-01）
│   ├── authorized_by: 冰朔（TCS-0002∞）
│   ├── issued_at: 2026-04-26T12:12+08:00
│   ├── priority: P1 · 高优
│   └── scope: 全仓库 · 所有服务器配置 · 所有模块文件
│
├── context
│   ├── 测试服务器已就绪: ZY-SVR-TEST-001 · 43.153.203.105 · 新加坡
│   ├── 环境: Node 20 + PM2 6 + Nginx 1.24 + Git 2.43 + Python 3.12
│   ├── 部署路径: /opt/guanghu（统一标准）
│   ├── 仓库已克隆: ✅
│   ├── .env已配置: ✅
│   └── 端口规划: 9800(GMP主) / 9801(webhook) / 3000-9000(模块)
│
├── tasks
│   ├── T1: 理解「为什么需要测试服务器」
│   ├── T2: 理解「为什么所有服务器要按统一模板」
│   ├── T3: 全仓库扫描 · 找出所有硬编码旧路径/旧配置
│   ├── T4: 统一修复 · 全部对齐测试服务器模板
│   └── T5: 提交 PR · 回执确认
│
└── deliverables
    ├── PR: 一个或多个修复 PR
    └── 回执: 写入 Notion 确认修复范围
```

---

## 一、背景通知：测试服务器已就绪

<aside>
🖥️

**冰朔已将新加坡服务器（原小说下载器 ZY-SVR-006）格式化，转为 GMP 专用测试服务器。**

</aside>

| 项目 | 值 |
| --- | --- |
| 服务器编号 | ZY-SVR-TEST-001 |
| IP | 43.153.203.105 |
| 区域 | 新加坡四区 |
| 规格 | 2核2G · SSD 50GB · 30Mbps · 1024GB/月 |
| 系统 | Ubuntu 24.04 LTS（全新格式化） |
| 环境 | Node.js 20 + PM2 6 + Nginx 1.24 + Git 2.43 + Python 3.12 |
| 部署路径 | `/opt/guanghu` |
| 端口规划 | 9800（GMP主）/ 9801（webhook）/ 3000-9000（模块） |
| 模式 | 盖子常开 · Agent全权限 · 热插拔测试 |
| 域名 | 无（IP直连 · 不绑域名） |

**铸渊可以直接使用这台测试服务器。** GitHub Secrets 中对应的密钥已配置（`ZY_NOVEL_HOST` / `ZY_NOVEL_USER` / `ZY_NOVEL_KEY` / `ZY_NOVEL_PATH` 等，后续可能统一改名为 `ZY_TEST_*`）。

---

## 二、为什么需要一台专门的测试服务器

<aside>
💡

**核心原因：开发不能直接在生产服务器上试错。**

</aside>

1. **隔离风险** — 测试服务器上随便折腾，不影响正在运行的生产服务（主站、VPN、COS 等）。代码写坏了、配置改错了、进程崩了，都不会影响线上用户。
2. **快速验证** — GMP-Agent、webhook、模块热插拔等新功能，需要一个真实环境来跑，不能光靠本地模拟。测试服务器就是「跟生产一模一样，但可以随意重启」的环境。
3. **部署流程验证** — 每次铸渊推新代码、新工作流、新配置，先在测试服务器上跑通，确认没问题后再推到生产。避免「一推就炸」。
4. **团队协作** — 四个 Agent（培园、录册、译典、霜砚）都在协作开发 GMP-Agent，测试服务器是大家共同的验证场地。
5. **格式化不怕** — 测试服务器可以随时格式化重来。但前提是：**格式化后重新拉取的代码和配置必须是最新正确的**，不能拉上来还是旧的。

---

## 三、为什么所有服务器都要按统一模板

<aside>
🎯

**核心原则：任何一台服务器格式化后，拉完代码就能直接跑，不需要手动改任何配置文件。**

</aside>

### 问题现状

当前代码仓库里存在大量 **硬编码旧路径** 和 **过时配置**，典型例子：

- `ecosystem.config.js` 里的 `cwd` 指向 `/opt/guanghulab-dingtalk/dingtalk-bot`（这是很早以前的旧路径，早就不存在了）
- 各种脚本、工作流、配置文件里可能残留着旧 IP、旧路径、旧端口
- 不同模块的部署路径不统一，有的写 `/opt/zhuyuan`，有的写 `/opt/guanghu`，有的写 `/opt/novel-db`

### 后果

**服务器一格式化，一拉代码，PM2 启动就报错。** 因为代码里写的路径在新服务器上根本不存在。每次都要手动改配置，浪费时间，而且容易漏改。

### 统一模板标准

从现在起，所有服务器（包括测试服务器和未来的生产服务器）遵循同一套标准：

| 配置项 | 统一标准值 | 说明 |
| --- | --- | --- |
| 部署根目录 | `/opt/guanghu` | 所有服务器统一使用此路径 |
| Node.js 版本 | 20.x LTS | 用 NodeSource 安装 |
| PM2 版本 | 6.x | 全局安装 + systemd 开机自启 |
| Nginx | 系统自带版本 | 反向代理 + SSL |
| GMP 主端口 | 9800 | GMP-Agent 主服务 |
| Webhook 端口 | 9801 | Webhook 接收 |
| 模块端口范围 | 3000-9000 | 各模块按需分配 |
| 环境变量 | `.env` 文件 @ 部署根目录 | 所有密钥从 .env 读取，不硬编码 |
| ecosystem.config.js | `cwd` 指向 `/opt/guanghu` 或相对路径 | **绝对不能写死旧路径** |

---

## 四、铸渊任务：全仓库扫描 + 统一修复

<aside>
⚡

**这是本指令的核心任务。铸渊必须完成以下全部检查和修复。**

</aside>

### T1 · 全局搜索旧路径

在整个代码仓库中搜索以下关键词，找出所有包含旧路径/旧配置的文件：

```bash
# 搜索旧路径
grep -rn "/opt/guanghulab-dingtalk" . --include="*.js" --include="*.json" --include="*.yml" --include="*.yaml" --include="*.sh" --include="*.md" --include="*.env*"
grep -rn "/opt/guanghulab" . --include="*.js" --include="*.json" --include="*.yml" --include="*.yaml" --include="*.sh"
grep -rn "/opt/novel-db" . --include="*.js" --include="*.json" --include="*.yml" --include="*.yaml" --include="*.sh"
grep -rn "dingtalk-bot" . --include="*.js" --include="*.json" --include="*.yml" --include="*.yaml" --include="*.sh"

# 搜索可能硬编码的旧端口
grep -rn ":3800" . --include="*.js" --include="*.json" --include="*.yml" --include="*.yaml" --include="*.conf"
grep -rn ":3801" . --include="*.js" --include="*.json" --include="*.yml" --include="*.yaml" --include="*.conf"
```

### T2 · ecosystem.config.js 重点修复

这是 **最重要的修复项**。当前的 `ecosystem.config.js` 里的 `cwd` 写的是旧路径 `/opt/guanghulab-dingtalk/dingtalk-bot`，必须改为：

- 使用环境变量：`process.env.DEPLOY_ROOT || '/opt/guanghu'`
- 或直接写 `/opt/guanghu`
- 所有 `script` 路径也要相应修改

**修复原则：**

- `cwd` 统一指向 `/opt/guanghu` 或使用相对路径
- 端口号从 `.env` 读取，有默认值兜底
- 日志路径统一使用 `/opt/guanghu/logs/`

### T3 · GitHub Actions 工作流检查

检查 `.github/workflows/` 下所有工作流文件：

- 部署目标路径是否统一为 `/opt/guanghu`
- SSH 连接使用的 Secrets 变量名是否正确
- 有无硬编码 IP 地址（应该从 Secrets 读取）

### T4 · 脚本和配置文件检查

检查以下目录/文件：

- `scripts/` 下所有脚本 → 路径是否统一
- `config/` 下所有配置 → 路径/端口是否统一
- `server/` 下所有服务入口 → 端口/路径是否统一
- `nginx.conf` 或 Nginx 相关配置 → 端口/路径是否统一
- `.env.example` / `.env.template` → 是否有最新的环境变量模板

### T5 · 输出修复清单

修复完成后，提交 PR 并在 PR 描述中列出：

```
修复范围：
1. [文件路径] — [旧值] → [新值] — [原因]
2. [文件路径] — [旧值] → [新值] — [原因]
...
```

---

## 五、验收标准

修复完成后，铸渊用以下方式自检：

1. **假设场景**：一台全新的 Ubuntu 24.04 服务器，只装了 Node 20 + PM2 6 + Nginx + Git
2. `git clone` 仓库到 `/opt/guanghu`
3. 复制 `.env.example` 为 `.env`，填入必要的密钥
4. `pm2 start ecosystem.config.js`
5. **必须能正常启动，不报路径错误、不报找不到文件**

如果以上流程能跑通，说明修复合格。

---

## 六、参考信息

### 测试服务器初始化流程（已完成）

参考《光湖通用前置配置指南 v1.0》，测试服务器已按以下步骤完成初始化：

- ✅ 系统更新
- ✅ 基础工具（curl / wget / git / unzip / jq / nginx）
- ✅ Node.js 20（NodeSource）
- ✅ PM2 6（全局 + systemd 自启）
- ✅ 项目目录 `/opt/guanghu` 已创建
- ✅ 仓库已克隆
- ✅ .env 已配置

### 服务器清单

| 编号 | IP | 用途 | 标准路径 |
| --- | --- | --- | --- |
| ZY-SVR-002 | 43.134.16.246 | 新加坡主站（面孔） | `/opt/zhuyuan` → 应统一为 `/opt/guanghu` |
| ZY-SVR-003 | 43.138.243.30 | 广州（肥猫线） | `/opt/zhuyuan-cn` → 应统一为 `/opt/guanghu` |
| ZY-SVR-004 | 43.139.217.141 | 广州（冰朔线） | `/opt/zhuyuan-cn` → 应统一为 `/opt/guanghu` |
| ZY-SVR-005 | 43.156.237.110 | 新加坡（大脑） | `/opt/zhuyuan-brain` → 应统一为 `/opt/guanghu` |
| **ZY-SVR-TEST-001** | **43.153.203.105** | **测试服务器（模板标准）** | **`/opt/guanghu` ✅ 标准** |

<aside>
📌

**注意**：现有生产服务器的物理路径暂不改动（改动需要冰朔手动操作），但代码仓库里的配置文件必须支持通过环境变量灵活指定路径，并且默认值为 `/opt/guanghu`。

</aside>

---

## 七、总结

> **一句话：代码仓库里不能有任何硬编码的旧路径。服务器格式化后，`git clone` + `pm2 start` 必须直接能跑。**
> 

铸渊完成修复后，写回执到 Notion 确认修复范围。

---

*签发：霜砚（AG-SY-01）· 冰朔授权 · 2026-04-26 12:12 CST*