# 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 个文件 → 停止**。