Codex Release Bot
913 lines
33 KiB
Markdown
913 lines
33 KiB
Markdown
# Nexus 6.0 — 功能开发指南（SSOT）
|
||
|
||
> **版本**: 2026-06-04
|
||
> **读者**: 接续开发工程师、AI Agent
|
||
> **定位**: 后续功能开发的**主参考文档**（比 handoff 更细、比 changelog 更稳）
|
||
> **关联**: [linux-dev-paths.md](linux-dev-paths.md) · [local-integration-test.md](local-integration-test.md) · [risk-acceptance-single-operator.md](risk-acceptance-single-operator.md)
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [项目概述](#1-项目概述)
|
||
2. [技术栈与仓库结构](#2-技术栈与仓库结构)
|
||
3. [启动模式与配置](#3-启动模式与配置)
|
||
4. [架构分层与请求生命周期](#4-架构分层与请求生命周期)
|
||
5. [认证、会话与安全](#5-认证会话与安全)
|
||
6. [数据模型（19 表）](#6-数据模型19-表)
|
||
7. [Redis 与实时数据流](#7-redis-与实时数据流)
|
||
8. [后台任务（Primary Worker）](#8-后台任务primary-worker)
|
||
9. [后端 API 全览](#9-后端-api-全览)
|
||
10. [核心业务模块详解](#10-核心业务模块详解)
|
||
11. [前端 SPA 架构](#11-前端-spa-架构)
|
||
12. [15 个业务页面功能说明](#12-15-个业务页面功能说明)
|
||
13. [Composables 与状态管理](#13-composables-与状态管理)
|
||
14. [WebSocket 与 WebSSH](#14-websocket-与-webssh)
|
||
15. [Agent 与子机协议](#15-agent-与子机协议)
|
||
16. [安装向导](#16-安装向导)
|
||
17. [本地开发、测试与门控](#17-本地开发测试与门控)
|
||
18. [部署与运维](#18-部署与运维)
|
||
19. [扩展开发指南](#19-扩展开发指南)
|
||
20. [不可改项与已接受风险](#20-不可改项与已接受风险)
|
||
21. [文档索引](#21-文档索引)
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
Nexus 是面向 **2000+ 子服务器** 的运维管理平台（中心机 + Agent 架构），核心能力：
|
||
|
||
| 能力域 | 说明 |
|
||
|--------|------|
|
||
| **服务器资产** | CRUD、分类、Platform/Node、心跳监控、健康检查 |
|
||
| **文件管理** | SSH 远程浏览/编辑/chmod/压缩，sudo 提权 |
|
||
| **批量推送** | Nexus 主机 rsync → 子机，4 种 sync 模式，ZIP 上传，调度与重试 |
|
||
| **脚本执行** | 脚本库 + 临时命令，SSH 并行或 Agent 长任务 |
|
||
| **WebSSH** | 浏览器终端，多 Tab，命令日志 |
|
||
| **告警** | CPU/内存/磁盘阈值，WebSocket + Telegram，恢复通知 |
|
||
| **审计** | 全 CUD + 登录/WebSSH/推送 审计 |
|
||
| **安全** | JWT + TOTP + IP 白名单 + Fernet 凭据加密 |
|
||
|
||
**生产域名**: `https://api.synaglobal.vip`
|
||
**后端端口**: `8600`
|
||
**前端入口**: `/app/`（Vue 3 SPA，Vite 构建到 `web/app/`）
|
||
|
||
---
|
||
|
||
## 2. 技术栈与仓库结构
|
||
|
||
### 2.1 技术栈
|
||
|
||
| 层 | 技术 |
|
||
|----|------|
|
||
| 后端 | Python 3.11+ · FastAPI · Async SQLAlchemy · Pydantic v2 |
|
||
| 数据库 | MySQL 8.x |
|
||
| 缓存/实时 | Redis 7（心跳、告警、WS 跨 worker、脚本执行状态） |
|
||
| SSH | asyncssh 连接池 |
|
||
| 前端 | Vue 3 · TypeScript · Vuetify 4 · Pinia · Vite |
|
||
| 编辑器/终端 | Monaco Editor · xterm.js |
|
||
| 进程守护 | Supervisor + Python self_monitor + Shell health_monitor |
|
||
|
||
### 2.2 目录结构
|
||
|
||
```
|
||
Nexus/
|
||
├── server/ # FastAPI 后端（Clean Architecture）
|
||
│ ├── main.py # 入口、lifespan、中间件、路由挂载
|
||
│ ├── config.py # Pydantic Settings + DB 覆盖
|
||
│ ├── api/ # 路由层（JWT、校验、审计）
|
||
│ ├── application/services/ # 业务编排
|
||
│ ├── domain/models/ # SQLAlchemy ORM（19 表）
|
||
│ ├── infrastructure/ # DB/Redis/SSH/Telegram 实现
|
||
│ └── background/ # 后台循环任务
|
||
├── frontend/ # Vue 3 SPA 源码
|
||
│ └── src/
|
||
│ ├── pages/ # 14 个页面
|
||
│ ├── components/ # 按模块分子目录
|
||
│ ├── composables/ # 业务逻辑（files/push/terminal…）
|
||
│ ├── stores/ # Pinia（auth、files）
|
||
│ ├── api/index.ts # HTTP 客户端
|
||
│ └── router/index.ts # Hash 路由
|
||
├── web/app/ # 静态挂载点（index.html + assets/）
|
||
│ └── install.html # 安装向导（独立静态页，非 Vue）
|
||
├── deploy/ # Supervisor、nginx、门控、部署脚本
|
||
├── docker/ # compose 环境生成
|
||
├── scripts/ # 本地 dev、验收、MCP
|
||
├── tests/ # pytest API 测试
|
||
└── docs/ # 设计、审计、changelog
|
||
```
|
||
|
||
### 2.3 架构分层（禁止跨层直连）
|
||
|
||
```
|
||
frontend/pages → api/index.ts → server/api/*.py
|
||
→ application/services/*.py
|
||
→ infrastructure/*
|
||
→ domain/models
|
||
```
|
||
|
||
- **API 层**: 路由 + Pydantic + `Depends(get_current_admin)`，不写裸 SQL
|
||
- **Service 层**: 业务编排，经 Repository 访问 DB
|
||
- **Infrastructure**: SSH 池、Redis、Telegram、Fernet
|
||
- **Domain**: ORM 模型，无 FastAPI 依赖
|
||
|
||
---
|
||
|
||
## 3. 启动模式与配置
|
||
|
||
### 3.1 两种启动模式
|
||
|
||
| 模式 | 条件 | 可用能力 |
|
||
|------|------|----------|
|
||
| **安装模式** | 仓库根无 `.env` | `/api/install/*`、`/app/install.html`、静态文件；其他 API **503** |
|
||
| **正常模式** | 存在 `.env` 且 `SECRET_KEY` / `API_KEY` / `ENCRYPTION_KEY` / `DATABASE_URL` 齐全 | 全功能 + 后台任务 |
|
||
|
||
`is_install_mode()` 在 **运行时** 检测 `.env`，安装向导写入后可立即切换（需重启 worker 加载完整 lifespan）。
|
||
|
||
### 3.2 配置三写（安装向导 Step 3）
|
||
|
||
安装成功时**同时写入**：
|
||
|
||
| 目标 | 内容 |
|
||
|------|------|
|
||
| `web/data/config.json` | 共享配置（API_BASE_URL、DB、API_KEY） |
|
||
| `.env` | `NEXUS_*` 前缀，Python 启动必需 |
|
||
| MySQL `settings` 表 | 可热覆盖的动态项（阈值、Telegram、pool 等） |
|
||
|
||
**不可从 DB 覆盖**（仅 `.env`）：`SECRET_KEY`、`API_KEY`、`ENCRYPTION_KEY`、`DATABASE_URL`。
|
||
|
||
### 3.3 重要环境变量（`NEXUS_` 前缀）
|
||
|
||
| 变量 | 说明 | 可 DB 覆盖 |
|
||
|------|------|------------|
|
||
| `NEXUS_DATABASE_URL` | `mysql+aiomysql://...` | ❌ |
|
||
| `NEXUS_SECRET_KEY` | JWT HS256 | ❌ |
|
||
| `NEXUS_API_KEY` | Agent 全局密钥 | ❌ |
|
||
| `NEXUS_ENCRYPTION_KEY` | Fernet 凭据加密 | ❌ |
|
||
| `NEXUS_REDIS_URL` | 默认 `redis://127.0.0.1:6379/0` | ✅ |
|
||
| `NEXUS_API_BASE_URL` | 公网 URL（Agent curl 安装） | ✅ |
|
||
| `NEXUS_CORS_ORIGINS` | 逗号分隔 | ✅ |
|
||
| `NEXUS_DEPLOY_PATH` | 部署根路径 | ✅ |
|
||
| `NEXUS_DB_POOL_SIZE` / `MAX_OVERFLOW` | 连接池 | ✅ |
|
||
| `NEXUS_CPU/MEM/DISK_ALERT_THRESHOLD` | 告警阈值 % | ✅ |
|
||
| `NEXUS_TELEGRAM_BOT_TOKEN` / `CHAT_ID` | 告警推送 | ✅ |
|
||
| `NEXUS_LOGIN_ALLOWLIST_*` | 登录 IP 白名单 | ✅ |
|
||
| `NEXUS_JWT_ACCESS_TOKEN_EXPIRE_MINUTES` | 默认 60 | ✅ |
|
||
| `NEXUS_TEST_ADMIN_PASSWORD` | 本地测试登录（不入 git） | — |
|
||
|
||
完整映射见 `server/config.py` 的 `DB_OVERRIDE_MAP`。
|
||
|
||
---
|
||
|
||
## 4. 架构分层与请求生命周期
|
||
|
||
### 4.1 HTTP 请求（普通 API）
|
||
|
||
```
|
||
Client → CORS → JwtAuthMiddleware → DbSessionMiddleware → Router
|
||
→ request.state.db
|
||
→ Service → Repo → MySQL
|
||
```
|
||
|
||
- **DbSessionMiddleware**: 每请求一个 `AsyncSession`，请求结束 close
|
||
- **例外**: WebSocket、`/api/install/` 自建 session
|
||
|
||
### 4.2 Primary Worker 锁
|
||
|
||
多 worker uvicorn 时，**仅一个** worker 运行后台任务：
|
||
|
||
1. Redis `SETNX nexus:primary_worker`（TTL 30s，续期）
|
||
2. Redis 不可用时 fallback：`flock /tmp/nexus-primary.lock`
|
||
|
||
后台任务列表见 [§8](#8-后台任务primary-worker)。
|
||
|
||
### 4.3 静态文件与 SPA
|
||
|
||
- FastAPI 挂载 `web/app/` → `/app/`
|
||
- Vue 使用 **Hash 路由** `#/servers`，刷新不依赖 nginx try_files
|
||
- 构建: `cd frontend && npx vite build` → 输出 `web/app/index.html` + `assets/`
|
||
|
||
---
|
||
|
||
## 5. 认证、会话与安全
|
||
|
||
### 5.1 管理端 JWT
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 登录 | `POST /api/auth/login`（username + password + 可选 TOTP） |
|
||
| Access Token | 响应 body，**仅存内存**（Pinia `auth.ts`） |
|
||
| Refresh Token | HttpOnly Cookie `nexus_refresh`，`POST /api/auth/refresh` |
|
||
| 过期 | Access 默认 60min；前端过期前 5min 主动 refresh |
|
||
| 失效 | 改密/TOTP 变更 → `token_version` 递增，旧 JWT 失效 |
|
||
| 防暴破 | 5 次失败 / 15min → HTTP 429 |
|
||
| 会话空闲 | 8 小时（refresh 重用检测） |
|
||
|
||
**JWT 中间件公开前缀**（无需 Bearer）:
|
||
|
||
`/api/auth/login` · `/api/auth/refresh` · `/api/auth/logout` · `/api/agent/` · `/api/install/` · `/api/settings/bing-wallpapers` · `/health` · `/ws/` · OpenAPI
|
||
|
||
### 5.2 TOTP
|
||
|
||
| API | 说明 |
|
||
|-----|------|
|
||
| `POST /api/auth/totp/setup` | 返回 QR + secret |
|
||
| `POST /api/auth/totp/enable` | 验证码确认 |
|
||
| `POST /api/auth/totp/disable` | 需当前密码 + TOTP |
|
||
|
||
### 5.3 敏感操作二次验证（Re-auth）
|
||
|
||
| 场景 | API | 需当前密码 |
|
||
|------|-----|------------|
|
||
| 查看 API Key | `POST /api/settings/api-key/reveal` | ✅ |
|
||
| 查看 Telegram Token | `POST /api/settings/telegram/reveal-token` | ✅ |
|
||
| 查看 Agent Key | `POST /api/servers/{id}/agent-key` | ✅ |
|
||
| 生成安装命令 | `POST /api/servers/{id}/agent-install-cmd` | ✅ |
|
||
| 改密 | `PUT /api/auth/password` | ✅ |
|
||
|
||
### 5.4 Agent API Key
|
||
|
||
| 层级 | 行为 |
|
||
|------|------|
|
||
| Per-server | `servers.agent_api_key`（`nxs-*`），优先 |
|
||
| 全局回退 | `NEXUS_API_KEY`（legacy，单人运维已接受） |
|
||
| 未知 server_id | **拒绝**（batch 安装仍可能用 global key） |
|
||
|
||
Header: `X-API-Key` 或 query（Agent 脚本约定）。
|
||
|
||
### 5.5 凭据存储
|
||
|
||
- `Server.password` / `ssh_key_private` → Fernet（`ENCRYPTION_KEY`）
|
||
- API 响应: `password_set: true`，**不返明文**
|
||
- 密码预设: `encrypted_pw` 字段，前端 POST 后不入 localStorage
|
||
|
||
### 5.6 登录 IP 白名单
|
||
|
||
- `settings` + `.env`: `LOGIN_ALLOWLIST_ENABLED`
|
||
- 手动 IP + 订阅 URL 解析（`ip_allowlist_refresh` 每 2h）
|
||
- 登录 API 在 JWT 之前校验客户端 IP
|
||
|
||
---
|
||
|
||
## 6. 数据模型（19 表）
|
||
|
||
定义文件: `server/domain/models/__init__.py`
|
||
|
||
| ORM | 表名 | 用途 | 关键字段 |
|
||
|-----|------|------|----------|
|
||
| `Platform` | `platforms` | 资产模板 | `name`, `category`, `default_protocols` |
|
||
| `Node` | `nodes` | 资产树节点 | `parent_id`, `sort_order` |
|
||
| `Server` | `servers` | 子服务器 | `domain`, `port`, SSH 凭据, `target_path`, `agent_api_key`, `is_online`, `system_info`, `files_elevation` |
|
||
| `SyncLog` | `sync_logs` | 推送历史 | `status`, `sync_mode`, 字节/文件统计, `operator` |
|
||
| `Admin` | `admins` | 管理员 | `password_hash`, `totp_*`, `token_version` |
|
||
| `LoginAttempt` | `login_attempts` | 登录尝试 | 防暴破 |
|
||
| `Setting` | `settings` | KV 配置 | `key` PK, `value` |
|
||
| `PasswordPreset` | `password_presets` | SSH 密码模板 | `encrypted_pw` |
|
||
| `SshKeyPreset` | `ssh_key_presets` | SSH 密钥模板 | `encrypted_private_key` |
|
||
| `PushSchedule` | `push_schedules` | 定时任务 | `cron_expr`, `server_ids`, `schedule_type` push/script |
|
||
| `PushRetryJob` | `push_retry_jobs` | 失败重试 | 指数退避, `max_retries=3` |
|
||
| `AuditLog` | `audit_logs` | 审计（**7 天**自动清理） | `action`, `target_*`, `ip_address` |
|
||
| `Script` | `scripts` | 脚本库 | `content`, `category` |
|
||
| `ScriptExecution` | `script_executions` | 执行记录 | `results` JSON, `status` |
|
||
| `DbCredential` | `db_credentials` | DB 凭据 | 脚本内 `$DB_*` 替换 |
|
||
| `AlertLog` | `alert_logs` | 告警历史（**7 天**自动清理） | `is_recovery` |
|
||
| `SshSession` | `ssh_sessions` | WebSSH 会话 | UUID `id` |
|
||
| `CommandLog` | `command_logs` | 终端命令 | `command` ≤2000 字符 |
|
||
| `QuickCommand` | `quick_commands` | 终端快捷命令 | `sort_order` |
|
||
|
||
---
|
||
|
||
## 7. Redis 与实时数据流
|
||
|
||
### 7.1 Key 约定
|
||
|
||
| Key 模式 | TTL | 内容 |
|
||
|----------|-----|------|
|
||
| `heartbeat:{server_id}` | 600s | 最新心跳字段（HSET） |
|
||
| `alerts:{server_id}` | 3600s | 活跃告警集合 |
|
||
| `sync:cancel:{batch_id}` | — | 推送取消标记 |
|
||
| `nexus:alerts` | Pub/Sub | 跨 worker WS 广播 |
|
||
| `script:exec:{id}` | — | 脚本执行实时状态 |
|
||
| `nexus:primary_worker` | 30s | Primary 锁 |
|
||
|
||
### 7.2 心跳数据流
|
||
|
||
```
|
||
Agent(60s) → POST /api/agent/heartbeat
|
||
→ Redis 实时写入
|
||
→ 前端 Dashboard 读 API（overlay Redis）
|
||
→ 每 600s heartbeat_flush → MySQL servers 历史字段
|
||
→ 超阈值 → WebSocket alert + Telegram（5min 防抖）
|
||
→ 恢复 → recovery 通知
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 后台任务（Primary Worker）
|
||
|
||
| 模块 | 间隔 | 文件 | 职责 |
|
||
|------|------|------|------|
|
||
| `heartbeat_flush` | 600s | `background/heartbeat_flush.py` | Redis → MySQL 心跳持久化 |
|
||
| `script_execution_flush` | 60s | `background/script_execution_flush.py` | 脚本状态 Redis → MySQL；stuck 检测 |
|
||
| `self_monitor` | 30s | `background/self_monitor.py` | Redis/MySQL/WS 自检；Telegram |
|
||
| `schedule_runner` | 60s | `background/schedule_runner.py` | Cron/once 调度 → 推送或脚本 |
|
||
| `retry_runner` | 300s | `background/retry_runner.py` | `push_retry_jobs` SKIP LOCKED 重试 |
|
||
| `ip_allowlist_refresh` | 7200s | `background/ip_allowlist_refresh.py` | 订阅 URL 更新白名单 |
|
||
| `upload_staging_cleanup` | 3600s | `background/upload_staging_cleanup.py` | 清理 `/tmp/nexus_upload_*` >24h |
|
||
| `alert_log_purge` | 24h | `background/alert_log_purge.py` | 清理 `alert_logs` >7d |
|
||
| `audit_log_purge` | 24h | `background/audit_log_purge.py` | 清理 `audit_logs` >7d |
|
||
|
||
---
|
||
|
||
## 9. 后端 API 全览
|
||
|
||
### 9.1 认证 `/api/auth`
|
||
|
||
| 方法 | 路径 | 鉴权 |
|
||
|------|------|------|
|
||
| POST | `/login` | 公开 |
|
||
| POST | `/refresh` | Cookie |
|
||
| POST | `/logout` | 公开 |
|
||
| POST | `/totp/setup|enable|disable` | JWT |
|
||
| PUT | `/password` | JWT + re-auth |
|
||
| POST | `/webssh-token` | JWT |
|
||
| GET | `/me` | JWT |
|
||
|
||
### 9.2 Agent `/api/agent`
|
||
|
||
| 方法 | 路径 | 鉴权 |
|
||
|------|------|------|
|
||
| POST | `/heartbeat` | X-API-Key |
|
||
| POST | `/script-callback` | X-API-Key + job token |
|
||
|
||
### 9.3 服务器 `/api/servers`
|
||
|
||
CRUD、stats、categories、logs、CSV import/export、batch agent install/upgrade/uninstall、**batch detect-path**（SSH 在 `/www/wwwroot` 下搜索 `crmeb` 目录写入 `target_path`）、health check、files-capability、setup-files-sudo、单台 agent 操作。
|
||
|
||
### 9.4 同步 `/api/sync`（`sync_v2.py`，核心）
|
||
|
||
| 分类 | 端点示例 |
|
||
|------|----------|
|
||
| 推送 | `POST /files`, `/preview`, `/cancel` |
|
||
| 远程文件 | `/browse`, `/file-ops`, `/read-file`, `/write-file`, `/chmod`, `/compress`… |
|
||
| 本机文件 | `/browse-local`, `/local-file-ops`, `/upload`, `/upload-zip` |
|
||
| 工具 | `/validate-source-path`, `/diagnose`, `/reconcile-stale-logs` |
|
||
|
||
### 9.5 文件浏览 `/api/files`
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/browse?server_id=&path=` | JWT + ETag 缓存 |
|
||
|
||
### 9.6 脚本 `/api/scripts`
|
||
|
||
脚本 CRUD、`POST /exec`、executions 停止/重试/stuck、DB 凭据 CRUD。
|
||
|
||
### 9.7 设置族 `/api/settings` + 子路由
|
||
|
||
| 路由器 | 前缀 | 内容 |
|
||
|--------|------|------|
|
||
| settings | `/api/settings` | 系统 KV、Telegram、IP 白名单、bing 壁纸 |
|
||
| schedule | `/api/schedules` | 调度 CRUD |
|
||
| preset | `/api/presets` | 密码预设 |
|
||
| ssh_key_preset | `/api/ssh-key-presets` | SSH 密钥预设 |
|
||
| alert_history | `/api/alert-history` | 告警列表/统计 |
|
||
| audit | `/api/audit` | 审计分页 |
|
||
| retry | `/api/retries` | 重试队列 |
|
||
|
||
### 9.8 其他
|
||
|
||
| 模块 | 前缀 | 说明 |
|
||
|------|------|------|
|
||
| assets | `/api/assets` | Platform/Node/ssh-sessions/command-logs |
|
||
| terminal | `/api/terminal` | 快捷命令 CRUD |
|
||
| search | `/api/search` | 全局搜索 |
|
||
| install | `/api/install` | 安装向导 |
|
||
| health | `/health`, `/health/detail` | 探活 |
|
||
|
||
### 9.9 WebSocket
|
||
|
||
| 路径 | Token | 用途 |
|
||
|------|-------|------|
|
||
| `/ws/alerts` | Access JWT | 告警/恢复/系统 |
|
||
| `/ws/sync` | Access JWT | 推送进度 |
|
||
| `/ws/terminal/{id}` | WebSSH JWT | 终端 Koko 协议 |
|
||
|
||
---
|
||
|
||
## 10. 核心业务模块详解
|
||
|
||
### 10.1 推送引擎 SyncEngineV2
|
||
|
||
文件: `server/application/services/sync_engine_v2.py`
|
||
|
||
| 概念 | 说明 |
|
||
|------|------|
|
||
| 执行位置 | **Nexus 中心机** 上执行 `rsync`，SSH 到子机 |
|
||
| 并发 | `asyncio.Semaphore`，默认 max 10 |
|
||
| 超时 | rsync 300s + 30s grace |
|
||
| 认证 | sshpass -e（密码）或临时 key 文件 0600 |
|
||
| 失败 | 写 `sync_logs` + 可选 `push_retry_jobs` |
|
||
| 取消 | Redis `sync:cancel:{batch_id}` |
|
||
| 预览 | `rsync --dry-run --stats` |
|
||
|
||
**Sync 模式**（`sync_mode`）:
|
||
|
||
| 模式 | rsync 参数 | 行为 |
|
||
|------|------------|------|
|
||
| `incremental` | `-az` | 默认增量 |
|
||
| `full` | `-az --delete` | 删除目标多余文件 |
|
||
| `checksum` | `-az --checksum` | 校验和 |
|
||
| `overwrite` | `-az --inplace` | 原地覆盖 |
|
||
|
||
**源路径安全**: `resolve_nexus_push_source_path()` 禁止 `/etc` 等系统路径；ZIP 解压至 `UPLOAD_STAGING_PREFIX` 下暂存目录。
|
||
|
||
### 10.2 远程文件浏览
|
||
|
||
- `GET /api/files/browse` → `files_browse_service.list_remote_directory`
|
||
- 远程命令: `ls -la` + `shlex.quote(path)`
|
||
- ETag: 目录 mtime + 条目数，支持 `If-None-Match` → 304
|
||
- 前端: `useFilesStore` 内存缓存 + TTL
|
||
|
||
**Files elevation**（`files_elevation` 字段）:
|
||
|
||
| 值 | 行为 |
|
||
|----|------|
|
||
| `off` | 不 sudo |
|
||
| `auto` | 写失败时尝试 sudo |
|
||
| `always_sudo` | 始终 sudo |
|
||
|
||
`POST /api/servers/{id}/setup-files-sudo` 远程配置 sudoers（密码走 stdin）。
|
||
|
||
### 10.3 脚本执行
|
||
|
||
文件: `server/application/services/script_service.py`
|
||
|
||
| 模式 | 条件 | 路径 |
|
||
|------|------|------|
|
||
| SSH 短命令 | 超时内完成 | asyncssh 并行，Semaphore |
|
||
| Agent 长任务 | 超时 > 阈值 | nohup + callback URL + Redis 状态 |
|
||
|
||
- DB 凭据: 脚本内 `$DB_HOST` 等占位符替换
|
||
- 危险命令: `check_dangerous_command()` WARN 日志（不阻断）
|
||
- 停止: `POST /scripts/executions/{id}/stop`
|
||
|
||
### 10.4 服务器 Agent
|
||
|
||
| 操作 | API | 方式 |
|
||
|------|-----|------|
|
||
| 安装 | batch/single install | SSH curl agent 脚本 |
|
||
| 升级 | upgrade-agent | SSH 拉取 agent.py |
|
||
| 卸载 | uninstall-agent | SSH systemctl stop |
|
||
| 安装命令 | agent-install-cmd | 返回 curl（**禁止**暴露 global API_KEY） |
|
||
|
||
Agent 心跳 JSON 含 CPU/内存/磁盘/负载；变化 >10% 或超阈值时主动告警。
|
||
|
||
### 10.5 告警与 Telegram
|
||
|
||
- 阈值: `CPU/MEM/DISK_ALERT_THRESHOLD`（默认 80%）
|
||
- 防抖: WebSocket 5min；Telegram 同类型去重
|
||
- 恢复: 指标回落 → recovery 事件
|
||
- 推送完成: `send_telegram_sync_complete`
|
||
|
||
---
|
||
|
||
## 11. 前端 SPA 架构
|
||
|
||
### 11.1 构建与开发
|
||
|
||
| 项 | 值 |
|
||
|----|-----|
|
||
| 开发 | `cd frontend && npm run dev` → `http://localhost:3000/app/` |
|
||
| API 代理 | Vite proxy `/api`、`/ws` → `127.0.0.1:8600` |
|
||
| 构建输出 | `web/app/`（`base: '/app/'`） |
|
||
| 路由 | Hash `#/path` |
|
||
|
||
### 11.2 入口链路
|
||
|
||
```
|
||
main.ts → App.vue（侧栏/搜索）→ router-view
|
||
→ pages/*.vue
|
||
→ composables → api/index.ts → /api/*
|
||
```
|
||
|
||
### 11.3 HTTP 客户端（`src/api/index.ts`）
|
||
|
||
| 能力 | 实现 |
|
||
|------|------|
|
||
| Token | 内存 access JWT |
|
||
| 401 | 自动 refresh 一次 |
|
||
| 202 | `TotpRequiredError` |
|
||
| 429 | 锁定文案 |
|
||
| 304 | 文件 browse ETag |
|
||
| Upload | FormData 不设 JSON Content-Type |
|
||
|
||
### 11.4 Pinia Stores
|
||
|
||
| Store | 职责 |
|
||
|-------|------|
|
||
| `auth` | token、admin、login/logout/refresh |
|
||
| `files` | selectedServer、currentPath、browse 缓存 |
|
||
|
||
其余状态在 composable 或页面 `ref` 中。
|
||
|
||
---
|
||
|
||
## 12. 15 个业务页面功能说明
|
||
|
||
> 路由均位于 `#/` 下；除 Login 外需 JWT。
|
||
|
||
### 12.1 DashboardPage `/`
|
||
|
||
| 功能 | API/机制 |
|
||
|------|----------|
|
||
| 统计卡片 | `GET /servers/stats` |
|
||
| 服务器分页表 | `useServerPagination` |
|
||
| 告警摘要 | `GET /alert-history/?limit=5` |
|
||
| 资源概览 | 拉 200 台算 CPU/内存均值 |
|
||
| 分类分布 | stats.categories |
|
||
| 最近审计 | `GET /audit/?limit=10` |
|
||
| 实时刷新 | `useWebSocket` → 告警时 reload stats |
|
||
| 快捷跳转 | 终端/文件 `?server_id=` |
|
||
|
||
### 12.2 ServersPage `/servers`
|
||
|
||
| 功能 | API |
|
||
|------|-----|
|
||
| CRUD | `/servers/` |
|
||
| **快速添加（仅 IP）** | `POST /servers/add-by-ip` — 轮询全部密码/SSH 预设；成功返回 `matched_preset` / `matched_username` |
|
||
| **连接失败列表** | `GET /servers/pending` |
|
||
| **失败重试 / 删除** | `POST /servers/pending/{id}/retry`、`DELETE /servers/pending/{id}` |
|
||
| 批量选择 | 安装/升级/卸载 Agent、**检测目标路径**、健康检查、删除 |
|
||
| **检测目标路径** | `POST /servers/batch/detect-path` — Body: `{ server_ids }`；SSH 在 `/www/wwwroot` 下搜索 `crmeb` 目录写入 `target_path`；结果弹窗逐台展示 |
|
||
| **列表快捷编辑** | 目标路径列 ✏️ → `PUT /servers/{id}` `{ target_path }` |
|
||
| CSV 导出 | 客户端生成（无密码列） |
|
||
| CSV 导入 | `POST /servers/import` FormData |
|
||
| 详情面板 | 系统信息 + `GET /servers/{id}/logs` |
|
||
| 表单 | `ServerFormDialog` + `useServerFormDialog` |
|
||
|
||
详见附录 J（凭据轮询契约）。
|
||
|
||
### 12.3 TerminalPage `/terminal`
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 多 Tab | `useTerminalSessions` |
|
||
| WebSSH | `POST /auth/webssh-token` → `WS /ws/terminal/{id}?token=` |
|
||
| xterm | FitAddon、256 色 |
|
||
| 命令栏 | shell 高亮、`sendCmd`/`sendCtrl` |
|
||
| 快捷命令 | `GET /terminal/quick-commands` |
|
||
| 路由入参 | `#/terminal?server_id=123` 自动开 Tab |
|
||
| 清理 | `onBeforeUnmount` → `disposeAllSessions` |
|
||
|
||
### 12.4 FilesPage `/files`
|
||
|
||
薄编排页，逻辑在 composables：
|
||
|
||
| 子模块 | 能力 |
|
||
|--------|------|
|
||
| Toolbar | 上传、刷新、上级目录 |
|
||
| List | 排序、多选、双击进目录 |
|
||
| Editor | Monaco，`POST /sync/read-file|write-file` |
|
||
| 权限 | files-capability 检测、sudo 提示 |
|
||
| 热键 | 复制/粘贴/删除（`useFilesHotkeys`） |
|
||
| 跨机传输 | 工具栏/右键跳转 `#/server-transfer`（见 §12.4.1） |
|
||
|
||
### 12.4.1 ServerTransferPage `/server-transfer`
|
||
|
||
| 能力 | 说明 |
|
||
|------|------|
|
||
| 源机浏览 | `POST /sync/browse`，多选 + 手动绝对路径 |
|
||
| 直传 | `POST /sync/server-transfer`（单文件 ≤500MB） |
|
||
| 打包投递 | `POST /sync/server-transfer/deliver` + 可选解压 |
|
||
| 深链 | `?source=&path=&paths=` 自文件页预填 |
|
||
|
||
### 12.5 PushPage `/push`
|
||
|
||
| 功能 | API/WS |
|
||
|------|--------|
|
||
| 源/目标路径 | 表单校验 |
|
||
| ZIP 上传 | `POST /sync/upload-zip` |
|
||
| 服务器网格 | 分类全选 |
|
||
| 预览 | `POST /sync/preview` 并发 |
|
||
| 推送 | `POST /sync/files` + `/ws/sync` 进度 |
|
||
| 取消 | `POST /sync/cancel` |
|
||
| 历史 | sync_logs 分页、诊断、对账 |
|
||
|
||
### 12.6 ScriptsPage `/scripts`
|
||
|
||
| 功能 | API |
|
||
|------|-----|
|
||
| 脚本 CRUD | `GET/POST/PUT/DELETE /scripts/`（分类 ops/deploy/check/cleanup） |
|
||
| Monaco 编辑 | `ScriptContentEditor` · `content` 字段 |
|
||
| 库内执行 | `POST /scripts/exec`（`script_id` 或 `command` 二选一） |
|
||
| 临时命令 | 页内 quick exec 面板 |
|
||
| 长任务 / DB 凭据 | `long_task`、`credential_id`；`GET /scripts/exec-config` |
|
||
| 提交执行 | `POST /scripts/exec` **立即返回** `running`（后台批次） |
|
||
| 全局进度 | `App.vue` + `useScriptExecutionQueue`（WS `script_progress` / `script_complete`） |
|
||
| 历史 | `GET /scripts/executions?script_id=` |
|
||
| 停止 / 重试 / 卡住 | `POST .../stop`、`.../retry`、`.../mark-stuck` |
|
||
|
||
### 12.7 ScriptRunsPage `/script-runs` · `/script-runs/:id`
|
||
|
||
| 功能 | API |
|
||
|------|-----|
|
||
| 执行看板列表 | `GET /scripts/executions`（状态筛选 running/completed/partial/failed） |
|
||
| 单次明细 | `GET /scripts/executions/{id}` · 失败分组 · 复制清单 · 跳转终端 |
|
||
| 重试 / 停止 | 同 ScriptsPage |
|
||
| 入口 | 侧栏「脚本看板」；Telegram 深链 `#/script-runs/{id}` |
|
||
|
||
### 12.8 CredentialsPage `/credentials`
|
||
|
||
三 Tab：密码预设、SSH 密钥、DB 凭据；编辑时空密码表示不修改。
|
||
|
||
| Tab | API | 契约要点 |
|
||
|-----|-----|----------|
|
||
| 密码预设 | `GET/POST /presets/`、`PUT/DELETE /presets/{id}` | 字段 `name`、`username`（默认 `root`）、`encrypted_pw`；列表返回 `username` |
|
||
| SSH 密钥 | `GET/POST /ssh-key-presets/`、`PUT/DELETE /ssh-key-presets/{id}` | 同上 `username`；私钥 `private_key` 仅创建/更新时传 |
|
||
| DB 凭据 | `GET/POST /scripts/credentials`、`PUT/DELETE /scripts/credentials/{id}` | 脚本执行用 DB 连接，与 SSH 轮询无关 |
|
||
|
||
`username` 供 `credential_poller` 在 `add-by-ip` / retry 时与预设密码或私钥组合尝试 SSH。
|
||
|
||
### 12.9 SchedulesPage `/schedules`
|
||
|
||
| 功能 | API / 行为 |
|
||
|------|------------|
|
||
| 类型 | `schedule_type`: `push`（rsync）或 `script`（ScriptService） |
|
||
| 运行模式 | `run_mode`: `cron`（5 字段 cron_expr）或 `once`（fire_at） |
|
||
| 推送字段 | `source_path`（必填）、`target_path`（可选，留空走各机配置）、`sync_mode` |
|
||
| 脚本字段 | `script_id` 或 `script_content`、`exec_timeout`、`long_task` |
|
||
| 列表 | `next_run` API 计算；`GET /schedules/` |
|
||
| 立即执行 | push → `POST /sync/files`；script → `POST /scripts/exec` |
|
||
| 后台 | `schedule_runner` 60s 扫描到期项 |
|
||
|
||
### 12.10 RetriesPage `/retries`
|
||
|
||
失败推送重试队列；`POST /retries/{id}/retry`。
|
||
|
||
### 12.11 CommandsPage `/commands`
|
||
|
||
| 视图 | API | 筛选 |
|
||
|------|-----|------|
|
||
| 命令视图 | `GET /assets/command-logs` | server_id |
|
||
| 会话视图 | `GET /assets/ssh-sessions` | server_id |
|
||
| 推送日志 | `GET /servers/logs` | server_id、status、sync_mode、trigger_type |
|
||
|
||
### 12.12 AlertsPage `/alerts`
|
||
|
||
告警统计 + 分页；按 type/status 过滤。
|
||
|
||
### 12.13 AuditPage `/audit`
|
||
|
||
操作审计；action/user/date 过滤；`normalizeAuditList`。
|
||
|
||
### 12.14 SettingsPage `/settings`
|
||
|
||
系统名/阈值/连接池、Telegram、改密、TOTP、API Key reveal、IP 白名单、终端快捷命令设置。
|
||
|
||
### 12.15 LoginPage `/login`
|
||
|
||
JWT 登录、TOTP、429 锁定、开放重定向防护（`//` 拒绝）、bing 壁纸背景。
|
||
|
||
---
|
||
|
||
## 13. Composables 与状态管理
|
||
|
||
### 13.1 模块索引
|
||
|
||
| 目录 | 入口 | 用途 |
|
||
|------|------|------|
|
||
| `composables/files/` | `useFilesPage` | 文件页总编排 |
|
||
| `composables/push/` | `usePushPage` | 推送页总编排 |
|
||
| `composables/terminal/` | `useTerminalSessions` | WebSSH 会话 |
|
||
| `composables/servers/` | `useServerFormDialog` | 服务器表单 |
|
||
| `composables/useWebSocket.ts` | — | 告警 WS |
|
||
| `composables/useServerPagination.ts` | — | 分页表 |
|
||
|
||
### 13.2 新增页面 Checklist
|
||
|
||
1. `frontend/src/pages/XxxPage.vue`
|
||
2. `router/index.ts` 注册路由
|
||
3. `App.vue` 侧栏 nav 项
|
||
4. `types/api.ts` 补充类型
|
||
5. 后端 API + 审计日志
|
||
6. E2E: `frontend/e2e/full-acceptance.spec.mjs`
|
||
|
||
---
|
||
|
||
## 14. WebSocket 与 WebSSH
|
||
|
||
### 14.1 告警 WS `/ws/alerts`
|
||
|
||
- 连接: `buildWebSocketUrl('/ws/alerts', { token: accessToken })`
|
||
- 消息类型: alert / recovery / system / **script_progress** / **script_complete**
|
||
- App.vue：`useWebSocket` + `useScriptExecutionQueue`（全局进度条与完成 Alert）
|
||
- WS 断线时队列 3s 轮询直至终态
|
||
|
||
### 14.2 推送 WS `/ws/sync`
|
||
|
||
- batch_id 维度进度
|
||
- `usePushProgress` 维护 per-server 状态
|
||
|
||
### 14.3 WebSSH
|
||
|
||
- 独立 JWT: `purpose=webssh`, `server_id`, 15min
|
||
- 绑定路径 server_id，防 IDOR
|
||
- Koko 消息: `TERMINAL_INIT`, `DATA`, `RESIZE`, `CLOSE`
|
||
- 命令日志: Enter 时写 `command_logs`
|
||
|
||
**已接受风险**: JWT 走 query string（ADR-011），见 risk-acceptance 文档。
|
||
|
||
---
|
||
|
||
## 15. Agent 与子机协议
|
||
|
||
### 15.1 网络模型
|
||
|
||
| 方向 | 端口 | 用途 |
|
||
|------|------|------|
|
||
| 子机 → 中心 | 443 出站 | 心跳、script callback |
|
||
| 中心 → 子机 | 22 | 推送、文件、脚本、Agent 安装 |
|
||
| 子机本机 | 127.0.0.1:8601 | Agent HTTP（可选） |
|
||
|
||
### 15.2 心跳 Payload（摘要）
|
||
|
||
`server_id`, `cpu`, `memory`, `disk`, `load`, `uptime`, `agent_version`, `system_info`, ...
|
||
|
||
### 15.3 脚本回调
|
||
|
||
长任务完成后 Agent `POST /api/agent/script-callback`，携带 job id 与 per-server 结果。
|
||
|
||
---
|
||
|
||
## 16. 安装向导
|
||
|
||
| 步骤 | UI | API |
|
||
|------|-----|-----|
|
||
| 1 | 环境检查 | `GET /install/env-check` |
|
||
| 2 | MySQL/Redis 配置 | `POST /install/init-db` |
|
||
| 3 | 三写配置 | 同上（写 .env + config.json + settings） |
|
||
| 4 | 创建管理员 | `POST /install/create-admin`（install_token） |
|
||
| 5 | 锁定 | `POST /install/lock` |
|
||
|
||
静态页: `web/app/install.html`（Tailwind，非 Vue SPA）。
|
||
锁定后 `/install/status` → 404，防止信息泄露。
|
||
|
||
---
|
||
|
||
## 17. 本地开发、测试与门控
|
||
|
||
### 17.1 快速启动
|
||
|
||
```bash
|
||
# Docker MySQL + Redis
|
||
docker compose up -d mysql redis
|
||
|
||
# 生成 .env（若无）
|
||
python3 docker/generate_env.py && python3 docker/sync_root_env.py
|
||
|
||
# 启动 API
|
||
bash scripts/start-dev.sh # → http://127.0.0.1:8600
|
||
|
||
# 前端
|
||
cd frontend && npm run dev # → http://localhost:3000/app/
|
||
```
|
||
|
||
### 17.2 验证命令
|
||
|
||
| 级别 | 命令 |
|
||
|------|------|
|
||
| L2b | `bash scripts/local_verify.sh` |
|
||
| L2c | `.venv/bin/pytest tests/ -q` |
|
||
| L3 | `bash deploy/pre_deploy_check.sh` |
|
||
| L4 | `python3 scripts/run_nexus_acceptance.py --base http://127.0.0.1:8600 --with-ui` |
|
||
| E2E | `cd frontend && NEXUS_E2E_BASE=http://127.0.0.1:8600 npm run test:e2e` |
|
||
|
||
### 17.3 七道门控
|
||
|
||
见 `deploy/pre_deploy_check.sh`：Changelog、Audit、Test、Ruff、Import、Bandit、Review。
|
||
|
||
---
|
||
|
||
## 18. 部署与运维
|
||
|
||
### 18.1 生产部署
|
||
|
||
```bash
|
||
git push origin main
|
||
bash deploy/pre_deploy_check.sh
|
||
bash deploy/deploy-production.sh
|
||
# 或手动: ssh nexus "cd $DEPLOY && git reset --hard origin/main && supervisorctl restart nexus"
|
||
# 前端: bash deploy/deploy-frontend.sh
|
||
```
|
||
|
||
### 18.2 三层守护
|
||
|
||
| 层 | 机制 |
|
||
|----|------|
|
||
| 1 | Supervisor 进程重启 |
|
||
| 2 | `self_monitor` 30s |
|
||
| 3 | `health_monitor.sh` cron 1min → 连续失败 restart + Telegram |
|
||
|
||
### 18.3 健康检查
|
||
|
||
- `GET /health` → 纯文本 `ok`
|
||
- `GET /health/detail` → JSON（需 JWT）
|
||
|
||
---
|
||
|
||
## 19. 扩展开发指南
|
||
|
||
### 19.1 新增 REST API
|
||
|
||
1. 设计文档 `docs/design/specs/YYYY-MM-DD-*.md`
|
||
2. Service + Repository（若需）
|
||
3. `server/api/xxx.py` + `Depends(get_current_admin)`
|
||
4. `main.py` include_router
|
||
5. 审计: `AuditLog` 写入
|
||
6. `tests/test_api.py` 或专项测试
|
||
7. Changelog + 审计 8 步
|
||
|
||
### 19.2 新增前端功能
|
||
|
||
1. 明确页面 vs 对话框 vs composable 边界
|
||
2. 类型先进 `types/api.ts`
|
||
3. 错误用 `formatApiError` + snackbar，**禁止静默吞错**
|
||
4. 敏感数据不进 localStorage
|
||
5. Playwright 抽测关键路径
|
||
|
||
### 19.3 新增后台任务
|
||
|
||
1. 仅 primary worker 注册（`main.py` lifespan）
|
||
2. 循环内 try/except + logger，不可空 pass
|
||
3. 需可关闭（CancelledError）
|
||
4. 文档 + changelog
|
||
|
||
### 19.4 数据库变更
|
||
|
||
1. 修改 `domain/models`
|
||
2. 启动时 `init_db` 或手写迁移 SQL（生产谨慎）
|
||
3. 不可破坏 `ENCRYPTION_KEY` 下已有密文
|
||
|
||
---
|
||
|
||
## 20. 不可改项与已接受风险
|
||
|
||
### 20.1 不可改（架构/安全一致性）
|
||
|
||
| 项 | 原因 |
|
||
|----|------|
|
||
| `API_KEY` | Agent 与加密回退一致 |
|
||
| `SECRET_KEY` | JWT 与已有 token |
|
||
| `ENCRYPTION_KEY` | 已加密凭据 |
|
||
| `DATABASE_URL` | 启动绑定 |
|
||
|
||
### 20.2 已接受风险（单人运维）
|
||
|
||
见 `docs/project/risk-acceptance-single-operator.md`：
|
||
|
||
- WebSocket / WebSSH JWT 在 query
|
||
- Agent global API_KEY 回退
|
||
- 危险命令仅 WARN 不阻断
|
||
- dev docker-compose 默认密码
|
||
|
||
---
|
||
|
||
## 21. 文档索引
|
||
|
||
| 文档 | 用途 |
|
||
|------|------|
|
||
| **本文** | 功能开发 SSOT（架构 + 模块概览） |
|
||
| **[附录](nexus-functional-development-guide-appendix.md)** | API 字段表、Files/Push/Terminal 调用链、E2E/L4 对照、组件映射 |
|
||
| [AI-HANDOFF-2026-06-03.md](AI-HANDOFF-2026-06-03.md) | 会话接续 |
|
||
| [linux-dev-paths.md](linux-dev-paths.md) | Linux 路径 |
|
||
| [local-integration-test.md](local-integration-test.md) | 本地验收 |
|
||
| [script-execution.md](script-execution.md) | 脚本执行细节 |
|
||
| [alert-push-policy.md](alert-push-policy.md) | 告警策略 |
|
||
| [deploy.md](deploy.md) | 部署补充 |
|
||
| [development-acceptance-standard.md](development-acceptance-standard.md) | L0–L5 验收 |
|
||
| `docs/design/specs/` | 新功能设计 |
|
||
| `docs/changelog/` | 每次变更记录 |
|
||
|
||
---
|
||
|
||
## 22. 详细参考（附录摘要）
|
||
|
||
完整查表见 **[nexus-functional-development-guide-appendix.md](nexus-functional-development-guide-appendix.md)**。
|
||
|
||
| 附录 | 内容 |
|
||
|------|------|
|
||
| **A** | `/api/sync` 全 21 端点 + Pydantic 字段 + WS 推送时序 |
|
||
| **B** | Files 页组件树、composable 依赖图、操作→API 映射 |
|
||
| **C** | Push 页 composable 与推送时序 |
|
||
| **D** | Terminal / WebSSH 调用链 |
|
||
| **E** | schedules/retries/audit/scripts/agent/search API 明细 |
|
||
| **F** | 15 页 ↔ composable ↔ 组件对照表 |
|
||
| **G** | L4 验收 + Playwright 15 用例对照 |
|
||
| **H** | HTTP 错误码与前端处理 |
|
||
| **I** | 扩展开发检查清单 |
|
||
|
||
---
|
||
|
||
**维护约定**: 新增模块或变更 API/页面时，**同步更新本文 + 附录对应章节** + changelog（≥10 行）。
|