Nexus/docs/reports/step-0-infrastructure/ag-code-review-report.md

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未做白名单校验
并发控制	✅ 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个中低优先级问题建议后续迭代修复。