admin/Nexus
1
0
Fork 0
Code Issues Pull Requests Actions 91 Packages Projects Releases Wiki Activity
Files
400dcae781483b8c28e2ce402869ea187bdd4bfb
Nexus/AGENTS.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

10 KiB
Raw Blame History

Nexus 6.0 — Project Memory

项目概述

Nexus 是一个 2000+ 服务器运维管理平台，从旧的 MultiSync (PHP + AdminLTE + pymysql) 完全重构为 Clean Architecture (FastAPI + Async SQLAlchemy + Redis + WebSocket + Telegram)。前端已全面迁移到 Tailwind CSS v4 + Alpine.js，PHP 依赖已移除。

仓库结构

  • 唯一仓库: Nexus (Gitea, 仓库地址在 .env 中配置)
  • 不再使用 multi-server-sync 仓库（旧项目，仅保留历史）
  • 部署路径: 由 NEXUS_DEPLOY_PATH 环境变量决定（安装向导自动写入 .env）
  • 域名/CORS: 由 NEXUS_CORS_ORIGINS 环境变量决定（安装向导自动写入）

目录结构 (仓库根目录)

Nexus/
├── server/            ← Python FastAPI后端 (Clean Architecture 4层)
│   ├── api/           ← API路由 (含 install.py 安装向导API)
│   ├── domain/        ← SQLAlchemy模型 (14张表)
│   ├── infrastructure/← SSH连接池 + Redis + Telegram
│   ├── background/    ← 后台任务 (心跳刷新/自检/调度/重试)
│   └── config.py      ← Pydantic Settings + MySQL覆盖
├── web/app/           ← Tailwind+Alpine.js 纯静态前端 (12个HTML页面)
│   ├── install.html   ← 安装向导 (5步)
│   ├── login.html     ← JWT登录+TOTP双因素
│   └── ...            ← index/servers/files/push/scripts等
├── deploy/            ← Supervisor配置 + Shell健康检查脚本
├── docs/              ← 项目文档
├── tests/             ← 测试
├── .env               ← NOT IN GIT (安装向导生成)
└── requirements.txt   ← Python依赖

启动模式

  • 安装模式 (无 .env): 仅 /api/install/ + 静态文件可用，其他路由返回503
  • 正常模式 (有 .env): 完整初始化 DB/Redis/后台任务

实现原则（强制）

所有设计和实现都必须是完美实现。 详见 .cursor/rules/perfect-implementation.mdc。

禁止 要求
为实现而实现、降级、妥协、技术债（TODO/FIXME 延后） 每一变更达到安全/架构/质量标准
无法完美实现时擅自从权换方案 停下与用户沟通，确认后再换方案
无文档直接开发 设计文档 → 技术文档 → 代码
改代码不写 changelog 每次修改记录到 docs/changelog/YYYY-MM-DD-*.md

文档路径：设计 docs/design/specs/ · 技术 docs/design/plans/ 或 docs/reports/ · 变更 docs/changelog/

AI 接续与标准（切换会话必读）

文档 路径
接续 SSOT docs/project/AI-HANDOFF-2026-05-23.md
标准转接包（全量） docs/project/standards-transfer-package.md
验收 L0～L5 docs/project/development-acceptance-standard.md
系统开发 / 逐行审计 standards/system-development-standard.md、standards/line-walk-audit-standard-v2.md、standards/audit-core-principles.md

逐行审查与开发规范同等强制（8 步、Closure 全表、FINDING 须 文件:行号、单回复 ≤5 文件）。

Cursor 规则与 MCP

  • 规则：.cursor/rules/（perfect-implementation + nexus-* + audit-line-review）
  • Skills：.cursor/skills/（superpowers-zh 20 个，重装：npx superpowers-zh --tool cursor）
  • MySQL MCP：docs/project/mysql-mcp-setup.md · 配置后运行 python scripts/sync_mysql_mcp_env.py

已确认的关键决策

决策 选择 原因
API_KEY ❌ 禁改，UI不显示 加密一致性 + 子服务器认证
SECRET_KEY ❌ 禁改 加密回退密钥
DATABASE_URL ❌ 禁改 启动必需
system_name/title ✅ 可改 前端显示
pool_size/overflow ✅ 可改 安装向导自动推荐
redis_url ✅ 可改 Redis连接
告警阈值 (CPU/mem/disk) ✅ 可改 监控参数 (默认80%)
Telegram配置 ✅ 可改 告警推送
Agent心跳间隔 60s 不太频繁
Redis→MySQL刷新 10min 降低MySQL负载
心跳数据流 Agent→Redis→前端直读→10min→MySQL 前端实时, MySQL只存历史
告警推送 WebSocket→前端 + Telegram 即时感知
Python守护 3层: Supervisor + Python自检(30s) + Shell(cron 1min) 全覆盖
安装向导 install.html + FastAPI API D2: 替代install.php
配置源 安装向导→config.php(PHP兼容)+settings表(MySQL)+.env(Python) 三写一致
Agent告警心跳 CPU/内存>80% 或变化>10% 时主动上报 智能监控
仓库统一 所有代码统一在Nexus仓库 不再用两个仓库

实现状态 (Phase A+B+C+D+E) — ~99% 完成

✅ 已完成 (全部6步 + 技术债务 + UX增强)

