admin/Nexus
1
0
Fork 0
Code Issues Pull Requests Actions 82 Packages Projects Releases Wiki Activity

docs: 完整交接文件 (15章节 + Cursor提示词 + 部署问题)

Browse Source 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Your Name
2026-06-01 11:58:11 +08:00
parent 91d0d4104e
commit 73fdcafb81
1 changed files with 123 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/handoff-2026-06-01.md
+123 -50
View File
@@ -2,7 +2,64 @@
> 生成时间: 2026-06-01
> 当前分支: main (与 origin/main 同步)
> 最后 commit: a20cefc docs: 审计+changelog 全站bug审查修复
> 最后 commit: 91d0d41 docs: 添加 .cursorrules 供 Cursor 接管
---
## 零、Cursor 接管第一步
### 1. 已为你准备好的文件
| 文件 | 位置 | 作用 |
|------|------|------|
| **Cursor Rules** | `.cursorrules`（项目根目录）| 强制规则、部署流程、文件速查 — Cursor 自动读取 |
| **MCP 配置** | `C:\Users\uzuma\.cursor\mcp.json` | nexus/playwright/gitea/fetch/context7 — 已写好 |
| **项目规则** | `CLAUDE.md`（项目根目录）| 完整项目记忆、决策、实现状态、部署常遇问题 |
| **交接文件** | `docs/handoff-2026-06-01.md` | 本文件 |
### 2. Cursor 中使用步骤
1. 用 Cursor 打开 `C:\Users\uzuma\Desktop\svn\Nexus`
2. MCP 自动加载（`~/.cursor/mcp.json` 已配置好）
3. `.cursorrules` 自动生效（Cursor 自动读取项目根目录的此文件）
4. 直接开始对话
### 3. 给 Cursor Agent 的开场提示词（复制到 Chat）
```
读取 docs/handoff-2026-06-01.md 了解项目全貌，然后读取 CLAUDE.md 了解强制规则。项目 ~99% 完成，当前待续事项见交接文件第八节。用中文回复。
```
### 4. 更完整的 Agent System Prompt（如需配置 Custom Agent）
```
你是 Nexus 6.0 项目的开发助手。这是一个 2000+ 服务器运维管理平台。
技术栈:
- 后端: FastAPI 0.115.6 + Async SQLAlchemy 2.0 + Redis 5.2 + WebSocket + Telegram
- 前端: Vue 3 + Vuetify 4 + TypeScript SPA (14个页面)
- 构建工具: Vite 8，输出到 web/app/
- 部署: Gitea → SSH git pull → supervisorctl restart (后端)，Vite build → tar+scp (前端)
强制规则:
1. 所有实现必须是完美实现 — 不允许降级、妥协、留技术债
2. 安全铁律: 禁止明文密码前端、禁止静默吞错、禁止f-string拼SQL、禁止硬编码密钥
3. 文档纪律: 每次修改必须写 changelog (docs/changelog/，行数≥10)，新功能必须先有设计文档
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"
7. 前端部署: 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"
8. 健康检查: ssh nexus "sleep 3 && curl -s http://127.0.0.1:8600/health" → 预期 "ok"
生产环境:
- 域名: https://api.synaglobal.vip
- SSH 别名: ssh nexus (root@47.254.123.106)
- 管理员: admin / Nexus@2026
- 数据库: MySQL nexus/Nexus@2026!@127.0.0.1:3306/nexus
详细项目文档: 项目根目录 CLAUDE.md
交接文件: docs/handoff-2026-06-01.md
```
---
@@ -51,9 +108,7 @@
## 三、MCP 服务器配置
### Cursor 中配置 MCP
Cursor 的 MCP 配置在 `~/.cursor/mcp.json`，格式：
### Cursor MCP 配置（已写入 `~/.cursor/mcp.json`）
```json
{
@@ -86,7 +141,7 @@ Cursor 的 MCP 配置在 `~/.cursor/mcp.json`，格式：
}
```
### Claude Code 中的 MCP 配置
### Claude Code MCP 配置（参考）
**全局配置位置**: `C:\Users\uzuma\.claude.json` → `mcpServers`
@@ -165,6 +220,18 @@ cd frontend && npm run dev # http://localhost:3000/app/
Vite proxy 配置: `/api` → `https://api.synaglobal.vip`, `/ws` → `wss://api.synaglobal.vip`
### 部署常遇问题
| 问题 | 解决 |
|------|------|
| `/app/` 返回 404 | AppAuthMiddleware 拦截 — 确认 `/app/` 和 `/app/index.html` 在 `_APP_PUBLIC_PATHS` 中 |
| `/app/` 返回旧 HTML (Tailwind/Alpine) | `git reset --hard` 恢复了旧文件 — 需要重新 tar+scp 前端构建产物 |
| MCP deploy → git pull 失败 `could not read Username` | 服务器 remote URL 没配 token，用 `git remote set-url` |
| Gate 2 Audit BLOCKED | 创建 `docs/audit/YYYY-MM-DD-topic.md`，含 Step3+Closure+DoD |
| Gate 3 Test BLOCKED (401) | 服务器 .env 中 `NEXUS_TEST_ADMIN_PASSWORD` 与数据库不一致 |
| Gate 6 Security BLOCKED (bandit HIGH) | md5 → sha256 等，参看 bandit 报告修复 |
| Gate 7 Review BLOCKED | 审计文件缺少实际改动文件清单 |
---
## 六、7道门控 (deploy/pre_deploy_check.sh)
@@ -229,15 +296,15 @@ MCP deploy 工具自动执行门控，任何一门不过返回 🚫 DEPLOY BLOCK
| 优先级 | 问题 | 文件 | 说明 |
|--------|------|------|------|
| P1 | 批量操作按钮无反应 | ServersPage.vue | 服务器列表顶部「升级/安装/卸载 Agent」按钮，选中后点击没反应 |
| P1 | agent script-callback 无 API Key 认证 | server/api/agent.py | 端点仅靠 job_id+secret 验证，无 API Key 校验 |
| P1 | 访问令牌 30 天有效期过长 | server/config.py | 行业标准 15-60 分钟 + refresh token 轮换，当前 30 天 |
| P2 | 47.121.118.30 持续发 422 | server/api/agent.py | 该 IP 不在数据库但持续发心跳，需静默丢弃或注册 |
| P2 | 422 调试日志是临时的 | server/main.py | RequestValidationError handler 仅用于调试，确认问题后应移除 |
| P2 | Admin 废弃列未清理 | server/domain/models/__init__.py | jwt_refresh_token/jwt_token_expires 旧单token设计遗留 |
| P2 | 壁纸 URL 请求命中单数端点 | LoginPage.vue | 浏览器缓存旧 JS 时请求 `/bing-wallpaper` 而非 `/bing-wallpapers`，清缓存可解决 |
| 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 轮换 |
| UX | 命令输入栏高亮与输入框对齐 | TerminalPage.vue | cmd-highlight 定位可能在不同浏览器/分辨率下有偏差 |
---
@@ -257,12 +324,14 @@ MCP deploy 工具自动执行门控，任何一门不过返回 🚫 DEPLOY BLOCK
| 快捷命令 CRUD | server/api/terminal.py |
| Agent 心跳 | server/api/agent.py |
| 同步引擎 | server/application/services/sync_engine_v2.py |
| 认证服务 | server/application/services/auth_service.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 |
| WebSocket composable | frontend/src/composables/useWebSocket.ts |
| Vite 配置 | frontend/vite.config.mts |
| 部署脚本 | deploy/deploy-frontend.sh |
| 门控脚本 | deploy/pre_deploy_check.sh |
@@ -270,7 +339,8 @@ MCP deploy 工具自动执行门控，任何一门不过返回 🚫 DEPLOY BLOCK
| Nginx | deploy/nginx_https.conf |
| DB 备份 | deploy/db_backup.sh |
| 健康检查 | deploy/health_monitor.sh |
| 项目记忆 | CLAUDE.md (非常详尽) |
| 项目规则 | CLAUDE.md (非常详尽，279行) |
| Cursor 规则 | .cursorrules (项目根目录) |
---
@@ -284,17 +354,15 @@ MCP deploy 工具自动执行门控，任何一门不过返回 🚫 DEPLOY BLOCK
---
## 十一、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` 格式
| **Cursor 规则** | `.cursorrules`（项目根目录）| 已创建，Cursor 自动读取 |
| **Cursor MCP** | `C:\Users\uzuma\.cursor\mcp.json` | 已创建，Cursor 自动读取 |
| 全局规则 (Claude) | `C:\Users\uzuma\.claude\CLAUDE.md` | 完美实现原则、安全铁律、文档纪律、执行顺序 |
| 项目规则 (Claude) | `C:\Users\uzuma\Desktop\svn\Nexus\CLAUDE.md` | 项目概述、目录结构、已确认决策、实现状态、部署流程 |
| 项目 Memory (Claude) | `C:\Users\uzuma\.claude\projects\C--Users-uzuma-Desktop-svn-Nexus\memory\MEMORY.md` | 语言偏好(中文)、浏览器偏好(Playwright)、SSH配置、部署流程、Vuetify进度 |
---
@@ -304,7 +372,7 @@ MCP deploy 工具自动执行门控，任何一门不过返回 🚫 DEPLOY BLOCK
需求确认 → 设计文档 → 技术文档 → 实现 → 测试验证 → changelog →（必要时）更新 CLAUDE.md
```
**强制文件修改流程**:
**强制文件修改流程（不可跳步）**:
```
实现 → WSL本地验证 → ★审计8步★ → 部署 → 健康检查 → 浏览器验证 → changelog
```
@@ -314,40 +382,45 @@ MCP deploy 工具自动执行门控，任何一门不过返回 🚫 DEPLOY BLOCK
□实现 □WSL验证 □审计8步 □部署 □健康检查 □浏览器验证 □changelog
```
审计8步：登记→全文Read→规则扫描H→Closure表→入口表→输入→Sink→归类→DoD
---
## 十三、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
Agent心跳(60s) → Redis(实时) → 前端直读 → 10min批量 → MySQL(历史)
告警: CPU/mem/disk > threshold → WebSocket推送浏览器 + Telegram推送手机
恢复: 之前告警的指标恢复正常 → 自动推送恢复通知
Redis心跳key: heartbeat:{server_id} (HSET, TTL=600s)
Redis告警key: alerts:{server_id} (SET, TTL=3600s)
```
### Cursor Rules 文件
---
在项目根目录创建 `.cursorrules` 文件，内容从 `CLAUDE.md` 复制。或者创建 `.cursor/rules/` 目录，按模块拆分规则。
## 十四、已确认的关键决策
| 不可改项 | 原因 |
|---------|------|
| API_KEY | 加密一致性 + 子服务器认证 |
| SECRET_KEY | 加密回退密钥 |
| DATABASE_URL | 启动必需 |
| ENCRYPTION_KEY | 凭据加密 |
| 可改项 | 说明 |
|--------|------|
| system_name/title | 前端显示 |
| pool_size/overflow | 安装向导自动推荐 |
| redis_url | Redis 连接 |
| 告警阈值 | 默认 80% |
| Telegram 配置 | 告警推送 |
---
## 十五、用户审查清单
验证 AI 是否偷懒：
1. 看 `deploy/gate_log.jsonl` — 每次门控都有记录，没有记录 = 没过门控
2. 看审计文件 — 必须有 Closure 表（每个H的判定+依据）、Step 3 规则扫描、DoD
3. 看进度条 — ☑必须在□前面，否则跳步
4. 看 changelog — 行数≥10，不能是空壳