Nexus/PROJECT_HANDOVER.md

# Nexus 6.0 项目交接文档

> **⚠️ 2026-05-23 起请以 SSOT 为准**: [`AI-HANDOFF`](docs/project/AI-HANDOFF-2026-05-23.md) · **全量标准** [`standards-transfer-package`](docs/project/standards-transfer-package.md) · 验收 [`development-acceptance-standard`](docs/project/development-acceptance-standard.md)  
> 本文保留历史结构；端口模型、待办 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 核心功能 (已完成)
- [x] JWT认证 + TOTP双因素
- [x] 登录防暴破 (15分钟锁定)
- [x] Agent心跳上报 (Redis实时)
- [x] WebSocket实时告警推送
- [x] Telegram告警通知
- [x] 安装向导 (5步)

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

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

### Sync引擎v2 (4种模式)
- [x] S1: 文件同步 (rsync)
- [x] S2: 命令批量执行 (SSH)
- [x] S3: 配置推送 (sysctl) + 去重 + 回滚
- [x] 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文件)
```bash
# 数据库
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. 安装依赖
```bash
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)
```bash
# 复制配置
cp deploy/supervisor/nexus.conf /etc/supervisor/conf.d/
supervisorctl reread
supervisorctl update
supervisorctl start nexus
```

### 4. 验证运行
```bash
# 健康检查
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分钟

---

## 测试验证

### 已完成的测试
```bash
# 模块导入测试 (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更改到主分支