Nexus/PROJECT_HANDOVER.md

Nexus 6.0 项目交接文档

⚠️ 2026-05-23 起请以 SSOT 为准: AI-HANDOFF · 全量标准 standards-transfer-package · 验收 development-acceptance-standard
本文保留历史结构；端口模型、待办 backlog、验证清单、否决项均以 SSOT 为准。

项目概述

项目名称: Nexus 6.0
类型: 2000+ 服务器运维管理平台
架构: Clean Architecture (FastAPI + Async SQLAlchemy + Redis + WebSocket + Telegram)
前端: Tailwind CSS v4 + Alpine.js（18 个 HTML 页面，含 alerts.html）
状态: 核心代码 ~98% 完成；尚未部署；待办见 SSOT §4、验证见 SSOT §5

---

仓库信息

• 仓库地址: Gitea (地址在 .env 中配置)
• 当前工作目录: C:\Users\uzuma\Desktop\svn\Nexus\.claude\worktrees\suspicious-williams-fe9492
• Git分支: 当前在 worktree 分支

---

技术栈

层级	技术
后端框架	FastAPI (Python 3.9+)
数据库	MySQL 8.0 + Async SQLAlchemy 2.0
缓存	Redis
实时通信	WebSocket
SSH连接	asyncssh (连接池模式)
告警推送	Telegram Bot API
前端	Tailwind CSS v4 + Alpine.js
进程守护	Supervisor + Python自检 + Shell健康检查

---

目录结构

Nexus/
├── server/                    # Python FastAPI 后端
│   ├── api/                   # API路由层 (15个模块)
│   │   ├── agent.py          # Agent心跳接收
│   │   ├── assets.py         # Platform/Node资产管理
│   │   ├── auth.py           # JWT登录/TOTP
│   │   ├── auth_jwt.py       # JWT验证中间件
│   │   ├── files.py          # 文件浏览
│   │   ├── install.py        # 安装向导API
│   │   ├── push.py           # 推送调度
│   │   ├── scripts.py        # 脚本库管理
│   │   ├── servers.py        # 服务器CRUD
│   │   ├── settings.py       # 系统设置
│   │   ├── sync_v2.py        # 同步引擎v2 (4种模式)
│   │   ├── webssh.py         # WebSSH终端
│   │   └── websocket.py      # WebSocket告警推送
│   ├── application/           # 应用服务层
│   │   └── services/         # 业务逻辑 (SyncEngineV2等)
│   ├── domain/                # 领域层
│   │   └── models/           # SQLAlchemy ORM (14张表)
│   ├── infrastructure/        # 基础设施层
│   │   ├── database/         # 数据库访问 (Repository模式)
│   │   ├── redis/            # Redis客户端
│   │   ├── ssh/              # SSH连接池 (asyncssh)
│   │   └── telegram/         # Telegram推送
│   ├── background/            # 后台任务
│   │   ├── self_monitor.py   # Python自检 (30s)
│   │   ├── heartbeat_flush.py  # Redis→MySQL刷新 (10min)
│   │   ├── scheduler.py      # 定时推送调度
│   │   └── retry_worker.py   # 失败重试队列
│   └── config.py             # Pydantic Settings
├── web/app/                   # 前端页面 (15个HTML)
│   ├── install.html          # 安装向导 (5步)
│   ├── login.html            # JWT登录+TOTP
│   ├── index.html            # 仪表盘
│   ├── servers.html          # 服务器管理
│   ├── assets.html           # Platform/Node管理
│   ├── push.html             # 文件推送
│   ├── scripts.html          # 脚本库
│   ├── commands.html         # 命令日志查询
│   ├── files.html            # 远程文件浏览
│   ├── settings.html         # 系统设置
│   ├── audit.html            # 审计日志
│   ├── retries.html          # 重试队列
│   ├── terminal.html         # WebSSH终端
│   ├── api.js                # 共享API模块 (JWT+Toast)
│   └── layout.js             # 共享布局组件
├── deploy/                    # 部署配置
│   ├── supervisor/           # Supervisor配置
│   ├── nginx/                # Nginx配置
│   └── db_backup.sh          # 数据库备份脚本
├── docs/                      # 项目文档
├── requirements.txt          # Python依赖
└── test_p1_p2.py             # 验证测试脚本

---

数据库模型 (14张表)

表名	说明
admins	管理员用户 (JWT+TOTP支持)
servers	服务器资产 (核心表)
platforms	平台类型模板
nodes	资产节点树
sync_logs	同步操作日志
push_schedules	定时推送调度
push_retry_jobs	失败重试队列
audit_logs	审计日志
scripts	脚本库
script_executions	脚本执行记录
password_presets	SSH密码预设
db_credentials	数据库凭据
ssh_sessions	WebSSH会话
command_logs	SSH命令日志
login_attempts	登录防暴破记录
settings	系统配置键值对

---

核心功能清单

P0 核心功能 (已完成)

