# 设计部审查报告 — 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 保留，其余已迁移 |
| 文档与代码不同步 | 中 | 高 | **本报告已修正**，需持续维护 |
