docs: 重写 README，明确 Migu2.0 与 SimpleLite 分仓协作

- 补充仓库定位、目录结构、SimpleLite 协作链路（YARP 代理 /api/sl、/vr）与开发机快速启动步骤
2026-05-29 23:53:15 +08:00
parent 3356c2cd12
commit 34635dca05
1 changed files with 107 additions and 46 deletions
@@ -1,68 +1,129 @@
 # Migu2.0

-「**迷毂 · 智能调度平台**」后端仓库。由原 Simple-FR  monorepo 中的 `Platform.Server` 拆出并重命名为 **`MiGu.Server`**。
+迷毂智能调度平台主仓库（平台后端 + 平台前端）。  
+该仓库承接原 `Simple` 仓库中的平台层能力，当前以 `MiGu.Server` 作为统一入口；调度内核 `SimpleLite` 仍在相邻仓库 `../Simple` 中维护。

-## 仓库结构
+## 仓库定位

-```
+- **平台后端**：`MiGu.Server`（ASP.NET Core 8 + YARP，默认 `:8080`）
+- **平台前端**：`frontends/apps/simple-platform-vue`（Vue 3 + Vite）
+- **调度内核**：`SimpleLite`（不在本仓库，位于 `../Simple/SimpleLite`）
+- **运行模式**：用户登录后由 `MiGu.Server` 按启动模式拉起 `SimpleLite.exe`
+
+## 目录结构
+
+```text
 Migu2.0/
-├── MiGu.Server/          # ASP.NET Core 8 主入口（Kestrel :8080 + YARP + 静态 SPA）
-│   ├── wwwroot/          # 已构建的平台前端（克隆即可运行）
-│   └── data/             # 运行时配置持久化（config-*.json，git 忽略）
-├── frontends/            # 平台 Vue 源码（simple-platform-vue）
-├── build-platform-frontend.bat
-├── ARCHITECTURE.md       # 总体架构（已从 Simple 移植并更新路径）
+├── MiGu.Server/                   # 平台后端入口工程
+│   ├── Controllers/               # Auth/Config/Ops/Health 等 API
+│   ├── Launcher/                  # SimpleLite 子进程拉起与健康探测
+│   ├── Auth/                      # JWT / 用户鉴权 / 内部 token
+│   ├── Configs/                   # 平台配置中心模型与存取
+│   ├── wwwroot/                   # 已构建前端静态资源（部署用）
+│   ├── appsettings.json           # 启动、YARP、SimpleLite 路径配置
+│   └── README.md                  # 后端详细说明
+├── frontends/                     # 平台前端源码 workspace
+│   └── apps/simple-platform-vue/
+├── build-platform-frontend.bat    # 一键构建前端并同步到 MiGu.Server/wwwroot
+├── MiGu.Server.sln
+├── ARCHITECTURE.md
 ├── PLATFORM_V3_CHANGES.md
