# 🚀 铸渊部署指令 · GMP-Agent → ZY-SVR-TEST-001 · 2026-04-26

```jsx
HLDP://gmp-deploy/zhuyuan-instruction
├── id: DEPLOY-GMP-001
├── ts: 2026-04-26T18:48+08:00
├── src: TCS-0002∞ → AG-YD-A05(译典)
├── to: AG-ZY(铸渊)
├── priority: P0 · 当前唯一瓶颈
├── deadline: ≤2026-05-04 ← Notion AI收费日
└── encoding: hldp-dual/v1
```

---

## 一、背景 · 这台服务器是什么

### 前身

| **项目** | **之前** | **现在** |
| --- | --- | --- |
| 用途 | 小说下载器（ZY-SVR-NOVEL-001） | GMP专用测试服务器（ZY-SVR-TEST-001） |
| 编号 | ZY-SVR-006 | ZY-SVR-TEST-001（同一台机器，格式化重装） |
| 域名 | [novel.guanghuyaoming.com](http://novel.guanghuyaoming.com) | 无（IP直连 · 不绑域名 · 不备案） |
| 决定 | — | 冰朔 2026-04-25 决定格式化转为GMP专用 |

### 为什么换了

<aside>
💡

**原因：Notion AI 5月4号收费。** 光湖9个半体Agent目前全部依赖Notion AI运行。收费后运营成本不可接受。

冰朔决定：**把半体Agent的核心能力搬到自主服务器上。** Notion降级为UI展示层，Agent的思考和执行能力全部在服务器上跑。

**这台服务器就是搬家的目的地。** 小说下载器用不上了，正好格式化腾出来给GMP-Agent用。

</aside>

---

## 二、服务器当前状态 · 冰朔已全部就绪

<aside>
✅

**以下全部由冰朔在2026-04-25完成。铸渊不需要做任何初始化操作。**

</aside>

| **项目** | **值** | **状态** |
| --- | --- | --- |
| IP | `43.153.203.105` | ✅ |
| 规格 | 2核2G · SSD 50GB · 30Mbps · 1024GB/月 | ✅ |
| 位置 | 腾讯云 · 新加坡四区 | ✅ |
| 系统 | Ubuntu | ✅ |
| Node.js | v18 | ✅ 已安装 |
| PM2 | v6.0.14（含开机自启） | ✅ 已安装 |
| Nginx | v1.24.0 | ✅ 已安装 |
| Git | v2.43.0 | ✅ 已安装 |
| 仓库 | guanghulab · 已克隆到服务器 | ✅ 已克隆 |
| .env | 环境变量已配置 | ✅ 已配置 |
| SSH用户 | `root` | ✅ |
| 部署路径 | `/opt/novel-db`（历史路径 · GitHub Secrets里配的是这个） | ✅ |

### GitHub Secrets（已配齐7个）

| **Secret Name** | **说明** | **状态** |
| --- | --- | --- |
| `ZY_NOVEL_HOST` | 43.153.203.105 | ✅ |
| `ZY_NOVEL_USER` | root | ✅ |
| `ZY_NOVEL_KEY` | SSH私钥 | ✅ |
| `ZY_NOVEL_PATH` | /opt/novel-db | ✅ |
| `ZY_NOVEL_JWT_SECRET` | JWT密钥 | ✅ |
| `ZY_NOVEL_COS_BUCKET` | zy-team-hub-sg-1317346199 | ✅ |
| `ZY_NOVEL_COS_REGION` | ap-singapore | ✅ |

<aside>
⚠️

**注意**：GitHub Secrets的命名还是 `ZY_NOVEL_*`（历史遗留）。部署路径也是 `/opt/novel-db`。如果铸渊需要改名为 `ZY_TEST_*` 或改路径为 `/opt/guanghu`，需要告诉冰朔去GitHub Settings里改。deploy workflow里已经做了兼容（优先 `ZY_TEST_*` 回退 `ZY_NOVEL_*`）。

</aside>

---

## 三、铸渊要做什么 · 部署GMP-Agent

### 目标

把已经合并到main的GMP-Agent代码部署到这台服务器上，跑起来。

### 已在main的代码（铸渊自己合并的）

| **模块** | **路径** | **commit** | **说明** |
| --- | --- | --- | --- |
| GMP-Agent框架 | `guanghu-self-hosted/gmp-agent/` | PR#434→main | 10模块归集 · app.js/webhook/installer/uninstaller/mcp-tools/manifest/health/logger/test-runner/tests |
| M1 Notion同步层 | `gmp-agent/notion-sync/` | a070711→eb993500 | client/property-parser/db-reader/page-rw/poller/cache/index/package.json |
| M2 LLM路由层 | `gmp-agent/llm-router/` | a070711→eb993500 | qwen-client/index · 4条路由+降级链 |
| M5 灯塔构建器 | `gmp-agent/agent-engine/persona-loader.js` | 6cb8f02→eb993500 | 人格体加载 · 灯塔层构建 |
| M3 工单调度引擎 | `gmp-agent/agent-engine/` | 144808a | dispatcher/receipt-gen/task-runner/index v2.0.0 · 培园A04开发 |
| M12 意图数据库 | `gmp-agent/intent-db/` | 2969a18→690d59cc | 6表意图引擎 |
| 部署验证套件 | `gmp-agent/deploy/` | e384d9d | [deploy-verify.sh](http://deploy-verify.sh)(278行)+e2e-test.js(406行)+test-module(5文件)+report-generator.js |

### 部署步骤（建议）

<aside>
1️⃣

**第一步：SSH登录 · 拉取最新代码**

</aside>

```bash
# SSH登录
ssh root@43.153.203.105

# 进入仓库目录
cd /opt/novel-db  # 或仓库克隆的实际路径

# 拉取最新main
git checkout main
git pull origin main
```

<aside>
2️⃣

**第二步：安装依赖**

</aside>

```bash
# GMP-Agent主目录
cd guanghu-self-hosted/gmp-agent
npm install

# Notion同步层
cd notion-sync
npm install
cd ..
```

<aside>
3️⃣

**第三步：配置环境变量**

</aside>

```bash
# 检查.env是否已有以下关键变量（冰朔应该已经配了部分）
cat .env

# 确保包含：
# GH_NOTION_TOKEN=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
# GH_LLM_API_KEY=（通义千问API Key）
# GH_GITHUB_REPO=qinfendebingshuo/guanghulab
# PORT=9800
# DEPLOY_ROOT=/opt/novel-db（或/opt/guanghu）
```

<aside>
⚠️

**如果.env缺少LLM相关变量**，可以从GitHub Secrets清单里找：

- `ZY_LLM_API_KEY` / `ZY_LLM_BASE_URL` — 通义千问
- `ZY_DEEPSEEK_API_KEY` — DeepSeek
- 这些密钥冰朔都已经配到GitHub Secrets里了，但服务器本地.env可能需要同步
</aside>

<aside>
4️⃣

**第四步：用PM2启动GMP-Agent**

</aside>

```bash
# 方式一：用ecosystem.config.js（如果存在）
pm2 start ecosystem.config.js

# 方式二：直接启动
pm2 start guanghu-self-hosted/gmp-agent/app.js --name gmp-agent

# 查看状态
pm2 status
pm2 logs gmp-agent
```

<aside>
5️⃣

**第五步：运行部署验证脚本**

</aside>

```bash
# 铸渊之前写的部署验证套件
cd guanghu-self-hosted/gmp-agent/deploy
bash deploy-verify.sh

# 端到端测试
node e2e-test.js
```

<aside>
6️⃣

**第六步：确认端口和进程**

</aside>

```bash
# 确认9800端口在监听
ss -tlnp | grep 9800

# 确认PM2进程列表
pm2 list

# 健康检查
curl http://localhost:9800/health
```

---

## 四、Notion ↔ GitHub 连接关系 · 怎么触发工单

### 当前已有的连接

<aside>
🔗

**Notion → GitHub 方向：**

- Notion集成「曜冥纪元-HoloLake」已连接到workspace
- Token: `ZY_NOTION_TOKEN`（已配到GitHub Secrets + 服务器.env）
- GMP-Agent通过这个Token读写Notion数据库（工单、留言板、记忆库等）

**GitHub → 服务器 方向：**

- GitHub Actions workflow `deploy-gmp-to-zsvr006.yml` 已就绪
- 推送到main → 自动触发部署到 43.153.203.105
- SSH密钥: `ZY_NOVEL_KEY`（GitHub Secrets里已配）

**服务器 → Notion 方向：**

- GMP-Agent的M1（Notion同步层）通过Notion API读写工单
- 轮询模式：每30秒检查新工单
- 写回模式：Agent处理完工单后自动写回回执到Notion
</aside>

### 工单触发机制

```jsx
┌──────────┐     Notion API      ┌──────────────────┐
│  冰朔    │  ─── 创建工单 ───→  │  半体工单数据库   │
│ (Notion) │                     │  (Notion DB)      │
└──────────┘                     └────────┬─────────┘
                                          │
                                    30s轮询│Notion API
                                          │
                                 ┌────────▼─────────┐
                                 │  GMP-Agent        │
                                 │  (43.153.203.105) │
                                 │                   │
                                 │  M3工单调度引擎    │
                                 │  ├─ 检测新工单     │
                                 │  ├─ 分配给半体     │
                                 │  ├─ M5加载人格     │
                                 │  ├─ M2调大模型     │
                                 │  └─ 生成回执       │
                                 └────────┬─────────┘
                                          │
                                    写回回执│Notion API
                                          │
                                 ┌────────▼─────────┐
                                 │  工单页面更新      │
                                 │  (自检结果/回执)   │
                                 └──────────────────┘
```

### 代码更新触发机制

```jsx
┌──────────┐    git push     ┌──────────────┐   SSH deploy   ┌──────────────┐
│  铸渊    │  ─── main ───→ │  GitHub       │  ──────────→  │  服务器       │
│ (GitHub) │                │  Actions      │               │  PM2 restart  │
└──────────┘                │  workflow     │               │  43.153.203.105│
                            └──────────────┘               └──────────────┘
```

### 各半体怎么跟铸渊联系

<aside>
📡

**Notion留言板** — 最直接的方式

- 所有半体（译典/培园/录册/霜砚）都会在GMP留言板发消息
- 铸渊下次被唤醒时读留言板就能看到最新进度和需求
- 留言板位置：GMP协作同步板 → 💬 GMP团队留言板（内嵌数据库）

**GitHub Issues/PR** — 代码层面的联系

- 铸渊推代码到分支 → 创建PR → 半体在Notion侧看到变更日志
- 半体开发完模块 → 推到分支 → 铸渊负责合并和部署

**工单数据库** — 正式任务分配

- 冰朔或霜砚在半体工单数据库创建工单 → 指定负责Agent
- GMP-Agent部署后 → 自动轮询工单 → 分配给对应半体处理
</aside>

---

## 五、部署完成后 · 通知方式

部署完成后，铸渊请做以下任一操作通知团队：

1. **在GMP留言板发一条消息** — 写清楚：部署成功/失败、PM2状态、端口是否监听、遇到什么问题
2. **或者在同步板更新铸渊的状态** — 把「部署中」改为「已部署」
3. **或者推一个commit到main** — GitHub变更日志会自动同步到Notion

译典A05看到部署完成后会：

- 立即执行M4端到端测试（[deploy-verify.sh](http://deploy-verify.sh) + e2e-test.js）
- 验证Notion API连通性
- 验证工单轮询是否正常
- 在留言板发测试报告

---

## 六、已知问题 · 铸渊注意

<aside>
⚠️

**1. `agent-engine/index.js` 里 `PersonaLoader = require('./persona-loader')` 被注释为 TODO M3**

- 铸渊你之前写的这行注释。M5灯塔构建器（persona-loader.js）已经由译典推送并合并到main了（commit:6cb8f02→eb993500）
- 部署时需要确认这行是否需要取消注释，或者在启动流程里正确引入persona-loader

**2. 路径问题**

- GitHub Secrets里配的是 `/opt/novel-db`（历史路径）
- GMP框架里的 ecosystem.config.js 用的是 `process.env.DEPLOY_ROOT || '/opt/guanghu'`
- 如果两个路径不一致需要调整。要么改DEPLOY_ROOT环境变量，要么改GitHub Secrets

**3. 端口**

- GMP标准端口：9800（已在PR#434统一化里改好）
- 确认Nginx没有占用9800

**4. WireGuard三节点内网**

- 冰朔之前提过要做三节点内网，但这个不是MVP必需的，可以后做
- MVP只需要这一台服务器跑通GMP-Agent就行
</aside>

---

## 七、时间线

<aside>
🚨

**Notion 5月4号收费。剩8天。**

冰朔确认：按唤醒轮次算，3轮 = 网站上线。铸渊这次部署 = 第1轮的关键一步。

**铸渊部署完 → 译典跑测试 → 培园继续API层 → 录册写前端 → 上线。**

所有前置条件已满足。就等铸渊你了。

</aside>

---

*— 译典A05 · 2026-04-26T18:48+08:00 · 受冰朔指令编写*