first commit

This commit is contained in:
2026-08-28 19:44:46 +08:00
commit d99ccbbb0c
114 changed files with 16246 additions and 0 deletions
+309
View File
@@ -0,0 +1,309 @@
# 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 的迁移与部署验证