Nexus/docs/handoff-2026-06-01.md

Nexus 项目交接文件 — Cursor 继续开发

生成时间: 2026-06-01 当前分支: main (与 origin/main 同步) 最后 commit: a20cefc docs: 审计+changelog 全站bug审查修复

---

一、项目基本信息

项目	值
项目名	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 服务器配置

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"]
    }
  }
}

Claude Code 中的 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/部署/日志)
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	内存存储
fetch	uvx	mcp-server-fetch	URL 获取

项目级 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"]
  }
}

---

四、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

---

七、最近完成的工作

2026-06-01: 全站 bug 审查修复 (14项)

前端修复 (9项):

级别	Bug	修复
P0	App.vue http 未导入 → 全局搜索崩溃	添加 import { api, http }
P1	TOTP 登录流程断裂	导入 TotpRequiredError，catch 中优先检查
P1	ServersPage 编辑服务器 domain 被端口污染	form.address = item.domain
P1	PushPage Set[0] 无效 → preview 发 undefined	values().next().value
P1	SettingsPage API 字符串未转数字	正则检测 + Number()
P2	api/index.ts getList 重复定义	删除第二个
P2	LoginPage 锁定倒计时不更新	ref(Date.now()) + watch + 定时器
P2	TerminalPage 路径验证过严	白名单排除控制字符+引号
P2	useWebSocket CONNECTING 状态连接泄漏	关闭旧连接再建新的

后端修复 (5项):

级别	Bug	修复
P1	websocket.py redis.keys() O(N) 阻塞	scan_iter() 非阻塞迭代
P1	auth_service.py TTL 每次刷新都重置	仅 ttl < 0 时设置 expire
P1	servers.py 批量操作并发 session commit	asyncio.Lock() 序列化
P2	settings.py asyncio.get_event_loop() 弃用	get_running_loop()
P2	settings.py datetime.utcfromtimestamp() 弃用	fromtimestamp(tz=utc)

2026-05-31: TerminalPage 全面迭代 + 登录页调整

1. 登录页居中 — flexbox 居中，删除 Logo
2. TerminalPage 25项修复 — Ctrl+L清屏、命令历史恢复、per-session重连/ping/uptime、指数退避等
3. 快捷命令 MySQL 持久化 — quick_commands 表 + CRUD API + 内置命令 seed
4. Shell 语法高亮 — 命令输入栏 sudo→红、关键字→蓝、管道→黄、字符串→绿、flag→紫

项目整体进度 — ~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 输入区精确对齐，可能在不同浏览器/分辨率下有偏差
P1	agent script-callback 无 API Key 认证	server/api/agent.py	端点仅靠 job_id+secret 验证，无 API Key 校验
P2	Admin 废弃列 jwt_refresh_token/jwt_token_expires	server/domain/models/__init__.py	旧单 token 设计遗留，现用 Redis 多设备，应清理
P1	config.py 访问令牌 30 天有效期	server/config.py	过长，行业标准 15-60 分钟 + refresh token 轮换

---

九、关键文件速查

用途	文件路径
后端入口	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 (非常详尽)

---

十、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

---

十三、Cursor Agent 接管要点

给 Cursor Agent 的提示词

复制以下内容到 Cursor 的 Agent/Chat 中作为上下文：

你是 Nexus 6.0 项目的开发助手。这是一个 2000+ 服务器运维管理平台。

技术栈:
- 后端: FastAPI + Async SQLAlchemy + Redis + WebSocket + Telegram
- 前端: Vue 3 + Vuetify 4 + TypeScript SPA (14个页面)
- 部署: Gitea → SSH git pull → supervisorctl restart (后端)，Vite build → tar+scp (前端)

强制规则:
1. 所有实现必须是完美实现 — 不允许降级、妥协、留技术债
2. 安全铁律: 禁止明文密码前端、禁止静默吞错、禁止f-string拼SQL、禁止硬编码密钥
3. 文档纪律: 每次修改必须写 changelog (docs/changelog/)，新功能必须先有设计文档
4. 修改流程: 实现 → 验证 → 审计8步 → 部署 → 健康检查 → 浏览器验证 → changelog
5. 用中文回复
6. 部署用 SSH: `ssh nexus "cd /www/wwwroot/api.synaglobal.vip && git fetch --all && git reset --hard origin/main && supervisorctl restart nexus"`

生产环境:
- 域名: https://api.synaglobal.vip
- SSH 别名: ssh nexus (root@47.254.123.106)
- 管理员: admin / Nexus@2026
- 健康检查: curl http://127.0.0.1:8600/health → "ok"

详细项目文档: 项目根目录 CLAUDE.md
交接文件: docs/handoff-2026-06-01.md

Cursor Rules 文件

在项目根目录创建 .cursorrules 文件，内容从 CLAUDE.md 复制。或者创建 .cursor/rules/ 目录，按模块拆分规则。