# ⚡ Nexus 6.0

服务器运维管理平台 — 全站功能说明书 · 2026-05-23

Markdown 维护版：`docs/project/nexus-full-site-features.md` · AI 接续：`docs/project/AI-HANDOFF-2026-05-23.md`

FastAPI SQLAlchemy 2.0 Redis 7 asyncssh Tailwind v4 2000+ 服务器 JWT + TOTP
🗺 全站页面地图（18 页）

页面 | 路径 | 功能
--- | --- | ---
安装向导 | `/app/install.html` | 无 .env 时安装中心机
登录 | `/app/login.html` | JWT + TOTP + 防暴破
仪表盘 | `/app/index.html` | 统计、WS 刷新统计
服务器 | `/app/servers.html` | CRUD、Agent 安装/升级、漂移徽章
资产管理 | `/app/assets.html` | Platform / Node
文件管理 | `/app/files.html` | SSH 浏览与文件操作
推送 | `/app/push.html` | rsync 批量 + dry-run
脚本库 | `/app/scripts.html` | 脚本 CRUD、直接执行
执行历史 | `/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
WebSSH | `/app/terminal.html` | xterm 终端

共享：`layout.js`（侧栏/移动适配）、`api.js`（JWT、toast、全局搜索）

🔌 网络与通道模型

方向 | 端口 | 用途 | 必须
--- | --- | --- | ---
子机 → 中心 | 443 出站 | Agent 心跳、长任务 curl 回调 | ✅
中心 → 子机 | 22 入站 | 推送、文件、脚本、健康检查、Agent 安装 | ✅
子机本机 | `127.0.0.1:8601` | Agent HTTP（可不暴露公网） | 可选

说明

脚本执行与手动健康检查已改走 SSH，不依赖公网 8601。宝塔环境请用系统 Python 3.12 + `install.sh` venv，勿用面板 Python 项目管理器托管 Agent。

🔒 1. 认证与访问控制
1 JWT 登录 + 自动刷新

管理员通过用户名+密码登录，获取 Access Token（30 分钟）和 Refresh Token（7 天）。前端到期前 2 分钟自动换新 Token，无感续期。

使用说明

- 访问 `/app/login.html`，输入管理员账号密码
- Token 存于 `localStorage`，关闭浏览器后 7 天内免登录
- 8 小时无操作自动退出

缺点 / 注意

- JWT 存于 localStorage，XSS 漏洞可能导致 Token 泄露（已做 CSP 缓解）
- 无 RBAC：只有一个管理员角色，鉴权即信任
- 不支持多管理员角色区分

2 TOTP 双因素认证

可选启用 Google Authenticator 兼容的 TOTP。登录时先验密码，再验 6 位动态码（30 秒窗口）。

使用说明

- 进入「设置」→「安全设置」→ 启用 / 重新绑定 TOTP，扫描二维码
- 禁用 TOTP 需同时提供当前密码 + TOTP 码

缺点 / 注意

- TOTP 秘钥丢失无法恢复，需提前备份
- 系统时间偏差 >30s 会导致验证失败（接受 ±1 窗口共 90s）

3 登录防暴破

同一 IP + 用户名 15 分钟内失败 5 次，账号自动锁定并返回 HTTP 429。

注意

锁定基于 IP + 用户名组合，更换 IP 可绕过。适合防自动化爆破，不防分布式攻击。

4 登录 IP 白名单

可在设置中开启「仅允许白名单 IP 登录」。支持手动 IP/CIDR，以及从代理订阅 URL解析节点 IP（每 2 小时自动刷新，与手动列表合并）。

使用说明

- 「设置」→「登录 IP 白名单」→ 总开关 + 订阅地址 + 手动 IP
- 非白名单 IP 登录被拒绝并记审计

📊 2. 仪表盘与实时告警
1 实时统计面板

首页展示服务器总数、在线数、离线数、告警中台数、最近推送记录。数据来源 Redis（实时）+ MySQL（历史），通过 WebSocket 触发刷新。

使用说明

- 在线状态取自 Redis `heartbeat:{id}`，子机 60s 上报一次
- 告警计数 = Redis `alerts:*` key 数量
- WS 断线会自动重连（3 次指数退避）

缺点 / 注意

- 在线状态最多滞后 60s（子机心跳间隔）
- Redis 不可用时统计退化为 MySQL 数据，可能不准

2 告警通知（Telegram）

CPU / 内存 / 磁盘超过阈值（默认 80%）时，通过 Telegram Bot 推送告警；恢复后发送恢复通知。同服务器同指标 5 分钟内不重复推送。

使用说明

- 「设置」配置 `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID`
- 阈值可在设置页调整（CPU/内存/磁盘各独立）
- 浏览器仪表盘只显示计数，不弹窗、不响铃（设计决策）

缺点 / 注意

- 浏览器仪表盘不弹告警列表；历史见「告警中心」页
- Telegram Bot 被封或网络不通时告警静默失败（有日志）
- 告警防抖 key 存于进程内存，重启后防抖状态重置

🔔 告警中心
1 告警历史（alerts.html）

将 CPU/内存/磁盘告警与恢复事件持久化到 `alert_logs`，支持分页、按服务器/类型/日期筛选，以及近 7 日统计图表数据。

使用说明

- 侧栏「告警中心」查看历史列表
- API：`GET /api/alert-history/`、`GET /api/alert-history/stats`

2 分项 Telegram 开关

设置页可单独关闭某类告警的 Telegram 推送（告警/恢复/系统/时钟漂移等），便于后续扩展通道。

🖥 3. 服务器管理
1 服务器 CRUD

增删改查服务器配置，支持 SSH 密钥 / 密码双认证，可按平台类型（Platform）和节点（Node 树）分组。

使用说明

- 新增服务器：填写名称、域名/IP、SSH 端口、认证方式
- 认证方式选「密钥」时粘贴私钥内容，自动 Fernet 加密存储
- 支持 `platform_id` / `node_id` 分组归类
- 服务器列表分页显示（默认 50 条/页）

缺点 / 注意

- 批量导入（CSV）未实现，2000 台需逐一或通过 API 批量添加
- 删除服务器同时删除关联推送日志（CASCADE）

2 健康检查

手动触发 `POST /api/servers/check`：经 SSH 执行 Python 采集 CPU/内存/磁盘（`remote_probe`），不需要公网 8601。

与在线状态区别

列表「在线」主要来自 Agent 443 心跳；健康检查用于即时 SSH 探活与指标快照。

4 Agent 安装与升级

服务器详情「Agent 安装」：复制 `install.sh` 命令或一键 SSH 安装（带日志）；安装后轮询在线。升级通过 SSH 拉取最新 `agent.py` 并 restart。

注意

- 安装脚本：Python 3.12 venv、监听 `127.0.0.1:8601`，无需公网放行 8601
- 时钟漂移：心跳带 `agent_time`，列表显示 warn/crit 徽章

3 每服务器 API Key

为每台服务器单独生成 Agent API Key（格式 `nxs-xxx`），用于该服务器子机与中心通信的专属认证。

使用说明

- 服务器详情 → 「生成 Agent Key」，完整 Key 仅本次显示，立即复制到子机 `config.json`
- 列表页只显示前 8 位用于识别

注意

- Key 生成后无法再次查看（一次性展示设计）
- 丢失需重新生成并更新子机配置

🗂 资产管理
1 Platform 与 Node

`assets.html` 管理资产类型模板（Platform）与树形节点（Node），服务器表单可关联分组。

API：`/api/assets/platforms`、`/api/assets/nodes`（含 tree）

2 SSH 会话与命令（只读查询）

同页或「命令日志」可查询 `ssh_sessions`、`command_logs`（WebSSH 产生）。

💻 4. Web SSH 终端
1 浏览器终端

基于 xterm.js + asyncssh，在浏览器内打开远程服务器 SSH 会话，支持全屏、自动 resize、彩色输出。

使用说明

- 服务器列表点击「终端」→ 弹出 `/app/terminal.html?server_id=X`
- 认证：先获取短效 webssh-token（15 分钟），绑定到该服务器，再建 WebSocket
- 支持窗口 resize 自动通知远程 shell

缺点 / 注意

- Token 通过 URL 参数传递（?token=...），HTTPS 下安全；HTTP 下有风险
- 不支持文件上传 / 拖拽（需用文件管理页）
- 会话不录像（已明确否决）
- 网络中断 WebSocket 不会自动重连，需刷新页面

💻 命令与推送日志
1 WebSSH 会话与命令

`commands.html`：会话列表、命令列表（危险命令高亮）、按服务器过滤。数据来自 WebSSH，直接 SSH 不记录。

2 推送日志

同页「推送日志」Tab：rsync 批量推送历史，支持服务器/状态/同步模式/触发方式过滤与分页。

📤 5. 批量文件推送
1 rsync 批量推送

将源目录通过 rsync-over-SSH 推送到选定的服务器列表，支持 4 种同步模式，内置分批（50 台/批）并发（10 路）控制。

同步模式 | rsync 参数 | 适用场景
--- | --- | ---
增量同步 | `-az` | 日常更新，只同步有变动的文件
全量同步 | `-az --delete` | 强制目标与源完全一致，会删除目标多余文件
校验和 | `-az --checksum` | 按文件内容而非时间戳判断差异
直接覆盖 | `-az --inplace` | 不用临时文件，直接覆盖（大文件节省空间）

缺点 / 注意

- 全量同步（--delete）会不可逆删除目标目录多余文件，务必先「预览」
- rsync 在中心机运行，中心机需能 SSH 到所有子机
- 失败的服务器自动加入重试队列（指数退避，最多 100 次）

2 推送前预览（dry-run）

选中全量/覆盖模式时，页面显示橙色警告，引导先对首台服务器运行 `rsync --dry-run --stats`，查看待传输/删除文件数量后再决定是否推送。

使用说明

- 选择「全量同步」→ 出现橙色预览按钮 → 点击 → 展示首台服务器变动摘要
- 可展开「详细文件列表」（最多 200 行）
- 预览不阻塞推送，看完数据自行决定是否点「开始推送」

注意

- 仅预览第一台选中的服务器，其余服务器可能略有差异
- 预览需 SSH 连通，与真实推送消耗相同时间（通常 <5s）

3 失败自动重试队列

推送失败的服务器自动进入 `push_retry_jobs` 队列，后台每 5 分钟按指数退避重试（60s → 120s → 240s...，最大 64 分钟）。

注意

最多重试 100 次。可在「重试」页手动强制立即重试或删除任务。

📜 脚本与执行历史
1 脚本库管理

维护可复用 Shell 脚本库（按 ops/deploy/check/cleanup 分类），一键下发到选定的服务器。

使用说明

- 「脚本」页 → 新建脚本 → 填写名称/类别/内容
- 点击脚本名 → 编辑；点击「执行」→ 选择服务器 → 运行
- 支持直接输入临时命令（无需保存到库）

2 批量执行（短任务 / 长任务）

短任务：同步等待结果（默认 30s 超时）。长任务：nohup 后台运行，完成后 curl 回调中心记录结果。

使用说明

- 选择服务器 → 填写命令 → 「执行」
- 执行走 SSH 22（结果含 `channel: ssh`），无需子机公网 8601
- 长任务：nohup + 子机 curl 回调中心（需 HTTPS `NEXUS_API_BASE_URL`）
- 「执行历史」页：停止 / 重试 / 标记卡住 / 拉取 nexus-job 日志

缺点 / 注意

- `rm -rf /` 等危险命令被中心拦截（400），但仅匹配预设规则
- 长任务依赖子机能访问中心 `NEXUS_API_BASE_URL`（必须配置且使用 HTTPS）
- 执行历史默认保留 2 小时 Redis 热数据，60s 刷入 MySQL
- 执行命令时密码等敏感 $DB_* 变量存储时已脱敏（替换为 ***）

3 $DB_* 数据库凭据替换

脚本中使用 `$DB_USER` / `$DB_PASS` / `$DB_HOST` / `$DB_PORT` / `$DB_NAME` 占位符，执行时自动替换为选定的数据库凭据，密码不出现在脚本文本或日志中。

注意

替换在中心机完成后发往子机，子机接收到的已是明文命令；传输通过 HTTPS，子机侧无加密保护。

📁 7. 远程文件管理
1 目录浏览

通过 SSH exec（`ls -la`）浏览指定服务器的远程目录，支持面包屑导航和目录点击进入。

使用说明

- 「文件管理」→ 选服务器 → 输入路径 → 「浏览」（或按 Enter）
- 点击目录名进入子目录，点击「..」返回上级
- 文件按 目录优先 / 字母顺序 排列

缺点 / 注意

- 无左侧树状面板（每次需手动导航）
- 显示的文件大小为 `ls` 输出的字节数，大文件不友好

2 文件操作（删除/重命名/新建目录）

鼠标悬停文件/目录行显示操作按钮，通过 SSH exec 在远程执行操作。

操作 | 命令 | 触发方式
--- | --- | ---
删除文件 | `rm -f path` | 悬停 → 🗑 → confirm 弹窗
删除目录 | `rm -rf path` | 悬停 → 🗑 → 额外警告弹窗
重命名 | `mv src dst` | 悬停 → ✏ → prompt 输入新名
新建目录 | `mkdir -p path` | 右上角 📁+ → prompt 输入名

缺点 / 注意

- 删除目录（rm -rf）不可恢复，浏览器弹窗确认无法替代真正的安全保障
- 无文件编辑器（已明确否决，用 WebSSH vim/nano 代替）
- 无文件上传功能（可用 SFTP API 或 WebSSH scp）
- 无文件内容预览

⏰ 8. 定时调度
1 Cron 调度（推送 + 脚本）

支持两种 `schedule_type`：文件推送 或 脚本执行。5 字段 Cron，后台每 60s 检查（仅 Primary Worker）。

使用说明

- 「定时」→ 选类型 → 填 Cron、目标服务器
- 脚本型：选脚本库 ID 或内联内容，可设超时与长任务
- 示例：`0 2 * * *` = 每天凌晨 2 点

注意

- Cron 精度受 60s 检查间隔限制
- 脚本调度同样走 SSH 执行通道

🔄 重试队列

`retries.html` 管理推送失败任务：`retry_runner` 每 5 分钟指数退避；可手动立即重试或删除。

🔍 全局搜索

侧栏搜索框调用 `GET /api/search/`，跨服务器、脚本、凭据、定时任务关键字匹配。

🔑 9. 凭据管理
1 数据库凭据

存储 MySQL/PostgreSQL 连接信息，密码 Fernet 加密，API 响应不含密码（仅元数据）。供脚本执行时通过 $DB_* 变量引用。

注意

凭据只加密存储，子机接收到的命令已含明文连接信息（仅在中心→子机的 HTTPS 传输中受保护）。

2 密码预设

存储 SSH 密码模板（Fernet 加密），可在推送配置中引用，避免重复输入常用密码。

注意

密码预设不能用于脚本 $DB_PASS 替换，只用于推送密码模板。

⚙️ 10. 系统设置
1 可配置项

设置项 | 说明 | 是否可改
--- | --- | ---
系统名称 / 标题 | 品牌展示名称 | ✅ 可改
告警阈值（CPU/内存/磁盘） | 超过阈值触发 Telegram 告警，默认 80% | ✅ 可改
Redis URL | Redis 连接地址 | ✅ 可改
数据库连接池大小 | pool_size / max_overflow | ✅ 可改
Telegram Bot Token / Chat ID | 告警推送配置 | ✅ 可改
SECRET_KEY / API_KEY / ENCRYPTION_KEY | 核心安全密钥 | ❌ 不可改（需改 .env 重启）
DATABASE_URL | 数据库连接 | ❌ 不可改

2 Telegram

配置 Bot Token / Chat ID；测试发送；通过 getUpdates 检测 Chat ID；各告警类型独立开关。

3 TOTP 与 API Key

TOTP 启用/禁用/重新绑定；全局 API Key 需密码二次验证后查看（记审计）。

4 登录 IP 白名单

总开关、订阅 URL（2h 刷新）、手动 IP、解析预览（见「认证」章节）。

📋 11. 审计日志
1 操作审计

所有 CUD 操作（创建/更新/删除服务器、推送、执行脚本、登录、改密码等）自动写入 `audit_logs`，记录操作人、IP、目标、详情。

使用说明

- 「审计」页：日期起止、管理员用户名、操作类型（分组下拉）
- 每页 50 条分页

缺点 / 注意

- 无日志导出（已否决 CSV/JSON）
- 审计日志不会自动清理，长期需归档

🚀 12. 安装向导
1 5 步安装向导

无 `.env` 文件时系统进入安装模式，访问 `/app/install.html` 完成 5 步配置：欢迎 → 数据库 → Redis → 管理员账号 → 完成。自动生成 API Key / Secret Key / Encryption Key。

使用说明

- 安装完成后 `.env` 自动生成，安装 API 除 GET /status 外全部锁定（返回 403）
- 重装需手动删除 `.env` 并重启

注意

- 安装过程未验证数据库/Redis 连接成功才允许进入下一步（应在步骤中手动验证）
- 安装模式下除 install API 和静态文件外，其余 API 返回 503

🛡 13. 三层守护机制
1 三层守护

层级 | 机制 | 触发条件 | 动作
--- | --- | --- | ---
Layer 1 | Supervisor | Python 进程崩溃 | 自动重启
Layer 2 | Python self_monitor（30s） | Redis/MySQL 不可达 | 发 Telegram 告警/恢复
Layer 3 | Shell cron（1 分钟） | 连续 3 次 /health 失败 | supervisorctl restart + Telegram

注意

Shell cron 依赖宝塔/系统 crontab 配置，部署时需手动添加定时任务。

🤖 14. 子机 Agent
1 Agent 功能

部署在每台被管服务器上的轻量服务：心跳走 443 出站；HTTP 仅本机 `127.0.0.1:8601`。中心侧脚本已改 SSH，/exec 端点保留供兼容。

能力 | 说明
--- | ---
心跳 | POST 中心 `/api/agent/heartbeat`，写 Redis，智能加急
时钟漂移 | `agent_time` 与中心比对，warn/crit + Telegram
IP 白名单 | `allowed_ips` 限制访问本机 Agent HTTP
长任务回调 | POST `/api/agent/script-callback`
安装 | `web/agent/install.sh` — python3.12 venv + systemd

注意

- 升级 API 存在，建议与 venv 安装脚本对齐后使用
- 长任务回调需子机出站访问中心 HTTPS

⚙ 后台任务（Primary Worker）

任务 | 间隔 | 说明
--- | --- | ---
heartbeat_flush | 10min | Redis 心跳 → MySQL
self_monitor | 30s | Redis/MySQL/WS 自检 + Telegram
schedule_runner | 60s | Cron 调度
retry_runner | 5min | 推送重试
ip_allowlist_refresh | 2h | 订阅 IP 刷新
script_execution_flush | 60s | 执行记录 Redis→MySQL

✅ 标准与验收（与团队同等严谨）

全量标准转接：`docs/project/standards-transfer-package.md` — 含 Cursor 规则、`standards/` 三件套、逐行八步 DoD、设计/上线清单。下一任 AI 不得降低执行力度。

类别 | 权威路径
--- | ---
标准转接包 | `docs/project/standards-transfer-package.md`
验收 L0～L5 | `development-acceptance-standard.md`
系统开发 | `standards/system-development-standard.md`
逐行审计 v2 | `standards/line-walk-audit-standard-v2.md`
审计原则 | `standards/audit-core-principles.md`
Cursor | `.cursor/rules/*.mdc`（含 audit-line-review）

逐行审查：8 步/文件、Closure 全表含 SAFE、FINDING 必须 `文件:行号`、单回复 ≤5 文件。AI 接续：HANDOFF + 全站功能 + 标准转接包。

🚫 15. 未实现 / 已否决功能

功能 | 状态 | 原因 / 替代方案
--- | --- | ---
文件编辑器（Monaco/ACE） | 已否决 | 运维场景用 WebSSH + vim/nano；嵌入编辑器增加复杂度无实质收益
会话录像（asciicast） | 已否决 | 命令日志已满足审计需求
RBAC 权限体系 | 已否决 | 鉴权即信任，单管理员模型；增加 RBAC 代价远超收益
移动端适配 | 已否决 | 2000 台服务器运维不会用手机操作
批量服务器导入（CSV） | 未实现 | 可通过 API 批量 POST /api/servers/ 实现
文件上传到远程服务器 | 未实现 | 可用 WebSSH scp / 推送功能代替
文件内容预览 | 未实现 | 可通过 WebSSH cat 查看
WebSSH 断线自动重连 | 未实现 | 当前需刷新页面；计划自动重试+按钮
仪表盘历史趋势图 | 未实现 | 仅实时 Redis 指标
宝塔 API 监控集成 | 未实现 | 可选；参考 btpanel-skills
Agent mTLS | 讨论中 | 未实现
首次部署 E2E（T1～T5、T-SE） | 待验证 | 见 production-verification-checklist.md