# Nexus 项目进度总览

> 最后更新: 2026-05-23  
> **AI 接续**: [`AI-HANDOFF-2026-05-23.md`](AI-HANDOFF-2026-05-23.md) · **标准转接**: [`standards-transfer-package.md`](standards-transfer-package.md) · **验收**: [`development-acceptance-standard.md`](development-acceptance-standard.md)

---

## 技术栈

| 维度 | 技术 |
|------|------|
| 后端 | Python 3.12 / FastAPI 0.115.6 / SQLAlchemy 2.0 Async |
| 数据库 | MySQL 8.4 (14 表) + Redis 7 (心跳/告警/Pub/Sub) |
| SSH | asyncssh 2.17.0 (引用计数连接池, ADR-004) |
| 认证 | JWT + TOTP (PyJWT 2.10.1, ADR-005) |
| 前端 | Tailwind CSS v4 + Alpine.js 3.14.8（**vendor 自托管** `/app/vendor/`） |
| 部署 | Nginx (模板化) + Supervisor (3层守护) |
| 通信 | WebSocket (两层架构, ADR-010) + Telegram |

---

## 数据库结构（14 张表）

```
核心表:
  platforms            资产类型模板: name, category, type, default_protocols(JSON)
  nodes                树形分组: name, parent_id, sort_order
  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
  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, sync_mode
  push_schedules       name, source_path, server_ids(JSON), cron_expr
  push_retry_jobs      server_id, retry_count, max_retries, next_retry_at
  password_presets      name, encrypted_pw
  db_credentials       db_type, host, port, username, 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
```

---

## 实施进度

### 第零步：基础设施 — ✅ 已完成

- [x] Redis BlockingConnectionPool + 启动强校验 (ADR-008/009)
- [x] WebSocket 两层架构 (ADR-010) + JWT 认证 (ADR-011)
- [x] Dashboard WebSocket 实时告警

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

- [x] Platform + Node 模型
- [x] Server 扩展字段 (platform_id, node_id, protocols, extra_attrs, connectivity)
- [x] CommandLog + SshSession 模型
- [x] Admin JWT 字段
- [x] 数据迁移: category → Node

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

- [x] JWT 登录/刷新/验证
- [x] TOTP 双因素
- [x] Tailwind 登录页 + api.js 共享模块

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

- [x] asyncssh 引用计数连接池
- [x] WebSocket 端点 + Koko 协议
- [x] 会话追踪 + 命令日志
- [x] xterm.js 前端页面 (terminal.html)

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

- [x] 文件/命令/配置/SFTP 四种同步模式
- [x] Semaphore 并发控制

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

- [x] 12 个 Tailwind+Alpine.js 页面 (含 install.html)
- [x] api.js JWT 共享模块
- [x] WebSocket 实时更新
- [x] install.php → install.html + FastAPI API 迁移
- [x] 条件启动模式 (install mode vs normal mode)
- [x] 脚本执行历史页 `script-executions.html`（侧栏「执行历史」）

### 脚本批量执行平台 — ✅ 已实现，⏳ 待 E2E

- [x] 内置分批（50/批，并发 10）+ 页顶批量状态条
- [x] 长任务 nohup + 子机 curl 回调（`NEXUS_API_BASE_URL`）
- [x] Redis 热数据 2h + MySQL 60s 分批刷盘
- [x] 短任务 stop（Agent exec/wait/kill，需子机升级）
- [x] 执行历史 / 停止 / 重试 / 标记卡住 / 自动卡住检测
- [ ] T-SE1～T-SE8 联调（见 `docs/project/script-execution.md` §11）

**文档**: `docs/project/script-execution.md` · Changelog: `docs/changelog/2026-05-22-script-execution-platform.md`

### Phase 2 安全走读 — ✅ 代码已闭环，⏳ 外网 E2E

- [x] 63 条 FINDING 逐行走读（2a–2j）
- [x] P0/P1/P2 代码修复（WebSSH、JWT 中间件、注入、告警策略、vendor 自托管等）
- [x] 单元回归 `tests/test_security_unit.py`（17 项）
- [ ] 首次部署 E2E（见 `production-verification-checklist.md`）

**SSOT**: `docs/project/phase-2-audit-remediation.md` · 矩阵: `docs/reports/audit-phase-2-findings-matrix.md`

> 未部署：无 API Key 轮换；F2f-04 代码侧已闭环。

---

## 架构决策

| 编号 | 决策 | 选择 | 状态 |
|------|------|------|------|
| ADR-001 | 资产模型 | Platform + Node + Server 扩展 | ✅ |
| ADR-002 | Web SSH | BFF + asyncssh 内嵌 | ✅ (后端) |
| ADR-003 | 前端终端 | xterm.js + Koko 协议 | ✅ |
| ADR-004 | SSH 连接池 | 引用计数模式 | ✅ |
| ADR-005 | 认证 | JWT + TOTP | ✅ |
| ADR-006 | 前端框架 | 弃用 AdminLTE → Tailwind | ✅ |
| ADR-007 | Redis 定位 | 核心数据层 | ✅ |
| ADR-008 | Redis 池 | BlockingConnectionPool | ✅ |
| ADR-009 | Redis 可用性 | 启动强校验 | ✅ |
| ADR-010 | WebSocket | 内存 + Pub/Sub 两层 | ✅ |
| ADR-011 | WS 认证 | JWT 查询参数 + webssh-token | ✅ |

**总完成度: ~98%**（Phase 2 代码闭环；首次部署时再跑 E2E）