-└── Doc/                  # 代码复审记录
+└── Doc/
 ```

-## 与 Simple 仓库的关系
+## 与 SimpleLite 的关系

-| 组件 | 本仓库 | Simple 仓库 (`../Simple`) |
-|------|--------|---------------------------|
-| 平台后端 | **MiGu.Server** | 已移除 `Platform.Server` |
-| 调度内核 | — | SimpleLite |
-| 前端源码 | `frontends/apps/simple-platform-vue` | 已迁出 |
-| 前端构建 | `.\build-platform-frontend.bat` → `MiGu.Server/wwwroot` | — |
+`Migu2.0` 与 `SimpleLite` 是分仓协作关系：

-登录后 `MiGu.Server` 按所选启动模式拉起 **SimpleLite.exe**。开发环境路径见 `MiGu.Server/appsettings.Development.json`（默认指向 `../Simple/SimpleLite/bin/Debug`）。
+- `MiGu.Server` 提供登录、权限、配置中心、平台 UI 托管与网关能力
+- `SimpleLite` 提供调度内核、投影接口、3D/仿真运行时能力
+- 两者通过以下链路协作：
+  - **进程编排**：`MiGu.Server` 登录后调用 `SimpleLiteLauncher` 拉起 `SimpleLite.exe`
+  - **接口代理**：`/api/sl/*` 通过 YARP 转发到 `http://127.0.0.1:8222/`
+  - **3D 页面代理**：`/vr/*` 转发到 `http://127.0.0.1:8223/`

-## 快速启动
+默认开发路径（可改）在 `MiGu.Server/appsettings.json`：

-```pwsh
-cd MiGu.Server
-dotnet run
-# 浏览器: http://localhost:8080/login
-# 默认账号: admin/admin、ops/ops（仅开发用）
+```json
+"SimpleLite": {
+  "Enabled": true,
+  "ExecutablePath": "..\\..\\Simple\\SimpleLite\\bin\\Debug\\SimpleLite.exe",
+  "WorkingDirectory": "..\\..\\Simple\\SimpleLite\\bin\\Debug",
+  "ProjectionPort": 8222
+}
 ```

-仅调试平台 UI、不拉 SimpleLite：将 `appsettings.json` 中 `SimpleLite.Enabled` 设为 `false`。
+## 快速启动（开发机）

-## 配置 SimpleLite（开发机）
+### 1) 先编译 SimpleLite

-1. 在 Simple 仓库编译内核：
-
-```pwsh
+```powershell
 cd ..\Simple
 dotnet build SimpleLite\SimpleLite.csproj -c Debug
 ```

-2. 打开 **`MiGu.Server/appsettings.json`**，找到 **`"SimpleLite"`**，确认 `ExecutablePath` 指向你的 `SimpleLite.exe`（默认相对路径 `..\\..\\Simple\\SimpleLite\\bin\\Debug\\SimpleLite.exe`）。也可访问 **http://localhost:8080/api/health/simplelite** 查看是否解析成功。
+### 2) 启动 MiGu.Server

-3. 启动 MiGu.Server 后登录，选择「本地 + Web」或「仅 Web」即可拉起 SimpleLite。
-
-详细说明见 [MiGu.Server/README.md — 配置 SimpleLite 路径](MiGu.Server/README.md#配置-simplelite-路径)。
-
-## 文档
-
- [MiGu.Server/README.md](MiGu.Server/README.md) — 部署、YARP、鉴权、联调
- [ARCHITECTURE.md](ARCHITECTURE.md) — 架构总览
- [PLATFORM_V3_CHANGES.md](PLATFORM_V3_CHANGES.md) — V3 变更说明
-
-## 更新前端
-
-```pwsh
-# 在本仓库根目录
-.\build-platform-frontend.bat
-# 产物同步到 MiGu.Server\wwwroot\
+```powershell
+cd ..\Migu2.0\MiGu.Server
+dotnet run
 ```
+
+打开 `http://localhost:8080/login`，使用默认开发账号：
+
+- `admin / admin`
+- `ops / ops`
+
+> 仅调试平台页面、不拉起内核：将 `MiGu.Server/appsettings.json` 中 `SimpleLite.Enabled` 改为 `false`。
+
+## 前端构建与发布
+
+仓库根目录提供脚本：
+
+```powershell
+cd E:\Work\Core\Simple-FR\Migu2.0
+.\build-platform-frontend.bat
+```
+
+该脚本会执行三步：
+
+1. 在 `frontends` 安装依赖（pnpm 优先）
+2. 构建 `simple-platform-vue`
+3. 将 `dist` 同步到 `MiGu.Server/wwwroot`
+
+仅构建不同步启动后端：
+
+```powershell
+.\build-platform-frontend.bat --no-start
+```
+
+## 部署说明（生产）
+
+- 发布内容至少包含：
+  - `MiGu.Server` 可执行文件及依赖
+  - `MiGu.Server/wwwroot` 静态资源
+- 生产环境务必覆盖以下配置（不要使用默认值）：
+  - `Jwt.Secret`
+  - `Internal.Token`
+  - `Auth.Users.*.Password`
+  - `SimpleLite.ExecutablePath` / `WorkingDirectory`（按部署实际路径）
+
+推荐通过环境变量覆盖（`__` 表示层级）：
+
+```powershell
+$env:Jwt__Secret = "<strong-secret>"
+$env:Internal__Token = "<internal-token>"
+$env:Auth__Users__admin__Password = "<strong-password>"
+```
+
+## 常见检查点
+
+- `http://localhost:8080/api/health`：后端健康
+- `http://localhost:8080/api/health/simplelite`：SimpleLite 路径与端口诊断
+- 访问平台时若出现 `502`：通常表示 `SimpleLite` 的 `8222` 未就绪或未启动
+
+## 相关文档
+
+- `MiGu.Server/README.md`：后端细节（鉴权、YARP、启动参数、联调）
+- `ARCHITECTURE.md`：整体架构说明
+- `PLATFORM_V3_CHANGES.md`：V3 变更记录