Files
2026-08-28 19:44:46 +08:00

310 lines
17 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Server-v3 架构设计(已定稿,基于用户 8 项决策)
> 状态:**定稿**。本文为 `FunGame.Server-v3` 的开发规格说明书,取代 `03-Server-v3-开发规划.md` 中的备选方案。
> 所有实现以本文为准;01/02 文档作为功能与 Core v3 能力参考。
---
## 0. 总体决策摘要
| # | 决策 | 结论 |
|---|---|---|
| 1 | 数据层 | **EF Core**,Provider 可切换:SQLite(默认/开发)与 MySQL(生产,Pomelo) |
| 2 | 管理入口 | **废弃控制台输入**,提供 **WebUI(React + Tailwind)** 服务器管理 |
| 3 | 启动方式 | **仅 WebSocket + WebAPI**(单一 ASP.NET Core 进程,同旧版 FunGameWebAPI 形态),移除 TCP Socket |
| 4 | 用户中心 | 重构为**细粒度权限角色模型**(RBAC + 权限点),**多端统一验证**(WebUI / WebAPI / WebSocket 共用同一 JWT 认证体系 + 刷新令牌 + 会话表) |
| 5 | 数据库/API | 数据表优化 + 追加新表;**每张数据表都有对应 CRUD REST 接口**(通用 CRUD 基类派生) |
| 6 | 加载项 | **始终热重载**(无普通加载模式);WebAPI 插件与服务器模组**合并为单一"服务器插件"**;角色/技能/物品模组仍是**独立加载项**,工厂注册保持模块化;DLL 热重载与实体 JSON 配置加载为**两条平行通道** |
| 7 | 负载模型 | **弃用 SocketObject**,全新设计负载模型(WebSocket 信封 + REST 响应包装) |
| 8 | 回合记录 | 支持 Core v3 的 **IRoundRecordSink 回合记录外发**(本地归档 + 可配置远程 POST) |
---
## 1. 解决方案结构
```
FunGame.Server-v3/
├── docs/ # 文档(01~04)
├── FunGame.Server-v3.slnx # 解决方案
├── src/
│ ├── FunGame.Server.Contracts/ # 共享契约:负载模型、插件接口、常量、事件参数
│ ├── FunGame.Server.Infrastructure/ # EF Core 数据层:实体、DbContext、迁移、种子数据
│ ├── FunGame.Server.PluginHost/ # 始终热重载的插件/模组加载系统
│ └── FunGame.Server.Host/ # 宿主:WebAPI + WebSocket + 认证 + 业务服务 + 对局宿主
├── plugins/ # 服务器插件示例(编译输出 → Host/plugins/)
├── modules/ # 角色/技能/物品模组示例(编译输出 → Host/modules/)
└── webui/ # React + Vite + Tailwind 管理台
```
**依赖方向(严格单向)**:
```
FunGame.Core (v3) ← Contracts ← Infrastructure ← PluginHost ← Host
↑ ↑
(共享程序集:插件 ALC 回退到默认上下文解析)
```
---
## 2. 数据层(决策 1/5)
### 2.1 Provider 切换
`appsettings.json`:
```json
"Database": {
"Provider": "Sqlite", // Sqlite | MySql
"ConnectionStrings": {
"Sqlite": "Data Source=Data/fungame-server.db",
"MySql": "Server=localhost;Port=3306;Database=fungame;User=root;Password=***;"
}
}
```
- `AppDbContextFactory`(设计时)与 `AddDbContext`(运行时)都按 `Provider` 注册对应 Provider:
- SQLite → `Microsoft.EntityFrameworkCore.Sqlite`
- MySQL → `Pomelo.EntityFrameworkCore.MySql`
- 迁移目录按 Provider 拆分:`Migrations/Sqlite/` 与 `Migrations/MySql/`(`--output-dir` 指定)
- 首次启动自动 `Migrate()` + 种子数据(系统角色、权限点、初始管理员)
### 2.2 数据表规划(v2 表优化 + 新增)
**认证与用户中心(新增/重构,决策 4)**
| 表 | 说明 |
|---|---|
| `Users` | 用户(v2 users 重构:密码散列 PBKDF2、邮箱验证、状态、昵称、头像、最后登录 IP/时间) |
| `UserProfiles` | 用户资料(v2 user_profiles 保留:个性签名、展示角色、偏好设置等) |
| `Roles` | 角色(Code/Name/是否系统内置) |
| `Permissions` | 权限点(Code/Name/分组,如 `users.read`、`plugins.reload`、`games.forceend`) |
| `UserRoles` | 用户-角色 多对多 |
| `RolePermissions` | 角色-权限 多对多 |
| `RefreshTokens` | 刷新令牌(散列存储、设备标识、过期/吊销;多端统一验证的基础) |
| `UserSessions` | 在线会话(每端一条:WebUI/WebAPI/WebSocket,登录挤下线/多端管理) |
| `LoginLogs` | 登录日志(v2 user_logs 细化:成功/失败、IP、UA、设备) |
| `ApiTokens` | API 访问令牌(v2 api_tokens 保留,供外部服务接入) |
**游戏业务(v2 表迁移/优化)**
| 表 | 说明 |
|---|---|
| `Rooms` | 房间(v2 rooms 保留,去掉 SQL 运行时依赖) |
| `UserCharacters` | 玩家角色库(v2 user_characters;实体数据以 Core JSON 存储 + 关键字段列冗余便于查询) |
| `UserItems` | 玩家物品(v2 user_items) |
| `Inventories` | 库存(v2 inventories:货币/材料) |
| `Stores` / `Goods` / `GoodsPrices` / `StoreGoods` | 商店体系(v2 保留) |
| `MarketItems` | 市场寄售(v2 保留) |
| `Offers` / `OfferItems` | 交易报价(v2 保留) |
| `VerifyCodes` | 验证码(v2 reg_verify_codes + forget_verify_codes 合并,加 Purpose 字段) |
| `UserSignIns` | 签到(v2 保留) |
**对局记录与运维(新增,决策 8/2)**
| 表 | 说明 |
|---|---|
| `GameRecords` | 对局记录索引(GamingQueue Guid、模式、起止时间、回合数、归档路径、胜者) |
| `RoundRecords` | 回合记录归档(可 JSON 列或归档文件路径;支持按回合查询回放) |
| `ServerLogs` | 服务器日志(供 WebUI 查看;结构化:级别/来源/分类/消息) |
| `SystemConfigs` | 系统配置键值(v2 configs 保留:动态公告、开关等) |
> 所有 `*Query` 静态 SQL 类(SQLQueryExtension)**废弃**,改为 EF LINQ。
### 2.3 CRUD API 约定(每表一套,决策 5)
通用基类 `CrudControllerBase<TEntity, TKey>`:
```
GET /api/{resource} 列表(分页 page/pageSize、排序 sort、过滤 filter=field:op:value)
GET /api/{resource}/{id} 详情
POST /api/{resource} 创建([Permission("{resource}.create")])
PUT /api/{resource}/{id} 整体更新
PATCH /api/{resource}/{id} 部分更新
DELETE /api/{resource}/{id} 删除
```
- 派生控制器:`UsersController`、`RolesController`、`PermissionsController`、`ApiTokensController`、`RoomsController`、`StoresController`、`GoodsController`、`MarketItemsController`、`OffersController`、`GameRecordsController`、`ServerLogsController`、`SystemConfigsController`……
- 关系表(UserRoles/RolePermissions)随主资源提供子路由:`GET/PUT /api/users/{id}/roles`、`GET/PUT /api/roles/{id}/permissions`
- 统一响应包装 `ApiResponse<T>`;权限用 `[Permission]` 授权过滤器校验
---
## 3. 认证:多端统一验证(决策 4)
**一条认证体系,三端共用**:
```
登录 → POST /api/auth/login (用户名/密码 或 刷新令牌) → { accessToken, refreshToken }
WebUI : Axios 拦截器 → Authorization: Bearer {accessToken};401 → /api/auth/refresh → 重试;失败 → 登录页
WebAPI : 同上(外部服务可用 ApiTokens 走 X-API-Token)
WebSocket : /ws?access_token=… 握手时校验 JWT(过期可先 refresh 再连)
```
- JWT:AccessToken 短时效(默认 30 分钟),RefreshToken 长时效(默认 14 天,可配置),**散列入库**,支持撤销/设备维度("踢出该设备")
- `UserSessions`:每端登录产生会话;同用户可多端同时在线,重复登录可配置"同端互踢"
- 密码:`PasswordHasher<T>`(PBKDF2);v2 的每用户密钥加密方案**废弃**(简化 + 标准库)
- 权限模型:`Permission` 权限点字符串(`users.read` / `plugins.reload` …)→ 角色聚合 → JWT Claim `perm` 数组;`PermissionAttribute("code")` 服务端校验
- 首次启动种子:系统角色(Admin/Moderator/User)、全部权限点、初始管理员(用户名/密码由 appsettings `Bootstrap:Admin` 提供,仅首次生效)
---
## 4. WebSocket 与负载模型(决策 3/7)
### 4.1 接入
- 端点:`GET /ws?access_token={jwt}`
- ASP.NET Core 原生 `UseWebSockets`;连接对象 `ClientSession`(会话模型,替代 v2 `ServerModel<T>`)
### 4.2 负载信封(替代 SocketObject)
```jsonc
// 客户端 → 服务器(请求)
{
"t": "room.create", // 消息类型(点分字符串,替代 SocketMessageType 枚举)
"i": 1, // 请求序号(客户端生成,用于响应关联)
"d": { ... } // 负载(Dictionary<string, object>,实体用 Core JsonService 序列化)
}
// 服务器 → 客户端(响应 / 广播)
{
"t": "room.created", // 或原样回显请求类型 + ".ok"/".error"
"i": 1,
"ok": true,
"error": null, // { code, message }
"d": { ... },
"ts": 1750000000000
}
```
- 消息类型注册表 `MessageTypes`(Contracts 常量类),覆盖:`auth.*`、`room.*`、`match.*`、`chat.*`、`gaming.*`(局内:`gaming.ready`、`gaming.action`、`gaming.sync`…)、`system.*`(公告/系统消息/踢人)
- 局内数据全部复用 **Core v3 实体 JSON**(JsonService.GeneralOptions 的转换器已支持 RoundRecord/ActionRecord/Character 等)
- `MessageDispatcher`:类型字符串 → 处理器注册表(业务服务 + 插件处理器合并)
- 心跳:`{ "t": "system.ping" }` ↔ `system.pong`;超时判定断线,断线重连(对局内重连保留 v2 思路,凭 `gameId` 重挂)
### 4.3 REST 响应包装(与 WS 对齐)
```jsonc
{ "ok": true, "code": 0, "message": null, "data": { ... }, "timestamp": "..." }
```
---
## 5. 加载项系统(决策 6)—— 始终热重载
### 5.1 三类加载项(DLL 热重载通道)
| 类型 | 目录 | 接口 | 说明 |
|---|---|---|---|
| **服务器插件**(合并 v2 WebAPIPlugin + GameModuleServer) | `plugins/` | `IServerPlugin` | 生命周期 + REST 端点注册(MapGroup)+ WS 消息处理器 + 对局模式(GameModule) |
| 角色模组 | `modules/characters/` | `ICharacterModule` | 提供角色实体集合,`Load()` 时通过工厂注册 |
| 技能模组 | `modules/skills/` | `ISkillModule` | 同上(技能) |
| 物品模组 | `modules/items/` | `IItemModule` | 同上(物品) |
> 实体模组也可只提供 `EntityModuleConfig` JSON 文件(平行通道,见 5.3),DLL 与 JSON 两者可共存。
### 5.2 DLL 热重载机制(始终开启,无普通加载模式)
- 每个加载项一个**可回收 AssemblyLoadContext**(`PluginLoadContext`,`isCollectible: true`),按 `Name + Guid` 命名
- `PluginManager`:
- `LoadAll()` / `Load(string name)` / `Unload(string name)` / `Reload(string name)` / `ReloadAll()`
- `Plugins` / `Modules` 清单(名称、版本、状态、加载时间)
- 文件监视(`FileSystemWatcher`,去抖合并变更)→ 自动热重载;也可 `POST /api/admin/plugins/{name}/reload` 手动触发
- 卸载顺序:`OnUnload()` → 摘除端点/处理器 → `ALC.Unload()` → 弱引用等待 GC(必要时 `GC.Collect`)
- 共享程序集(FunGame.Core、Contracts、Infrastructure、PluginHost)**不随插件加载**:`PluginLoadContext.Load` 优先返回默认上下文已加载程序集;插件自有依赖从插件目录解析
- 插件端点用 **Minimal API `MapGroup`**(`plugin.ConfigureEndpoints(app)`),可热卸载(v2 的 Controller 程序集注册方式因无法热移除而弃用)
- 对局中途插件被卸载:`PluginManager` 拒绝卸载"仍被活跃对局引用"的插件(引用计数)
### 5.3 实体 JSON 通道(与 5.2 平行)
- `EntityModuleConfig<T>` 生成/读取 JSON 配置;`Factory.GetGameModuleInstances<T>(module, file)` 实例化实体
- WebUI 提供"实体模组管理"页:查看/编辑/重新加载 JSON 配置(不重启进程改游戏内容)
### 5.4 服务器插件接口(Contracts)
```csharp
public interface IServerPlugin : IPluginBase
{
// 注册 HTTP 端点(挂载 /plugin/{name}/{path},注册表 + 单一路由分发,可热移除)
// 与 WebSocket 消息处理器(随插件热卸载自动注销)
void ConfigureEndpoints(IPluginHttpHandlerRegistry http, IMessageHandlerRegistry messages);
// 对局模式逻辑(可选):局内消息转发到模式插件
Task<Dictionary<string, object>?> HandleGamingMessage(IGameSession session, string type, Dictionary<string, object> data);
void OnLoad(IServiceProvider services); // 继承自 IPluginBase
void OnUnload(); // 继承自 IPluginBase
}
```
> 注:插件 HTTP 端点采用 **注册表 + 单一路由分发**(`/plugin/{name}/{path}`)而非动态注册 Controller/MapGroup——保证端点可随 ALC 热添加/热移除。
---
## 6. 对局宿主与回合记录外发(决策 8)
### 6.1 对局宿主 `GameHostService`
- 房间/匹配就绪 → 创建 `GamingQueue(characters, map)` → 绑定 `RoundRecordSink`
- 局内循环:行动顺序(`NextCharacter()`)→ 等待该角色决策(WS `gaming.action`)→ `ProcessTurn(character)`(或插件模式接管整回合逻辑)
- 维护 `gameId → GameSession`(队列、玩家会话映射、状态);断线重连、强制结束、观战
- 游戏结束:结算 `GameResult`/`CharacterStatistics` → 写 `GameRecords` → 通知各端
### 6.2 回合记录外发 `GameRoundRecordSink : IRoundRecordSink`
- 实现 Core v3 的 9 个外发事件(Action/Round/CheckpointRound/CharacterStatistics/Characters/Teams/QueueData/EliminatedCharacters/EliminatedTeams)
- **本地归档**:每局一个 `records/{gameId}.zip`(沿用 Testing-v3 的 rounds_data.json 格式)或按配置写入 `RoundRecords` 表
- **远程转发**(可选):配置 `RoundRecordSink:PostUrl` + `Secret` 时,内部包装 `DefaultRoundRecordSink` 转发(生产者/消费者都可)
- 回放 REST:`GET /api/games/{id}/rounds`、`GET /api/games/{id}/rounds/{n}`、`GET /api/games/{id}/statistics`(参考 Testing-v3 端点设计),配合 `BattleStatePredictor` 提供任意回合状态
- WS 实时推送:订阅 sink 事件 → 广播 `gaming.round` / `gaming.action`(观战/直播能力)
---
## 7. WebUI 管理台(决策 2)
技术栈:**React 18 + Vite + TypeScript + Tailwind CSS v4**(与 Testing-v3 webui 同栈,可复用组件风格)。
| 页面 | 功能 |
|---|---|
| 登录 | 统一 JWT 登录(与 WebAPI/WS 同一认证) |
| 仪表盘 | 在线玩家/连接数、进行中对局、服务器状态、近期日志 |
| 玩家管理 | Users CRUD、资料、角色分配、会话管理(踢下线)、登录日志 |
| 权限管理 | Roles / Permissions CRUD、角色-权限配置 |
| 房间/对局 | 房间列表、对局监控、强制结束、观战入口 |
| 插件/模组管理 | 插件清单、热重载/卸载、实体模组 JSON 编辑与重载 |
| 数据管理 | 各业务表 CRUD 通用表格页(商店/市场/物品/系统配置…) |
| 回放中心 | 对局记录、回合回放(复用 Testing-v3 回放面板) |
| 日志 | ServerLogs 检索、级别过滤、实时尾巴 |
- 开发:`vite dev`(5173)代理 `/api`、`/ws` → 服务器(默认 5000)
- 生产:`npm run build` → `webui/dist` 由 Host 静态托管(同 Testing-v3 模式)
---
## 8. 目录与命名约定
- 根命名空间:`FunGame.Server.Contracts` / `FunGame.Server.Infrastructure` / `FunGame.Server.PluginHost` / `FunGame.Server.Host`;模组/插件可自定义(如 `FunGame.Server.Plugins.OfficialStandard`)
- REST 路由:`/api/{resource}`;管理端 `[Permission]` 保护
- WS 消息类型:小写点分(`room.create`、`gaming.action`)
- 配置:`appsettings.json`(分层:Database/Jwt/Auth/Server/RoundRecordSink/Bootstrap/Cors/Plugins)
- 日志:`ILogger` + ServerLogs 数据库通道(Serilog 可选接入)
---
## 9. 里程碑(对应实施顺序)
- **M0 骨架**:解决方案 + 4 个类库/宿主 + Core 引用 + 编译通过 ✅
- **M1 数据层**:实体、DbContext、双 Provider、迁移、种子数据、CRUD 基类 + 首批控制器 ✅
- **M2 认证**:JWT + 刷新令牌 + 会话 + 权限过滤 + WS 握手认证 ✅
- **M3 插件系统**:PluginHost 热重载 + 示例插件/模组 + 管理端点 ✅(影子加载 + _staging 热替换 + 文件监视)
- **M4 WebSocket**:ClientSession、信封、消息分发、心跳/断线 ✅
- **M5 业务**:房间/匹配/聊天/对局宿主 + 回合记录归档与外发 + 回放端点 ✅(AI 对局循环为演示实现,玩家局内决策接入待办)
- **M6 WebUI**:管理台全页面(登录/仪表盘/用户/插件/对局/回放/日志)✅
- **M7 加固发布**:测试、Linux 发布、文档 ⏳(进行中)
### M7 剩余事项
- 玩家局内决策接入(`gaming.action` 驱动 GamingQueue,当前为 AI 自动循环)
- 更完整的匹配队列(Elo 扩圈,当前为快速匹配演示)
- 单元/集成测试项目(参考 Testing-v3 的 Tests)
- Linux 自包含发布脚本(参考 Testing-v3 publish-linux.sh)
- WebUI 权限/角色管理页、系统配置页
- MySQL Provider 的迁移与部署验证