@agentunion/kite 1.4.0 → 1.6.0

package/docs//345/277/203/350/267/263/346/234/272/345/210/266/351/207/215/346/236/204/346/200/273/347/273/223.md

@@ -0,0 +1,166 @@
+# 心跳机制重构总结
+
+## 重构目标
+
+移除冗余的被动心跳机制，改为 Watchdog 主动健康检查，提升系统监控的实际价值。
+
+## 重构原因
+
+### 被动心跳的问题
+
+1. **与 WebSocket ping/pong 功能重复** — WebSocket 协议自带 ping/pong 机制（20秒间隔），已经能检测网络层连接状态
+2. **无法检测业务层健康** — 模块只是发送"我还活着"的消息，无法反映实际业务处理能力
+3. **检测不到僵死状态** — 如果模块事件循环正常但业务逻辑卡死，心跳仍能发出
+4. **架构不清晰** — 被动心跳 + TTL 检查的设计增加了系统复杂度
+
+### 主动健康检查的优势
+
+1. **真实检测业务能力** — 调用模块的 health RPC，测试实际的请求处理能力
+2. **获取详细健康信息** — 可以返回运行时指标（运行模块数、失败次数、资源使用等）
+3. **超时机制** — RPC 调用有超时限制，能检测出响应缓慢的模块
+4. **职责清晰** — Watchdog 专职监控，Kernel 专注核心功能
+
+## 重构内容
+
+### 第一步：添加 Launcher 的 health RPC
+
+**修改文件：** `launcher/entry.py`
+
+- 在注册信息中添加 `module.health` RPC 声明
+- 在 RPC 处理器中添加 `health` 方法映射
+- 实现 `_rpc_health()` 方法，返回：
+  - `status`: "healthy"
+  - `uptime_seconds`: 运行时长
+  - `details`: 总模块数、运行中模块数、失败模块数、总重启次数
+
+### 第二步：移除模块端的被动心跳循环
+
+**修改文件：**
+- `extensions/services/watchdog/entry.py` — 移除 `_heartbeat_loop()` 函数及其调用
+- `extensions/services/backup/entry.py` — 移除 `_heartbeat_loop()` 函数及其调用
+
+**变更：**
+- 删除每 30 秒发送 `registry.heartbeat` RPC 的后台任务
+- 保留 WebSocket ping/pong 机制（20秒间隔）用于连接检测
+
+### 第三步：移除 Kernel 端的心跳机制
+
+**修改文件：**
+- `kernel/registry_store.py`
+  - 移除 `heartbeats` 字典
+  - 移除 `ttl` 和 `heartbeat_interval` 字段
+  - 移除 `heartbeat()` 方法
+  - 移除 `check_ttl()` 方法
+  - 简化 `register_module()` 返回值（移除 ttl 和 heartbeat_interval）
+  - 简化 `deregister_module()`（移除 heartbeats 清理）
+
+- `kernel/rpc_router.py`
+  - 从方法分发表中移除 `registry.heartbeat`
+  - 删除 `_registry_heartbeat()` 方法
+
+- `kernel/server.py`
+  - 移除 `_ttl_task` 字段
+  - 移除 `_ttl_loop()` 方法
+  - 移除启动时创建 TTL 任务的代码
+  - 移除关闭时取消 TTL 任务的代码
+  - 移除 WebSocket 连接时更新心跳的代码
+
+### 第四步：清理 Watchdog monitor.py 废弃字段
+
+**修改文件：** `extensions/services/watchdog/monitor.py`
+
+- `ModuleStatus.__init__()` — 移除 `base_url` 和 `health_path` 参数
+- `discover_modules()` — 移除从 Registry 查询 health_path 的逻辑（Step 2）
+- `_check_one()` — 移除 `base_url` 检查（已废弃，现在直接通过 RPC 调用）
+
+## 当前健康检查机制
+
+### Watchdog 主动检查流程
+
+1. **模块发现** — 从 Launcher 获取运行中的模块列表（含 PID）
+2. **健康检查** — 通过 RPC 调用 `{module_id}.health` 检测每个模块
+3. **资源监控** — 通过 psutil 监控 CPU、内存使用率
+4. **失败处理** — 连续 3 次失败后自动重启模块
+5. **动态间隔** — 根据资源状态调整检查频率（NORMAL=15s, WARNING=5s, CRITICAL=2s）
+
+### 各模块 Health RPC 实现状态
+
+| 模块 | Health RPC | 返回内容 |
+|------|-----------|---------|
+| Kernel | ✅ | status, module_count, online_count, event_stats |
+| Launcher | ✅ | status, uptime_seconds, total_modules, running_modules, failed_modules, total_restarts |
+| Watchdog | ✅ 增强 | status, uptime_seconds, monitored_modules, unhealthy_modules, critical_resources, total_restarts |
+| Backup | ✅ | status, uptime_seconds |
+| Model Service | ✅ | status, uptime_seconds |
+| Web | ✅ 增强 | status, uptime_seconds, active_ws_connections |
+| Evol | ✅ 增强 | status, uptime_seconds, active_ws_connections |
+
+## 连接状态检测机制
+
+### WebSocket ping/pong（网络层）
+
+- **间隔**: 20 秒
+- **超时**: 20 秒
+- **作用**: 检测 TCP 连接是否存活
+- **局限**: 无法检测应用层僵死
+
+### Watchdog 健康检查（应用层）
+
+- **间隔**: 15 秒（正常）/ 5 秒（警告）/ 2 秒（严重）
+- **超时**: 5 秒（RPC 调用超时）
+- **作用**: 检测模块业务处理能力
+- **优势**: 能检测出僵死、响应缓慢、业务逻辑失效
+
+## 后续优化建议
+
+### 1. 增强 health 响应内容 ✅ 已完成
+
+各模块已返回更详细的健康信息：
+
+- **Launcher**: total_modules, running_modules, failed_modules, total_restarts
+- **Watchdog**: monitored_modules, unhealthy_modules, critical_resources, total_restarts
+- **Web**: active_ws_connections
+- **Evol**: active_ws_connections
+- **Backup/Model Service**: 保持基础信息（uptime_seconds）
+
+### 2. 健康状态分级（待实现）
+
+支持三级健康状态：
+
+- `healthy` — 完全正常
+- `degraded` — 部分功能受损但仍可用
+- `unhealthy` — 无法正常工作
+
+### 3. 自定义健康检查逻辑
+
+允许模块实现自定义的健康检查逻辑，例如：
+
+- 检查数据库连接
+- 检查依赖服务可用性
+- 检查关键线程状态
+
+## 兼容性说明
+
+### 向后兼容
+
+- WebSocket 连接机制不变
+- 模块注册流程不变
+- 事件发布/订阅机制不变
+
+### 不兼容变更
+
+- `registry.heartbeat` RPC 方法已移除（模块不应再调用）
+- `registry.register` 返回值不再包含 `ttl` 和 `heartbeat_interval` 字段
+- `RegistryStore.check_ttl()` 方法已移除
+
+## 测试建议
+
+1. **启动测试** — 验证所有模块能正常启动并注册
+2. **健康检查测试** — 验证 Watchdog 能正常检测各模块健康状态
+3. **故障恢复测试** — 手动停止模块，验证 Watchdog 能检测并重启
+4. **资源监控测试** — 验证 CPU/内存监控和告警功能
+5. **连接断开测试** — 验证 WebSocket 断开后的重连机制
+
+## 总结
+
+本次重构移除了冗余的被动心跳机制，改为 Watchdog 主动健康检查，使系统监控更加实用和高效。重构后的架构更加清晰，职责分离更加明确，为后续的监控功能扩展奠定了良好基础。

