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) |

生产 Docker 栈 **仅含 Nexus 容器**；MySQL / Redis 在宿主机或 1Panel 自行安装。

---

## 一键命令速查（root · 公共仓库 · 无需令牌）

| 场景 | 一条命令 |
|------|----------|
| **仅装 Nexus**（1Panel 已就绪） | `curl -fsSL "http://66.154.115.8:3000/admin/Nexus/raw/branch/main/deploy/quick-install.sh" \| bash` |
| **重装服务器**（1Panel + Docker + Nexus） | `curl -fsSL "http://66.154.115.8:3000/admin/Nexus/raw/branch/main/deploy/install-1panel-docker.sh" \| bash` |
| **一键更新**（pull + 重建镜像） | `curl -fsSL "http://66.154.115.8:3000/admin/Nexus/raw/branch/main/deploy/update.sh" \| bash` |
| **强制无缓存重建**（entrypoint 变更后） | `curl -fsSL ".../deploy/update.sh" \| bash -s -- --no-cache` |
| **已 clone** | `cd /opt/nexus && bash deploy/update.sh` |

指定资源档位（`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
```

**raw 地址**：`http://66.154.115.8:3000/admin/Nexus/raw/branch/main/deploy/<脚本名>`

安装完成后浏览器打开安装向导，完成 MySQL（自建）/ Redis（自建）/ 管理员初始化。

---

## NX 统一运维菜单

装好后在服务器任意目录输入 **`nx`**（`install` / `update` / 首次运行 `nx` 会自动注册 `/usr/local/bin/nx`）：

```bash
nx                  # 统一菜单：安装 + 一键更新 + 重启 + 日志 + 备份
nx update           # 非交互一键更新
nx update --no-cache
nx install-fresh    # 全新安装
nx health           # 健康检查
```

| 菜单项 | 作用 |
|--------|------|
| `[4] 一键更新` | pull + 重建 Docker 镜像（等同 `deploy/update.sh`） |
| `[5] 重启 Nexus` | 重启 Python 应用 |
| `[6] 日志` | 跟踪容器日志 |
| `[1][2]` | 安装 / 全新安装向导 |

全局命令（符号链接）：

| 命令 | 作用 |
|------|------|
| `nx` | 统一运维菜单 |
| `nexus-update` | 等同 `deploy/update.sh` |
| `nexus-fresh` | 等同 `install-nexus-fresh.sh` |
| `nexus-install` | 等同 `quick-install.sh` |

> `nx god` 已合并进 `nx` 主菜单，仍可作为兼容别名使用。

---

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

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

| 脚本 | 用途 | curl 入口 |
|------|------|-----------|
| [quick-install.sh](deploy/quick-install.sh) | **公共仓库安装入口** | ✅ 上表 |
| [install-1panel-docker.sh](deploy/install-1panel-docker.sh) | 1Panel + Docker + Nexus 全链 | ✅ 上表 |
| [install-nexus-fresh.sh](deploy/install-nexus-fresh.sh) | 全新空库 → 安装向导 | `bash deploy/install-nexus-fresh.sh --skip-clone` |
| [update.sh](deploy/update.sh) | **一键更新**（pull + 重建） | ✅ 上表 |
| [upgrade-1panel-docker.sh](deploy/upgrade-1panel-docker.sh) | 转调 `nexus-1panel.sh upgrade` | — |
| [nexus-1panel.sh](deploy/nexus-1panel.sh) | 安装 / 升级 / check / ports 底层 | — |
| [nx](deploy/nx) | **统一交互菜单** | `nx` |
| [uninstall-mysql-compose.sh](deploy/uninstall-mysql-compose.sh) | 卸载遗留 Compose MySQL 容器 | — |
| [uninstall-redis-compose.sh](deploy/uninstall-redis-compose.sh) | 卸载遗留 Compose Redis 容器 | — |
| [sync-install-wizard-to-container.sh](deploy/sync-install-wizard-to-container.sh) | 热同步 install.html 到容器 | — |
| [download-install-fresh.sh](deploy/download-install-fresh.sh) | 下载安装脚本（私有库可选 Token） | — |

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

### 更新选项

```bash
bash deploy/update.sh              # 默认：Git 拉取（若有）+ 重建容器
bash deploy/update.sh --check      # 仅查 Git
bash deploy/update.sh --no-cache   # 无缓存重建镜像
bash deploy/update.sh --no-backup  # 跳过 MySQL 备份
```

### Docker Compose 与档位

| 路径 | 用途 |
|------|------|
| [docker/docker-compose.prod.yml](docker/docker-compose.prod.yml) | 生产 Compose（**仅 nexus 服务**） |
| [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) | 镜像与本地开发说明 |

### 经典 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 道门控** |
| [health_monitor.sh](deploy/health_monitor.sh) | cron 健康检查 |
| [db_backup.sh](deploy/db_backup.sh) | MySQL 备份 |
| [uninstall.sh](deploy/uninstall.sh) | 卸载 |

---

## 迁机 vs 全新安装

| 场景 | 做法 |
|------|------|
| **新 VPS、空库** | `curl \| quick-install.sh` → 1Panel 自建 MySQL/Redis → `/app/install.html` |
| **已有数据、换机** | `nexus-1panel.sh install --from-env` 或 `nx` → 安装向导 |
| **仅升级代码/镜像** | `nx update` 或 `bash deploy/update.sh` |
| **不必重装 VPS** | `cd /opt/nexus && nx update` |

每台新服务器自动生成唯一 `NEXUS_SECRET_KEY` / `NEXUS_API_KEY` / `NEXUS_ENCRYPTION_KEY`（写入 `docker/.env.prod`，备份 `/root/.nexus-install-secrets-*.env`）。MySQL 密码由自建库时自行设定。

---

## 技术栈与目录

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

---

## 开发

```bash
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) | 文档总索引 |
| [docs/project/nexus-functional-development-guide.md](docs/project/nexus-functional-development-guide.md) | 功能 / API / 14 页 |
| [AGENTS.md](AGENTS.md) · [CLAUDE.md](CLAUDE.md) | Agent 薄入口 |

变更：`docs/changelog/` · 门控：`docs/audit/`

---

## 许可与仓库

| 用途 | 地址 |
|------|------|
| 仓库首页 | http://66.154.115.8:3000/admin/Nexus |
| Git | http://66.154.115.8:3000/admin/Nexus.git |

分支 `main` · 提交前跑 `deploy/pre_deploy_check.sh`（7 道门控）

**勿提交**：`deploy/nexus-1panel.secrets.sh`、根目录 `.env`、`SECRETS.md`