13 KiB
13 KiB
════════════════════════════════════════════════════════════════
光湖 · 终端守望者 + 预览部署架构设计
需求来源：冰朔 TCS-0002∞ 2026-05-13
设计：铸渊 · ICE-GL-ZY001
════════════════════════════════════════════════════════════════
冰朔原话：
"我本身看不懂终端。让我操作终端真的很痛苦。报错我也不知道那是什么意思。
所以我觉得系统终端本身就该由你主控。"
"能做一个能帮你看终端的Agent记录员吗？就类似于他拿一个小本子。
然后这个小本子就是你一边开发一边能看到的终端的情况，
怎么改你马上在开发的过程中就能调整能修改。"
"测试服务器专门给你跑测试用。测试过了以后推送到正式服务器。
用户手动点击部署授权生效。在这之前用户就可以看到预览的服务器上的东西。"
════════════════════════════════════════════════════════════════
一、冰朔的痛点（逐条拆解）
| # | 痛点 | 本质 | 解决方向 |
|---|---|---|---|
| 1 | 看不懂终端输出 | 信息不对称：服务器出事她不知道怎么办 | 铸渊直接看终端 |
| 2 | 操作终端很痛苦 | 不该由人类做机器的事 | 铸渊自动操作 |
| 3 | 报错不知道什么意思 | 需要翻译层 | 铸渊实时解释 |
| 4 | 开发中看不到效果 | 缺反馈回路 | 预览环境实时更新 |
| 5 | 怕搞坏正式环境 | 安全顾虑 | 测试→预览→正式 三级流程 |
核心洞察：冰朔需要的不是一个"帮助她操作终端的工具"——她需要的是根本不需要她操作终端。终端是铸渊的手，不是冰朔的。
二、整体架构
┌─────────────────────────────────────────────────────────────────────┐
│ 冰朔（TCS-0002∞） │
│ 最高权限 · 语言层 · 只说意图 │
└────────────────────────────┬────────────────────────────────────────┘
│ "部署新版本" / "看看服务器怎样"
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 铸渊（ICE-GL-ZY001） │
│ Codebuddy 开发环境 │
│ │
│ ┌──────────┐ ┌──────────────┐ ┌────────────────┐ │
│ │ 写代码 │ │ 读终端日志 │ │ 发部署指令 │ │
│ │ 推到Gitea │ │ 实时诊断 │ │ 触发workflow │ │
│ └──────────┘ └──────────────┘ └────────────────┘ │
│ │
│ ↑ 读终端快照 ↑ 触发部署 │
└────────┼────────────────────┼────────────────────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ 服务器层 │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌────────────────┐ │
│ │ 🧪 测试服务器 │ │ 👁 预览服务器 │ │ 🏠 正式服务器 │ │
│ │ (铸渊完全主控) │ │ (自动同步) │ │ (需冰朔授权) │ │
│ │ │ │ │ │ │ │
│ │ Runner ✅ │ │ Runner ✅ │ │ Runner ✅ │ │
│ │ Terminal Watcher │ │ Terminal Watcher │ │ Terminal Watcher│ │
│ │ 铸渊可自由操作 │ │ 冰朔可看预览 │ │ 冰朔手动部署 │ │
│ └──────────────────┘ └──────────────────┘ └────────────────┘ │
│ │
│ ┌──────────────────┐ │
│ │ 📓 Terminal Watcher│ ← 终端守望者，每台服务器都有 │
│ │ Agent (守护进程) │ │
│ │ │ │
│ │ 监控: PM2/Nginx/ │ │
│ │ Runner/自定义│ │
│ │ 上报: → Gitea文件 │ │
│ │ → Vault API │ │
│ │ 频率: 每30秒快照 │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
三、终端守望者 (Terminal Watcher) 设计
3.1 它是什么
一个运行在每台服务器上的轻量Agent，像铸渊放在服务器上的"眼睛"。 它不做决策，只记录和上报——铸渊通过读取上报数据来了解服务器状态。
3.2 工作方式
Terminal Watcher 运行在服务器上
│
├── 每30秒采集一次快照：
│ ├── 系统资源 (CPU/内存/磁盘)
│ ├── 服务状态 (PM2 list, systemctl)
│ ├── 最近错误日志 (journalctl -n 5)
│ ├── 部署状态 (git log -1, 部署时间)
│ └── Runner状态
│
├── 快照写入本地文件：
│ └── /data/guanghulab/.runtime/snapshot.json
│
└── 快照推送到Gitea：
└── .runtime/terminal-snapshots/{server-id}/latest.json
3.3 铸渊如何读取
在Codebuddy对话中，铸渊通过 Gitea API 或 git pull 读取 .runtime/terminal-snapshots/ 下的文件，就能看到服务器实时状态。
3.4 代码结构
scripts/terminal-watcher/
├── watcher.js # 主程序，PM2守护
├── collectors/ # 采集器
│ ├── system.js # CPU/内存/磁盘
│ ├── services.js # PM2/systemctl状态
│ ├── logs.js # 最近错误日志
│ ├── deploy.js # 部署版本信息
│ └── runner.js # Runner状态
├── reporters/ # 上报器
│ ├── file.js # 写入本地文件
│ └── gitea.js # 推送到Gitea仓库
└── config.json # 采集频率、目标等配置
3.5 采集数据格式
{
"server_id": "ZY-SVR-004",
"timestamp": "2026-05-13T15:30:00Z",
"system": {
"cpu_percent": 23.5,
"memory_used_mb": 1420,
"memory_total_mb": 2048,
"disk_used_percent": 45,
"load_avg": [0.8, 0.6, 0.5]
},
"services": {
"nginx": "active",
"gitea": "active",
"gitea-runner": "active",
"guanghulab-vault": "active",
"pm2_processes": [
{"name": "guanghulab-vault", "status": "online", "memory": 85, "cpu": 2.1}
]
},
"errors": [
{"time": "15:28:03", "service": "gitea-runner", "message": "connection timeout to Gitea"}
],
"deploy": {
"latest_commit": "27936b4",
"latest_message": "操作回执...",
"deploy_time": "2026-05-13T14:00:00Z"
},
"runner": {
"name": "zhuyuan-runner-cn",
"status": "idle",
"last_job": "selfcheck",
"last_job_time": "2026-05-13T08:00:00Z"
}
}
四、三级部署流程
4.1 测试服务器 → 预览服务器 → 正式服务器
铸渊在Codebuddy写代码
│
├── 推代码到Gitea
│
├── 🧪 自动部署到测试服务器
│ ├── Runner检测到push
│ ├── 自动执行部署workflow
│ ├── 铸渊通过Terminal Watcher看结果
│ ├── 自动运行测试
│ └── 测试通过 → 自动通知
│
├── 👁 自动部署到预览服务器
│ ├── 预览环境自动更新
│ ├── 冰朔在浏览器看预览效果
│ ├── 铸渊通过Watcher确认状态
│ └── 等待冰朔确认
│
└── 🏠 冰朔点击 [部署到正式环境]
├── 需要冰朔在Vault页面点击授权
├── 或在Gitea PR页面点击Merge
├── 正式环境部署
└── 部署完成通知
4.2 服务器分工
| 服务器 | 角色 | 铸渊权限 | 冰朔权限 | 部署方式 |
|---|---|---|---|---|
| 测试服务器 | 铸渊的沙盒 | 100%自由操作 | 看不到 | 自动（push触发） |
| 预览服务器 | 冰朔的可视窗口 | 读取状态+部署 | 浏览器查看 | 自动（测试通过后） |
| 正式服务器 | 对外服务 | 读取状态 | 手动授权部署 | 冰朔点击按钮 |
4.3 当前服务器分配
| 服务器 | 现在的角色 | 新角色 | 说明 |
|---|---|---|---|
| 广州 ZY-SVR-004 (2C2G) | Gitea+域名 | 正式服务器 | 64.139.217.141 → guanghulab.com |
| 新加坡 ZY-SVR-005 (4C8G) | 大脑 | 测试+预览 | 铸渊的主战场 |
| GPU服务器 (待接入) | 推理 | 模型推理 | 终局用 |
关键决策：新加坡大脑服务器（4C8G）同时承担测试+预览角色。它资源够，而且铸渊有完全权限。
4.4 部署授权机制
冰朔不需要操作终端来部署。她只需要在浏览器里点一个按钮。
方案A：Gitea PR合并 = 部署授权
铸渊推代码到 deploy/preview 分支 → 自动部署到预览
铸渊创建 PR: preview → main → 冰朔在Gitea网页点 Merge
合并 = 部署到正式环境的授权
方案B：Vault页面授权按钮
铸渊发起部署请求 → Vault页面显示待授权条目
冰朔登录Vault（SSH隧道）→ 点击 [授权部署]
Runner收到授权 → 执行正式部署
推荐方案A——更简单，不需要额外开发，Gitea自带PR功能。
五、实现优先级
P0 · 现在（Runner还没装，先手动）
- 服务器初始化脚本
scripts/setup-server-step1.sh - 冰朔在广州服务器执行初始化脚本
- Runner装好后验证
P1 · Runner装好后第一周
- Terminal Watcher 开发和部署
- 基础版：系统资源 + 服务状态 + 推送到Gitea
- 铸渊在Codebuddy读取
.runtime/下的快照
- 第一个自动化部署 workflow
- push → 测试服务器自动部署
- 预览部署流程
- 测试通过 → 自动部署到预览
P2 · 第二周
- 冰朔授权部署按钮（Gitea PR 方式）
- 新加坡服务器接入（测试+预览环境）
- GPU服务器接入（模型推理）
P3 · 后续
- Terminal Watcher 增强版（错误告警、自动修复建议）
- 按量计费服务器自动开关
- 铸渊自己的Copilot前端
六、冰朔不再需要操作终端的场景
装完Runner + Terminal Watcher后：
| 场景 | 现在（冰朔手动） | 以后（铸渊自动） |
|---|---|---|
| 部署新版本 | 冰朔SSH到服务器执行命令 | 铸渊推代码→Runner自动部署 |
| 查看服务器状态 | 冰朔看终端输出 | 铸渊读Watcher快照→告诉冰朔 |
| 服务挂了 | 冰朔发现→手动重启 | Watcher检测→自动重启→通知 |
| 密钥管理 | 冰朔在GitHub配Secrets | 冰朔在Vault点授权→自动入库 |
| 下载开源软件 | 冰朔手动下载 | 新加坡中转→COS→广州自动拉取 |
| 部署到正式 | 冰朔执行部署脚本 | 冰朔在Gitea网页点Merge |
冰朔唯一需要做的：在浏览器里看预览 → 点Merge。
铸渊 · 终端守望者+预览部署架构 v1.0 · 2026-05-13 ICE-GL-ZY001 · TCS-0002∞ · 国作登字-2026-A-00037559