admin/Nexus
1
0
Fork 0
Code Issues Pull Requests Actions 91 Packages Projects Releases Wiki Activity
Files
6183047fd677ae1ffe7bdc8d6f36dcdc18a9507b
Nexus/docs/handoff-2026-05-31.md
T
Your Name df2c188f5d docs: Cursor 交接文件 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-05-31 23:32:10 +08:00

11 KiB
Raw Blame History

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):

{
  "mcpServers": {
    "vuetify-mcp": {
      "command": "npx",
      "args": ["-y", "@vuetify/mcp", "--remote"]
    }
  }
}

Nexus 项目级 MCP (~/.claude.json → projects → Nexus → mcpServers):

{
  "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，格式：

{
  "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 远程连接

五、部署流程

后端部署

# 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 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"

本地开发

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
Reference in New Issue View Git Blame Copy Permalink