289 lines
13 KiB
Markdown
289 lines
13 KiB
Markdown
# ════════════════════════════════════════════════════════════════
|
||
# 光湖 · 终端守望者 + 预览部署架构设计
|
||
# 需求来源：冰朔 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 采集数据格式
|
||
|
||
```json
|
||
{
|
||
"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还没装，先手动）
|
||
|
||
- [x] 服务器初始化脚本 `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*
|