模块 文件 说明
Step 0: 基础设施 Redis + WebSocket
E1 WebSocket推送 server/api/websocket.py alert/recovery/system broadcast
E2 心跳→Redis+告警 server/api/agent.py Redis write + threshold detection
E3 Redis→MySQL刷新 server/background/heartbeat_flush.py 10min batch
Step 1: 数据层 14张表
E4 load_settings_from_db server/config.py MySQL overrides mutable settings
Step 2: 认证层 JWT + TOTP
Step 3: Web SSH asyncssh + xterm.js
E5 asyncssh连接池 server/infrastructure/ssh/asyncssh_pool.py 引用计数模式
E6 WebSSH前端 web/app/terminal.html xterm.js + Koko协议 + 自动resize
Step 4: Sync引擎 4种同步模式
Step 5: 前端迁移 Tailwind+Alpine.js
E7 13个前端页面 web/app/*.html 含install.html安装向导
E8 安装向导API server/api/install.py 6端点, 无JWT, 临时引擎
E9 条件启动模式 server/main.py 无.env=安装模式
后台任务
E10 Python自检 server/background/self_monitor.py 30s loop
E11 Telegram推送 server/infrastructure/telegram/__init__.py alert/recovery/system
E12 /health端点 server/api/health.py Shell health_monitor.sh checks this
技术债务
D1 ✅ paramiko删除 — pool.py已删除, 全部迁移asyncssh
D2 ✅ install迁移 server/api/install.py install.php→install.html+API
D3 ✅ WebSSH前端 web/app/terminal.html xterm.js+Koko协议+全屏
安全增强
S1 JWT全局保护 server/api/*.py 所有业务API都有JWT验证
S2 审计日志 server/api/*.py 所有CUD操作记录审计日志
S3 登录防暴破 server/application/services/auth_service.py 失败计数+15min锁定+429状态码
前端UX增强
UX1 共享布局 web/app/layout.js 11页面统一侧边栏+全局搜索+用户信息
UX2 Toast通知 web/app/api.js 全局toast()函数，4种类型
UX3 全局搜索 server/api/search.py 跨服务器/脚本/凭据/调度搜索
UX4 服务器详情 web/app/servers.html 点击展开详情面板(系统信息/同步日志/SSH会话)
UX5 脚本编辑 web/app/scripts.html 点击脚本名编辑+执行结果格式化
UX6 推送增强 web/app/push.html 逐服务器状态+进度条+推送历史
UX7 审计分页 web/app/audit.html 分页控件+操作过滤+每页50条
UX8 重试操作 web/app/retries.html 手动重试+删除按钮+状态过滤
UX9 文件浏览 web/app/files.html 面包屑导航+目录排序+父目录链接
UX10 登录安全 web/app/login.html 密码可见切换+失败计数+429锁定+shake动画
P1功能补全
P1-1 资产管理 web/app/assets.html Platform/Node管理页面
P1-2 服务器表单 web/app/servers.html 补全platform/node/protocols字段
P1-3 Push对接 web/app/push.html + sync_v2.py target_path对接+统一SyncEngineV2
P1-4 安全设置 web/app/settings.html TOTP QR码+修改密码+API Key复制
P1-5 WebSSH授权 server/api/webssh.py SSH凭据验证+4003关闭码+审计
P1-6 Agent认证 server/api/agent.py 每服务器API Key + 全局回退
P1-7 Config去重 server/application/services/sync_engine_v2.py sed去重+备份+_rollback_config()
P2安全增强
P2-1 告警防抖 server/api/websocket.py 5分钟冷却+Telegram去重+恢复重置
P2-2 命令日志 web/app/commands.html 命令/会话双视图+服务器过滤+危险命令高亮
P2-3 DB分页 server/infrastructure/database/server_repo.py DB层offset/limit+count
P2-4 Dashboard实时 web/app/index.html WS触发stats刷新+声音+标签页闪烁
P2-5 移动适配 web/app/layout.js <768px侧边栏overlay+backdrop+表格滚动
P2-6 会话安全 server/api/auth_jwt.py + api.js 8小时超时+JWT updated_at+刷新重用检测
P2-7 凭据加密 server/api/servers.py Server.password/ssh_key_private Fernet加密存储
P2-8 凭据脱敏 server/api/scripts.py + servers.py API响应不返回密码，password_set布尔标记
P2-9 DB备份 deploy/db_backup.sh mysqldump+30天保留+cron集成

🔄 待测试

  • T1: 心跳Redis写入验证
  • T2: WebSocket连接测试
  • T3: 3层守护测试 (kill Python→Supervisor重启)
  • T4: Telegram推送测试
  • T5: install.html 5步流程测试

测试流程 (用户确认)

  1. WSL本地基础测试 → 2. 推到仓库 → 3. 外网服务器正式测试

配置三写机制

安装向导 Step 3 POST处理同时写入：

  1. web/data/config.php — PHP兼容配置 (API_BASE_URL, DB_*, API_KEY)
  2. .env — Python后端启动必需 (NEXUS_前缀)
  3. settings MySQL表 — 共享动态配置 (api_key, thresholds, Telegram等)

不可改项 (SECRET_KEY/API_KEY/ENCRYPTION_KEY/DATABASE_URL) 不在MySQL覆盖映射中。

3层守护机制

  • Layer 1: Supervisor — Python崩溃自动重启
  • Layer 2: Python self_monitor — 每30s检查Redis/MySQL/WebSocket
  • Layer 3: Shell health_monitor.sh — 每分钟HTTP GET /health, 连续3次失败→supervisorctl restart + Telegram

数据流

Agent心跳(60s) → Redis(实时) → 前端直读 → 10min批量 → MySQL(历史)
告警: CPU/mem/disk > threshold → WebSocket推送浏览器 + Telegram推送手机
恢复: 之前告警的指标恢复正常 → 自动推送恢复通知
Redis心跳key: heartbeat:{server_id} (HSET, TTL=600s)
Redis告警key: alerts:{server_id} (SET, TTL=3600s)
Reference in New Issue View Git Blame Copy Permalink