Your Name
b9139093f1
- .env.example: install.php→install.html引用, 添加NEXUS_API_BASE_URL - install.py: 移除_write_env中重复的site_url计算 - CLAUDE.md: 全面更新项目记忆, 反映6步完成+D1/D2/D3解决
119 lines
6.0 KiB
Markdown
119 lines
6.0 KiB
Markdown
# 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)
|
||
```
|