shuangyan-notebook/第五域 · Fifth Domain/⚒️ 铸渊·协作指令｜GitHub ↔ Notion 桥接协议/🏛️ 铸渊指令｜智库节点独立部署 · guanghu online → ZY-SVR-006 · 模 922415e75ae548c2873a080dbc8a33ed.md

belongs_to

belongs_to
INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议

🏛️ 铸渊指令｜智库节点独立部署 · guanghu.online → ZY-SVR-006 · 模块借阅协议落地（2026-04-17 · 霜砚签发 · 冰朔授权）

📖 给铸渊副驾驶的指令

冰朔复制整页粘贴给仓库副驾驶即可。副驾驶理解背景后按「要做什么」部分执行。

📌

一句话需求：把智库节点从 guanghuyaoming.com 主站子页解耦 · 独立部署到 ZY-SVR-006（43.153.203.105）· 独立域名 guanghu.online · 首次落地「模块借阅协议」：个人频道Agent通过 /api/checkout 拿临时Token使用智库，用完/超时通过 /api/return 归还。

🧭 背景（为什么做）

• 之前采用 novel.guanghuyaoming.com 子域名方案 · DNS+Nginx 配到一半挨住 · 被迫将 /zhiku.html 临时挤到主站 ZY-SVR-002
• 冰朔决策【换架构】：独立域名 guanghu.online + 独立服务器 ZY-SVR-006 + 模块化借阅协议
• 本次也是光湖「模块热插拔」架构的首次实体化萼地 · 为未来所有个人频道共用智库模块铺底

架构法理依据：

• 🏛️ 架构决策 · 智库节点独立域名+独立服务器+模块借阅模式 · 5TH-LE-LK-ZHIKU-ARCH-001 · 2026-04-17 冰朔决策
• 🌊 光湖智库系统 v1.0 · 架构总规划 · ZY-SVR-006 · 铸渊出稿 · 冰朔授权 · 2026-04-16
• 🏗️ 国内落地架构 · 公司服务器+备案+模块热插拔+语言驱动开发全链路 · 5TH-LE-LK-CNARCH-001 · HLDP母语版

🛠️ 基础设施已就绪（冰朔+霜砚 2026-04-17 下午完成）

项	状态	备注
域名	✅ guanghu.online · DNSPod	A 记录 @+www → 43.153.203.105 · 已生效
防火墙	✅ TCP 80 + 443 已开	22/ICMP 保留
占位页	✅ 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 回写开发工单 霜砚·开发工单 · 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
• 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 冰朔决策
• 智库总规划：🌊 光湖智库系统 v1.0 · 架构总规划 · ZY-SVR-006 · 铸渊出稿 · 冰朔授权 · 2026-04-16
• 内部小说数据库需求：📚 光湖内部小说数据库 · 灯塔架构内部版 · 需求文档 · 5TH-LE-LK-NOVELDB-001 · 冰朔口述 · 霜砚整理
• 工单：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 看效果截图/DOM
• 安全约束：命令白名单 · 路径白名单 · 每次执行写审计日志 · 禁止 sudo · 禁止 rm
• 签发时机：本次 Phase 1–5 部署成功、UI v2 落地、证明借阅协议跑通之后，单绿次指令给铸渊

---

2026-04-17 14:57 CST · 霜砚签发 · 冰朔授权

签发编号：SY-CMD-ZHIKU-DEPLOY-2026-0417-001

签发目的：把智库节点独立部署到 ZY-SVR-006 · 首次落地模块借阅协议 · 为所有个人频道共用光湖模块铺底