Codex Release Bot
224 lines
8.6 KiB
Markdown
224 lines
8.6 KiB
Markdown
# Nexus 项目建议书
|
||
|
||
> 更新: 2026-05-22
|
||
|
||
---
|
||
|
||
## 一、项目现状
|
||
|
||
### 运行状态
|
||
|
||
```
|
||
技术栈: Python 3.12 / FastAPI / MySQL 8.4 / Redis 7 / Nginx
|
||
后端: Clean Architecture 4层 (domain → infrastructure → application → api)
|
||
前端: Tailwind CSS v4 + Alpine.js (纯静态 HTML，JWT 认证)
|
||
数据库: 14 张表 (servers, admins, platforms, nodes, command_logs, ssh_sessions 等)
|
||
核心功能: rsync 文件推送 + WebSocket 实时告警 + asyncssh 连接池 + Telegram 推送
|
||
守护机制: 3层 (Supervisor + Python self_monitor 30s + Shell cron 1min)
|
||
```
|
||
|
||
### 数据库现有表（14 张）
|
||
|
||
```
|
||
核心表:
|
||
servers (扩展) id, name, domain, port, username, auth_method,
|
||
password(加密), ssh_key_*(3), agent_port, agent_api_key,
|
||
category, is_online, system_info, last_heartbeat,
|
||
platform_id, node_id, protocols(JSON), extra_attrs(JSON),
|
||
connectivity, last_checked_at
|
||
|
||
platforms 资产类型模板: name, category, type, default_protocols(JSON)
|
||
nodes 树形分组: name, parent_id, sort_order
|
||
admins 认证: username, password_hash, totp_secret, totp_enabled,
|
||
jwt_refresh_token, jwt_token_expires
|
||
|
||
settings 配置: key → value
|
||
|
||
业务表:
|
||
sync_logs 推送日志: server_id, source/target_path, status, files_*
|
||
push_schedules 定时推送: cron_expr, server_ids(JSON)
|
||
push_retry_jobs 重试队列: retry_count, max_retries
|
||
password_presets 密码预设: name, encrypted_pw
|
||
db_credentials 数据库凭据: db_type, host, encrypted_password
|
||
|
||
scripts 脚本库: name, category, content
|
||
script_executions 执行记录: script_id, command, server_ids(JSON), results(JSON)
|
||
|
||
辅助表:
|
||
audit_logs 审计: admin_username, action, target_type, detail
|
||
login_attempts 防暴力: username, ip_address, success
|
||
|
||
Web SSH 表:
|
||
ssh_sessions 会话: UUID id, server_id, admin_id, status, started_at, closed_at
|
||
command_logs 命令: session_id, server_id, admin_id, command
|
||
```
|
||
|
||
### 前端页面（Tailwind CSS v4 + Alpine.js）
|
||
|
||
| 页面 | 文件 | 功能 |
|
||
|------|------|------|
|
||
| 登录 | `login.html` | JWT 登录 + TOTP 双因素 |
|
||
| 仪表盘 | `index.html` | 统计 + WebSocket 实时告警 |
|
||
| 服务器 | `servers.html` | CRUD + 心跳状态 + 健康检测 |
|
||
| 文件管理 | `files.html` | 远程文件浏览 (SFTP/SSH) |
|
||
| 推送 | `push.html` | 批量文件推送 + 进度 |
|
||
| 脚本 | `scripts.html` | 脚本库 + 批量执行状态条 |
|
||
| 执行历史 | `script-executions.html` | 脚本执行记录、停止/重试/日志 |
|
||
| 凭据 | `credentials.html` | 密码预设 + 数据库凭据 |
|
||
| 定时 | `schedules.html` | Cron 调度管理 |
|
||
| 重试 | `retries.html` | 失败重试队列 |
|
||
| 设置 | `settings.html` | 系统配置 |
|
||
| 审计 | `audit.html` | 操作日志 |
|
||
|
||
共享模块: `api.js` — JWT 自动刷新、apiFetch 封装、登出
|
||
|
||
---
|
||
|
||
## 二、架构决策记录
|
||
|
||
### 已落地决策
|
||
|
||
| 编号 | 决策 | 选择 | 状态 |
|
||
|------|------|------|------|
|
||
| ADR-001 | 资产模型 | Platform 模板 + 单表 Asset + JSONB | ✅ 已落地 |
|
||
| ADR-002 | Web SSH 架构 | BFF 模式，asyncssh 内嵌 FastAPI | ✅ 已落地 (后端) |
|
||
| ADR-003 | 前端终端 | xterm.js + Koko 消息协议 | ⚠️ 后端落地，前端待做 |
|
||
| ADR-004 | SSH 连接池 | 引用计数模式 | ✅ 已落地 |
|
||
| ADR-005 | 登录认证 | JWT + TOTP 全新替换 | ✅ 已落地 |
|
||
| ADR-006 | 前端框架 | 全面弃用 AdminLTE → Tailwind CSS v4 | ✅ 已落地 |
|
||
| ADR-007 | Redis 定位 | 核心数据层 | ✅ 已落地 |
|
||
| ADR-008 | Redis 连接池 | BlockingConnectionPool | ✅ 已落地 |
|
||
| ADR-009 | Redis 可用性 | 启动强校验，不可用直接退出 | ✅ 已落地 |
|
||
| ADR-010 | WebSocket 架构 | 内存 + Redis Pub/Sub 两层 | ✅ 已落地 |
|
||
| ADR-011 | WebSocket 认证 | JWT 令牌（查询参数传递） | ✅ 已落地 |
|
||
|
||
### 已否决
|
||
|
||
| 功能 | 原因 |
|
||
|------|------|
|
||
| 会话录像 asciicast | 不需要 |
|
||
| RBAC 权限体系 | 保持"鉴权即信任"模型 |
|
||
| 推送结果邮件报告 | 不需要 |
|
||
|
||
---
|
||
|
||
## 三、实施进度
|
||
|
||
### 第零步：基础设施加固（Redis + WebSocket）— ✅ 已完成
|
||
|
||
- [x] Redis BlockingConnectionPool + 启动强校验 (ADR-008/009)
|
||
- [x] WebSocket 两层架构: 内存 ConnectionManager + Redis Pub/Sub (ADR-010)
|
||
- [x] WebSocket JWT 认证 (ADR-011)
|
||
- [x] Ping/pong 心跳 + 僵尸连接清理
|
||
|
||
### 第一步：数据层 — ✅ 已完成
|
||
|
||
- [x] platforms 表（资产类型模板）
|
||
- [x] nodes 表（树形分组）
|
||
- [x] servers 表扩展字段 (platform_id, node_id, protocols, extra_attrs, connectivity)
|
||
- [x] command_logs 表（SSH 命令日志）
|
||
- [x] ssh_sessions 表（Web SSH 会话）
|
||
- [x] admins 表 JWT 字段
|
||
- [x] 数据迁移: category → Node, 回填 platform_id
|
||
|
||
### 第二步：认证层 — ✅ 已完成
|
||
|
||
- [x] JWT 登录/刷新/验证 (`server/api/auth_jwt.py`)
|
||
- [x] TOTP 双因素认证
|
||
- [x] Tailwind CSS v4 登录页 (`web/app/login.html`)
|
||
- [x] 共享 JWT 模块 (`web/app/api.js`)
|
||
- [x] Pydantic 请求模型 (`server/api/schemas.py`)
|
||
- [x] 所有 API 路由 JWT 保护
|
||
|
||
### 第三步：Web SSH 终端 — ✅ 已完成
|
||
|
||
- [x] asyncssh 连接池模块 (`server/infrastructure/ssh/asyncssh_pool.py`)
|
||
- [x] WebSocket 端点 `/ws/terminal/{server_id}` (`server/api/webssh.py`)
|
||
- [x] Koko 消息协议 (TERMINAL_INIT/DATA/RESIZE/CLOSE)
|
||
- [x] SSH 会话生命周期追踪 (SshSession + CommandLog)
|
||
- [x] xterm.js 前端页面 (`web/app/terminal.html`，含 webssh-token + 全屏 + resize)
|
||
|
||
### 第四步：Sync 引擎升级 — ✅ 已完成
|
||
|
||
- [x] rsync 文件同步 (SyncEngineV2.sync_files)
|
||
- [x] SSH 命令批量执行 (SyncEngineV2.sync_commands)
|
||
- [x] 系统配置推送 (SyncEngineV2.sync_config)
|
||
- [x] SFTP 文件传输 (SyncEngineV2.sftp_transfer)
|
||
- [x] Semaphore 并发控制 (MAX_CONCURRENT=10)
|
||
- [x] 远程目录浏览 (POST /api/sync/browse)
|
||
|
||
### 第五步：前端全量迁移 — ✅ 已完成
|
||
|
||
- [x] @theme 设计系统（品牌色/间距/字体/暗黑模式）
|
||
- [x] 布局壳（sidebar + header + main，Alpine.js 交互）
|
||
- [x] Dashboard + WebSocket 实时告警
|
||
- [x] 服务器列表 + 文件管理 + 推送页面
|
||
- [x] 设置/配置/审计日志/脚本库/凭据管理
|
||
- [x] 定时推送/重试队列
|
||
- [x] install.php → install.html + FastAPI API 迁移
|
||
- [x] 条件启动模式 (install mode: 无 .env 时仅安装 API 可用)
|
||
|
||
---
|
||
|
||
## 四、安全性
|
||
|
||
### 已实施
|
||
|
||
| 措施 | 状态 |
|
||
|------|------|
|
||
| SSH 密码 Fernet + AES 加密 | ✅ |
|
||
| JWT 认证全覆盖 | ✅ |
|
||
| CORS 可配置域名 | ✅ |
|
||
| 默认凭据启动拒绝 | ✅ |
|
||
| Shell 注入防御 (shlex.quote) | ✅ |
|
||
| XSS 防御 (dataset 属性替代模板字面量) | ✅ |
|
||
| WebSocket JWT 认证 | ✅ |
|
||
| DbSessionMiddleware 防连接泄漏 | ✅ |
|
||
| Telegram 共享 httpx 客户端 | ✅ |
|
||
|
||
---
|
||
|
||
## 五、数据流
|
||
|
||
```
|
||
Agent心跳(60s) → Redis heartbeat:{id} (HSET, TTL=600s) → 前端直读
|
||
↓
|
||
10min批量flush
|
||
↓
|
||
MySQL (历史)
|
||
|
||
告警: CPU/mem/disk > threshold
|
||
→ WebSocket nexus:alerts (Redis Pub/Sub) → 浏览器实时显示
|
||
→ Telegram 推送手机
|
||
→ Redis alerts:{id} (SET, TTL=3600s) 告警标记
|
||
|
||
恢复: 之前告警指标恢复正常
|
||
→ WebSocket + Telegram 推送恢复通知
|
||
→ self_monitor 服务恢复时 Telegram 通知
|
||
```
|
||
|
||
---
|
||
|
||
## 六、技术债务
|
||
|
||
| # | 项 | 影响 | 建议 |
|
||
|---|------|------|------|
|
||
| D1 | ~~paramiko pool.py 废弃~~ | 无（已无引用） | ✅**已删除** — pool.py 已移除，requirements.txt 已移除 paramiko |
|
||
| D2 | ~~config.php PHP 残留~~ | 低 | ✅**已迁移** — install.php → install.html + FastAPI API，条件启动模式 |
|
||
| D3 | ~~WebSSH 前端未实现~~ | 中 | ✅**已实现** — xterm.js + Koko协议 + 自动resize + 全屏 |
|
||
| ~~D4~~ | ~~文件编辑器未集成~~ | — | ❌ **已否决** — 运维场景无需嵌入编辑器；远程文件通过 WebSSH / SFTP 处理 |
|
||
|
||
---
|
||
|
||
## 七、文件索引
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| `docs/design/specs/design-standards.md` | 设计标准 |
|
||
| `docs/design/tech-stack-evaluation.md` | 技术栈评估 |
|
||
| `docs/project/status.md` | 项目进度总览 |
|
||
| `docs/project/deploy.md` | 部署指南 |
|
||
| `docs/research/jumpserver-easynode-architecture-analysis.md` | 竞品架构分析 |
|
||
| `CLAUDE.md` | 项目记忆（开发上下文） |
|
||
| `server/domain/models/__init__.py` | SQLAlchemy 数据库模型 |
|