Files

T

Your Name c9a99f4fb3 fix: 全项目文档对齐 + 代码清理

代码修复:
- web/agent/agent.py: datetime.utcnow() → datetime.now(timezone.utc)
- requirements.txt: 移除 paramiko==3.5.0 (已无活跃引用)
- 删除 server/infrastructure/ssh/pool.py (DEPRECATED, 无引用)

连接池三层对齐 (config.py/.env.example/session.py):
- DB_POOL_SIZE 100→160, DB_MAX_OVERFLOW 100→120
- 基于 MySQL max_connections=400, install.php 公式

文档修复 (21项):
- P0: 硬编码域名/IP替换为配置变量占位符
- P1: 10个过时设计文档加归档标注 (引用旧文件结构)
- P2: step-3-webssh报告 paramiko引用修正
- 6份审查报告连接池参数勘误 100/100→160/120
- ECC安全报告 EC5 datetime.utcnow 标记已修复
- docs/README.md 文档索引重写
- docs/memory/mem_nexus_overview.md 移除硬编码凭证
- docs/project/tech-stack-inventory.md paramiko标记已移除

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-22 08:19:56 +08:00

4.8 KiB

Raw Blame History

Nexus 6.0 — Project Memory

项目概述

Nexus 是一个 2000+ 服务器运维管理平台，从旧的 MultiSync (PHP + AdminLTE + pymysql) 完全重构为 Clean Architecture (FastAPI + Async SQLAlchemy + Redis + WebSocket + Telegram)。

仓库结构

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

Nexus/
├── server/            ← Python FastAPI后端 (Clean Architecture 4层)
├── web/               ← PHP前端 (install.php, config.php, login.php...)
├── deploy/            ← Supervisor配置 + Shell健康检查脚本
├── docs/              ← 部署文档
├── tests/             ← 测试
├── .env               ← NOT IN GIT (install.php生成)
├── .gitignore         ← 排除 .env, SECRETS.md, web/data/config.php
└── requirements.txt   ← Python依赖

已确认的关键决策

决策	选择	原因
API_KEY	❌ 禁改，UI不显示	加密一致性 + 子服务器认证
SECRET_KEY	❌ 禁改	加密回退密钥
DATABASE_URL	❌ 禁改	启动必需
system_name/title	✅ 可改	前端显示
pool_size/overflow	✅ 可改	install自动推荐
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.php安装后	rename→install.php.locked + .env锁定	防重装
配置源	install→config.php(PHP)+settings表(MySQL)+.env(Python)	三方一致
Agent告警心跳	CPU/内存>80% 或变化>10% 时主动上报	智能监控
仓库统一	所有代码统一在Nexus仓库	不再用两个仓库

实现状态 (Phase A+B+C)

✅ 已完成

模块	文件	说明
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
E4 load_settings_from_db	server/config.py	MySQL overrides mutable settings
E5 Python自检	server/background/self_monitor.py	30s loop
E6 Telegram推送	server/infrastructure/telegram/__init__.py	alert/recovery/system
E7 Redis实时状态	server/api/servers.py	frontend reads Redis directly
E8 /health端点	server/api/health.py	Shell health_monitor.sh checks this
E9 lifespan+后台任务	server/main.py	startup: init_db + load_settings + background tasks
D1 Supervisor	deploy/nexus.conf	autorestart nexus process
D2 Shell健康检查	deploy/health_monitor.sh	cron 1min, 3 failures→restart+Telegram
P1 install.php	web/install.php	5步向导 (欢迎→环境→DB+Redis+API→管理员+品牌→完成清单)
P2 config.php	web/config.php	data/config.php + MySQL settings override

🔄 待测试 (Phase D)

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

测试流程 (用户确认)

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

配置三写机制

install.php Step 3 POST处理同时写入：

web/data/config.php — PHP前端配置 (API_BASE_URL, DB_*, API_KEY)
.env — Python后端启动必需 (NEXUS_前缀)
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)

4.8 KiB Raw Blame History Unescape Escape