From f71da47ccf7b4aa167a66392d1ac47dbc8797720 Mon Sep 17 00:00:00 2001 From: Nexus Deploy Date: Sat, 6 Jun 2026 00:14:34 +0800 Subject: [PATCH] docs: add root README for Gitea product page and install scripts --- README.md | 206 ++++++++++++++++++ .../2026-06-05-gitea-readme-product.md | 24 ++ 2 files changed, 230 insertions(+) create mode 100644 README.md create mode 100644 docs/changelog/2026-06-05-gitea-readme-product.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..e20552ea --- /dev/null +++ b/README.md @@ -0,0 +1,206 @@ +# 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： +- 分支：`main` +- 提交前请通过 `deploy/pre_deploy_check.sh`（7 道门控） + +**注意**：`deploy/nexus-1panel.secrets.sh`、根目录 `.env`、`SECRETS.md` 含敏感信息，**勿提交到 Git**。生产密钥仅保存在服务器与本机私密文档中。 diff --git a/docs/changelog/2026-06-05-gitea-readme-product.md b/docs/changelog/2026-06-05-gitea-readme-product.md new file mode 100644 index 00000000..1081fc9e --- /dev/null +++ b/docs/changelog/2026-06-05-gitea-readme-product.md @@ -0,0 +1,24 @@ +# 2026-06-05 — Gitea 仓库产品说明 README + +## 摘要 + +在仓库根目录新增 `README.md`，作为 Gitea 项目页产品说明：项目简介、公共仓库一键安装、NX 上帝菜单、deploy/docker/scripts 脚本索引、迁机与全新安装对照、文档链接。 + +## 动机 + +Gitea 仓库页原先无根 README（Description 为空），运维无法在仓库首页看到 `curl | bash` 与脚本用法。 + +## 涉及文件 + +- `README.md`（新建） +- `docs/changelog/2026-06-05-gitea-readme-product.md` + +## 迁移 / 重启 + +无。仅文档。 + +## 验证 + +1. 本地打开 `README.md` 链接与脚本路径存在。 +2. `git push origin main` 后在 首页应渲染 README。 +3. 确认 `raw/branch/main/deploy/quick-install.sh` 可匿名下载（200 + `#!/`）。