97 lines
3.8 KiB
Markdown
97 lines
3.8 KiB
Markdown
|
# Nexus 6.0 — Agent 入口（薄 stub）
|
|||
|
|
|
|||
|
|
> **长文 SSOT**: [docs/project/nexus-functional-development-guide.md](docs/project/nexus-functional-development-guide.md) + [附录](docs/project/nexus-functional-development-guide-appendix.md)
|
|||
|
|
> **会话接续**: [docs/project/AI-HANDOFF-2026-06-03.md](docs/project/AI-HANDOFF-2026-06-03.md)
|
|||
|
|
> **文档总索引**: [docs/README.md](docs/README.md)
|
|||
|
|
|
|||
|
|
## 项目概要
|
|||
|
|
|
|||
|
|
Nexus：2000+ 子机运维平台。后端 FastAPI + MySQL + Redis；前端 **Vue 3 + Vuetify 4 + TypeScript SPA**（15 页，`frontend/src/pages/`）；构建输出 `web/app/`；安装向导 `web/app/install.html`。
|
|||
|
|
|
|||
|
|
## 本地开发
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
docker compose up -d mysql redis
|
|||
|
|
bash scripts/start-dev.sh # API :8600
|
|||
|
|
bash scripts/local_verify.sh # L2b
|
|||
|
|
cd frontend && npm run dev # :3000/app/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
路径见 [linux-dev-paths.md](docs/project/linux-dev-paths.md)。
|
|||
|
|
|
|||
|
|
## Git（仅本机快照）
|
|||
|
|
|
|||
|
|
- 本地 `git commit` 用于回滚；**不 `git push`**（除非你明确要求）。
|
|||
|
|
- 已移除 `origin` 跟踪，避免误推；原远程：`http://66.154.115.8:3000/admin/Nexus.git`（需恢复时说一声）。
|
|||
|
|
- `.env`、`SECRETS.md`、`*.pem` 已在 `.gitignore`，**勿提交**。
|
|||
|
|
- 改代码仍写 `docs/changelog/YYYY-MM-DD-*.md`（≥10 行）。
|
|||
|
|
- 用户说「提交快照 / commit」时执行。
|
|||
|
|
|
|||
|
|
## 强制约束
|
|||
|
|
|
|||
|
|
- 完美实现：`.cursor/rules/perfect-implementation.mdc`
|
|||
|
|
- 安全 / 后端 / 前端：`.cursor/rules/nexus-*.mdc`
|
|||
|
|
- 改代码必 `docs/changelog/YYYY-MM-DD-*.md`（≥10 行）
|
|||
|
|
- 测试由 Agent 完成；用户只做终验
|
|||
|
|
|
|||
|
|
## 不可改
|
|||
|
|
|
|||
|
|
`API_KEY` · `SECRET_KEY` · `ENCRYPTION_KEY` · `DATABASE_URL`
|
|||
|
|
|
|||
|
|
## 部署
|
|||
|
|
|
|||
|
|
默认 **本机 rsync → SSH 生产机**（不 push Gitea）：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
bash deploy/pre_deploy_check.sh
|
|||
|
|
bash deploy/deploy-production.sh # rsync + Docker upgrade --skip-git + 前端
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
可选：`NEXUS_DEPLOY_VIA_GIT=1` 恢复远程 `git pull`。仅 `git push` 当你明确要求时。
|
|||
|
|
|
|||
|
|
详情见功能指南 §17–18。
|
|||
|
|
|
|||
|
|
## 归档文档
|
|||
|
|
|
|||
|
|
历史审计合并卷：`docs/archive/README.md`
|
|||
|
|
|
|||
|
|
## 代码地图（Agent 先读这里，勿全库搜）
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
server/main.py # 路由挂载入口
|
|||
|
|
server/config.py # 配置（.env + settings 表）
|
|||
|
|
server/api/*.py # HTTP/WebSocket 路由（按模块拆分）
|
|||
|
|
server/application/ # 业务 services
|
|||
|
|
server/infrastructure/ # DB / Redis / SSH / Telegram
|
|||
|
|
server/domain/models/ # SQLAlchemy ORM
|
|||
|
|
frontend/src/pages/ # Vue 页面（15 页 SPA）
|
|||
|
|
frontend/src/router/ # Hash 路由 #/
|
|||
|
|
frontend/src/api/ # 前端 API 客户端
|
|||
|
|
frontend/e2e/ # Playwright 验收
|
|||
|
|
tests/test_*.py # pytest
|
|||
|
|
docs/project/ # 功能/部署 SSOT
|
|||
|
|
deploy/ # 生产部署脚本
|
|||
|
|
scripts/ # 本地验证、MCP、门控
|
|||
|
|
.cursor/mcp.json # mysql-mcp
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 问题 → 文件（常见锚点）
|
|||
|
|
|
|||
|
|
| 问什么 | 先看 |
|
|||
|
|
|--------|------|
|
|||
|
|
| 某 API 怎么实现 | `server/main.py` 找 router → `server/api/<模块>.py` |
|
|||
|
|
| 服务器列表/搜索/exec | `server/api/servers.py`, `server/api/scripts.py` |
|
|||
|
|
| 认证/JWT | `server/api/auth.py`, `server/api/dependencies.py` |
|
|||
|
|
| Agent 心跳/安装 | `server/api/agent.py` |
|
|||
|
|
| WebSSH/终端 | `server/api/webssh.py`, `server/api/terminal.py` |
|
|||
|
|
| 同步/文件/搜索 | `server/api/sync_v2.py`, `files.py`, `search.py` |
|
|||
|
|
| 设置/审计/告警 | `server/api/settings.py` |
|
|||
|
|
| 前端某页 UI | `frontend/src/router/index.ts` → `frontend/src/pages/` |
|
|||
|
|
| MySQL MCP | `.cursor/mcp.json`, `scripts/linux_mcp_mysql.sh` |
|
|||
|
|
| 本地开发路径 | `docs/project/linux-dev-paths.md` |
|
|||
|
|
| 14 页/API 全览 | `docs/project/nexus-functional-development-guide.md` §9–10 |
|
|||
|
|
|
|||
|
|
## 探索规则（省 token）
|
|||
|
|
|
|||
|
|
详见 `.cursor/rules/agent-exploration.mdc`。要点：**先地图再 Grep（带 path）→ Read ≤5 个文件 → 停止**。
|