Nexus/docs/project/roadmap.md

Nexus 项目建议书

更新: 2026-05-22

---

一、项目现状

运行状态

技术栈:     Python 3.12 / FastAPI / MySQL 8.4 / Redis 7 / Nginx
后端:       Clean Architecture 4层 (domain → infrastructure → application → api)
前端:       Tailwind CSS v4 + Alpine.js (纯静态 HTML，JWT 认证)
数据库:     14 张表 (servers, admins, platforms, nodes, command_logs, ssh_sessions 等)
核心功能:   rsync 文件推送 + WebSocket 实时告警 + asyncssh 连接池 + Telegram 推送
守护机制:   3层 (Supervisor + Python self_monitor 30s + Shell cron 1min)

数据库现有表（14 张）

核心表:
  servers (扩展)      id, name, domain, port, username, auth_method,
                       password(加密), ssh_key_*(3), agent_port, agent_api_key,
                       category, is_online, system_info, last_heartbeat,
                       platform_id, node_id, protocols(JSON), extra_attrs(JSON),
                       connectivity, last_checked_at

  platforms            资产类型模板: name, category, type, default_protocols(JSON)
  nodes                树形分组: name, parent_id, sort_order
  admins               认证: username, password_hash, totp_secret, totp_enabled,
                       jwt_refresh_token, jwt_token_expires

  settings             配置: key → value

业务表:
  sync_logs            推送日志: server_id, source/target_path, status, files_*
  push_schedules       定时推送: cron_expr, server_ids(JSON)
  push_retry_jobs      重试队列: retry_count, max_retries
  password_presets      密码预设: name, encrypted_pw
  db_credentials       数据库凭据: db_type, host, encrypted_password

  scripts              脚本库: name, category, content
  script_executions    执行记录: script_id, command, server_ids(JSON), results(JSON)

辅助表:
  audit_logs           审计: admin_username, action, target_type, detail
  login_attempts       防暴力: username, ip_address, success

Web SSH 表:
  ssh_sessions         会话: UUID id, server_id, admin_id, status, started_at, closed_at
  command_logs         命令: session_id, server_id, admin_id, command

前端页面（Tailwind CSS v4 + Alpine.js）

页面	文件	功能
登录	login.html	JWT 登录 + TOTP 双因素
仪表盘	index.html	统计 + WebSocket 实时告警
服务器	servers.html	CRUD + 心跳状态 + 健康检测
文件管理	files.html	远程文件浏览 (SFTP/SSH)
推送	push.html	批量文件推送 + 进度
脚本	scripts.html	脚本库 + 批量执行状态条
执行历史	script-executions.html	脚本执行记录、停止/重试/日志
凭据	credentials.html	密码预设 + 数据库凭据
定时	schedules.html	Cron 调度管理
重试	retries.html	失败重试队列
设置	settings.html	系统配置
审计	audit.html	操作日志

共享模块: api.js — JWT 自动刷新、apiFetch 封装、登出

---

二、架构决策记录

已落地决策

编号	决策	选择	状态
ADR-001	资产模型	Platform 模板 + 单表 Asset + JSONB	✅ 已落地
ADR-002	Web SSH 架构	BFF 模式，asyncssh 内嵌 FastAPI	✅ 已落地 (后端)
ADR-003	前端终端	xterm.js + Koko 消息协议	⚠️ 后端落地，前端待做
ADR-004	SSH 连接池	引用计数模式	✅ 已落地
ADR-005	登录认证	JWT + TOTP 全新替换	✅ 已落地
ADR-006	前端框架	全面弃用 AdminLTE → Tailwind CSS v4	✅ 已落地
ADR-007	Redis 定位	核心数据层	✅ 已落地
ADR-008	Redis 连接池	BlockingConnectionPool	✅ 已落地
ADR-009	Redis 可用性	启动强校验，不可用直接退出	✅ 已落地
ADR-010	WebSocket 架构	内存 + Redis Pub/Sub 两层	✅ 已落地
ADR-011	WebSocket 认证	JWT 令牌（查询参数传递）	✅ 已落地

已否决

功能	原因
会话录像 asciicast	不需要
RBAC 权限体系	保持"鉴权即信任"模型
推送结果邮件报告	不需要

---

三、实施进度

第零步：基础设施加固（Redis + WebSocket）— ✅ 已完成

• Redis BlockingConnectionPool + 启动强校验 (ADR-008/009)
• WebSocket 两层架构: 内存 ConnectionManager + Redis Pub/Sub (ADR-010)
• WebSocket JWT 认证 (ADR-011)
• Ping/pong 心跳 + 僵尸连接清理

