⚡ 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

目录

  1. 全站页面地图
  2. 网络与通道
  3. 认证与访问控制
  4. 仪表盘
  5. 告警中心
  6. 服务器管理
  7. 资产管理
  8. Web SSH
  9. 命令与推送日志
  10. 批量文件推送
  11. 脚本与执行历史
  12. 远程文件管理
  13. 定时调度
  14. 凭据管理
  15. 重试队列
  16. 全局搜索
  17. 系统设置
  18. 审计日志
  19. 安装向导
  20. 3 层守护
  21. 子机 Agent
  22. 后台任务
  23. 开发验收标准
  24. 未实现 / 已否决
🗺 全站页面地图（18 页）
页面路径功能
安装向导/app/install.html无 .env 时安装中心机
登录/app/login.htmlJWT + TOTP + 防暴破
仪表盘/app/index.html统计、WS 刷新统计
服务器/app/servers.htmlCRUD、Agent 安装/升级、漂移徽章
资产管理/app/assets.htmlPlatform / Node
文件管理/app/files.htmlSSH 浏览与文件操作
推送/app/push.htmlrsync 批量 + dry-run
脚本库/app/scripts.html脚本 CRUD、直接执行
执行历史/app/script-executions.html停止/重试/日志
凭据/app/credentials.htmlDB 凭据 + 密码预设
定时调度/app/schedules.htmlCron 推送或脚本
重试队列/app/retries.html推送失败重试
命令日志/app/commands.htmlWebSSH 命令 + 推送日志
告警中心/app/alerts.html告警历史与统计
审计/app/audit.html操作审计、多维过滤
设置/app/settings.html阈值、Telegram、白名单、TOTP
WebSSH/app/terminal.htmlxterm 终端

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

🔌 网络与通道模型
方向端口用途必须
子机 → 中心443 出站Agent 心跳、长任务 curl 回调✅
中心 → 子机22 入站推送、文件、脚本、健康检查、Agent 安装✅
子机本机127.0.0.1:8601Agent 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 分钟指数退避；可手动立即重试或删除。

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

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

注意

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

2 密码预设

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

注意

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

⚙️ 10. 系统设置
1 可配置项
设置项说明是否可改
系统名称 / 标题品牌展示名称✅ 可改
告警阈值（CPU/内存/磁盘）超过阈值触发 Telegram 告警，默认 80%✅ 可改
Redis URLRedis 连接地址✅ 可改
数据库连接池大小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 1SupervisorPython 进程崩溃自动重启
Layer 2Python self_monitor（30s）Redis/MySQL 不可达发 Telegram 告警/恢复
Layer 3Shell 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_flush10minRedis 心跳 → MySQL
self_monitor30sRedis/MySQL/WS 自检 + Telegram
schedule_runner60sCron 调度
retry_runner5min推送重试
ip_allowlist_refresh2h订阅 IP 刷新
script_execution_flush60s执行记录 Redis→MySQL
✅ 标准与验收（与团队同等严谨）

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

类别权威路径
标准转接包docs/project/standards-transfer-package.md
验收 L0～L5development-acceptance-standard.md
系统开发standards/system-development-standard.md
逐行审计 v2standards/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