# RMDC-Watchdog 内部交互流程

## 一、交互流程总览

本文档详细描述了RMDC-Watchdog系统内部各组件之间的交互流程，包括Agent心跳上报、Node信息上报以及项目级别（二级授权中心）的完整业务流程。

### 1.1 组件关系图

```mermaid
graph TB
    subgraph "项目环境 (K8S集群)"
        WATCHDOG["rmdc-watchdog<br/>(二级授权中心)<br/>Port: 8990"]
        AGENT1["rmdc-watchdog-agent<br/>业务Pod A"]
        AGENT2["rmdc-watchdog-agent<br/>业务Pod B"]
        NODE1["rmdc-watchdog-node<br/>节点1 (DaemonSet)"]
        NODE2["rmdc-watchdog-node<br/>节点2 (DaemonSet)"]
    end
    
    NODE1 --"POST /api/node/info<br/>主机信息+运行指标"--> WATCHDOG
    NODE2 --"POST /api/node/info<br/>主机信息+运行指标"--> WATCHDOG
    
    AGENT1 <--"POST /api/heartbeat<br/>心跳+TOTP验证"--> WATCHDOG
    AGENT2 <--"POST /api/heartbeat<br/>心跳+TOTP验证"--> WATCHDOG
    
    style WATCHDOG fill:#4ecdc4
    style AGENT1 fill:#ff8787
    style AGENT2 fill:#ff8787
    style NODE1 fill:#a9e34b
    style NODE2 fill:#a9e34b
```

---

## 二、Agent心跳上报流程

Agent是嵌入到业务Pod中的启动器，负责向Watchdog发送心跳请求进行授权验证。

### 2.1 首次连接流程

```mermaid
sequenceDiagram
    autonumber
    participant Agent as rmdc-watchdog-agent<br/>(业务启动器)
    participant Watchdog as rmdc-watchdog<br/>(二级授权中心)
    
    rect rgb(200, 255, 200)
        Note over Agent,Watchdog: ===== 首次连接 - 获取TOTP密钥 =====
    end
    
    Agent->>Agent: 1. 收集环境信息<br/>GetEnvInfo()
    Agent->>Agent: 2. 收集主机信息<br/>host_info.GetAllInfo()
    
    Agent->>Watchdog: 3. POST /api/heartbeat<br/>{HostInfo, EnvInfo, Timestamp, TOTPCode=""}
    
    Watchdog->>Watchdog: 4. 验证时间戳有效性<br/>|now - timestamp| < 5分钟
    Watchdog->>Watchdog: 5. 添加主机信息到集合<br/>AddHostInfo()
    Watchdog->>Watchdog: 6. 检测TOTPCode为空<br/>返回TOTP密钥
    
    Watchdog-->>Agent: 7. 返回响应<br/>{Authorized:false, SecondTOTPSecret:secret}
    
    Agent->>Agent: 8. 保存TOTP密钥<br/>tierTwoTotpSecret = secret
    
    Note over Agent: 密钥保存在内存中<br/>后续心跳使用此密钥
```

### 2.2 后续心跳流程

```mermaid
sequenceDiagram
    autonumber
    participant Agent as rmdc-watchdog-agent<br/>(业务启动器)
    participant Watchdog as rmdc-watchdog<br/>(二级授权中心)
    participant Business as 业务进程<br/>(Java/Python)
    
    rect rgb(220, 255, 220)
        Note over Agent,Business: ===== 心跳循环 - 授权验证 =====
    end
    
    loop 心跳循环 (成功后2小时, 失败后1小时)
        Agent->>Agent: 1. 生成TOTP验证码<br/>GenerateTierTwoTOTPCode(secret)<br/>6位, 30秒有效
        
        Agent->>Watchdog: 2. POST /api/heartbeat<br/>{HostInfo, EnvInfo, Timestamp, TOTPCode}
        
        Watchdog->>Watchdog: 3. 验证时间戳有效性
        Watchdog->>Watchdog: 4. 验证TOTP验证码<br/>VerifyTierTwoTOTPCode()
        
        alt TOTP验证成功
            Watchdog->>Watchdog: 5. 检查主机授权状态<br/>IsHostAuthorized(hostInfo)
            Watchdog->>Watchdog: 6. 生成响应TOTP验证码<br/>(双向验证)
            Watchdog-->>Agent: 7. 返回{Authorized:true/false, TOTPCode}
            
            Agent->>Agent: 8. 验证服务端TOTP<br/>双向验证确保安全
            
            alt 授权成功
                Agent->>Agent: 9. failCount = 1<br/>等待2小时
            else 授权失败
                Agent->>Agent: 9. failCount++<br/>等待1小时
            end
        else TOTP验证失败
            Watchdog-->>Agent: 返回错误:无效的TOTP验证码
            Agent->>Agent: failCount++
        end
        
        alt failCount >= 12
            Note over Agent,Business: 死手系统触发
            Agent->>Business: 10. 发送SIGTERM信号
            Note over Business: 业务进程终止
        end
    end
```