第一步：数据层 — ✅ 已完成

• platforms 表（资产类型模板）
• nodes 表（树形分组）
• servers 表扩展字段 (platform_id, node_id, protocols, extra_attrs, connectivity)
• command_logs 表（SSH 命令日志）
• ssh_sessions 表（Web SSH 会话）
• admins 表 JWT 字段
• 数据迁移: category → Node, 回填 platform_id

第二步：认证层 — ✅ 已完成

• JWT 登录/刷新/验证 (server/api/auth_jwt.py)
• TOTP 双因素认证
• Tailwind CSS v4 登录页 (web/app/login.html)
• 共享 JWT 模块 (web/app/api.js)
• Pydantic 请求模型 (server/api/schemas.py)
• 所有 API 路由 JWT 保护

第三步：Web SSH 终端 — ✅ 已完成

• asyncssh 连接池模块 (server/infrastructure/ssh/asyncssh_pool.py)
• WebSocket 端点 /ws/terminal/{server_id} (server/api/webssh.py)
• Koko 消息协议 (TERMINAL_INIT/DATA/RESIZE/CLOSE)
• SSH 会话生命周期追踪 (SshSession + CommandLog)
• xterm.js 前端页面 (web/app/terminal.html，含 webssh-token + 全屏 + resize)

第四步：Sync 引擎升级 — ✅ 已完成

• rsync 文件同步 (SyncEngineV2.sync_files)
• SSH 命令批量执行 (SyncEngineV2.sync_commands)
• 系统配置推送 (SyncEngineV2.sync_config)
• SFTP 文件传输 (SyncEngineV2.sftp_transfer)
• Semaphore 并发控制 (MAX_CONCURRENT=10)
• 远程目录浏览 (POST /api/sync/browse)

第五步：前端全量迁移 — ✅ 已完成

• @theme 设计系统（品牌色/间距/字体/暗黑模式）
• 布局壳（sidebar + header + main，Alpine.js 交互）
• Dashboard + WebSocket 实时告警
• 服务器列表 + 文件管理 + 推送页面
• 设置/配置/审计日志/脚本库/凭据管理
• 定时推送/重试队列
• install.php → install.html + FastAPI API 迁移
• 条件启动模式 (install mode: 无 .env 时仅安装 API 可用)

---

四、安全性

已实施

措施	状态
SSH 密码 Fernet + AES 加密	✅
JWT 认证全覆盖	✅
CORS 可配置域名	✅
默认凭据启动拒绝	✅
Shell 注入防御 (shlex.quote)	✅
XSS 防御 (dataset 属性替代模板字面量)	✅
WebSocket JWT 认证	✅
DbSessionMiddleware 防连接泄漏	✅
Telegram 共享 httpx 客户端	✅

---

五、数据流

Agent心跳(60s) → Redis heartbeat:{id} (HSET, TTL=600s) → 前端直读
                                                              ↓
                                                      10min批量flush
                                                              ↓
                                                       MySQL (历史)

告警: CPU/mem/disk > threshold
  → WebSocket nexus:alerts (Redis Pub/Sub) → 浏览器实时显示
  → Telegram 推送手机
  → Redis alerts:{id} (SET, TTL=3600s) 告警标记

恢复: 之前告警指标恢复正常
  → WebSocket + Telegram 推送恢复通知
  → self_monitor 服务恢复时 Telegram 通知

---

六、技术债务

#	项	影响	建议
D1	paramiko pool.py 废弃	无（已无引用）	✅已删除 — pool.py 已移除，requirements.txt 已移除 paramiko
D2	config.php PHP 残留	低	✅已迁移 — install.php → install.html + FastAPI API，条件启动模式
D3	WebSSH 前端未实现	中	✅已实现 — xterm.js + Koko协议 + 自动resize + 全屏
D4	文件编辑器未集成	—	❌ 已否决 — 运维场景无需嵌入编辑器；远程文件通过 WebSSH / SFTP 处理

---

七、文件索引

文档	说明
docs/design/specs/design-standards.md	设计标准
docs/design/tech-stack-evaluation.md	技术栈评估
docs/project/status.md	项目进度总览
docs/project/deploy.md	部署指南
docs/research/jumpserver-easynode-architecture-analysis.md	竞品架构分析
CLAUDE.md	项目记忆（开发上下文）
server/domain/models/__init__.py	SQLAlchemy 数据库模型