# Nexus 6.0 — 全站功能清单（SSOT）

> **更新**: 2026-05-23  
> **读者**: 产品、运维、接续开发的 AI  
> **HTML 版**: [`docs/Nexus-功能说明书.html`](../Nexus-功能说明书.html)  
> **接续开发**: [`AI-HANDOFF-2026-05-23.md`](AI-HANDOFF-2026-05-23.md)

---

## 0. 全站页面地图（18 页）

| 页面 | 路径 | 功能摘要 |
|------|------|----------|
| 安装向导 | `/app/install.html` | 无 `.env` 时 5 步安装中心机 |
| 登录 | `/app/login.html` | JWT + TOTP + 防暴破 |
| 仪表盘 | `/app/index.html` | 统计、WebSocket 刷新、告警计数 |
| 服务器 | `/app/servers.html` | CRUD、详情、Agent 安装/升级、时钟漂移 |
| 资产管理 | `/app/assets.html` | Platform / Node 树 |
| 文件管理 | `/app/files.html` | SSH 浏览、删/改名/建目录 |
| 推送 | `/app/push.html` | rsync 批量、dry-run 预览、历史 |
| 脚本库 | `/app/scripts.html` | 脚本 CRUD、直接执行、$DB_* |
| 执行历史 | `/app/script-executions.html` | 停止/重试/日志/卡住检测 |
| 凭据 | `/app/credentials.html` | DB 凭据 + 密码预设 |
| 定时调度 | `/app/schedules.html` | Cron 推送 **或** 脚本执行 |
| 重试队列 | `/app/retries.html` | 推送失败指数退避重试 |
| 命令日志 | `/app/commands.html` | WebSSH 会话/命令 + **推送日志** |
| 告警中心 | `/app/alerts.html` | 告警历史、统计、时间过滤 |
| 审计 | `/app/audit.html` | 操作审计、时间/用户/类型过滤 |
| 设置 | `/app/settings.html` | 品牌、阈值、Telegram、TOTP、IP 白名单 |
| WebSSH | `/app/terminal.html` | xterm.js 终端（独立页） |

共享：`layout.js`（侧栏）、`api.js`（JWT、toast、全局搜索）

---

## 1. 网络与通道模型

| 通道 | 端口 | 用途 |
|------|------|------|
| 子机 → 中心 | **443 出站** | Agent 心跳、长任务完成回调 |
| 中心 → 子机 | **22 入站** | 推送、文件、**脚本**、手动健康检查、Agent 安装/升级 |
| 子机本机 | **127.0.0.1:8601** | Agent HTTP（可不暴露公网） |

---

## 2. 认证与访问控制

- JWT 登录 / 刷新 / 登出（`POST /api/auth/*`）
- TOTP：启用、禁用、**重绑**（设置页）
- 登录防暴破：5 次/15 分钟 → 429
- 会话：8 小时无操作退出；刷新令牌重用检测
- **登录 IP 白名单**：总开关、手动 IP、**代理订阅 URL 解析**（2h 自动刷新）、与登录防暴破联动
- WebSSH 专用短票：`POST /api/auth/webssh-token`（绑定 server_id）

**不可改密钥**（仅 `.env`）：`SECRET_KEY`、`API_KEY`、`ENCRYPTION_KEY`、`DATABASE_URL`

---

## 3. 仪表盘（index.html）

- 服务器总数 / 在线 / 离线 / 告警中（Redis 实时）
- WebSocket：告警/恢复时**刷新统计**（浏览器不响铃、不弹告警列表）
- 最近推送记录摘要

---

## 4. 告警中心（alerts.html）— 新增模块

- MySQL `alert_logs` 持久化告警与恢复记录
- 列表：按服务器、类型、是否恢复、**日期范围**分页
- 统计：近 N 日 Top 服务器、按日计数
- API：`GET /api/alert-history/`、`GET /api/alert-history/stats`

**实时告警路径**：Agent 心跳超阈值 → Redis + WebSocket Pub/Sub + Telegram（5 分钟防抖）

---

## 5. 服务器管理（servers.html）

- 分页列表；Redis 覆盖 `is_online`、`system_info`、**时钟漂移**（warn/crit 徽章）
- CRUD：SSH 密钥/密码（Fernet）、`platform_id`/`node_id`、`target_path`、`agent_port`
- 每机 **Agent API Key**（`nxs-*`，一次性展示）
- **Agent 安装**：复制 curl 命令 / **一键 SSH 远程安装**（实时日志）
- 安装后 **轮询在线状态**
- **Agent 升级**：`POST /api/servers/{id}/upgrade-agent`（SSH 拉 agent.py + restart）
- **健康检查**：`POST /api/servers/check`（**SSH 探测**，非 8601）
- 详情：系统信息、同步日志、WebSSH 入口
- 推送：`POST /api/servers/push`；日志：`GET /api/servers/logs`

