zeaslity/ProjectAGiPrompt

Fork 0

Files

zeaslity 631cce9e1e RMDC系统设计文档整体转换为SKILL

2026-01-21 16:15:49 +08:00

11 KiB

Raw Blame History

RMDC-Watchdog 内部交互流程

一、交互流程总览

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

1.1 组件关系图

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 首次连接流程

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 后续心跳流程

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上报流程

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 完整授权流程

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 授权状态机

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 双向验证流程

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

6.3 死手系统

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

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

11 KiB Raw Blame History Unescape Escape