package/docs//346/217/241/346/211/213/350/256/244/350/257/201/346/226/271/346/241/210-/345/256/211/345/205/250/345/256/241/346/237/245.md

@@ -0,0 +1,176 @@
+# 握手认证方案 - 安全审查与改进清单
+
+## 问题汇总表
+
+| # | 问题 | 严重性 | 当前代码实现 | 新设计已考虑 | 解决方案 | 补充说明 |
+|---|------|---------|-------------|-------------|---------|---------|
+| 1 | Token 比较时序攻击 | 🔴 CRITICAL | ❌ 使用 `==` | ✅ 已考虑 | 新设计要求 `hmac.compare_digest()` | 改造清单已包含，`kernel/registry_store.py` 一行改动 |
+| 2 | Token 永不过期（自动延期） | 🔴 CRITICAL | ❌ 每次使用延期 30 天 | ⚠️ 部分考虑 | 引入绝对过期时间 + refresh_token 机制 | 需要在 AuthManager 中增加 `created_at` 字段，过期判断改为 `now > created_at + TTL` |
+| 3 | Kernel 侧无速率限制 | 🔴 CRITICAL | ❌ 无 | ⚠️ 仅 Relay 有 | Kernel 对本地模块也应有速率限制（宽松） | 本地模块由 Launcher 管理，风险较低，可作为 P1 补充 |
+| 4 | JSONL 无限增长 | 🔴 CRITICAL | ❌ 只追加不清理 | ❌ 未考虑 | 定期归档（按月）+ 过期记录清理 | 需要增加后台任务，每天清理过期 token 记录 |
+| 5 | Nonce 池内存泄漏 | 🔴 CRITICAL | ❌ 未实现 | ⚠️ 提到超时清理 | LRU 淘汰 + 定期清理 + 容量上限 | 新设计中 nonce 有 timeout，需要实现定期清理任务 |
+| 6 | 无 TLS 强制 | 🟠 HIGH | ⚠️ 支持但不强制 | ❌ 未明确 | 生产环境强制 WSS + 证书校验 | 需要在配置中增加 `require_tls` 选项，默认 true |
+| 7 | OAuth callback 无 state | 🟠 HIGH | ❌ 未实现 OAuth | ✅ 已考虑 | 新设计明确要求验证 state 参数 | OAuth 时序图中已标注 state 验证 |
+| 8 | Token 无签名 | 🟠 HIGH | ❌ 纯随机字符串 | ❌ 未考虑 | 使用 JWT 或 HMAC 签名 token | 可选增强，当前随机 token + 数据库验证也足够安全 |
+| 9 | 同 IP 多设备无区分 | 🟠 HIGH | ❌ 未实现速率限制 | ⚠️ 按 IP 限制 | 增加 IP + User-Agent 组合判定 | Relay 速率限制可以改为 `(IP, device_id)` 二元组 |
+| 10 | Token 撤销无实时性 | 🟠 HIGH | ⚠️ 内存缓存 1 小时 | ❌ 未考虑 | 撤销时清除内存缓存 + 广播撤销事件 | AuthManager 撤销时需要清除 `_cache`，或改为 Redis 共享缓存 |
+| 11 | 无审计日志 | 🟡 MEDIUM | ❌ 无结构化日志 | ❌ 未考虑 | 增加审计日志模块，记录所有认证事件 | 可以复用现有 Audit 模块，增加 `auth.*` 事件类型 |
+| 12 | 无 MFA/2FA | 🟡 MEDIUM | ❌ 无 | ❌ 未考虑 | 增加 TOTP 二次验证 | 可作为 `auth.method: "mfa"` 的额外步骤 |
+| 13 | 无设备信任等级 | 🟡 MEDIUM | ❌ 无 | ❌ 未考虑 | Token 记录中增加 `trust_level` 字段 | 可以根据认证方式自动分级：AID=高，配对码=中，短信=低 |
+| 14 | Token 轮换无强制 | 🟡 MEDIUM | ❌ 未实现 | ⚠️ 可选字段 | 高权限 token 强制轮换 | hello-ok 中 `token_rotation` 改为必填（针对 admin role） |
+| 15 | 时钟偏移无容忍 | 🟡 MEDIUM | ❌ 未实现 AID | ✅ 已考虑 | AID 签名 ±10 分钟容忍 | 新设计已包含，但需要处理极端偏移（如客户端时钟错误数小时） |
+| 16 | 无地理位置限制 | 🟢 LOW | ❌ 无 | ❌ 未考虑 | Token 记录中增加 `allowed_regions` | 可选增强，需要 IP 地理位置库 |
+| 17 | 无异常检测 | 🟢 LOW | ❌ 无 | ❌ 未考虑 | 监控 token 使用模式，检测异常 | 可选增强，需要机器学习或规则引擎 |
+| 18 | Relay 重定向无防循环 | 🟢 LOW | ❌ 未实现重定向 | ⚠️ 提到但未详细 | 客户端维护重定向计数器，最多 3 次 | 新设计已补充 |
+| 19 | 无 Token 元数据验证 | 🟢 LOW | ❌ 无签名 | ❌ 未考虑 | 使用 JWT 自包含 token | 同问题 8，可选增强 |
+| 20 | Challenge 超时后 nonce 未清理 | 🟡 MEDIUM | ❌ 未实现 | ⚠️ 提到超时 | 定期清理任务（每分钟） | 需要在 Kernel/Relay 中增加后台清理线程 |
+
+---
+
+## 优先级分级与实施方案
+
+### P0（立即修复，阻塞上线）
+
+| # | 问题 | 方案 | 改动量 | 责任模块 |
+|---|------|------|--------|---------|
+| 1 | Token 比较时序攻击 | ✅ 方案 1：`hmac.compare_digest()` | 极小（3 处，每处 1 行） | Kernel + Kite Console |
+| 6 | 无 TLS 强制 | ✅ 方案 1+3：配置项 `require_tls`，默认值根据环境变量（开发 WS，生产 WSS） | 小（10-20 行） | Kernel + Kite Console |
+| 7 | OAuth callback 无 state | ✅ 两种都实现：默认内存（60s TTL），配置项 `oauth.state_mode: "memory"/"jwt"` | 小（30 行） | Kite Console |
+
+### P1（公网前必须修复）
+
+| # | 问题 | 方案 | 改动量 | 责任模块 |
+|---|------|------|--------|---------|
+| 2 | Token 永不过期 | ✅ 方案 3：滑动 30 天 + 绝对半年上限 | 中（30 行） | Kite Console |
+| 4 | JSONL 无限增长 | ✅ 方案 1：每月归档到 `archive/YYYY-MM.jsonl.gz` | 中（50 行） | Kite Console |
+| 5 | Nonce 池内存泄漏 | ✅ 方案 3：TTL 字典（`expiringdict`，10000 容量，600s 过期） | 小（10 行） | Kernel + Kite Console |
+| 10 | Token 撤销无实时性 | ✅ 方案 1：撤销时清除内存缓存 `_cache.pop(token)` | 极小（2 行） | Kite Console |
+| 11 | 无审计日志 | ✅ 方案 1：复用 Audit 模块，增加 `auth.*` 事件 | 中（20 行） | Kernel + Kite Console |
+| 20 | Challenge 超时后 nonce 未清理 | ✅ 同 P1-3（TTL 字典自动过期） | 同 P1-3 | Kernel + Kite Console |
+
+### P2（运维增强）
+
+| # | 问题 | 方案 | 改动量 | 责任模块 |
+|---|------|------|--------|---------|
+| 3 | Kernel 侧无速率限制 | ✅ 方案 1：按 module_id 限制（10s 内最多 20 次） | 中（30 行） | Kernel |
+| 9 | 同 IP 多设备无区分 | ✅ 方案 1：速率限制改为 `(IP, device_id)` 二元组 | 小（10 行） | Kite Console |
+| 12 | 无 MFA/2FA | ✅ 方案 2：connect 请求中增加可选 `mfa_code` 字段 | 中（30 行） | Kite Console |
+| 13 | 无设备信任等级 | ✅ 方案 1：Token 记录中增加 `trust_level`，根据认证方式自动分级 | 小（10 行） | Kite Console |
+| 14 | Token 轮换无强制 | ✅ 方案 3：滑动 30 天 + 绝对半年（同 P1-2） | 同 P1-2 | Kite Console |
+| 15 | 时钟偏移无容忍 | ✅ 方案 2：客户端在 challenge 中获取服务端时间，自动校准 | 小（20 行） | Kite Console + 客户端 |
+
+### P3（可选增强）
+
+| # | 问题 | 方案 | 改动量 | 责任模块 |
+|---|------|------|--------|---------|
+| 8 | Token 无签名 | ✅ 方案 1：完全替换为 JWT（`PyJWT` 库） | 大（100 行） | Kite Console |
+| 16 | 无地理位置限制 | ✅ 方案 1：Token 记录中增加 `allowed_countries`，验证 IP 地理位置 | 中（50 行） | Kite Console |
+| 17 | 无异常检测 | ✅ 方案 1：简单规则引擎（IP 突变、异常时段、高频使用） | 大（200 行） | Kite Console |
+| 18 | Relay 重定向无防循环 | ✅ 客户端维护重定向计数器，最多 3 次 | 极小（10 行） | 客户端 |
+| 19 | 设备指纹 | ✅ 方案 3：前端 + 后端混合（后续实现） | 大（80 行） | Kite Console + 前端 |
+
+---
+
+## 关键发现
+
+### ✅ 新设计已解决的问题
+
+1. **时序攻击** — 明确要求 `hmac.compare_digest()`
+2. **OAuth CSRF** — 时序图中已标注 state 验证
+3. **速率限制** — Relay 层有完整的 IP + 节点维度限制
+4. **版本协商** — 协议版本范围协商机制完善
+5. **Token 轮换** — 双窗口过渡机制设计合理
+6. **同 ID 并发** — (device, channel) 二元组判定精细
+7. **Nonce 防重放** — 一次性 nonce + 超时机制
+
+### ⚠️ 新设计部分考虑但需补充的问题
+
+1. **Token 过期** — 提到 30 天 TTL，但未明确是绝对过期还是滑动过期
+2. **Nonce 清理** — 提到超时，但未明确清理机制
+3. **TLS** — 未在方案中明确强制要求
+4. **审计日志** — 未提及
+5. **Token 撤销实时性** — 未考虑缓存失效问题
+
+### ❌ 新设计未考虑的问题
+
+1. **JSONL 增长** — 长期运行的存储问题
+2. **MFA/2FA** — 高权限账户的二次验证
+3. **设备信任等级** — 所有设备一视同仁
+4. **异常检测** — 无主动安全监控
+5. **JWT 签名** — Token 仍是纯随机字符串
+
+---
+
+## 总体评价（更新后）
+
+**架构设计：9.5/10** — 两层模型 + 统一四步握手 + 9 种认证方式（含 MFA）+ JWT + 设备指纹 + 异常检测，架构非常完善。
+
+**安全性：9/10** — 修复所有 P0+P1 问题后，核心安全机制齐全（时序安全、TLS 强制、OAuth CSRF 防护、token 过期、审计日志）。补充 P2+P3 后可达 9.5/10。
+
+**可运维性：8.5/10** — 有审计日志、token 撤销实时、JSONL 归档、异常检测、地理位置限制。
+
+**与行业标准对比**：
+- **优于** Auth0/Keycloak：WebSocket 长连接场景的 challenge-nonce 机制更适合实时通信
+- **持平**：OAuth/LDAP/SAML 支持、MFA、JWT、速率限制、token 轮换、设备指纹、异常检测
+- **不如**：Auth0 的机器学习异常检测更强（我们是规则引擎）
+
+**结论**：修复 P0（3 项）+ P1（6 项）后，可以安全上生产。P2（6 项）建议在公网运行 1 个月内补充。P3（5 项）可以根据实际需求逐步补充。
+
+---
+
+## 实施建议
+
+### 第一阶段（上线前，1-2 周）
+
+- ✅ P0-1：时序安全比较（1 天）
+- ✅ P0-2：TLS 强制（1 天）
+- ✅ P0-3：OAuth state 验证（2 天）
+- ✅ P1-1：Token 过期机制（3 天）
+- ✅ P1-2：JSONL 归档（2 天）
+- ✅ P1-3：Nonce 池清理（1 天）
+- ✅ P1-4：Token 撤销实时性（0.5 天）
+- ✅ P1-5：审计日志（2 天）
+
+**总计**：约 12.5 天
+
+### 第二阶段（上线后 1 个月内）
+
+- ✅ P2-1：Kernel 速率限制（2 天）
+- ✅ P2-2：IP+设备 ID 速率限制（1 天）
+- ✅ P2-3：MFA/2FA（3 天）
+- ✅ P2-4：设备信任等级（1 天）
+- ✅ P2-6：时钟偏移容忍（2 天）
+
+**总计**：约 9 天
+
+### 第三阶段（按需实施）
+
+- ✅ P3-1：JWT Token（5 天）
+- ✅ P3-2：地理位置限制（3 天）
+- ✅ P3-3：异常检测（10 天）
+- ✅ P3-4：重定向防循环（0.5 天）
+- ✅ P3-5：设备指纹（5 天）
+
+**总计**：约 23.5 天
+
+---
+
+## 模块职责明确
+
+**Kite Console 模块**（`extensions/services/kite_console/`）负责：
+- 所有远程认证方式（OAuth/LDAP/SAML/MFA/配对码/短信/邮箱/AID）
+- Token 管理（颁发/验证/撤销/轮换/过期）
+- 设备指纹、异常检测、地理位置限制
+- Relay 服务（四步握手、速率限制、重定向）
+
+**Kernel 模块**（`kernel/`）负责：
+- 本地模块认证（token 验证）
+- 速率限制（本地模块）
+- 审计日志（认证事件）
+- 同 ID 并发连接判定
+
+**客户端**（前端 JS / Python 模块）负责：
+- 实现四步握手协议
+- 处理 token 轮换
+- 重定向防循环
+- 设备指纹采集（前端）