# AG组 代码审查报告

> 日期: 2026-05-21
> 部门: AG组
> 审查范围: AG1 Redis Pub/Sub + AG2 asyncssh + AG3 全链路代码审查 + S7 Sync引擎审查

---

## AG1: Redis Pub/Sub 架构审查

| 项目 | 评估 |
|------|------|
| 频道设计 | ✅ 单频道 `nexus:alerts` 简洁有效 |
| 消息格式 | ✅ JSON序列化，含 type/server_id/alert_type 字段 |
| 发布失败处理 | ✅ catch异常后logger.error，不影响主流程 |
| 订阅重连 | 🟡 当前无自动重连 — 如果Redis断连后恢复，subscriber不会自动重新订阅 |
| 建议 | 添加 subscriber 断连检测+自动重连逻辑 |

## AG2: asyncssh 连接池审查

| 项目 | 评估 |
|------|------|
| 引用计数模式 | ✅ acquire/release配对设计合理 |
| 空闲清理 | ✅ 300s IDLE_TIMEOUT + 60s CLEANUP_INTERVAL |
| 最大连接数 | ✅ MAX_CONNECTIONS=100，满时evict最旧idle连接 |
| 异常处理 | ✅ exec_ssh_command 捕获TimeoutError/ConnectionError |
| SSH Key解密 | ✅ 使用Fernet解密key_content，无明文泄漏 |
| 建议 | 考虑添加 `pool.stats` 到 /health 端点供监控 |

## AG3: 全链路代码审查

### 代码质量评分

| 模块 | 评分 | 说明 |
|------|------|------|
| `client.py` (Redis) | A | ADR-007/008/009 决策落实完整 |
| `websocket.py` | A- | 两层架构清晰；_verify_ws_token可提取为公共函数 |
| `auth_jwt.py` | B+ | 公开路由判断正确；`return None` type:ignore 需改用Optional返回 |
| `webssh.py` | A- | Koko协议实现完整；命令日志按行记录 |
| `sync_engine_v2.py` | A | 四种模式设计清晰；Semaphore并发控制 |
| `dependencies.py` | A | Session泄漏修复方案简洁 |
| `main.py` | A | lifespan完整；middleware注册顺序正确 |

### 发现的问题

| # | 严重度 | 文件 | 问题 | 建议 |
|---|--------|------|------|------|
| 1 | 🟡 中 | `auth_jwt.py:60` | `return None # type: ignore` — 公开路由返回None不安全 | 改为Optional[Admin]返回类型，路由handler自行判断 |
| 2 | 🟡 中 | `websocket.py` | Redis subscriber无断连自动重连 | 添加重连逻辑：catch异常后sleep+重新subscribe |
| 3 | 🟢 低 | `webssh.py` | 命令日志buffer在WebSocket断开时可能丢失最后一行 | 在disconnect前flush buffer |
| 4 | 🟢 低 | `sync_engine_v2.py` | `nonlocal completed, failed` 在并行task中存在竞态 | 改用asyncio.AtomicCounter或gather后统计 |

## S7: Sync引擎代码审查

| 项目 | 评估 |
|------|------|
| 文件同步 | ✅ rsync命令参数化，无注入风险 |
| 命令同步 | ✅ 用户输入通过asyncssh执行，不经过shell |
| 配置同步 | 🟡 sysctl key未做白名单校验 | 建议添加key格式校验 |
| 并发控制 | ✅ Semaphore控制，默认10并发 |
| 审计日志 | ✅ 所有操作写入AuditLog |

## AG4: 技术栈学习资料（投喂产品部）

### 整理清单

| 技术 | 官方文档 | 学习重点 |
|------|---------|---------|
| Tailwind CSS v4 | https://tailwindcss.com/docs | @theme配置、响应式断点、暗黑模式 |
| Alpine.js | https://alpinejs.dev | x-data/x-show/x-on/数据绑定 |
| FastAPI | https://fastapi.tiangolo.com | 依赖注入、异步路由、WebSocket |
| Redis | https://redis.io/docs | Pub/Sub、数据结构、连接池 |
| WebSocket | MDN WebSocket API | 连接管理、心跳、重连策略 |
| JWT | https://jwt.io/introduction | HS256签名、token结构、刷新机制 |

---

## 审查结论

**通过** — 代码质量整体A-级。4个中低优先级问题建议后续迭代修复。

