Nexus/README.md

# Nexus 6.0

面向 **2000+ 服务器** 的运维管理平台：FastAPI + Async SQLAlchemy + Redis + WebSocket + Telegram（后端），Vue 3 + Vuetify 4 + TypeScript SPA（前端 14 页）。

| 项 | 说明 |
|----|------|
| 生产域名 | https://api.synaglobal.vip |
| 默认安装目录 | `/opt/nexus` |
| 后端端口 | `8600`（1Panel 反代到 `http://127.0.0.1:8600`） |
| 安装向导 | `https://你的域名/app/install.html` |
| 文档索引 | [docs/README.md](docs/README.md) |

---

## 一键安装（公共仓库，推荐）

在 **root** 登录的 Linux 服务器上执行（仿 [1Panel](https://1panel.cn/) 风格，无需 Gitea Token）：

```bash
curl -fsSL "http://66.154.115.8:3000/admin/Nexus/raw/branch/main/deploy/quick-install.sh" | bash
```

指定资源档位（`1c4g` / `2c8g` 默认 / `4c16g`）：

```bash
curl -fsSL "http://66.154.115.8:3000/admin/Nexus/raw/branch/main/deploy/quick-install.sh" | bash -s -- --profile 4c16g
```

可选：先下载再执行（便于审计脚本内容）：

```bash
curl -fsSL "http://66.154.115.8:3000/admin/Nexus/raw/branch/main/deploy/quick-install.sh" -o /tmp/quick-install.sh
bash /tmp/quick-install.sh --profile 2c8g
```

**raw 地址说明**（匿名可访问，须返回 `#!/` 而非 HTML 404）：

- `http://66.154.115.8:3000/admin/Nexus/raw/branch/main/deploy/<脚本名>`
- 等价：`http://66.154.115.8:3000/raw/main/deploy/<脚本名>`

安装完成后在浏览器打开安装向导，完成 `.env` / MySQL / 管理员初始化。

---

## 已 clone 到本机（跳过再次拉仓）

```bash
cd /opt/nexus && git pull
bash deploy/install-nexus-fresh.sh --skip-clone
```

或交互菜单：

```bash
nx
# 选「全新安装」或子命令: nx install-fresh
```

---

## NX 运维菜单（装好后）

安装脚本会向 `PATH` 注册：

| 命令 | 作用 |
|------|------|
| `nx` | 交互主菜单（安装 / 升级 / 健康检查） |
| `nx god` | **上帝菜单**：重启 Python、全栈重启、日志、升级、备份等 |
| `nexus-fresh` | 等同 `install-nexus-fresh.sh` |
| `nexus-install` | 快捷安装入口 |

常用子命令：

```bash
nx                    # 主菜单
nx god                # 上帝运维菜单
nx install-fresh      # 全新空库安装 → /app/install.html
nx install-auto       # 非交互安装（需已配置密钥，默认 2c8g）
nx health             # 健康检查 / 端口预检
```

底层仍可直接调用：`bash deploy/nexus-1panel.sh install|upgrade|check|ports`

---

## 部署脚本一览（`deploy/`）

### 1Panel + Docker 生产（主路径）

| 脚本 | 用途 |
|------|------|
| [quick-install.sh](deploy/quick-install.sh) | **公共仓库 curl 入口**；clone + 调用全新安装 |
| [install-nexus-fresh.sh](deploy/install-nexus-fresh.sh) | 全新安装（空库 → 安装向导）；支持 `--skip-clone`、`--profile` |
| [nexus-1panel.sh](deploy/nexus-1panel.sh) | 迁机 / 升级 / 检查 / 端口预检；可被 `nx` 调用 |
| [nx](deploy/nx) | 交互主菜单 + 上帝菜单 |
| [install-1panel-docker.sh](deploy/install-1panel-docker.sh) | 转调 `nx` 的 Docker 安装包装 |
| [upgrade-1panel-docker.sh](deploy/upgrade-1panel-docker.sh) | 转调 `nx` 的升级包装 |
| [download-install-fresh.sh](deploy/download-install-fresh.sh) | 从 Gitea API/raw 下载安装脚本（私有库需 Token） |

详细说明：[deploy/README-1panel.md](deploy/README-1panel.md)

### Docker Compose 与档位

| 路径 | 用途 |
|------|------|
| [docker/docker-compose.prod.yml](docker/docker-compose.prod.yml) | 生产 Compose（变量化 CPU/内存） |
| [docker/profiles/1c4g.env](docker/profiles/1c4g.env) | 1 核 4G |
| [docker/profiles/2c8g.env](docker/profiles/2c8g.env) | 2 核 8G（默认） |
| [docker/profiles/4c16g.env](docker/profiles/4c16g.env) | 4 核 16G |
| [docker/README.md](docker/README.md) | 镜像与本地开发说明 |

安装参数：`--profile 1c4g|2c8g|4c16g`

### 经典 SSH / Supervisor 部署（宝塔 / 裸机）

| 脚本 | 用途 |
|------|------|
| [install.sh](deploy/install.sh) | 传统安装 |
| [upgrade.sh](deploy/upgrade.sh) | 拉代码 + 重启 |
| [deploy-on-server.sh](deploy/deploy-on-server.sh) | 服务器侧部署 |
| [deploy-production.sh](deploy/deploy-production.sh) | 生产发布流程 |
| [deploy-frontend.sh](deploy/deploy-frontend.sh) | 构建 Vue 前端并打包到 `web/app/` |
| [pre_deploy_check.sh](deploy/pre_deploy_check.sh) | **7 道门控**（changelog / 审计 / 测试 / ruff / import / bandit / review） |
| [health_monitor.sh](deploy/health_monitor.sh) | cron 健康检查，`/health` 失败重启 |
| [db_backup.sh](deploy/db_backup.sh) | MySQL 备份（30 天保留） |
| [run_test_api_on_server.sh](deploy/run_test_api_on_server.sh) | 服务器上跑 `test_api` |
| [uninstall.sh](deploy/uninstall.sh) | 卸载 |
| [check_shell_eol.sh](deploy/check_shell_eol.sh) | Shell 脚本 EOL 检查 |

### 本地与验收

| 脚本 | 用途 |
|------|------|
| [scripts/local_verify.sh](scripts/local_verify.sh) | L2b 本地验证（ruff / import / 前端 typecheck 等） |
| [scripts/run_nexus_acceptance.py](scripts/run_nexus_acceptance.py) | L4 验收 |
| [verify.py](verify.py) | 快速验证入口 |

---

## 迁机 vs 全新安装

| 场景 | 做法 |
|------|------|
| **新 VPS、空 MySQL** | `curl \| bash` 或 `install-nexus-fresh.sh` → 浏览器走完安装向导 |
| **已有数据、换机** | `nexus-1panel.sh install`（带备份/恢复逻辑）或 `nx` 迁机流程 |
| **仅升级代码/镜像** | `nx` → 升级，或 `upgrade-1panel-docker.sh` / `nexus-1panel.sh upgrade` |
| **不必重装整台 VPS** | 在 `/opt/nexus` 内 `git pull` + `nx god` 重启即可 |

---

## 技术栈与目录

```
Nexus/
├── server/          # FastAPI 后端（Clean Architecture）
├── frontend/      # Vue 3 + Vuetify 4 SPA → 构建到 web/app/
├── web/app/         # 静态资源挂载点（构建产物 gitignore）
├── deploy/          # 安装、门控、健康检查、运维脚本
├── docker/          # Compose、镜像、profiles
├── docs/            # 设计 / changelog / 审计 / 报告
├── tests/           # API 与集成测试
└── standards/       # 开发与逐行审计标准
```

启动模式：

- **无 `.env`**：仅 `/api/install/` + 安装页（安装模式）
- **有 `.env`**：完整业务 API + 后台任务

---

## 开发

```bash
# 后端（需 .env）
pip install -r requirements.txt
uvicorn server.main:app --reload --port 8600

# 前端
cd frontend && npm run dev   # http://localhost:3000/app/
```

Linux 路径与本地联调：[docs/project/linux-dev-paths.md](docs/project/linux-dev-paths.md) · [UBUNTU-DEV-README.txt](UBUNTU-DEV-README.txt)

---

## 文档与规范

| 文档 | 说明 |
|------|------|
| [docs/README.md](docs/README.md) | 文档总索引（SSOT） |
| [docs/project/nexus-functional-development-guide.md](docs/project/nexus-functional-development-guide.md) | 功能 / API / 14 页 |
| [docs/project/AI-HANDOFF-2026-06-03.md](docs/project/AI-HANDOFF-2026-06-03.md) | 当前会话接续 |
| [AGENTS.md](AGENTS.md) · [CLAUDE.md](CLAUDE.md) | Agent 薄入口 |

变更记录：`docs/changelog/` · 门控审计：`docs/audit/`

---

## 许可与仓库

- Gitea：<http://66.154.115.8:3000/admin/Nexus>
- 分支：`main`
- 提交前请通过 `deploy/pre_deploy_check.sh`（7 道门控）

**注意**：`deploy/nexus-1panel.secrets.sh`、根目录 `.env`、`SECRETS.md` 含敏感信息，**勿提交到 Git**。生产密钥仅保存在服务器与本机私密文档中。