admin/Nexus
1
0
Fork 0
Code Issues Pull Requests 1 Actions 83 Packages Projects Releases Wiki Activity
Files
b866e944ab18c0aaeb6e3d572950b69cf04493e0
Nexus/docs/project/AI-HANDOFF-2026-05-23.md
T
Nexus Deploy b866e944ab fix: Code Review P0/P1 batches 1-3 and single-operator risk acceptance 
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>
2026-06-04 15:57:49 +08:00

15 KiB
Raw Blame History

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）

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
开发验收 L0～L5 development-acceptance-standard.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

层级 何时用 关键文档
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。

Reference in New Issue View Git Blame Copy Permalink