**未实现**：CSV 批量导入

---

## 6. 资产管理（assets.html）

- Platform 模板 CRUD
- Node 树形分组 CRUD
- SSH 会话列表、命令日志查询（与 commands.html 数据同源）

API：`/api/assets/platforms`、`/api/assets/nodes`、`/api/assets/ssh-sessions`、`/api/assets/command-logs`

---

## 7. WebSSH（terminal.html）

- xterm.js + Koko 协议 + asyncssh 连接池
- `webssh-token` 15 分钟、**绑定 server_id**（越权关闭码 4003）
- 全屏、自动 resize
- 会话与命令写入 `ssh_sessions` / `command_logs`

**未实现**：断线自动重连（需刷新页面）

---

## 8. 命令日志（commands.html）

- **会话视图**：WebSSH 会话列表、过滤
- **命令视图**：逐条命令、危险命令高亮
- **推送日志视图**：rsync 批量推送历史、分页、服务器/状态/模式/触发源过滤

---

## 9. 批量推送（push.html）

- SyncEngineV2：`sync_files` rsync-over-SSH
- 模式：增量 / 全量(--delete) / 校验和 / inplace
- 分批 50、并发 10；失败 → `push_retry_jobs`
- **dry-run 预览**（方案 D）：首台 `--dry-run --stats`，可选 `-v` 前 200 行
- 推送历史列表

API：`POST /api/sync/files`、`POST /api/sync/preview`

---

## 10. Sync 引擎其他能力（API，部分无独立页）

| 模式 | API | 说明 |
|------|-----|------|
| 命令批量 | `POST /api/sync/commands` | SSH 批量执行命令 |
| 配置推送 | `POST /api/sync/config` | 批量写配置项 |
| 配置回滚 | `POST /api/sync/config/rollback` | 回滚 |
| SFTP | `POST /api/sync/sftp` | 上传/下载 |
| 目录浏览 | `POST /api/sync/browse` | 文件页也用 |
| 文件操作 | `POST /api/sync/file-ops` | 删/改名/mkdir |

---

## 11. 脚本与执行历史

### 脚本库（scripts.html）

- 脚本 CRUD（分类：ops/deploy/check/cleanup）
- **直接执行命令**（无需入库）
- 批量选机执行；危险命令中心拦截（400）
- **执行通道：SSH 22**（结果 `channel: ssh`）
- $DB_* 凭据替换（中心替换后 SSH 下发）

### 执行历史（script-executions.html）

- 列表 / 详情 / 停止 / 重试 / 标记卡住
- 长任务：nohup + 子机 `curl` 回调 `POST /api/agent/script-callback`
- Redis 热数据 2h + 60s 刷 MySQL

API：`POST /api/scripts/exec`、`GET /api/scripts/executions/*`

---

## 12. 远程文件管理（files.html）

- SSH `ls -la` 浏览、面包屑、目录优先排序
- 删除文件/目录、重命名、新建目录（confirm/二次确认）

**未实现**：上传、在线预览、树形侧栏

---

## 13. 定时调度（schedules.html）

- **类型**：`push`（文件推送）或 `script`（脚本执行）
- 5 字段 Cron；`schedule_runner` 60s 检查；仅 Primary Worker
- 脚本调度：关联 `script_id` 或内联 `script_content`、超时、长任务标志

---

## 14. 凭据管理（credentials.html）

- **数据库凭据**：MySQL/PG 等，Fernet 加密，供 $DB_*
- **密码预设**：SSH 密码模板（推送场景）

脚本页也可管理 DB 凭据（`/api/scripts/credentials`）

---

## 15. 重试队列（retries.html）

- 推送失败自动入队；`retry_runner` 5 分钟指数退避
- 手动立即重试 / 删除任务

---

## 16. 全局搜索

- 侧栏搜索框：`GET /api/search/` 跨服务器/脚本/凭据/调度

---

## 17. 系统设置（settings.html）

