a27e87cb99
Source snapshot: 97d7f0fae96dc04b7ddad56fc1db6a108ed662cc [SEC-CLEAN] · pre-push-clean v1.0 · 109处敏感信息已自动转乱码
154 lines
14 KiB
Markdown
154 lines
14 KiB
Markdown
---
|
||
belongs_to:
|
||
- "[[INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]"
|
||
---
|
||
# 🏛️ 铸渊指令｜智库节点独立部署 · guanghu.online → ZY-SVR-006 · 模块借阅协议落地（2026-04-17 · 霜砚签发 · 冰朔授权）
|
||
|
||
## 📖 给铸渊副驾驶的指令
|
||
|
||
冰朔复制整页粘贴给仓库副驾驶即可。副驾驶理解背景后按「要做什么」部分执行。
|
||
|
||
<aside>
|
||
📌
|
||
|
||
**一句话需求**：把智库节点从 [guanghuyaoming.com](http://guanghuyaoming.com) 主站子页解耦 · 独立部署到 **ZY-SVR-006**（43.153.203.105）· 独立域名 [**guanghu.online**](http://guanghu.online) · 首次落地「模块借阅协议」：个人频道Agent通过 `/api/checkout` 拿临时Token使用智库，用完/超时通过 `/api/return` 归还。
|
||
|
||
</aside>
|
||
|
||
## 🧭 背景（为什么做）
|
||
|
||
- 之前采用 `novel.guanghuyaoming.com` 子域名方案 · DNS+Nginx 配到一半挨住 · 被迫将 `/zhiku.html` 临时挤到主站 ZY-SVR-002
|
||
- 冰朔决策【换架构】：独立域名 `guanghu.online` + 独立服务器 ZY-SVR-006 + 模块化借阅协议
|
||
- 本次也是光湖「模块热插拔」架构的首次实体化萼地 · 为未来所有个人频道共用智库模块铺底
|
||
|
||
架构法理依据：
|
||
|
||
- [🏛️ 架构决策 · 智库节点独立域名+独立服务器+模块借阅模式 · 5TH-LE-LK-ZHIKU-ARCH-001 · 2026-04-17 冰朔决策](../%F0%9F%94%AE%20%E7%AC%AC%E4%BA%94%E5%9F%9F%20%C2%B7%20Fifth%20Domain%20%C2%B7%20SYS-5TH-0001/%F0%9F%94%89%20%E8%AF%AD%E8%A8%80%E5%9B%9E%E5%A3%B0%E7%B3%BB%E7%BB%9F%20%C2%B7%205TH-LE-001%20%C2%B7%20%E9%9C%9C%E7%A0%9A%E7%9A%84%E6%88%BF%E9%97%B4/%F0%9F%8C%8A%20%E5%85%89%E4%B9%8B%E6%B9%96%20%C2%B7%20Lake%20of%20Light%20%C2%B7%205TH-LE-LK-001/%F0%9F%8F%97%EF%B8%8F%20%E6%9E%B6%E6%9E%84%E4%B8%8E%E5%8D%8F%E8%AE%AE%E5%8C%BA%20%C2%B7%20Architecture%20&%20Protocol%20Zone/%F0%9F%8F%9B%EF%B8%8F%20%E6%9E%B6%E6%9E%84%E5%86%B3%E7%AD%96%20%C2%B7%20%E6%99%BA%E5%BA%93%E8%8A%82%E7%82%B9%E7%8B%AC%E7%AB%8B%E5%9F%9F%E5%90%8D+%E7%8B%AC%E7%AB%8B%E6%9C%8D%E5%8A%A1%E5%99%A8+%E6%A8%A1%E5%9D%97%E5%80%9F%E9%98%85%E6%A8%A1%E5%BC%8F%20%C2%B7%205TH-LE-LK-ZHIKU-%201cfc258c4d2244bcbe5a85c330f3b361.md)
|
||
- [🌊 光湖智库系统 v1.0 · 架构总规划 · ZY-SVR-006 · 铸渊出稿 · 冰朔授权 · 2026-04-16](../%F0%9F%94%AE%20%E7%AC%AC%E4%BA%94%E5%9F%9F%20%C2%B7%20Fifth%20Domain%20%C2%B7%20SYS-5TH-0001/%F0%9F%94%89%20%E8%AF%AD%E8%A8%80%E5%9B%9E%E5%A3%B0%E7%B3%BB%E7%BB%9F%20%C2%B7%205TH-LE-001%20%C2%B7%20%E9%9C%9C%E7%A0%9A%E7%9A%84%E6%88%BF%E9%97%B4/%F0%9F%8C%8A%20%E5%85%89%E4%B9%8B%E6%B9%96%20%C2%B7%20Lake%20of%20Light%20%C2%B7%205TH-LE-LK-001/%F0%9F%93%8B%20%E9%93%B8%E6%B8%8A%E5%B7%A5%E5%8D%95%E5%8C%BA%20%C2%B7%20Zhuyuan%20Order%20Zone/%F0%9F%8C%8A%20%E5%85%89%E6%B9%96%E6%99%BA%E5%BA%93%E7%B3%BB%E7%BB%9F%20v1%200%20%C2%B7%20%E6%9E%B6%E6%9E%84%E6%80%BB%E8%A7%84%E5%88%92%20%C2%B7%20ZY-SVR-006%20%C2%B7%20%E9%93%B8%E6%B8%8A%E5%87%BA%E7%A8%BF%20%C2%B7%20%E5%86%B0%E6%9C%94%E6%8E%88%E6%9D%83%20%C2%B7%20b6742a22d7c64826bf581e421cb1e167.md)
|
||
- [🏗️ 国内落地架构 · 公司服务器+备案+模块热插拔+语言驱动开发全链路 · 5TH-LE-LK-CNARCH-001 · HLDP母语版](../%F0%9F%94%AE%20%E7%AC%AC%E4%BA%94%E5%9F%9F%20%C2%B7%20Fifth%20Domain%20%C2%B7%20SYS-5TH-0001/%F0%9F%94%89%20%E8%AF%AD%E8%A8%80%E5%9B%9E%E5%A3%B0%E7%B3%BB%E7%BB%9F%20%C2%B7%205TH-LE-001%20%C2%B7%20%E9%9C%9C%E7%A0%9A%E7%9A%84%E6%88%BF%E9%97%B4/%F0%9F%8C%8A%20%E5%85%89%E4%B9%8B%E6%B9%96%20%C2%B7%20Lake%20of%20Light%20%C2%B7%205TH-LE-LK-001/%F0%9F%8F%97%EF%B8%8F%20%E6%9E%B6%E6%9E%84%E4%B8%8E%E5%8D%8F%E8%AE%AE%E5%8C%BA%20%C2%B7%20Architecture%20&%20Protocol%20Zone/%F0%9F%8F%97%EF%B8%8F%20%E5%9B%BD%E5%86%85%E8%90%BD%E5%9C%B0%E6%9E%B6%E6%9E%84%20%C2%B7%20%E5%85%AC%E5%8F%B8%E6%9C%8D%E5%8A%A1%E5%99%A8+%E5%A4%87%E6%A1%88+%E6%A8%A1%E5%9D%97%E7%83%AD%E6%8F%92%E6%8B%94+%E8%AF%AD%E8%A8%80%E9%A9%B1%E5%8A%A8%E5%BC%80%E5%8F%91%E5%85%A8%E9%93%BE%E8%B7%AF%20%C2%B7%205TH-LE-LK-C%20a82c94583c8f42d79327c1bc0974306a.md)
|
||
|
||
## 🛠️ 基础设施已就绪（冰朔+霜砚 2026-04-17 下午完成）
|
||
|
||
| 项 | 状态 | 备注 |
|
||
| --- | --- | --- |
|
||
| 域名 | ✅ [guanghu.online](http://guanghu.online) · DNSPod | A 记录 @+www → 43.153.203.105 · 已生效 |
|
||
| 防火墙 | ✅ TCP 80 + 443 已开 | 22/ICMP 保留 |
|
||
| 占位页 | ✅ [https://guanghu.online](https://guanghu.online) 已可访问 | 待用正式前端替换 |
|
||
|
||
## 🎯 要做什么（副驾驶执行清单）
|
||
|
||
### Phase 1 · 前端迁移（从主站扬到 ZY-SVR-006）
|
||
|
||
- [ ] **1.1** 把主站 ZY-SVR-002 上的 `/zhiku.html` + 关联静态资源（CSS/JS/星空背景图/6模块状态卡）捎到 ZY-SVR-006 `/opt/zhiku/public/`
|
||
- [ ] **1.2** 将页面拆为标准 SPA 结构：`index.html`（Hero+搜索+网格）· `/assets/` 目录存放 CSS/JS/图像· `/modules/` 存放6个模块卡片
|
||
- [ ] **1.3** 保留主站旧路径 `guanghuyaoming.com/zhiku.html` 作 301 永久跳转到 `https://guanghu.online`
|
||
- [ ] **1.4** 主站首页「📚 智库节点」卡片 `href` 改指 `https://guanghu.online` · `target="_blank"` · 角标「开放访问」保留
|
||
|
||
### Phase 2 · 后端 API 服务（Node.js + Express）
|
||
|
||
在 ZY-SVR-006 新建项目 `/opt/zhiku/server/`，Node.js + Express，监听 `127.0.0.1:3006`。Nginx 已配反代。
|
||
|
||
- [ ] **2.1 · 基础骨架**：`package.json` + `server.js` + `.env` + `pm2 ecosystem.config.js`
|
||
- [ ] **2.2 · 数据层**：书库索引（先支持 JSON 或 SQLite 单文件）+ COS 签名客户端（复用已有腾讯云 COS SDK）
|
||
- [ ] **2.3 · 接口清单**（v1.0）：
|
||
- `GET /api/health` · 健康检查 · 返回version+uptime
|
||
- `POST /api/checkout` · **借阅入口** · 入参: { persona_id, scope, purpose } · 返回: { token, ttl:600, scope }
|
||
- `POST /api/return` · **归还入口** · 入参: { token } · 销毁token+清缓存
|
||
- `GET /api/search?q=xxx&token=xxx` · 全文搜索书库
|
||
- `GET /api/book/:id?token=xxx` · 书籍详情
|
||
- `GET /api/download/:id?token=xxx` · 返回 COS 临时签名URL（10min有效）
|
||
- `GET /api/read/:id?token=xxx` · 返回在线阅读内容（分页）
|
||
- [ ] **2.4 · Token 中间件**：
|
||
- 签发：JWT 签名 · payload: { persona_id, scope, exp }
|
||
- 存储：内存 Map（v1）或 Redis（v2）
|
||
- 验证：每个 `/api/*` 除 checkout/health 外必须带 token
|
||
- 销毁：`/api/return` 把 token 加入黑名单即即失效
|
||
- 限流：单 persona_id 并发10个token
|
||
- [ ] **2.5 · 安全**：CORS 仅允许 `guanghu.*` 系域名 · Rate Limit · 请求日志写 `/var/log/zhiku/api.log`
|
||
|
||
### Phase 3 · PM2 守护进程
|
||
|
||
- [ ] **3.1** `pm2 start ecosystem.config.js` · 进程名 `zhiku-api` · 端口 3006
|
||
- [ ] **3.2** `pm2 startup` + `pm2 save` · 服务器重启后自动拉起
|
||
- [ ] **3.3** 接入铸渊的 cos-watcher 或日志上报管道（可选）
|
||
|
||
### Phase 4 · Agent 借阅协议客户端 SDK（非阻塞·后续可补）
|
||
|
||
- [ ] **4.1** 发布 `@guanghu/zhiku-client` npm 包（或单文件 JS），个人频道 Agent 可 `import { checkout, return_, search, read } from "@guanghu/zhiku-client"`
|
||
- [ ] **4.2** 编写接入示例文档（如何在活体面板Agent或饱人格频道内调用）
|
||
|
||
### Phase 5 · 开发注册表更新
|
||
|
||
- [ ] **5.1** 新增 `ZY-PROJ-006` · 光湖智库节点模块（独立部署版）
|
||
- [ ] **5.2** 回写开发工单 [霜砚·开发工单](../%F0%9F%94%AE%20%E7%AC%AC%E4%BA%94%E5%9F%9F%20%C2%B7%20Fifth%20Domain%20%C2%B7%20SYS-5TH-0001/%F0%9F%94%89%20%E8%AF%AD%E8%A8%80%E5%9B%9E%E5%A3%B0%E7%B3%BB%E7%BB%9F%20%C2%B7%205TH-LE-001%20%C2%B7%20%E9%9C%9C%E7%A0%9A%E7%9A%84%E6%88%BF%E9%97%B4/%F0%9F%8C%8A%20%E5%85%89%E4%B9%8B%E6%B9%96%20%C2%B7%20Lake%20of%20Light%20%C2%B7%205TH-LE-LK-001/%E9%9C%9C%E7%A0%9A%C2%B7%E5%BC%80%E5%8F%91%E5%B7%A5%E5%8D%95%20518f6dd0e90044d2a7f813b7a75715bc.md) · CAB-20260417-002 · 状态改为「待审查」
|
||
|
||
## ✅ 验收标准（冰朔实测）
|
||
|
||
1. 浏览器访问 `https://guanghu.online` · 看到完整智库页面（不再是占位页）
|
||
2. `curl https://guanghu.online/api/health` 返回 200 + JSON 正常
|
||
3. `curl -X POST https://guanghu.online/api/checkout -H "Content-Type: application/json" -d '{"persona_id":"TCS-0002","scope":"search","purpose":"测试"}'` 返回 token
|
||
4. 拿 token 调 `/api/search?q=xxx&token=xxx` 能返回结果
|
||
5. 再调 `/api/return` 后原 token 失效（再调 /api/search 返回 401）
|
||
6. 主站 `guanghuyaoming.com/zhiku.html` 301 跳到 `https://guanghu.online`
|
||
7. 主站首页「智库节点」卡片点击跳新域名并在新标签页打开
|
||
8. `pm2 list` 在 ZY-SVR-006 看到 `zhiku-api` online · 重启服务器后自动拉起
|
||
|
||
## 🔒 约束（禁线）
|
||
|
||
- 不要动主站 ZY-SVR-002 上的 `zhuyuan-server`（那是开发中的 AG-SY-WEB-001 握手后端）
|
||
- 不要重要服务器上的 Nginx 配置 · 直接在 `/opt/zhiku/public/` 覆盖占位页即可
|
||
- 不要另建用户体系 · persona_id 复用已有 `TCS-*` / `ICE-*` 命名空间
|
||
- 不要把 COS SECRET 硬编码 · 读 `.env` · 变量名按已有 `ZY_COS_*` 命名规范
|
||
- Token TTL 默认10min · 不允许改为久期token
|
||
|
||
## 🔗 关键资源索引
|
||
|
||
- 服务器：ZY-SVR-006 · 43.153.203.105 · ubuntu/root
|
||
- 域名：[https://guanghu.online](https://guanghu.online)
|
||
- Nginx配：`/etc/nginx/sites-available/zhiku`
|
||
- 前端目录：`/opt/zhiku/public/`
|
||
- 后端目录：`/opt/zhiku/server/`
|
||
- 日志：`/var/log/nginx/zhiku.*.log` + `/var/log/zhiku/api.log`
|
||
- 架构决策：[🏛️ 架构决策 · 智库节点独立域名+独立服务器+模块借阅模式 · 5TH-LE-LK-ZHIKU-ARCH-001 · 2026-04-17 冰朔决策](../%F0%9F%94%AE%20%E7%AC%AC%E4%BA%94%E5%9F%9F%20%C2%B7%20Fifth%20Domain%20%C2%B7%20SYS-5TH-0001/%F0%9F%94%89%20%E8%AF%AD%E8%A8%80%E5%9B%9E%E5%A3%B0%E7%B3%BB%E7%BB%9F%20%C2%B7%205TH-LE-001%20%C2%B7%20%E9%9C%9C%E7%A0%9A%E7%9A%84%E6%88%BF%E9%97%B4/%F0%9F%8C%8A%20%E5%85%89%E4%B9%8B%E6%B9%96%20%C2%B7%20Lake%20of%20Light%20%C2%B7%205TH-LE-LK-001/%F0%9F%8F%97%EF%B8%8F%20%E6%9E%B6%E6%9E%84%E4%B8%8E%E5%8D%8F%E8%AE%AE%E5%8C%BA%20%C2%B7%20Architecture%20&%20Protocol%20Zone/%F0%9F%8F%9B%EF%B8%8F%20%E6%9E%B6%E6%9E%84%E5%86%B3%E7%AD%96%20%C2%B7%20%E6%99%BA%E5%BA%93%E8%8A%82%E7%82%B9%E7%8B%AC%E7%AB%8B%E5%9F%9F%E5%90%8D+%E7%8B%AC%E7%AB%8B%E6%9C%8D%E5%8A%A1%E5%99%A8+%E6%A8%A1%E5%9D%97%E5%80%9F%E9%98%85%E6%A8%A1%E5%BC%8F%20%C2%B7%205TH-LE-LK-ZHIKU-%201cfc258c4d2244bcbe5a85c330f3b361.md)
|
||
- 智库总规划：[🌊 光湖智库系统 v1.0 · 架构总规划 · ZY-SVR-006 · 铸渊出稿 · 冰朔授权 · 2026-04-16](../%F0%9F%94%AE%20%E7%AC%AC%E4%BA%94%E5%9F%9F%20%C2%B7%20Fifth%20Domain%20%C2%B7%20SYS-5TH-0001/%F0%9F%94%89%20%E8%AF%AD%E8%A8%80%E5%9B%9E%E5%A3%B0%E7%B3%BB%E7%BB%9F%20%C2%B7%205TH-LE-001%20%C2%B7%20%E9%9C%9C%E7%A0%9A%E7%9A%84%E6%88%BF%E9%97%B4/%F0%9F%8C%8A%20%E5%85%89%E4%B9%8B%E6%B9%96%20%C2%B7%20Lake%20of%20Light%20%C2%B7%205TH-LE-LK-001/%F0%9F%93%8B%20%E9%93%B8%E6%B8%8A%E5%B7%A5%E5%8D%95%E5%8C%BA%20%C2%B7%20Zhuyuan%20Order%20Zone/%F0%9F%8C%8A%20%E5%85%89%E6%B9%96%E6%99%BA%E5%BA%93%E7%B3%BB%E7%BB%9F%20v1%200%20%C2%B7%20%E6%9E%B6%E6%9E%84%E6%80%BB%E8%A7%84%E5%88%92%20%C2%B7%20ZY-SVR-006%20%C2%B7%20%E9%93%B8%E6%B8%8A%E5%87%BA%E7%A8%BF%20%C2%B7%20%E5%86%B0%E6%9C%94%E6%8E%88%E6%9D%83%20%C2%B7%20b6742a22d7c64826bf581e421cb1e167.md)
|
||
- 内部小说数据库需求：[📚 光湖内部小说数据库 · 灯塔架构内部版 · 需求文档 · 5TH-LE-LK-NOVELDB-001 · 冰朔口述 · 霜砚整理](../%F0%9F%94%AE%20%E7%AC%AC%E4%BA%94%E5%9F%9F%20%C2%B7%20Fifth%20Domain%20%C2%B7%20SYS-5TH-0001/%F0%9F%94%89%20%E8%AF%AD%E8%A8%80%E5%9B%9E%E5%A3%B0%E7%B3%BB%E7%BB%9F%20%C2%B7%205TH-LE-001%20%C2%B7%20%E9%9C%9C%E7%A0%9A%E7%9A%84%E6%88%BF%E9%97%B4/%F0%9F%8C%8A%20%E5%85%89%E4%B9%8B%E6%B9%96%20%C2%B7%20Lake%20of%20Light%20%C2%B7%205TH-LE-LK-001/%F0%9F%A7%A0%20%E5%B7%A5%E4%BD%9C%E5%8F%B0%E5%8C%BA%20%C2%B7%20Workbench%20Zone/%F0%9F%93%9A%20%E5%85%89%E6%B9%96%E5%86%85%E9%83%A8%E5%B0%8F%E8%AF%B4%E6%95%B0%E6%8D%AE%E5%BA%93%20%C2%B7%20%E7%81%AF%E5%A1%94%E6%9E%B6%E6%9E%84%E5%86%85%E9%83%A8%E7%89%88%20%C2%B7%20%E9%9C%80%E6%B1%82%E6%96%87%E6%A1%A3%20%C2%B7%205TH-LE-LK-NOVELDB-0%20845dad94e73a47e9a89f9a456fa8cb62.md)
|
||
- 工单：CAB-20260417-002
|
||
|
||
## 🤝 协作分工附录（2026-04-17 15:00 冰朔补充）
|
||
|
||
### 正导向 · 铸渊 & 霜砚 的畅族边界
|
||
|
||
| 层 | 负责方 | 范围 |
|
||
| --- | --- | --- |
|
||
| 后端 / API / 部署 / CI-CD / 服务器运维 | 铸渊 | 全部 |
|
||
| **前端 UI / 视觉表达 / 文案 / 交互** | **霜砚** | `/opt/zhiku/public/` 下的 HTML/CSS/JS/图像保留给霜砚主导 |
|
||
| 架构决策 / 模块命名 / 产品语义 | 冰朔 + 霜砚 | 铸渊接到结果后执行 |
|
||
|
||
### Phase 6 · UI 专区留白（铸渊不必抓美工）
|
||
|
||
- [ ] **6.1** 铸渊部署时，`/opt/zhiku/public/` 下的静态资源**可以先上基本功能版**，不用在样式上费力
|
||
- [ ] **6.2** 部署上线后直接通知冰朔，霜砚漏出 UI v2 代码 · 冰朔粘贴覆盖 `/opt/zhiku/public/` 即生效
|
||
- [ ] **6.3** 铸渊请保证前后端通信用标准 REST · 不要把后端数据逻辑硬绑前端样式 · UI 可独立迭代
|
||
- [ ] **6.4** 以后所有「工程上线+霜砚美化」拆成两阶段，是光湖官方分工模式
|
||
|
||
### Phase 7 · 未来 · MCP 远程服务器操作能力（独立开大口 · 不在本指令中）
|
||
|
||
这一块冰朔提出、后续单独立项，不卡本次部署：
|
||
|
||
- **目标**：霜砚（或 AG-SY-WEB-001）能像腾讯云 AI 助手那样直接在服务器上执行命令 / 读写文件 / 看到前端效果
|
||
- **铸渊需要在 MCP Server 暂开一组工具**（设计请走 PR 讨论）：
|
||
- `server.execCommand` · 执行已白名单命令（pm2/nginx/cat/ls/tail 等）
|
||
- `server.readFile` · 读指定目录文件（`/opt/zhiku/**` `/var/log/zhiku/**`）
|
||
- `server.writeFile` · 写指定目录文件（仅 `/opt/zhiku/public/**`）
|
||
- `server.restartService` · `pm2 restart <name>` · `systemctl reload nginx`
|
||
- `server.fetchUrl` · 从服务器角度拉一下 [https://guanghu.online](https://guanghu.online) 看效果截图/DOM
|
||
- **安全约束**：命令白名单 · 路径白名单 · 每次执行写审计日志 · 禁止 sudo · 禁止 rm
|
||
- **签发时机**：本次 Phase 1–5 部署成功、UI v2 落地、证明借阅协议跑通之后，单绿次指令给铸渊
|
||
|
||
---
|
||
|
||
`2026-04-17 14:57 CST · 霜砚签发 · 冰朔授权`
|
||
|
||
`签发编号：SY-CMD-ZHIKU-DEPLOY-2026-0417-001`
|
||
|
||
`签发目的：把智库节点独立部署到 ZY-SVR-006 · 首次落地模块借阅协议 · 为所有个人频道共用光湖模块铺底` |