• JWT认证 + TOTP双因素
• 登录防暴破 (15分钟锁定)
• Agent心跳上报 (Redis实时)
• WebSocket实时告警推送
• Telegram告警通知
• 安装向导 (5步)

P1 功能 (已完成)

• Platform/Node资产管理
• 服务器详情面板 (点击展开)
• WebSSH终端 (xterm.js)
• 推送页面增强 (逐服务器状态+进度条)
• 脚本编辑+执行结果格式化
• 全局Toast通知系统
• 审计日志分页+过滤
• 重试队列手动操作
• 文件浏览 (面包屑导航)

P2 功能 (已完成)

• 告警聚合防抖 (5分钟冷却)
• 命令日志查询页面
• 服务器列表DB级分页
• Dashboard WebSocket实时刷新
• 移动端响应式适配
• 会话安全加固 (8小时超时)
• 服务器凭据Fernet加密存储
• 凭据API脱敏 (password_set标记)
• 数据库自动备份脚本

Sync引擎v2 (4种模式)

• S1: 文件同步 (rsync)
• S2: 命令批量执行 (SSH)
• S3: 配置推送 (sysctl) + 去重 + 回滚
• S4: SFTP文件传输

---

关键Bug修复记录

任务ID	问题	修复内容
#81	DateTime默认求值BUG	添加_utcnow()可调用函数，替换所有default=datetime.now()
#82	session.py logger未定义	添加import logging和logger定义，移除@property死代码
#83	审计日志缺失	验证所有CUD端点都有审计记录
#84	模型缺失索引	添加7个索引(login_attempts, audit_logs等)

---

环境配置

必需环境变量 (.env文件)

# 数据库
DATABASE_URL=mysql+aiomysql://user:pass@localhost/nexus

# 安全密钥 (安装时生成)
SECRET_KEY=xxx
API_KEY=xxx
ENCRYPTION_KEY=xxx

# Redis
REDIS_URL=redis://localhost:6379/0

# Telegram告警 (可选)
TELEGRAM_BOT_TOKEN=xxx
TELEGRAM_CHAT_ID=xxx

# 告警阈值
CPU_ALERT_THRESHOLD=80
MEM_ALERT_THRESHOLD=80
DISK_ALERT_THRESHOLD=80

启动模式

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

---

部署步骤

1. 安装依赖

pip install -r requirements.txt

2. 运行安装向导

访问 http://localhost:8000/app/install.html

• Step 1: 数据库配置
• Step 2: Redis配置
• Step 3: 安全密钥生成
• Step 4: Telegram配置 (可选)
• Step 5: 创建管理员账号

3. 启动服务 (Supervisor)

# 复制配置
cp deploy/supervisor/nexus.conf /etc/supervisor/conf.d/
supervisorctl reread
supervisorctl update
supervisorctl start nexus

4. 验证运行

# 健康检查
curl http://localhost:8000/health

# 运行测试
python test_p1_p2.py

---

团队分工建议

角色	职责	相关文件
后端开发	API开发、业务逻辑	server/api/*.py, server/application/services/*.py
前端开发	UI页面、交互逻辑	web/app/*.html, web/app/api.js, web/app/layout.js
DevOps	部署、监控、备份	deploy/, supervisor/, nginx/
DBA	数据库优化、迁移	server/domain/models/, server/infrastructure/database/
安全	审计、加密、认证	server/api/auth*.py, 凭据加密逻辑

---

监控与告警

3层守护机制

1. Supervisor: Python崩溃自动重启
2. Python自检 (self_monitor.py): 30秒检查Redis/MySQL/WebSocket
3. Shell健康检查 (health_monitor.sh): 1分钟HTTP检查，3次失败重启

告警通道

• WebSocket → 前端实时通知
• Telegram → 手机推送

关键指标

• Agent心跳间隔: 60秒
• Redis→MySQL刷新: 10分钟
• 会话超时: 8小时
• 告警冷却: 5分钟

---

测试验证

已完成的测试

# 模块导入测试 (19/19通过)
python -c "import server.domain.models; ..."

# 功能测试 (7/7通过)
python test_p1_p2.py
# - JWT updated_at claim
# - JWT password invalidation
# - Alert dedup cooldown
# - Server repo pagination
# - Config dedup command
# - Server dict no password
# - Admin.updated_at field

---

注意事项

⚠️ 安全相关

1. API_KEY: 禁止修改，用于Agent认证
2. SECRET_KEY: 禁止修改，用于JWT签名
3. ENCRYPTION_KEY: 禁止修改，用于凭据加密
4. 生产环境必须修改默认密码

⚠️ 数据库迁移

首次启动会自动执行 _apply_migrations():

• 添加 admins.updated_at 列
• 创建7个索引 (如果不存在)

⚠️ 文件权限

• SSH私钥文件需要正确权限 (600)
• 日志目录需要写权限

---

联系方式

• 项目文档: docs/
• 配置文件: .env (不提交到Git)
• 测试脚本: test_p1_p2.py

---

交接日期: 2026/05/22
代码状态: ✅ 开发完成，待部署测试
Git提交: 建议提交当前worktree更改到主分支