| 模块 | 功能 |
|------|------|
| 品牌 | system_name、title |
| 监控 | CPU/内存/磁盘阈值 |
| 连接 | redis_url、pool_size |
| Telegram | Token、Chat ID、**测试发送**、**getUpdates 解析 Chat ID** |
| 告警开关 | 各类型 Telegram 通知独立开关 |
| 安全 | 改密码、TOTP 启用/禁用/重绑、API Key 二次验证查看 |
| 登录白名单 | 开关、订阅 URL、手动 IP 列表、解析预览 |

配置三写：安装时 `.env` + `settings` 表 + `web/data/config.php`（PHP 兼容）

---

## 18. 审计日志（audit.html）

- 全站 CUD 与关键操作写入 `audit_logs`
- 过滤：**日期起止**、管理员用户名、操作类型（分组下拉）
- 分页 50 条/页

**未实现**：导出 CSV/JSON（已否决）

---

## 19. 安装向导（install.html）

- 无 `.env` → 安装模式（其他 API 503）
- 步骤：环境 → DB/Redis → 管理员/品牌 → 完成
- 生成密钥、写三处配置、Nginx 模板、cron 提示
- 完成后 install API 锁定（403）

---

## 20. 子机 Agent（web/agent/）

| 能力 | 说明 |
|------|------|
| 心跳 | 60s → `POST /api/agent/heartbeat`；变化>10% 或超阈值加急 |
| 时钟漂移 | `agent_time` vs 中心；warn/crit + Telegram |
| IP 白名单 | `allowed_ips` 限制访问 Agent HTTP |
| 安装 | `install.sh`：python3.12 venv、127.0.0.1:8601 |
| 端点 | `/health`、`/exec*`（中心脚本已改 SSH，子机端点保留） |

---

## 21. 后台任务（仅 Primary Worker）

| 任务 | 间隔 | 文件 |
|------|------|------|
| heartbeat_flush | 10min | Redis → MySQL |
| self_monitor | 30s | Redis/MySQL/WS 自检 |
| schedule_runner | 60s | Cron 调度 |
| retry_runner | 5min | 推送重试 |
| ip_allowlist_refresh | 2h | 订阅 IP 刷新 |
| script_execution_flush | 60s | 执行记录刷盘 |
| asyncssh 清理 | 60s | 空闲 SSH 连接 |

---

## 22. 三层守护

1. Supervisor — 进程崩溃重启  
2. Python self_monitor — 30s，Redis/MySQL 异常 Telegram  
3. Shell `health_monitor.sh` — 1min，连续 3 次 `/health` 失败重启  

---

## 23. 未实现（待开发）

| 功能 | 优先级 |
|------|--------|
| WebSSH 断线重连 | P1 |
| 服务器 CSV 批量导入 | P1 |
| Agent upgrade 与 venv install 对齐 | P1 |
| 仪表盘历史趋势图 | P2 |
| 远程文件上传 / 内容预览 | P2 |
| 宝塔 API 监控增强 | 可选 |
| Agent mTLS | 可选 |

---

## 24. 已否决（不做）

文件编辑器、RBAC、移动端、会话录像、审计导出、邮件报告、Redis Cluster、Docker（当前阶段）

---

## 25. 标准与验收（必查 · 与团队同等严谨）

| 文档 | 路径 |
|------|------|
| **标准转接包（全量）** | [`standards-transfer-package.md`](standards-transfer-package.md) |
| 开发验收 L0～L5 | [`development-acceptance-standard.md`](development-acceptance-standard.md) |
| 系统开发标准 | [`standards/system-development-standard.md`](../../standards/system-development-standard.md) |
| 逐行审计 v2 | [`standards/line-walk-audit-standard-v2.md`](../../standards/line-walk-audit-standard-v2.md) |
| 审计原则 | [`standards/audit-core-principles.md`](../../standards/audit-core-principles.md) |
| Cursor 规则 | `.cursor/rules/*.mdc`（含 `audit-line-review.mdc`） |

**逐行审查**：8 步/文件、Closure 全表、FINDING 必须 `文件:行号`、单回复 ≤5 文件 — **不可降级**。

| 层级 | 说明 |
|------|------|
| L0 | 完美实现 + 全部 mdc + system-development-standard |
| L2 | `pytest` + `local_integration_smoke.sh` |
| L3 | 逐行 DoD（同 standards-transfer-package §2） |
| L4 | 脚本 T-SE、告警策略、T1～T5 |
| L5 | `production-verification-checklist.md` |

---

## 26. 待验证（非功能缺失）

- 首次部署 E2E：`docs/project/production-verification-checklist.md`
- 脚本 T-SE1～8：`docs/project/script-execution.md`
- 本地代码向：`docs/project/local-integration-test.md`