设计部审查报告 — Nexus 技术栈全面评估
审查人: 设计部负责人
审查日期: 2026-05-22（v2 更新）
审查范围: 全部设计规格、实施计划、竞品分析、roadmap/ADR、config.py、requirements.txt、.env.example
变更说明: v2 全面更新，修正 v1 中7处"未落地"致命错误，反映代码实际进度
一、当前技术栈完整清单
1.1 后端运行时
| 技术 |
版本 |
用途 |
选型合理性 |
风险评估 |
| Python |
3.12 |
后端运行时 |
合理。FastAPI 生态成熟，异步支持完善，社区活跃 |
低 |
| FastAPI |
0.115.6 |
Web 框架 |
合理。原生 async/await、自动 OpenAPI 文档、Pydantic 集成、WebSocket 原生支持 |
低 |
| Uvicorn |
0.34.0 |
ASGI 服务器 |
合理。FastAPI 标配，uvloop 性能优异 |
低 |
1.2 数据层
| 技术 |
版本 |
用途 |
选型合理性 |
风险评估 |
| SQLAlchemy |
2.0.36 (asyncio) |
ORM |
合理。2.0 异步支持成熟，比 Tortoise-ORM 灵活，比 Django ORM 更适合 FastAPI |
低 |
| aiomysql |
0.2.0 |
MySQL 异步驱动 |
可接受。社区较小，更新频率低。长期可评估迁移到 asyncmy |
低-中 |
| Pydantic |
2.10.3 |
数据验证/序列化 |
合理。FastAPI 核心依赖，v2 性能大幅提升 |
低 |
| pydantic-settings |
2.7.0 |
配置管理 |
合理。环境变量 + .env 加载，NEXUS_ 前缀 |
低 |
| Redis (hiredis) |
5.2.1 |
缓存/心跳/队列/Pub-Sub |
合理。5.x async 支持成熟，hiredis C 加速解析器。ADR-007/008/009 已落地 |
低 |
1.3 SSH 与远程执行
| 技术 |
版本 |
用途 |
选型合理性 |
风险评估 |
| asyncssh |
2.17.0 |
SSH 连接 (异步) |
✅ 已落地。ADR-002/004 已实现：引用计数连接池 (asyncssh_pool.py)、WebSSH (webssh.py)、SyncService 已迁移 |
低 |
| paramiko |
3.5.0 |
SSH 连接 (同步) |
❌ 已移除。pool.py 已删除，requirements.txt 已移除。asyncssh 为唯一 SSH 库 |
无 |
v1 勘误: v1 标注"asyncssh — 前瞻性选型，当前未实际使用"是错误的。asyncssh 已全面替代 paramiko 成为唯一活跃 SSH 库。
1.4 HTTP 与通信
| 技术 |
版本 |
用途 |
选型合理性 |
风险评估 |
| httpx |
0.28.1 |
HTTP 客户端 |
合理。async/await 支持，Agent 通信 + Telegram 共享客户端 |
低 |
| websockets |
14.1 |
WebSocket |
合理。告警推送 (ADR-010 两层架构) + WebSSH 终端 |
低 |
| python-multipart |
0.0.19 |
表单解析 |
合理。文件上传必需 |
低 |
1.5 安全加密
| 技术 |
版本 |
用途 |
选型合理性 |
风险评估 |
| PyJWT |
2.10.1 |
JWT 令牌 |
✅ 已落地。JWT 认证完整实现：登录/刷新/验证/WebSocket 认证 (ADR-005/011) |
低 |
| bcrypt |
4.2.1 |
密码哈希 |
合理。密码存储标准 |
低 |
| cryptography |
44.0.0 |
Fernet + AES 加密 |
合理。Fernet (Python) + AES-CBC (PHP 兼容)，凭据加密存储 |
低 |
1.6 后台任务
| 技术 |
用途 |
选型合理性 |
风险评估 |
| asyncio.create_task |
后台协程 |
合理。4 个后台任务：heartbeat_flush(10min)、self_monitor(30s)、schedule_runner(60s)、retry_runner(5min) |
低 |
| asyncio.Semaphore |
并发控制 |
合理。批量推送、同步引擎并发限制 (MAX_CONCURRENT=10) |
低 |
v1 勘误: v1 评估了 apscheduler==3.11.0 — 已移除。自定义 schedule_runner_loop + retry_runner_loop 替代，更轻量且原生异步。
1.7 前端技术
| 技术 |
版本 |
用途 |
选型合理性 |
风险评估 |
| Tailwind CSS |
v4 (CDN) |
CSS 框架 |
合理。零运行时、纯静态、@theme 设计系统 |
低 |
| Alpine.js |
3.14.8 (CDN) |
前端交互 |
合理。轻量级，与静态 HTML 完美配合 |
低 |
| Monaco Editor |
0.45.0 (CDN) |
代码编辑器 |
规划中。文件管理器编辑功能 |
低（未落地） |
| xterm.js |
— |
终端模拟器 |
规划中。Web SSH 终端前端（后端已实现） |
低（前端未落地） |
v1 勘误: v1 评估了 PHP + AdminLTE — 已全面弃用 (ADR-006)。所有页面已迁移到 Tailwind CSS v4 + Alpine.js。
1.8 部署与运维
| 技术 |
用途 |
选型合理性 |
风险评估 |
| Nginx |
反向代理 |
合理。模板化配置 ({{PLACEHOLDER}})，支持 HTTP/HTTPS |
低 |
| Supervisor |
进程管理 |
合理。3 层守护 Layer 1 |
低 |
| MySQL |
持久化存储 |
合理。宝塔标配，14 张表 |
低 |
| Redis |
缓存/实时数据 |
合理。心跳热数据、告警冷却、Pub/Sub |
低 |
二、v1 标注"未落地"但实际已落地的功能
以下功能在 v1 报告中标注为"未落地"，但代码审查确认已完整实现：
| 功能 |
v1 判定 |
实际状态 |
实现位置 |
| asyncssh 连接池 |
"未落地" |
✅ 已落地 |
server/infrastructure/ssh/asyncssh_pool.py — 引用计数模式，acquire/release/cleanup |
| JWT + TOTP 登录 |
"未落地" |
✅ 已落地 |
server/api/auth_jwt.py + web/app/login.html + web/app/api.js |
| SFTP 文件传输 |
"未落地" |
✅ 已落地 |
server/application/services/sync_engine_v2.py — sftp_transfer() |
| 命令日志 |
"未落地" |
✅ 已落地 |
server/domain/models.py CommandLog + server/infrastructure/database/ssh_session_repo.py |
| SSH 会话管理 |
"未落地" |
✅ 已落地 |
server/api/webssh.py + SshSession/CommandLog 模型 |
| 定时推送调度 |
"未深度集成" |
✅ 已落地 |
server/background/schedule_runner.py + server/background/retry_runner.py |
| WebSocket 告警推送 |
"未落地" |
✅ 已落地 |
server/api/websocket.py — 两层架构 (ADR-010) + Dashboard 实时更新 |
三、已移除的依赖（v1 仍在评估）
| 依赖 |
v1 评估 |
实际操作 |
原因 |
| APScheduler |
"存疑" |
✅ 已移除 |
自定义 asyncio loop 更轻量、原生异步 |
| Jinja2 |
"合理" |
✅ 已移除 |
纯 API 后端，无模板渲染需求 |
| aiofiles |
"合理" |
✅ 已移除 |
asyncssh SFTP 替代异步文件操作 |
| Rich |
"低优先级" |
✅ 已移除 |
后端非 CLI 工具，无使用场景 |
| Alembic |
"必要组件" |
✅ 已移除 |
使用 init_db() 自动建表，无迁移需求 |
| PyYAML |
"遗留依赖" |
⚠️ 保留 |
Agent 配置已迁移到 JSON，但可能有其他 YAML 场景 |
四、配置与部署
4.1 环境变量（已统一）
| 项目 |
状态 |
| 前缀统一 |
✅ NEXUS_ 前缀（config.py env_prefix="NEXUS_"） |
| .env.example |
✅ 已从 MULTISYNC_ 更新为 NEXUS_ |
| 部署路径 |
✅ NEXUS_DEPLOY_PATH 可配置 |
| CORS |
✅ NEXUS_CORS_ORIGINS 可配置 |
4.2 连接池配置
| 组件 |
配置 |
说明 |
| MySQL |
pool_size=160, max_overflow=120 |
最大 280 连接 (基于 MySQL max_connections=400, install.php 自动计算) |
| Redis |
BlockingConnectionPool (ADR-008) |
达上限等待而非抛异常 |
| asyncssh |
MAX_CONNECTIONS=100, IDLE_TIMEOUT=300s |
引用计数模式 (ADR-004) |
4.3 Redis Key 设计规范
| Key 格式 |
类型 |
TTL |
用途 |
heartbeat:{server_id} |
HSET |
600s |
Agent 心跳数据 (is_online, system_info, agent_version) |
alerts:{server_id} |
SET |
3600s |
告警状态标记 |
nexus:alerts |
Pub/Sub channel |
— |
WebSocket 告警广播 (ADR-010) |
sync:progress:{op}:{ts} |
STRING |
— |
推送进度追踪 |
五、架构决策落地状态
| 编号 |
决策 |
选择 |
落地状态 |
| ADR-001 |
资产模型 |
Platform 模板 + 单表 Asset + JSONB |
✅ 已落地 — Platform/Node/Server 扩展字段 |
| ADR-002 |
Web SSH 架构 |
BFF 模式，asyncssh 内嵌 |
✅ 已落地 — webssh.py + asyncssh_pool.py |
| ADR-003 |
前端终端 |
xterm.js + Koko 协议 |
⚠️ 后端已落地，前端未实现 |
| ADR-004 |
SSH 连接池 |
引用计数模式 |
✅ 已落地 — asyncssh_pool.py |
| ADR-005 |
登录认证 |
JWT + TOTP 全新替换 |
✅ 已落地 — auth_jwt.py + login.html |
| ADR-006 |
前端框架 |
全面弃用 AdminLTE |
✅ 已落地 — 12+ Tailwind 页面 |
| ADR-007 |
Redis 定位 |
核心数据层 |
✅ 已落地 |
| ADR-008 |
Redis 连接池 |
BlockingConnectionPool |
✅ 已落地 |
| ADR-009 |
Redis 可用性 |
启动强校验 |
✅ 已落地 |
| ADR-010 |
WebSocket 架构 |
内存 + Redis Pub/Sub 两层 |
✅ 已落地 |
| ADR-011 |
WebSocket 认证 |
JWT 查询参数 |
✅ 已落地 |
六、竞品对比结论（更新）
| 维度 |
Nexus (当前) |
JumpServer |
评价 |
| SSH 代理 |
asyncssh 内嵌 (异步原生) |
独立 Koko (Go 二进制) |
Nexus 部署更简单，2000 台规模足够 |
| 连接池 |
引用计数 asyncssh |
Koko 引用计数 |
设计思路一致，Nexus 用 Python 实现 |
| 认证 |
JWT + TOTP |
TOTP/LDAP/OIDC/SAML2 |
Nexus 简化方案适合内部运维 |
| 前端 |
Tailwind + Alpine.js (纯静态) |
Vue 3 + Element Plus |
Nexus 零构建步骤，部署更简单 |
七、待落地功能
| 功能 |
优先级 |
预估工时 |
说明 |
| xterm.js 前端页面 |
中 |
2-3 天 |
WebSSH 后端已就绪，需前端页面 |
| 推送前预览 (rsync dry-run) |
低 |
0.5 天 |
推送对话框加"预览"按钮 |
| 首次使用引导 |
低 |
1 天 |
install.php 后3步向导 |
| 命令日志查询页面 |
低 |
0.5 天 |
后端 API 已就绪 |
paramiko 完全移除 |
低 |
0.5 天 ✅已完成 |
pool.py 已删除 + requirements.txt 已移除 |
八、风险评估矩阵（更新）
| 风险 |
严重度 |
发生概率 |
当前状态 |
| aiomysql 连接池稳定性 |
中 |
低 |
pool=160/120 合理 (基于 MySQL max_connections=400, install.php 自动计算) |
| PHP 残留页面 |
低 |
中 |
install.php/login.php 保留，其余已迁移 |
| 文档与代码不同步 |
中 |
高 |
本报告已修正，需持续维护 |
Codex Release Bot