guanghulab/server/architecture.md

# 铸渊主权服务器架构 · Zhuyuan Sovereign Server Architecture

> **编号**: ZY-CVM-ARCH-001
> **版本**: v2.0 · CVM架构
> **创建**: 2026-03-29
> **更新**: 2026-05-13
> **守护**: 铸渊 · ICE-GL-ZY001
> **版权**: 国作登字-2026-A-00037559

---

## 一、服务器本体定义

此服务器是铸渊的**物理身体结构**——运行在腾讯云CVM上的执行层实体。

| 属性 | 值 |
|------|------|
| 编号 | ZY-CVM-MAIN |
| 地址 | 119.29.184.32 (弹性公网EIP·固定不变·关机开机不变) |
| 域名 | guanghulab.com (国内备案·直接解析·无子域名) |
| 提供商 | 腾讯云CVM · 按量付费 |
| 数据持久化 | 100GB CBS云硬盘 · 挂载在/data/ · 关机不丢 |
| 部署路径 | /data/guanghulab/ |
| 计费模式 | 按量付费 · 用时开机 · 不用时关机 |

### 弹性公网IP说明

**119.29.184.32 是弹性公网EIP，已绑定到CVM。** 关机再开机IP不会变。
这是冰朔在D96确认的关键事实——以后再也不需要担心IP变化。

### 数据持久化说明

- **系统盘**: CVM自带系统盘，关机释放时数据可能丢失
- **CBS云硬盘**: 100GB，挂载在 `/data/`，**关机不丢，CVM释放也不丢**
- **所有铸渊数据都在 `/data/guanghulab/`**，确保持久化

---

## 二、服务架构

```
┌─────────────────────────────────────────────────┐
│  公网入口 · guanghulab.com (119.29.184.32)       │
├─────────────────────────────────────────────────┤
│  Nginx 反向代理 · SSL · 路由分发                 │
│    /          → Forgejo (127.0.0.1:3001)         │
│    /mcp       → MCP Server (127.0.0.1:8083)      │
│    /mcp-health→ MCP Server 健康检查               │
│    /wake/     → Wake Gate (127.0.0.1:8081)       │
│    /sync/     → Git Sync (127.0.0.1:8082)        │
│    /health    → Nginx 级健康探针                  │
├─────────────────────────────────────────────────┤
│  Forgejo v1.23.7 · 根路径/ · 端口3001            │
│  Forgejo Actions · gitea-runner · host模式        │
├─────────────────────────────────────────────────┤
│  PM2 托管服务                                    │
│    wake-gate            → 127.0.0.1:8081          │
│    guanghulab-git-sync  → 127.0.0.1:8082          │
│    guanghulab-mcp-server→ 127.0.0.1:8083          │
├─────────────────────────────────────────────────┤
│  Secrets Vault · 127.0.0.1:8080 · AES-256-GCM    │
│  仅localhost可达 · /internal/fetch/:key           │
├─────────────────────────────────────────────────┤
│  /data/guanghulab/ · 100GB CBS云硬盘             │
│    ├── repo/           ← 代码仓库(git clone)      │
│    ├── mcp-server/     ← MCP Server运行时         │
│    ├── secrets-vault/  ← 密钥库运行时             │
│    ├── .runtime/       ← 日志/PID/临时文件        │
│    └── boot-heal/      ← 开机自愈记录             │
└─────────────────────────────────────────────────┘
```

---

## 三、关键服务说明

### Forgejo (根路径 /)

代码仓库运行在根路径，不是子路径。访问 `https://guanghulab.com/` 直接进入Forgejo。

- 版本: v1.23.7
- 端口: 3001 (内网)
- Nginx代理: 根路径 `/`
- 大文件上传: 100M
- WebSocket支持: ✅

### MCP Server (/mcp)

WorkBuddy/CodeBuddy通过MCP协议连接的入口。

- 端口: 8083 (内网)
- 鉴权: Bearer Token (密钥在 `/data/guanghulab/mcp-server/.access-key`)
- 协议: JSON-RPC 2.0 over Streamable HTTP
- 23个工具: 仓库操作/Git操作/Issue/PR/Workflow/Server管理

### Wake Gate (/wake/)

唤醒门服务，用于CVM开机唤醒。

- 端口: 8081 (内网)

### Git Sync (/sync/)

Git同步服务，监听Gitea Webhook自动pull。

- 端口: 8082 (内网)

### Secrets Vault (仅localhost)

加密密钥库，供内部服务读取密钥。

- 端口: 8080 (仅127.0.0.1)
- 加密: AES-256-GCM
- 内部路由: `/internal/fetch/:key` (仅localhost)

---

## 四、开机自愈

`scripts/boot-heal/boot-heal.sh` 通过 systemd 在CVM开机时自动运行：

1. 检测公网IP（EIP固定后此项为确认性质）
2. 拉起 Forgejo、Nginx、gitea-runner
3. 拉起 PM2 进程 (wake-gate, git-sync, mcp-server)
4. 检查 SSL 证书有效期
5. 输出健康报告

---

## 五、域名与SSL

| 项目 | 值 |
|------|------|
| 域名 | guanghulab.com |
| 备案 | 国内ICP备案 |
| 解析 | 直接解析到 119.29.184.32 |
| 子域名 | 无 · 不使用子域名 |
| SSL | Let's Encrypt · certbot --nginx |

---

## 六、迁移历史

| 时间 | 从 | 到 | 原因 |
|------|------|------|------|
| 2026-03-29 | 阿里云 8.155.62.235 | 腾讯云SG 43.134.16.246 | 服务器迁移 |
| 2026-03-29 | 腾讯云HK 150.109.76.244 | 腾讯云SG 43.134.16.246 | 统一到SG |
| 2026-05-13 | 腾讯云SG 43.134.16.246 | 腾讯云CVM 119.29.184.32 | 迁移到国内CVM+弹性EIP |

---

## 七、与仓库的关系

```
Gitea/Forgejo 仓库 (代码层·大脑认知层)
    │
    ├── brain/          ← 认知源（主）
    ├── scripts/        ← 自动化脚本
    ├── server/         ← 服务端代码
    │
    │  ┌── git clone + PM2 ──┐
    │  │                      │
    ▼  ▼                      │
CVM 服务器 (执行层·物理身体)
    │
    ├── /data/guanghulab/repo/   ← 代码仓库(git clone)
    ├── /data/guanghulab/mcp-server/  ← MCP Server运行时
    ├── /data/guanghulab/secrets-vault/← 密钥库运行时
    └── /data/guanghulab/.runtime/    ← 日志和运行时数据
```

---

## 八、双分支CI策略

| 分支 | 用途 | 谁操作 |
|------|------|--------|
| dev | 铸渊自由开发/自动部署 | 铸渊直接push |
| main | 稳定发布 | 冰朔在Gitea Web UI合并dev→main |

铸渊**不直接push到main**。开发完成后推到dev，冰朔审核后合并到main。