# 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）— ✅ 已完成

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

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

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

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

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

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

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

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

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

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

- [x] @theme 设计系统（品牌色/间距/字体/暗黑模式）
- [x] 布局壳（sidebar + header + main，Alpine.js 交互）
- [x] Dashboard + WebSocket 实时告警
- [x] 服务器列表 + 文件管理 + 推送页面
- [x] 设置/配置/审计日志/脚本库/凭据管理
- [x] 定时推送/重试队列
- [x] install.php → install.html + FastAPI API 迁移
- [x] 条件启动模式 (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 数据库模型 |