From df2c188f5dd9ec482b1561fe76257b23c21452ef Mon Sep 17 00:00:00 2001 From: Your Name Date: Sun, 31 May 2026 23:32:10 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20Cursor=20=E4=BA=A4=E6=8E=A5=E6=96=87?= =?UTF-8?q?=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/handoff-2026-05-31.md | 303 +++++++++++++++++++++++++++++++++++++ 1 file changed, 303 insertions(+) create mode 100644 docs/handoff-2026-05-31.md diff --git a/docs/handoff-2026-05-31.md b/docs/handoff-2026-05-31.md new file mode 100644 index 00000000..06c89a83 --- /dev/null +++ b/docs/handoff-2026-05-31.md @@ -0,0 +1,303 @@ +# Nexus 项目交接文件 — Cursor 继续开发 + +> 生成时间: 2026-05-31 +> 当前分支: main (与 origin/main 同步) +> 最后 commit: 2d00d6a fix: 登录页居中布局 + 删除Logo区域 + +--- + +## 一、项目基本信息 + +| 项目 | 值 | +|------|------| +| 项目名 | Nexus 6.0 | +| 功能 | 2000+ 服务器运维管理平台 | +| 仓库 | http://66.154.115.8:3000/admin/Nexus.git | +| 本地路径 | `C:\Users\uzuma\Desktop\svn\Nexus` | +| 生产域名 | https://api.synaglobal.vip | +| 生产 IP | 47.254.123.106 | +| 后端端口 | 8600 | +| 部署路径 | `/www/wwwroot/api.synaglobal.vip/` | +| 管理员凭据 | admin / Nexus@2026 | +| 数据库 | MySQL nexus/Nexus@2026!@127.0.0.1:3306/nexus | +| Gitea 部署 Token | SHA: 26fee743a9332895b55f79b2dbe2e931dc7c2fe5 | + +--- + +## 二、技术栈 + +### 后端 (server/) +- **FastAPI** 0.115.6 + **uvicorn** 0.34.0 +- **SQLAlchemy** 2.0.49 (Async) + **aiomysql** 0.2.0 +- **Redis** 5.2.1 (心跳/缓存/告警去重) +- **asyncssh** 2.17.0 (WebSSH 连接池) +- **PyJWT** 2.10.1 + **bcrypt** 4.2.1 (认证) +- **cryptography** 44.0.0 (Fernet 凭据加密) +- Clean Architecture 4层: api/ → application/ → domain/ → infrastructure/ + +### 前端 (frontend/) +- **Vue 3** ^3.5.30 + **Vuetify 4** ^4.0.2 + **TypeScript** ~5.9.3 +- **Vite** ^8.0.0 + **Pinia** ^3.0.4 +- **xterm.js** ^6.0.0 (WebSSH 终端) +- **Monaco Editor** ^0.55.1 (代码编辑器) +- 14个页面组件，Hash History 路由 +- 构建输出到 `web/app/` (后端 StaticFiles 挂载点) + +### 旧前端 (web/app/) — 仍存在但不维护 +- Tailwind CSS v4 + Alpine.js，12 个 HTML 页面 +- 新 SPA 构建后覆盖 web/app/index.html 和 assets/ + +--- + +## 三、MCP 服务器配置 + +**全局配置位置**: `C:\Users\uzuma\.claude.json` → `mcpServers` + +| MCP 名称 | 类型 | 命令 | 用途 | +|----------|------|------|------| +| Nexus Remote MCP | SSH | `ssh -o StrictHostKeyChecking=no -i /c/Users/uzuma/.ssh/id_rsa_mcp root@47.254.123.106 python3 /www/wwwroot/api.synaglobal.vip/mcp/nexus_server.py` | 后端操作(API/DB/部署/日志) | +| Nexus Remote MCP (旧) | SSH | 同上但运行 `multisync_server.py` | 旧版(可忽略) | +| gitea | npx | `gitea-mcp` | Gitea 仓库操作 | +| github | npx | `@modelcontextprotocol/server-github` | GitHub 操作 | +| playwright | npx | `@playwright/mcp@latest` | 浏览器自动化 | +| context7 | npx | `@upstash/context7-mcp` | 库文档查询 | +| megamemory | 本地 | `megamemory` | 项目知识图谱 | +| memory | npx | `@modelcontextprotocol/server-memory` | 内存存储 | +| semble | uvx | `semble[mcp]` | 代码搜索 | +| fetch | uvx | `mcp-server-fetch` | URL 获取 | +| sequential-thinking | npx | `@modelcontextprotocol/server-sequential-thinking` | 顺序思考 | +| time | npx | `@modelcontextprotocol/server-time` | 时间服务 | + +**项目级 MCP** (`.claude/settings.local.json`): +```json +{ + "mcpServers": { + "vuetify-mcp": { + "command": "npx", + "args": ["-y", "@vuetify/mcp", "--remote"] + } + } +} +``` + +**Nexus 项目级 MCP** (`~/.claude.json` → projects → Nexus → mcpServers): +```json +{ + "nexus": { + "type": "stdio", + "command": "ssh", + "args": ["-o", "StrictHostKeyChecking=no", "-i", "C:/Users/uzuma/.ssh/id_rsa_nexus", "root@47.254.123.106", "cd /www/wwwroot/api.synaglobal.vip && NEXUS_DEPLOY_DIR=/www/wwwroot/api.synaglobal.vip python3 mcp/Nexus_server.py"] + } +} +``` + +### Cursor 中配置 MCP +Cursor 的 MCP 配置在 `~/.cursor/mcp.json`，格式： +```json +{ + "mcpServers": { + "nexus": { + "command": "ssh", + "args": ["-o", "StrictHostKeyChecking=no", "-i", "C:/Users/uzuma/.ssh/id_rsa_nexus", "root@47.254.123.106", "cd /www/wwwroot/api.synaglobal.vip && NEXUS_DEPLOY_DIR=/www/wwwroot/api.synaglobal.vip python3 mcp/Nexus_server.py"] + }, + "playwright": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@playwright/mcp@latest"] + }, + "gitea": { + "command": "cmd", + "args": ["/c", "npx", "-y", "gitea-mcp"], + "env": { + "GITEA_ACCESS_TOKEN": "4dfc8e2edeaf86bc9c485779652e2eb67a8604dc", + "GITEA_HOST": "http://66.154.115.8:3000" + } + }, + "fetch": { + "command": "uvx", + "args": ["mcp-server-fetch"] + }, + "context7": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@upstash/context7-mcp"] + } + } +} +``` + +--- + +## 四、SSH 配置 + +**`~/.ssh/config`**: +``` +Host nexus + HostName 47.254.123.106 + User root + IdentityFile C:/Users/uzuma/.ssh/id_rsa_nexus + StrictHostKeyChecking no +``` + +**密钥文件**: +- `C:\Users\uzuma\.ssh\id_rsa_nexus` — 生产服务器 SSH +- `C:\Users\uzuma\.ssh\id_rsa_mcp` — MCP 远程连接 + +--- + +## 五、部署流程 + +### 后端部署 +```bash +# 1. Push 到 Gitea +git push origin main + +# 2. 服务器拉取 + 重启 +ssh nexus "cd /www/wwwroot/api.synaglobal.vip && git fetch --all && git reset --hard origin/main && supervisorctl restart nexus" + +# 3. 健康检查 +ssh nexus "sleep 3 && curl -s http://127.0.0.1:8600/health" +# 预期: ok +``` + +### 前端部署 +```bash +# 一键脚本 +bash deploy/deploy-frontend.sh + +# 或手动: +cd frontend && npx vite build && cd .. +tar czf /tmp/nexus-frontend.tar.gz -C web/app index.html assets/ +scp /tmp/nexus-frontend.tar.gz nexus:/tmp/nexus-frontend.tar.gz +ssh nexus "cd /www/wwwroot/api.synaglobal.vip/web/app && tar xzf /tmp/nexus-frontend.tar.gz && rm /tmp/nexus-frontend.tar.gz" +``` + +### 本地开发 +```bash +cd frontend && npm run dev # http://localhost:3000/app/ +``` + +Vite proxy 配置: `/api` → `https://api.synaglobal.vip`, `/ws` → `wss://api.synaglobal.vip` + +--- + +## 六、7道门控 (deploy/pre_deploy_check.sh) + +| # | 门 | 检查内容 | +|---|----|---------| +| 1 | Changelog门 | 文件存在且行数≥10 | +| 2 | Audit门 | 文件存在且含 Step3+Closure+DoD | +| 3 | Test门 | test_api.py 必须存在且通过 | +| 4 | Lint门 | `ruff check server/` 零错误 | +| 5 | Import门 | `import server.main` 成功 | +| 6 | Security门 | `bandit` 无 HIGH/MEDIUM | +| 7 | Review门 | 审计文件包含实际改动文件清单 | + +MCP deploy 工具自动执行门控，任何一门不过返回 🚫 DEPLOY BLOCKED + +--- + +## 七、当前完成状态 + +### 本次 Session 完成 (2026-05-31) + +1. **登录页居中** — 移除 v-container+v-row，改用 flexbox 居中 +2. **登录页删除 Logo** — 移除头像 + "登录 Nexus" + "服务器运维管理平台" +3. **TerminalPage 全面迭代 (25项修复)**: + - P0: Ctrl+L清屏、命令历史恢复、重连per-session、onopen不忽略、ping per-session、uptime per-session + - P1: 空catch处理、termRefs用session.id、错误透传、initialCdSent per-session、剪贴板权限 + - P2: 全选菜单、指数退避重连、快捷命令编辑、硬编码高度→flex-grow +4. **快捷命令 MySQL 持久化** — 新增 quick_commands 表 + CRUD API + 启动 seed +5. **Shell 语法高亮** — 命令输入栏实时着色 (sudo→红、关键字→蓝、管道→黄、字符串→绿、flag→紫) +6. **全部已部署到生产** — 后端 git pull + supervisorctl restart，前端 tar+scp + +### 项目整体进度 — ~99% 完成 + +14 页面全部完成部署。所有 P0/P1/P2 功能已实现。 + +--- + +## 八、已知待续事项 + +| 优先级 | 问题 | 文件 | 说明 | +|--------|------|------|------| +| P1 | 批量操作按钮无反应 | ServersPage.vue | 服务器列表顶部「升级/安装/卸载 Agent」按钮，选中后点击没反应 | +| P2 | 47.121.118.30 持续发 422 | server/api/agent.py | 该 IP 不在数据库但持续发心跳，需静默丢弃或注册 | +| P2 | 422 调试日志是临时的 | server/main.py | RequestValidationError handler 仅用于调试，确认问题后应移除 | +| P3 | agent.py on_event 弃用 | server/api/agent.py | `on_event("startup")` 已弃用应改 lifespan | +| P3 | Agent 心跳缺指数退避 | server/api/agent.py | 心跳失败时无退避策略 | +| P2 | 壁纸 URL 请求命中单数端点 | LoginPage.vue | 浏览器缓存旧 JS 时请求 `/bing-wallpaper` 而非 `/bing-wallpapers`，清缓存可解决 | +| UX | 命令输入栏高亮与输入框对齐 | TerminalPage.vue | cmd-highlight 定位需要与 v-text-field 输入区精确对齐，可能在不同浏览器/分辨率下有偏差 | + +--- + +## 九、关键文件速查 + +| 用途 | 文件路径 | +|------|----------| +| 后端入口 | server/main.py | +| 路由注册 | server/main.py 行525-560 | +| 数据模型 | server/domain/models/__init__.py | +| JWT 认证 | server/api/auth_jwt.py | +| 登录API | server/api/auth.py | +| WebSSH | server/api/webssh.py | +| 终端 WS | server/api/websocket.py | +| 设置 CRUD | server/api/settings.py | +| 服务器 CRUD | server/api/servers.py | +| 快捷命令 CRUD | server/api/terminal.py (新建) | +| Agent 心跳 | server/api/agent.py | +| 同步引擎 | server/application/services/sync_engine_v2.py | +| 前端入口 | frontend/src/main.ts | +| 路由 | frontend/src/router/index.ts | +| API 客户端 | frontend/src/api/index.ts | +| Auth Store | frontend/src/stores/auth.ts | +| 登录页 | frontend/src/pages/LoginPage.vue | +| 终端页 | frontend/src/pages/TerminalPage.vue | +| Vite 配置 | frontend/vite.config.mts | +| 部署脚本 | deploy/deploy-frontend.sh | +| 门控脚本 | deploy/pre_deploy_check.sh | +| Supervisor | deploy/nexus.conf | +| Nginx | deploy/nginx_https.conf | +| DB 备份 | deploy/db_backup.sh | +| 健康检查 | deploy/health_monitor.sh | +| 项目记忆 | CLAUDE.md (279行，非常详尽) | + +--- + +## 十、Megamemory 知识图谱 + +**统计**: 34 nodes, 23 edges, 11 removed + +使用 `megamemory:understand` 查询项目上下文，`megamemory:list_roots` 查看所有根节点。 + +核心概念: nexus(总览), clean-architecture-4, db-tables-14, jwt-totp, webssh, terminal-11, sync, install-wizard, 3(3层守护), websocket, telegram, redis, security, settings, vuetify-spa, pushpage, ide, v2(文件管理器), pipeline-7(7道门控), push-cancel, reveal-with-password, nexus-theme, ruff-2026-05-30, appauthmiddleware-fix-chain, browser-tool-preference, session-2026-05-30-progress, agent, servers-list, child-server-operation-rules + +--- + +## 十一、Cursor Rules / CLAUDE.md 位置 + +| 文件 | 路径 | 说明 | +|------|------|------| +| 全局规则 | `C:\Users\uzuma\.claude\CLAUDE.md` | 完美实现原则、安全铁律、文档纪律、执行顺序 | +| 项目规则 | `C:\Users\uzuma\Desktop\svn\Nexus\CLAUDE.md` | 项目概述、目录结构、已确认决策、实现状态、部署流程 | +| 项目 Memory | `C:\Users\uzuma\.claude\projects\C--Users-uzuma-Desktop-svn-Nexus\memory\MEMORY.md` | 语言偏好(中文)、浏览器偏好(Playwright)、SSH配置、部署流程、Vuetify进度 | + +**重要**: Cursor 中对应的规则文件位置： +- `.cursorrules` 或 `.cursor/rules/` 目录 +- 需要把 CLAUDE.md 内容复制为 `.cursorrules` 格式 + +--- + +## 十二、开发流程提醒 + +``` +需求确认 → 设计文档 → 技术文档 → 实现 → 测试验证 → changelog →（必要时）更新 CLAUDE.md +``` + +**强制文件修改流程**: +``` +实现 → WSL本地验证 → ★审计8步★ → 部署 → 健康检查 → 浏览器验证 → changelog +``` + +**进度条**（每次改代码必须输出）: +``` +□实现 □WSL验证 □审计8步 □部署 □健康检查 □浏览器验证 □changelog +```