Nexus/CLAUDE.md

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/后台任务

已确认的关键决策

决策	选择	原因
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) — ~95% 完成

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

模块	文件	说明
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 12个前端页面	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协议+全屏
D4 文件编辑器	—	低优先级, Monaco/ACE

🔄 待测试

• 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)