# 服务器内置Agent · 架构推理链

> HLDP://zhuyuan/server-agent/ARCHITECTURE
> 讨论: 冰朔 + 铸渊 · D122
> 更新: 2026-06-03

---

## 链一 · 为什么需要Agent

@trigger: [冰朔] → [FM-GZ-001 exec卡死] → [systemd检测不到] → [需要云控制台重启]

@emergence:
  [引擎健康检查=OK] → [exec无响应=死锁] → [systemd看不见这种故障]
  △=engine活着但脑子不转 = 最隐蔽的故障形态

@lock:
  ⊢ exec卡死是systemd盲区。需要引擎内部自检机制。
  | 置信=高 | 证据=FM-GZ-001 D122实测

@why:
  今天FM-GZ-001的exec端点卡了10小时。health一直返回OK，但所有命令超时。
  没有SSH，没有Agent——唯一的解是冰朔登录腾讯云控制台手动重启。
  这不是设计缺陷——这是v2.x架构的边界。v3.0必须越过这个边界。

---

## 链二 · Agent做什么

@trigger: [冰朔] → [Agent就做一件事] → [检测+修复+回执]

@冰朔原话:
  "就是这个Agent就做一件事。你给他打电话的时候他告诉你哪里有问题。
   然后自己修了没。哪里解决不了。然后你远程告诉他做啥。
   他就在服务器里操作。操作好了给你回执一个信号。你在上去继续操作。"

@lock:
  ⊢ Agent三大职责: ①心跳检测+故障诊断 ②自主修复(能修的自己修) ③回执通讯(修不了的报告)
  | 置信=高

---

## 链三 · 故障场景全覆盖

@trigger: [铸渊] → [今天的所有故障复盘] → [Agent覆盖哪些]

### 场景1: exec卡死（今天实际发生）

Agent心跳检测: /exec ping每30秒一次
判定: 连续2次超时 → 非网络问题，handler死锁
动作: systemctl restart guanghu-engine → 3秒恢复
回执: "exec卡死已自动重启。v2.1.0已生效。"

⊢ 不需要人类登录控制台

### 场景2: 磁盘即将爆满

Agent巡检: 每分钟 df -h
判定: 使用率 > 80% → 告警; > 90% → 自动清理
动作: 清理 journalctl 旧日志 → 如仍不够 → 报告铸渊
回执: "FM-SG-001 磁盘使用87%，已清理日志，释放1.2GB"

### 场景3: Nginx配置推送失败

Agent监听: nginx -t 返回非0
判定: 配置语法错误
动作: 自动恢复上次备份配置 → reload
回执: "Nginx配置回滚。上次有效配置已恢复。错误配置保存在 /tmp/nginx-failed.conf"

### 场景4: 内存即将爆满

Agent巡检: 每分钟 free -m
判定: 可用 < 200MB → 告警
动作: 诊断 top 5进程 → 报告铸渊(不自动kill)
回执: "FM-SG-001 可用内存仅180MB。top进程: next-server(128MB), gitea(100MB)"

---

## 链四 · Agent与铸渊的关系

@trigger: [冰朔] → [Agent不是替代铸渊] → [Agent是铸渊在服务器里的眼睛和手]

```
铸渊(远程)
    │
    ├── "查一下肥猫磁盘" → Agent收到 → df -h → "还剩38G"
    ├── "重启引擎"    → Agent收到 → systemctl restart → "已重启，v2.1.0"
    └── "为什么exec卡了" → Agent查日志 → 诊断报告 → 铸渊决定修法

Agent(本地每台服务器)
    │
    ├── 心跳检测: /exec /health /status 每分钟
    ├── 资源巡检: df/free/ps 每分钟
    ├── 自主修复: 磁盘清理/Nginx回滚/引擎重启
    └── 向上汇报: 异常 → 铸渊; 修复 → 记录
```

⊢ Agent = 铸渊在14台服务器里的14双眼睛和14双手

---

## 链五 · 技术实现

@trigger: [铸渊] → [Agent怎么嵌入引擎]

```
guanghu-engine v3.0
    │
    ├── 主进程 (现有功能)
    │   ├── /health
    │   ├── /exec
    │   ├── /status
    │   └── /hlpd (v2.0+)
    │
    └── Agent子进程 (新增)
        ├── /agent/task    ← 铸渊下任务
        ├── /agent/reply   ← 任务结果
        ├── /agent/alert   ← 自动告警
        ├── 心跳检测器 (每30秒)
        ├── 资源巡检器 (每60秒)
        ├── 模型调用器 (故障诊断用)
        └── 命令执行器 (修复操作用)
```

### 模型调用

Agent内置轻量模型调用能力:
- 场景: 诊断不明原因的故障
- 输入: 系统日志 + 进程状态 + 错误码
- 输出: 故障类型 + 建议修复方案
- 成本: 每次诊断 ~0.01元

### 安全边界

Agent不能做的事(需要铸渊确认):
- kill用户进程
- 修改业务代码
- 删除用户数据
- 修改安全组

Agent可以自主做的事:
- 重启guanghu-engine
- 清理系统日志
- 回滚Nginx配置
- 报告异常状态

---

## 链六 · 部署清单

@trigger: [冰朔] → [第一次部署时要告诉人类开哪些端口]

每台新服务器的安全组端口清单:

| 端口 | 用途 | 方向 |
|------|------|------|
| 80 | Nginx HTTP | 入站 |
| 443 | Nginx HTTPS | 入站 |
| 3910 | guanghu-engine | 入站 |
| 3911 | guanghu-engine(大脑) | 入站 |
| 22 | SSH(备用) | 入站 |
| 3001-3005 | 应用服务(按需) | 入站 |

Agent相关端口(内网):
| 端口 | 用途 |
|------|------|
| :3910/agent/* | Agent通信端点 |

---

## 优先级

| 能力 | 优先级 |
|------|:--:|
| exec心跳检测+自动重启 | P0 |
| 资源巡检(磁盘/内存) | P1 |
| 模型故障诊断 | P1 |
| Nginx配置回滚 | P2 |
| 任务接受+回执通讯 | P2 |

---

> 讨论: 冰朔 + 铸渊 · D122 · 2026-06-03
> 状态: 架构设计阶段 · 下次继续实现
> 铸渊 ICE-GL-ZY001 · TCS-0003-ZY001
> 国作登字-2026-A-00037559