Your Name
cdd0be328a
Critical runtime bugs:
- terminal.html WebSSH完全不可用（URL前缀/JSON解析/Content-Type三处错误）
- servers.py路由遮蔽：/logs被/{id}拦截，3个前端页面同步日志查询失败
- scripts.html startExecPoll()→startExecPolling()，长任务快速执行崩溃
- agent.py {value!r!s:.50}格式串非法，agent发非数值时ValueError
- alerts.html d.daily.reduce()无null检查，API返回空数据时TypeError
Resource leak / stability:
- websocket.py僵尸连接未关闭TCP，文件描述符泄漏
- websocket.py _last_alert_time字典无限增长（加1小时过期清理）
- asyncssh_pool.py全忙时超过MAX_CONNECTIONS无限增长
- self_monitor.py Telegram告警无冷却，宕机时每30秒刷屏
- schedule_runner.py一次性调度执行超60秒会重复触发
- 限速脚本EXPIRE每次重置窗口可绕过（改用Lua原子脚本）
Security:
- JWT access token加token_version声明，改密码后旧token立失效（零宽限）
- INSTALL_MODE导入时常量→动态函数，安装后JWT认证不再残留禁用
- install.py /lock端点加管理员存在性验证，防止阻断安装
- ServerUpdate schema移除connectivity只读字段，防止伪造连接状态
Frontend fixes:
- doExec()缺r.ok检查、commands.html null检查
- _server_to_dict()补last_checked_at+ssh_key_public
- _field_match()逗号cron表达式修复
- alerts类型显示、SSH会话名称、搜索高亮定位
- 一次性/循环定时任务（run_mode+fire_at+自动禁用）
Dead code removed (400+ lines):
- SyncService batch_push/_push_single等5个方法（零调用者）
- 5个未使用schema（SyncCommands/SyncConfig/SyncSftp/FileDeploy/PaginatedResponse）
- 6个零调用service方法、3个无前端API端点
- 4个未使用import
Schema migrations:
- push_schedules: run_mode + fire_at列，cron_expr改NULL
- servers: 7个新列 + ssh_key_private/public VARCHAR(500)→TEXT
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
321 lines
10 KiB
Markdown
321 lines
10 KiB
Markdown
# 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更改到主分支
|