Nexus Deploy
b866e944ab
Apply sync/install/auth/schedule/retry/agent/settings fixes from full code review; document accepted WS and Agent legacy risks for solo ops. Co-authored-by: Cursor <cursoragent@cursor.com>
338 lines
15 KiB
Markdown
338 lines
15 KiB
Markdown
# Nexus 6.0 — AI 接续工作交接（SSOT）
|
||
|
||
> **生成日期**: 2026-05-23
|
||
> **用途**: 切换 AI / 新会话时**唯一接续入口**；下文汇总本会话决策、代码状态、待办与验证清单。
|
||
> **工作区（历史 Windows 路径，勿再使用）**: `C:\Users\uzuma\Desktop\svn\Nexus\...`
|
||
> **Linux SSOT**: `docs/project/linux-dev-paths.md` · `docs/project/AI-HANDOFF-2026-06-03.md` · `~/Nexus`
|
||
> **部署状态**: 以各 handoff 日期为准；生产见 `CLAUDE.md` 部署节
|
||
|
||
---
|
||
|
||
## 0. 给下一任 AI 的复制提示词
|
||
|
||
```
|
||
【严谨性】与 Nexus 团队同等严谨，不得降低标准。全量标准索引：
|
||
docs/project/standards-transfer-package.md
|
||
|
||
【必读 · 按序】
|
||
1. docs/project/AI-HANDOFF-2026-05-23.md
|
||
1b. docs/project/2026-06-01-master-backlog-plan.md（文件管理/POSIX/部署/审计 长计划任务）
|
||
2. docs/project/nexus-full-site-features.md
|
||
3. docs/project/development-acceptance-standard.md
|
||
4. docs/project/standards-transfer-package.md
|
||
|
||
【规范 · 全文内化（开发 + 审计同等强制）】
|
||
- .cursor/rules/perfect-implementation.mdc
|
||
- .cursor/rules/nexus-tech-stack.mdc + nexus-python-backend.mdc + nexus-frontend.mdc + nexus-security.mdc
|
||
- .cursor/rules/audit-line-review.mdc（走读/Phase2 触发）
|
||
- standards/system-development-standard.md
|
||
- standards/line-walk-audit-standard-v2.md
|
||
- standards/audit-core-principles.md
|
||
|
||
【逐行审查】8步/文件、全文Read至EOF、Closure全表(含SAFE)、FINDING必须文件:行号、单回复≤5文件；
|
||
禁止grep/Top15冒充审计；P0/P1当场修+changelog+矩阵。提示词见 v2 §十四.1。
|
||
|
||
【验收】完成前：pytest tests/test_security_unit.py + wsl_integration_smoke.sh + changelog；
|
||
上线前：production-verification-checklist.md；宣称完成前读 verification-before-completion SKILL。
|
||
|
||
项目未部署。端口：子机出站443心跳；中心→子机SSH22；8601仅本机。
|
||
P1待办：WebSSH断线重连、CSV批量导入。首次部署E2E见本文§6。
|
||
已否决见§7。风险接受（单人运维·不排期）见§7b。
|
||
```
|
||
|
||
---
|
||
|
||
## 1. 项目一句话
|
||
|
||
Nexus 6.0：2000+ 台服务器运维平台；FastAPI 四层架构 + Redis 实时心跳 + WebSocket/Telegram 告警 + asyncssh 推送/WebSSH/脚本；前端 Tailwind v4 + Alpine.js 静态页。
|
||
|
||
---
|
||
|
||
## 2. 端口与通道模型（2026-05-23 最终决策）
|
||
|
||
| 方向 | 端口 | 用途 | 是否必须 |
|
||
|------|------|------|----------|
|
||
| 子机 → 中心 | **443 出站** | Agent 心跳、长任务 `curl` 回调 | ✅ 必须 |
|
||
| 中心 → 子机 | **22 入站** | rsync 推送、文件浏览/操作、**脚本执行**、**手动健康检查**、Agent 安装/升级 | ✅ 必须 |
|
||
| 子机本机 | **127.0.0.1:8601** | Agent uvicorn（仅本机） | 可选进程；**不要求公网 8601** |
|
||
|
||
**已否定/不推荐**
|
||
|
||
- 为脚本/健康检查强制公网开放 8601
|
||
- 用宝塔「Python 项目管理器」托管 Agent（与面板生命周期耦合）
|
||
- 用 btpanel-skills 安装 Agent（skills 仅适合读面板监控 API，见 [btpanel-skills](https://github.com/aaPanel/btpanel-skills)）
|
||
|
||
**Go 单二进制 Agent**：长期可选；当前子机均有 Python 3.12，优先 venv 方案。
|
||
|
||
---
|
||
|
||
## 3. 本会话及近期已完成（代码）
|
||
|
||
### 3.1 架构 / 运维向
|
||
|
||
| 项 | 说明 | 关键文件 |
|
||
|----|------|----------|
|
||
| 脚本执行改 SSH | 不再依赖中心访问子机 8601；结果含 `channel: ssh` | `server/application/services/script_service.py` |
|
||
| 手动健康检查改 SSH | `check_all_servers` 经 SSH 探测指标 | `server_service.py`, `server/infrastructure/ssh/remote_probe.py` |
|
||
| Agent 安装脚本 | python3.12+ venv、`127.0.0.1` 监听、不自动放行公网 8601 | `web/agent/install.sh` |
|
||
| 安装说明文案 | 心跳 443 / 脚本 SSH / 无需公网 8601 | `web/app/servers.html` |
|
||
| Changelog | | `docs/changelog/2026-05-23-ssh-exec-no-8601.md` |
|
||
|
||
### 3.2 功能向（会话前后期，代码已在仓库）
|
||
|
||
| 项 | 说明 |
|
||
|----|------|
|
||
| 推送 dry-run 预览 | `push.html` + `SyncEngineV2.preview_sync()`，方案 D 智能提示 |
|
||
| 推送日志视图 | `commands.html` 推送日志 Tab |
|
||
| 脚本快捷执行 | `scripts.html` 直接执行面板 |
|
||
| 定时脚本执行 | `schedule_runner.py` + `schedules.html`，`schedule_type=script` |
|
||
| 审计时间/用户过滤 | `audit.html` + `settings.py` API |
|
||
| 告警中心页 | `alerts.html` + `/api/alert-history` + `AlertLog` 表 |
|
||
| Telegram 测试 / Chat ID | `settings.html` + settings API |
|
||
| 告警分项 Telegram 开关 | `settings.html` + `NOTIFY_*` 配置 |
|
||
| 登录 IP 白名单 + 订阅解析 | `subscription_parser.py` + `ip_allowlist_refresh.py`（2h） |
|
||
| Agent 远程安装 / 安装命令 | `servers.html` + `install-agent` API |
|
||
| Agent 升级（SSH） | `POST /servers/{id}/upgrade-agent`（**未**随新 venv install.sh 对齐，见待办） |
|
||
| Agent IP 白名单 | `agent.py` + `install.sh` 写入 `allowed_ips` |
|
||
| 时钟漂移检测 | 心跳 `agent_time` + UI 徽章 + Telegram |
|
||
| TOTP 重绑 UX | `settings.html` |
|
||
| 远程文件删/改名/建目录 | `sync_v2.py` |
|
||
| Phase 2 审计 63 项 | 矩阵 `docs/reports/audit-phase-2-findings-matrix.md` |
|
||
| WSL 联调脚本/venv | `scripts/wsl_*.sh`, `docs/project/wsl-integration-test.md` |
|
||
| 标准文档目录 | `standards/` + `docs/project/*-standard*.md` |
|
||
|
||
### 3.3 代码完成度（主观）
|
||
|
||
- **核心业务代码**: ~95%～98%
|
||
- **首次部署 E2E**: 0%（未部署）
|
||
- **用户要求的增强功能**: 仍有 **5～7 项未写代码**（见 §4）
|
||
|
||
---
|
||
|
||
## 4. 待实现功能（下一任 AI 工作 backlog）
|
||
|
||
按用户确认优先级排序。
|
||
|
||
### P1 — 建议先做
|
||
|
||
| ID | 功能 | 说明 | 建议触及文件 |
|
||
|----|------|------|--------------|
|
||
| F-01 | **WebSSH 断线重连** | 方案 C：断线自动重试 1 次 + 手动重连按钮 | `web/app/terminal.html`, `server/api/webssh.py` |
|
||
| F-02 | **服务器批量导入 CSV** | 上传 CSV → 校验 → 批量 `POST /api/servers/` | 新 API + `servers.html` |
|
||
| F-03 | **Agent 升级与 install.sh 对齐** | `upgrade-agent` 应使用 `/opt/nexus-agent/.venv` + 127.0.0.1 | `server/api/servers.py` |
|
||
|
||
### P2 — 迭代
|
||
|
||
| ID | 功能 | 说明 |
|
||
|----|------|------|
|
||
| F-04 | **仪表盘历史趋势图** | CPU/内存时序；需 Redis/MySQL 历史或新聚合 |
|
||
| F-05 | 远程文件上传 UI | 可用 WebSSH/scp/推送代替；非阻塞上线 |
|
||
| F-06 | 远程文件内容预览 | 可用 WebSSH cat 代替 |
|
||
|
||
### 可选 / 讨论项（未承诺实现）
|
||
|
||
| ID | 功能 | 说明 |
|
||
|----|------|------|
|
||
| F-07 | 宝塔面板 API 监控增强 | 参考 aaPanel/btpanel-skills，补站点/服务状态（**不**替代 Agent） |
|
||
| F-08 | Agent ↔ 中心 mTLS | 安全增强，工作量大 |
|
||
| F-09 | Docker Compose 部署 | 用户称暂不需要 |
|
||
| F-10 | Go 单二进制 Agent | 2000+ 台 Python 3.12 齐全时可暂缓 |
|
||
|
||
### SSH 回退（已采用主路径，非待办）
|
||
|
||
用户曾问「SSH 回退」：已实现为**默认 SSH**，非「Agent 失败再回退」。无需再做了 Agent 优先逻辑，除非用户改口。
|
||
|
||
---
|
||
|
||
## 5. 标准转接（与团队同等严谨 · 下一任 AI 必读）
|
||
|
||
| 文档 | 路径 |
|
||
|------|------|
|
||
| **标准转接包（全量索引）** | [`standards-transfer-package.md`](standards-transfer-package.md) |
|
||
| 开发验收 L0～L5 | [`development-acceptance-standard.md`](development-acceptance-standard.md) |
|
||
| 标准目录 | [`standards/README.md`](../../standards/README.md) |
|
||
|
||
**逐行审查**：与开发规范**同等强制** — 全文见 `standards/line-walk-audit-standard-v2.md` + `standards/audit-core-principles.md`；Cursor 触发器 `audit-line-review.mdc`。
|
||
|
||
**开发规范**：`standards/system-development-standard.md` 全文 + 档 B 全部 `.cursor/rules/nexus-*.mdc`。
|
||
|
||
---
|
||
|
||
## 5b. 开发验收标准（L0～L5 速查）
|
||
|
||
**SSOT**：[`development-acceptance-standard.md`](development-acceptance-standard.md)
|
||
|
||
| 层级 | 何时用 | 关键文档 |
|
||
|------|--------|----------|
|
||
| L0 | 始终 | `perfect-implementation.mdc`、`standards/system-development-standard.md` |
|
||
| L1 | 新功能/大改 | `docs/design/specs/`、`docs/design/plans/` 内验收标准 |
|
||
| L2 | 每次改代码合并前 | `pytest tests/test_security_unit.py`、`scripts/wsl_integration_smoke.sh` |
|
||
| L3 | 安全路径改动 | `standards/line-walk-audit-standard-v2.md`、`audit-core-principles.md` |
|
||
| L4 | 模块 E2E | `script-execution.md` §11、`alert-push-policy.md`、T1～T5 |
|
||
| L5 | 首次部署/上线 | `production-verification-checklist.md`（逐项勾选） |
|
||
|
||
**禁止**：未跑 L2 命令就声称「已完成」；未勾 L5 就声称「可上线」。
|
||
|
||
---
|
||
|
||
## 6. 待验证（非「未实现」，但上线前必做）
|
||
|
||
**项目未部署时不要写「请重启生产」**；以下在 **first deploy** 后执行。
|
||
|
||
### 6.1 基础（`CLAUDE.md` / `AGENTS.md`）
|
||
|
||
- [ ] T1 心跳 Redis 写入
|
||
- [ ] T2 WebSocket
|
||
- [ ] T3 三层守护（杀 Python → Supervisor 拉起）
|
||
- [ ] T4 Telegram
|
||
- [ ] T5 install.html 五步
|
||
|
||
### 6.2 脚本平台（`docs/project/script-execution.md` §11）
|
||
|
||
- [ ] T-SE1～T-SE8（分批、长任务回调、停止、Redis 刷盘等）
|
||
- **注意**: 文档仍写 Agent `:8601` 执行，**实际已改 SSH** — 验证时按 SSH 测，并更新文档。
|
||
|
||
### 6.3 首次生产清单
|
||
|
||
完整表：`docs/project/production-verification-checklist.md`
|
||
|
||
### 6.4 WSL 代码向（无密钥核对）
|
||
|
||
`docs/project/wsl-integration-test.md` + `scripts/wsl_integration_smoke.sh --code-only`
|
||
|
||
### 6.5 建议「最小首次部署 10 条」
|
||
|
||
1. install 向导生成 `.env` + 管理员
|
||
2. 登录 + TOTP
|
||
3. 添加 1 台子机（SSH 凭据）
|
||
4. 子机安装 Agent（新 `install.sh`），确认 **无需公网 8601** 仍有心跳
|
||
5. 仪表盘看到 Redis 在线/指标
|
||
6. SSH 推送 1 个目录（dry-run + 正式）
|
||
7. SSH 执行短脚本（`channel: ssh`）
|
||
8. WebSSH 连接 + 命令审计
|
||
9. Telegram 测试发送
|
||
10. `alerts.html` 有告警历史记录
|
||
|
||
---
|
||
|
||
## 7. 已否决（永久不做，除非用户书面改口）
|
||
|
||
| 功能 | 原因 |
|
||
|------|------|
|
||
| 文件编辑器（Monaco/ACE） | 2026-05-23 用户明确抛弃；WebSSH + vim |
|
||
| RBAC / 多管理员 | 鉴权即信任 |
|
||
| 审计日志导出 CSV/JSON | 用户不需要 |
|
||
| 移动端适配 | 用户否决 |
|
||
| 会话录像 asciicast | 不需要 |
|
||
| Redis Sentinel/Cluster | 用户不需要 |
|
||
| Docker 部署（当前阶段） | 用户暂不需要 |
|
||
| 推送结果邮件报告 | 不需要 |
|
||
|
||
记录：`docs/Nexus-功能说明书.html` §15（部分条目已过期，见 §8）
|
||
|
||
---
|
||
|
||
## 7b. 风险接受（单人运维 · 不排期，2026-06-04）
|
||
|
||
> **SSOT**: `docs/project/risk-acceptance-single-operator.md`
|
||
> Operator 确认：后台仅 **一名** 操作员自用，管理员身份完全可信。
|
||
|
||
| 项 | 决定 | 说明 |
|
||
|----|------|------|
|
||
| WebSocket JWT query | **维持 ADR-011** | 不排首帧鉴权 / WS ticket；batch3 已统一 4401 |
|
||
| Agent global API_KEY 回退 | **保留 legacy** | 不硬禁用；batch3 已禁 unknown server_id + fail-closed |
|
||
|
||
**≠ 已否决**：若新增管理员、日志外发第三方、等保审计、global key 泄露或 Agent 全量 per-server 迁移，须重评并见 risk-acceptance 文档「重评触发条件」。
|
||
|
||
Code Review 三批 changelog：`docs/changelog/2026-06-04-code-review-*.md`
|
||
|
||
---
|
||
|
||
## 8. 文档债务（下一任 AI 应同步）
|
||
|
||
| 文档 | 问题 | 动作 |
|
||
|------|------|------|
|
||
| `docs/Nexus-功能说明书.html` | §15 仍写审计过滤/定时脚本「未实现」 | 更新为已实现 |
|
||
| `docs/project/script-execution.md` | 仍写 Agent HTTP 执行、:8800/:8601 | 改为 SSH 22 + 443 心跳 |
|
||
| `docs/design/specs/2026-05-19-sprint-planning.md` | WebSSH/ install 仍标待做 | 标为已完成或归档 |
|
||
| `PROJECT_HANDOVER.md` | 日期与端口模型旧 | 顶部链到本文 |
|
||
| `CLAUDE.md` / `AGENTS.md` | 待测试列表仍有效 | 部署后勾选 |
|
||
|
||
**新变更务必**: `docs/changelog/YYYY-MM-DD-*.md`（`perfect-implementation.mdc`）
|
||
|
||
---
|
||
|
||
## 9. 环境与约束（用户确认）
|
||
|
||
- **子机**: 宝塔面板；Python **3.7.16**（面板 pyenv）+ 系统 **3.12.3**
|
||
- **Agent 安装**: 固定 **3.12 venv**，隔离于宝塔 pyenv 3.7
|
||
- **防火墙**: 多数子机**未开公网 8601**；推送/脚本依赖 **22**；心跳依赖 **出站 443**
|
||
- **WSL 联调**: 只验证代码路径，不纠结部署密钥是否入 git（install 生成）
|
||
- **仓库**: 唯一 Nexus 仓库；worktree 开发
|
||
|
||
---
|
||
|
||
## 10. 关键路径索引
|
||
|
||
| 类别 | 路径 |
|
||
|------|------|
|
||
| 接续 SSOT | **本文** |
|
||
| **全站功能清单** | `docs/project/nexus-full-site-features.md` |
|
||
| **标准转接包** | `docs/project/standards-transfer-package.md` |
|
||
| **开发验收标准** | `docs/project/development-acceptance-standard.md` |
|
||
| **系统开发标准** | `standards/system-development-standard.md` |
|
||
| **逐行审计 v2** | `standards/line-walk-audit-standard-v2.md` |
|
||
| **审计原则** | `standards/audit-core-principles.md` |
|
||
| **功能说明书 HTML** | `docs/Nexus-功能说明书.html` |
|
||
| 项目记忆 | `CLAUDE.md`, `AGENTS.md` |
|
||
| 进度 | `docs/project/status.md`, `docs/project/roadmap.md` |
|
||
| 部署 | `docs/project/deploy.md` |
|
||
| 审计矩阵 | `docs/reports/audit-phase-2-findings-matrix.md` |
|
||
| 脚本 SSOT | `docs/project/script-execution.md` |
|
||
| 标准 | `standards/README.md`, `docs/project/line-walk-audit-standard-v2.md` |
|
||
| Agent | `web/agent/agent.py`, `web/agent/install.sh` |
|
||
| 脚本 SSH | `server/application/services/script_service.py` |
|
||
| 健康 SSH | `server/infrastructure/ssh/remote_probe.py` |
|
||
| 告警历史 | `web/app/alerts.html`, `server/api/settings.py`（alert_history_router） |
|
||
| Changelog 示例 | `docs/changelog/2026-05-23-ssh-exec-no-8601.md` |
|
||
| 风险接受（单人运维） | `docs/project/risk-acceptance-single-operator.md` |
|
||
| Code Review 2026-06-04 | `docs/changelog/2026-06-04-code-review-p0-p1-fixes.md` 等三批 |
|
||
|
||
---
|
||
|
||
## 11. 架构分层（禁止违反）
|
||
|
||
```
|
||
web/app/*.html → server/api/*.py → application/services → infrastructure/* → domain/models
|
||
```
|
||
|
||
- API 层：JWT + Pydantic；不写 SQL
|
||
- 无 `.env` → 安装模式（仅 `/api/install/` + 静态）
|
||
- 不可从 DB 覆盖：`SECRET_KEY`, `API_KEY`, `ENCRYPTION_KEY`, `DATABASE_URL`
|
||
|
||
---
|
||
|
||
## 12. Git / 提交说明
|
||
|
||
- 用户**未要求 commit** 时勿主动提交
|
||
- 当前 worktree 含大量未跟踪 `.cursor/`、修改的 `server/**`、`web/**`、`docs/**`
|
||
- 合并前建议：按逻辑拆分 commit（SSH 通道 / 功能增强 / 文档）
|
||
|
||
---
|
||
|
||
## 13. 会话决策时间线（摘要）
|
||
|
||
1. WSL 全链路联调 → Redis pool、SQLAlchemy aiomysql patch、venv
|
||
2. Phase 2/3/4 逐行审计 → 63+ 项修复
|
||
3. 标准文档 → `standards/`
|
||
4. 功能 gap 讨论 → dry-run、告警中心、白名单、定时脚本等 **已实现**
|
||
5. 文件编辑器 → **否决**
|
||
6. Agent 8601 vs SSH → **脚本+健康检查走 22；心跳走 443；弱化 8601**
|
||
7. 宝塔 Python 管理 → **不用**；venv + 3.12
|
||
8. 项目未部署 → **无需重启**
|
||
9. 2026-06-04 Code Review 三批本地验证；单人运维风险接受 → `risk-acceptance-single-operator.md` §7b
|
||
|
||
---
|
||
|
||
**文档维护**: 下一任 AI 完成待办或验证后，更新本文 §4 §5 §7 的勾选状态，并写 changelog。
|