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

docs: consolidate archive, SSOT guide, and agent entry stubs

Browse Source 
Move line-walk/delta/phase2/frontend audits and legacy memory into
docs/archive/, add functional development SSOT, thin AGENTS/CLAUDE stubs,
and regenerate changelog/audit indexes via consolidate_docs.py.
This commit is contained in:
Nexus Deploy
2026-06-04 23:01:03 +08:00
parent b866e944ab
commit 0100ab2582
181 changed files with 6474 additions and 1502 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursorrules
+27 -160
View File
@@ -1,176 +1,43 @@
# Nexus 6.0 — Cursor Rules
# Nexus 6.0 — Cursor 速查
## 项目概述
Nexus 是一个 2000+ 服务器运维管理平台。技术栈：FastAPI + Async SQLAlchemy + Redis + WebSocket + Telegram (后端)，Vue 3 + Vuetify 4 + TypeScript SPA (前端，14页面)。项目 ~99% 完成。
> SSOT: [docs/project/nexus-functional-development-guide.md](docs/project/nexus-functional-development-guide.md)
> Handoff: [docs/project/AI-HANDOFF-2026-06-03.md](docs/project/AI-HANDOFF-2026-06-03.md)
## 基本信息
- 仓库: 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
- SSH 别名: ssh nexus (key: id_rsa_nexus)
## 栈
## 目录结构
```
Nexus/
├── server/ ← FastAPI 后端 (Clean Architecture 4层)
│ ├── api/ ← API 路由
│ ├── domain/ ← SQLAlchemy 模型 (14+张表)
│ ├── infrastructure/← SSH 连接池 + Redis + Telegram
│ ├── background/ ← 后台任务
│ └── config.py ← Pydantic Settings + MySQL 覆盖
├── frontend/ ← Vue 3 + Vuetify 4 + TypeScript SPA
│ └── src/pages/ ← 14 个页面组件
├── web/app/ ← Vite 构建输出 (后端 StaticFiles 挂载点)
├── deploy/ ← Supervisor + Nginx + 健康检查脚本
├── docs/ ← 设计文档/审计/changelog
└── .env ← NOT IN GIT (安装向导生成)
```
FastAPI + Async SQLAlchemy + Redis · Vue 3 + Vuetify 4 SPA（14 页）· Vite → `web/app/`
## 实现原则（强制）
## 环境（勿在仓库写密码）
**所有设计和实现都必须是完美实现。**
- 生产: `https://api.synaglobal.vip` · 端口 8600 · `ssh nexus`
- 本地: `~/Nexus` 或 `$NEXUS_ROOT` · 见 [linux-dev-paths.md](docs/project/linux-dev-paths.md)
- 凭据: 仅 `.env`（不入 git）
- ❌ 不允许为了实现而实现 — 每一行代码必须有明确的目的和质量标准
- ❌ 不允许降级实现 — 不得以「先用着」为由降低安全、架构或代码质量标准
- ❌ 不允许妥协实现 — 不得在发现问题后选择绕过而非根治
- ❌ 不允许留技术债 — 发现问题必须当场修复，不得标注 TODO/FIXME 延后
- ✅ 无法完美实现时必须停下来与用户交流后再换方案，不得擅自从权
## 关键路径
## 安全铁律（强制）
| 用途 | 路径 |
|------|------|
| 后端入口 | `server/main.py` |
| 前端路由 | `frontend/src/router/index.ts` |
| API 客户端 | `frontend/src/api/index.ts` |
| Sync | `server/api/sync_v2.py` |
| 门控 | `deploy/pre_deploy_check.sh` |
| 本地验证 | `bash scripts/local_verify.sh` |
- ❌ 禁止明文密码出现在前端 JS 变量、localStorage、URL 参数中
- ❌ 禁止静默吞错 — except 块不得空 pass 或 return None 掩盖异常
- ❌ 禁止硬编码密钥/密码/Token — 必须走配置或环境变量
- ❌ 禁止 f-string 拼 SQL — 必须参数化查询
- ❌ 禁止未验证的用户输入拼入 shell 命令 — 必须用 shlex.quote() 或 subprocess 参数化
- ✅ 敏感操作必须二次验证身份（re-auth pattern）
- ✅ API 响应不得返回密码/密钥明文 — 用 password_set 布尔标记
- ✅ 所有 CUD 操作必须记录审计日志
## 铁律
## 文档纪律（强制）
见 `.cursor/rules/perfect-implementation.mdc` · `nexus-security.mdc` — 完美实现、无静默吞错、无明文密钥、CUD 审计。
- 新功能/架构变更：先写 docs/design/specs/YYYY-MM-DD-*-design.md，再写代码
- 开发前：写 docs/design/plans/ 或 docs/reports/ 技术文档
- 项目缺文档的模块：改动时一并补全
- 每次修改：在 docs/changelog/YYYY-MM-DD-*.md 留 changelog（行数≥10，不能空壳）
## 部署
## 强制文件修改流程（不可跳步）
```
实现 → WSL本地验证 → ★审计8步★ → 部署 → 健康检查 → 浏览器验证 → changelog
```
进度条（每次改代码必须输出）：
```
□实现 □WSL验证 □审计8步 □部署 □健康检查 □浏览器验证 □changelog
```
审计8步：登记→全文Read→规则扫描H→Closure表→入口表→输入→Sink→归类→DoD
## 部署流程
### 后端部署
```bash
git push origin main
ssh nexus "cd /www/wwwroot/api.synaglobal.vip && git fetch --all && git reset --hard origin/main && supervisorctl restart nexus"
ssh nexus "sleep 3 && curl -s http://127.0.0.1:8600/health" # 预期: ok
bash deploy/pre_deploy_check.sh && bash deploy/deploy-production.sh
```
### 前端部署
```bash
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 && npx vite build` → tar/scp（见 `deploy/deploy-frontend.sh`）
## 进度条（改代码时输出）
```
### 本地开发
```bash
cd frontend && npm run dev # http://localhost:3000/app/
□实现 □本地验证 □审计8步 □部署 □健康检查 □浏览器验证 □changelog
```
## 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门 — 审计文件包含实际改动文件清单
## 已确认的关键决策
| 不可改项 | 原因 |
|---------|------|
| API_KEY | 加密一致性 + 子服务器认证 |
| SECRET_KEY | 加密回退密钥 |
| DATABASE_URL | 启动必需 |
| ENCRYPTION_KEY | 凭据加密 |
| 可改项 | 说明 |
|--------|------|
| system_name/title | 前端显示 |
| pool_size/overflow | 安装向导自动推荐 |
| redis_url | Redis 连接 |
| 告警阈值 | 默认 80% |
| Telegram 配置 | 告警推送 |
## 关键文件速查
| 用途 | 文件路径 |
|------|----------|
| 后端入口 | server/main.py |
| 数据模型 | server/domain/models/__init__.py |
| JWT 认证 | server/api/auth_jwt.py |
| 登录 API | server/api/auth.py |
| WebSSH | server/api/webssh.py |
| WebSocket | server/api/websocket.py |
| 设置 CRUD | server/api/settings.py |
| 服务器 CRUD | server/api/servers.py |
| 快捷命令 | 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 |
## 已知待续事项（2026-06-01）
已修复：批量 Agent、JWT 60min+refresh、script-callback API Key、未知心跳丢弃、Admin 列迁移 — 见 `docs/changelog/2026-06-01-bug-remediation.md`。
| 优先级 | 问题 | 文件 |
|--------|------|------|
| P2 | 422 handler 是否精简 | server/main.py |
| UX | 终端命令栏高亮对齐 | TerminalPage.vue |
| 验收 | 告警/Telegram、WebSSH、Sync、三层守护 | 见 handoff §八 |
## 协作方式（单 Agent）
- 只与用户直接对话，不分派管理组/工程部/测试部/产品部/设计部，不自动加载 Skill 包。
- 规范见 `.cursor/rules/no-department-agents.mdc`、`standards/`、`docs/design/`。
## 测试分工（强制）
**由 Agent 完成全部测试与修复验证；用户仅在 Agent 报告通过后做最终验收。**
Agent 在宣称「已修复 / 可交付」前必须自行完成（有证据：命令输出、生产 URL、浏览器抽测记录）：
1. 本地：`ruff` / `import server.main` / `frontend` type-check（若改前端）
2. 能跑则跑：`pytest tests/` 或 `tests/test_api.py`
3. 生产或 WSL：`/health`、`test_api`、关键页面浏览器验证
4. 更新 `docs/changelog/` + 必要时 `docs/reports/*-verification.md`
**禁止**把「请你试一下」「请人工确认」当作交付终点；未验证不得让用户代测 bug 是否修好。
用户终验：Agent 提交「验收清单」后，用户做最后一遍业务确认即可。
## 用中文回复