### 2.3 心跳请求/响应数据结构

| 字段 | 类型 | 说明 |
|------|------|------|
| **HeartbeatRequest** | | |
| host_info | HostInfo | 主机硬件信息 |
| env_info | EnvInfo | 环境信息(K8S_NAMESPACE, APPLICATION_NAME等) |
| timestamp | int64 | 请求时间戳 |
| totp_code | string | TOTP验证码(首次为空) |
| **HeartbeatResponse** | | |
| authorized | bool | 是否已授权 |
| totp_code | string | 响应TOTP验证码(双向验证) |
| timestamp | int64 | 响应时间戳 |
| second_totp_secret | string | 二级TOTP密钥(首次连接时返回) |

---

## 三、Node主机信息上报流程

Node以DaemonSet方式运行在每个K8S节点上，负责收集主机硬件信息和运行指标。

### 3.1 Node上报流程

```mermaid
sequenceDiagram
    autonumber
    participant Node as rmdc-watchdog-node<br/>(DaemonSet)
    participant Watchdog as rmdc-watchdog<br/>(二级授权中心)
    
    rect rgb(200, 220, 255)
        Note over Node,Watchdog: ===== 首次上报 - 获取TOTP密钥 =====
    end
    
    Node->>Node: 1. 收集主机硬件信息<br/>CollectHostInfo()
    Node->>Node: 2. 收集运行指标<br/>CollectMetrics()
    
    Node->>Watchdog: 3. POST /api/node/info<br/>{NodeID, HostInfo, Metrics, Timestamp, TOTPCode=""}
    
    Watchdog->>Watchdog: 4. 验证时间戳
    Watchdog->>Watchdog: 5. 存储Node信息
    Watchdog->>Watchdog: 6. 同步更新AuthService<br/>AddHostInfo()
    Watchdog-->>Node: 7. 返回{Success:true, SecondTOTPSecret:secret}
    
    Node->>Node: 8. 保存TOTP密钥
    
    rect rgb(220, 255, 220)
        Note over Node,Watchdog: ===== 定时上报 (默认60秒) =====
    end
    
    loop 定时上报
        Node->>Node: 9. 生成TOTP验证码
        Node->>Node: 10. 收集最新指标
        
        Node->>Watchdog: 11. POST /api/node/info<br/>{NodeID, HostInfo, Metrics, Timestamp, TOTPCode}
        
        Watchdog->>Watchdog: 12. 验证TOTP
        Watchdog->>Watchdog: 13. 更新Node信息
        Watchdog->>Watchdog: 14. 生成响应TOTP
        Watchdog-->>Node: 15. 返回{Success:true, TOTPCode}
        
        Node->>Node: 16. 验证响应TOTP(双向)
    end
```

### 3.2 Node信息数据结构

| 字段 | 类型 | 说明 |
|------|------|------|
| **NodeInfoRequest** | | |
| node_id | string | 节点唯一标识(MachineID) |
| host_info | HostInfo | 主机硬件信息 |
| metrics | NodeRuntimeMetrics | 运行指标 |
| timestamp | int64 | 请求时间戳 |
| totp_code | string | TOTP验证码 |
| **NodeRuntimeMetrics** | | |
| cpu_usage | float64 | CPU使用率(%) |
| memory_usage | float64 | 内存使用率(%) |
| disk_usage | float64 | 磁盘使用率(%) |
| network_rx_kb | uint64 | 网络接收KB |
| network_tx_kb | uint64 | 网络发送KB |
| collect_time | int64 | 采集时间戳 |

---

## 四、项目级别(二级授权中心)完整业务流程

### 4.1 完整授权流程

