admin/Nexus
1
0
Fork 0
Code Issues Pull Requests Actions 91 Packages Projects Releases Wiki Activity
Files
400dcae781483b8c28e2ce402869ea187bdd4bfb
Nexus/docs/project/nexus-full-site-features.md
T
Your Name cdd0be328a fix: 六轮深度扫描 — 47项Bug修复、安全加固、死代码清理 
Critical runtime bugs:
- terminal.html WebSSH完全不可用（URL前缀/JSON解析/Content-Type三处错误）
- servers.py路由遮蔽：/logs被/{id}拦截，3个前端页面同步日志查询失败
- scripts.html startExecPoll()→startExecPolling()，长任务快速执行崩溃
- agent.py {value!r!s:.50}格式串非法，agent发非数值时ValueError
- alerts.html d.daily.reduce()无null检查，API返回空数据时TypeError

Resource leak / stability:
- websocket.py僵尸连接未关闭TCP，文件描述符泄漏
- websocket.py _last_alert_time字典无限增长（加1小时过期清理）
- asyncssh_pool.py全忙时超过MAX_CONNECTIONS无限增长
- self_monitor.py Telegram告警无冷却，宕机时每30秒刷屏
- schedule_runner.py一次性调度执行超60秒会重复触发
- 限速脚本EXPIRE每次重置窗口可绕过（改用Lua原子脚本）

Security:
- JWT access token加token_version声明，改密码后旧token立失效（零宽限）
- INSTALL_MODE导入时常量→动态函数，安装后JWT认证不再残留禁用
- install.py /lock端点加管理员存在性验证，防止阻断安装
- ServerUpdate schema移除connectivity只读字段，防止伪造连接状态

Frontend fixes:
- doExec()缺r.ok检查、commands.html null检查
- _server_to_dict()补last_checked_at+ssh_key_public
- _field_match()逗号cron表达式修复
- alerts类型显示、SSH会话名称、搜索高亮定位
- 一次性/循环定时任务（run_mode+fire_at+自动禁用）

Dead code removed (400+ lines):
- SyncService batch_push/_push_single等5个方法（零调用者）
- 5个未使用schema（SyncCommands/SyncConfig/SyncSftp/FileDeploy/PaginatedResponse）
- 6个零调用service方法、3个无前端API端点
- 4个未使用import

Schema migrations:
- push_schedules: run_mode + fire_at列，cron_expr改NULL
- servers: 7个新列 + ssh_key_private/public VARCHAR(500)→TEXT

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-05-24 16:26:40 +08:00

11 KiB
Raw Blame History

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

更新: 2026-05-23
读者: 产品、运维、接续开发的 AI
HTML 版: docs/Nexus-功能说明书.html
接续开发: 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
开发验收 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.mdc）

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

层级 说明
L0 完美实现 + 全部 mdc + system-development-standard
L2 pytest + wsl_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
  • WSL 代码向：docs/project/wsl-integration-test.md
Reference in New Issue View Git Blame Copy Permalink