NEXUS API Management

NEXUS 是一个包含「接口管理 UI + 后端 API + 前端代码生成器」的完整工程：

• 后端维护 Service / API / 参数树与版本迭代（可选 Owner 迭代审批 与 变更审计）；
• 前端提供可视化管理界面（含待审列表 /approvals）；
• CLI 可在任意前端项目中生成 TypeScript 调用代码（可注入 axios/fetch 等 request）。

产品说明（PRD）已整理到 docs/PRD.md。

目录结构

• BACKEND-NEXUS：后端（Python + Robyn）
• FRONTEND-NEXUS：前端（React + Vite）
• nexus-api-codegen：前端代码生成器（Node CLI，命令 nexus）

快速开始（本机开发）

1) 启动后端（BACKEND-NEXUS）

依赖：Python（见 BACKEND-NEXUS/pyproject.toml 里的 requires-python）、uv、PostgreSQL（以及按需的 Redis）。

1. 安装依赖（首次运行）：

cd BACKEND-NEXUS
uv sync

2. 准备环境变量（复制 BACKEND-NEXUS/.env.example 为 BACKEND-NEXUS/.env，字段说明见 BACKEND-NEXUS/README.md）。

• 默认端口：PORT=1024

3. 初始化数据库（首次搭建）：

   1. 安装并启动 PostgreSQL

   2. 创建数据库用户与库（示例以 .env.example 默认值为准：用户/库名都是 cam）：

   -- 进入 psql（以超级用户 postgres 为例）
   -- psql -U postgres
   
   CREATE USER cam WITH PASSWORD 'YOUR_PASSWORD';
   CREATE DATABASE cam OWNER cam;
   GRANT ALL PRIVILEGES ON DATABASE cam TO cam;

3. 在 BACKEND-NEXUS/.env.example 的基础上填写 DATABASE_* 与 DATABASE_URI

4. 创建表结构（首次建表建议用 create_all）：

cd BACKEND-NEXUS
uv run python -m database.init_db

4. 数据库迁移（模型变更时）：

目前仓库提供了迁移脚本（见 BACKEND-NEXUS/database/db-migrate.ps1），用于在你修改 database/models.py 后生成/执行迁移。 若你的本地环境已配置好 Alembic（alembic.ini / 迁移目录等），可直接运行：

cd BACKEND-NEXUS
./database/db-migrate.ps1

5. 启动开发环境（热重载）：

cd BACKEND-NEXUS
./run-dev.ps1

也可以在仓库根目录直接执行 run-dev.ps1，一次同时启动前后端。

后端默认监听：http://127.0.0.1:1024（根路径 / 返回 OK）。

2) 启动前端（FRONTEND-NEXUS）

前端默认端口为 9000，并且默认会请求本机后端 http://127.0.0.1:1024。

1. 安装依赖：

cd FRONTEND-NEXUS
npm install
# 或 pnpm install

2. 启动：

npm run dev
# 或 pnpm dev

前端开发环境变量已在 FRONTEND-NEXUS/.env.development 中给出：

• VITE_API_BASE_URL=http://127.0.0.1:1024
• VITE_FE_PORT=9000

注意：后端 CORS 白名单默认允许 http://localhost:9000 与 http://127.0.0.1:9000。

3) 使用代码生成器（nexus-api-codegen）

生成器是一个 CLI：你在哪个目录执行 nexus ...，就会在那个目录生成/读取 nexus.config.json，并把代码输出到该配置的 outDir。

在本机安装/构建（一次性）

cd nexus-api-codegen
npm install
npm run build

让 nexus 命令全局可用（推荐本机用）

在 nexus-api-codegen 目录执行：

npm link

之后你在任意项目目录都可以直接用：nexus -h / nexus --help。

方式 2：装到某个项目里（更可复现/不污染全局）

1. 在生成器目录打包：

cd e:\API-Management\nexus-api-codegen
npm run build
npm pack

会生成一个类似 nexus-api-codegen-1.7.0.tgz 的文件。

2. 在另一个前端项目根目录安装该 tgz（建议作为开发依赖）：

cd <你的前端项目根目录>
npm i -D <生成的tgz文件路径>

3. 用 npx 调用：

  npx nexus init
  npx nexus update

也可以用 `npx nexus -h` / `npx nexus --help` 查看全部命令与参数。

在另一个独立前端项目里生成代码

在你的“目标前端项目根目录”执行：

nexus login
nexus init
nexus list     # 列出所有服务
nexus add <service_name>:<service_uuid>@latest
nexus update

生成器会默认输出到 nexus.config.json 里的 outDir（默认 src/nexus-auto-generate）。

注意：nexus update 会递归删除并重建 outDir，请确保该目录仅用于生成产物。

生成器请求地址

当前生成器请求后端的 baseURL 在 nexus-api-codegen/src/request/index.ts 中配置；本仓库默认按本机后端 http://127.0.0.1:1024 使用。

常用脚本

后端（Windows PowerShell）：

• 开发：BACKEND-NEXUS/run-dev.ps1
• 生产：BACKEND-NEXUS/run-prod.ps1
• 数据库迁移：BACKEND-NEXUS/database/db-migrate.ps1

前端：

• 开发：cd FRONTEND-NEXUS && pnpm dev
• 构建：cd FRONTEND-NEXUS && pnpm build

生成器：

• 构建：cd nexus-api-codegen && npm run build

更多文档

• 产品说明（PRD）：docs/PRD.md（迭代审批见 PRD §6.7）
• 阿里云部署（含自动更新）：docs/DEPLOY-ALIYUN.md 第 14 节
• GitHub Actions 补充说明：docs/GITHUB-ACTIONS-DEPLOY.md
• 服务器 git pull 失败（手动上传后）：docs/DEPLOY-SERVER-GIT.md
• 后端说明：见 BACKEND-NEXUS/README.md
• 生成器说明：见 nexus-api-codegen/README.md