```mermaid
sequenceDiagram
    autonumber
    participant Node as rmdc-watchdog-node<br/>(DaemonSet)
    participant Agent as rmdc-watchdog-agent<br/>(业务启动器)
    participant Watchdog as rmdc-watchdog<br/>(二级授权中心)
    participant MQTT as Exchange-Hub<br/>(MQTT Server)
    participant Center as rmdc-watchdog-center<br/>(一级授权中心)
    
    rect rgb(200, 220, 255)
        Note over Node,Center: ===== 阶段1: 信息收集与初始化 =====
    end
    
    Note over Node: 项目部署后<br/>DaemonSet启动
    Node->>Watchdog: 1. 上报主机信息<br/>POST /api/node/info
    Watchdog-->>Node: 2. 返回TOTP密钥
    
    Note over Agent: 业务Pod启动
    Agent->>Watchdog: 3. 发送首次心跳<br/>POST /api/heartbeat
    Watchdog-->>Agent: 4. 返回TOTP密钥
    
    rect rgb(220, 255, 220)
        Note over Node,Center: ===== 阶段2: 授权申请 =====
    end
    
    Watchdog->>Watchdog: 5. 生成授权文件<br/>GenerateAuthorizationFile()
    Note over Watchdog: 授权文件包含:<br/>- EncryptedHostMap<br/>- TOTPCode (8位,30分钟)<br/>- EncryptedNamespace
    
    Watchdog->>MQTT: 6. 发布授权申请Command<br/>wdd/RDMC/command/up
    MQTT->>Center: 7. 转发授权申请
    
    rect rgb(255, 240, 220)
        Note over Node,Center: ===== 阶段3: 授权验证与下发 =====
    end
    
    Center->>Center: 8. 解密项目命名空间
    Center->>Center: 9. 验证Tier-One TOTP验证码
    Center->>Center: 10. 验证主机信息完整性
    
    alt 验证成功
        Center->>Center: 11. 生成新TOTP验证码
        Center->>Center: 12. 构造授权码
        Center->>MQTT: 13. 发布授权码<br/>wdd/RDMC/command/down/{project_id}
    else 验证失败
        Center->>MQTT: 发布授权拒绝消息
    end
    
    MQTT->>Watchdog: 14. 推送授权码
    
    rect rgb(230, 230, 255)
        Note over Node,Center: ===== 阶段4: 授权存储与生效 =====
    end
    
    Watchdog->>Watchdog: 15. 验证返回的TOTP
    Watchdog->>Watchdog: 16. 解密并验证命名空间
    Watchdog->>Watchdog: 17. 解密每个主机信息
    Watchdog->>Watchdog: 18. 计算时间偏移<br/>timeOffset = now - firstAuthTime
    Watchdog->>Watchdog: 19. 加密并持久化保存
    
    rect rgb(200, 255, 200)
        Note over Node,Center: ===== 阶段5: 授权使用 =====
    end
    
    loop Agent心跳循环
        Agent->>Watchdog: 20. 发送心跳请求
        Watchdog->>Watchdog: 21. 检查主机授权状态
        Watchdog-->>Agent: 22. 返回{Authorized:true}
    end
    
    Note over Agent: 授权成功<br/>业务正常运行
```

### 4.2 授权状态机

```mermaid
stateDiagram-v2
    [*] --> 未初始化: 项目部署
    
    未初始化 --> 收集主机信息: Node/Agent连接
    收集主机信息 --> 等待授权: 生成授权文件
    
    等待授权 --> 已授权: 收到有效授权码
    等待授权 --> 未授权: 授权被拒绝
    
    已授权 --> 已授权: 心跳成功
    已授权 --> 授权过期: 时间篡改检测
    已授权 --> 未授权: 授权撤销
    
    未授权 --> 等待授权: 重新申请
    授权过期 --> 未授权: 需重新授权
```

---

## 五、API接口清单

### 5.1 Watchdog API (Port: 8990)

| 路径 | 方法 | 说明 |
|------|------|------|
| `/api/heartbeat` | POST | Agent心跳接口 |
| `/api/heartbeat/hosts` | GET | 获取所有心跳主机 |
| `/api/node/info` | POST | Node信息上报接口 |
| `/api/node/list` | GET | 获取所有Node列表 |
| `/api/node/metrics/:node_id` | GET | 获取指定Node的运行指标 |
| `/api/authorization/generate` | GET | 生成授权文件 |
| `/api/authorization/auth` | POST | 接收授权码 |
| `/api/authorization/hosts` | GET | 获取所有已授权主机 |

---

## 六、安全机制

### 6.1 TOTP验证机制

| 场景 | 验证方式 | 参数 |
|------|----------|------|
| Agent ↔ Watchdog | Tier-Two TOTP | 6位码, 30秒有效, SHA1 |
| Node ↔ Watchdog | Tier-Two TOTP | 6位码, 30秒有效, SHA1 |
| Watchdog ↔ Center | Tier-One TOTP | 8位码, 30分钟有效, SHA256 |

### 6.2 双向验证流程

1. **客户端(Agent/Node)** 生成TOTP验证码并发送请求
2. **服务端(Watchdog)** 验证客户端TOTP后，生成新的TOTP验证码返回
3. **客户端** 验证服务端返回的TOTP验证码
4. 双向验证确保通信双方身份合法

### 6.3 死手系统

Agent内置死手系统，当连续12次心跳失败后，将发送SIGTERM信号终止业务进程。

| 参数 | 值 | 说明 |
|------|------|------|
| maxRetryCount | 12 | 最大重试次数 |
| defaultHeartbeatInterval | 2小时 | 成功后心跳间隔 |
| failWaitInterval | 1小时 | 失败后等待间隔 |