# FunGame.Server-v3 基于 **FunGame.Core v3**(net10.0)全新构建的服务器项目:EF Core 数据层、React/Tailwind WebUI 管理台、仅 WebSocket + WebAPI 启动、细粒度权限角色与多端统一验证、全表 CRUD REST API、始终热重载的插件系统、新负载模型与回合记录外发。 > 架构设计与规划文档见 [`docs/`](docs/),开发依据为 [docs/04-架构设计.md](docs/04-架构设计.md)。 ## 解决方案结构 ``` src/FunGame.Server.Contracts/ 共享契约:负载模型(MessageEnvelope/ApiResponse)、插件接口、权限点 src/FunGame.Server.Infrastructure/ EF Core 数据层:实体、AppDbContext、迁移、种子数据 src/FunGame.Server.PluginHost/ 始终热重载的插件/模组加载系统(可回收 AssemblyLoadContext + 文件监视) src/FunGame.Server.Host/ ASP.NET Core 宿主:WebAPI + WebSocket + JWT 认证 + 对局宿主 + 回放归档 webui/ React + Vite + Tailwind 管理控制台 ``` ## 快速开始 ```powershell # 1. 启动服务器(默认 http://localhost:5000,SQLite 自动建库并创建初始管理员) dotnet run --project src/FunGame.Server.Host # 2. 开发模式启动 WebUI(http://localhost:5173,代理 /api 与 /ws 到 5000) cd webui npm install npm run dev # 3. 生产模式:构建前端后由服务器托管 cd webui && npm run build # 重启服务器后直接访问 http://localhost:5000 ``` 初始管理员账号由 `appsettings.json` 的 `Bootstrap:Admin` 配置(默认 `admin` / `admin123456`,仅首次启动生效,请尽快修改)。 ## 核心特性 | 特性 | 说明 | |---|---| | 数据层 | EF Core 10,`Database:Provider` 切换 SQLite / MySQL(迁移:`Migrations/Sqlite`) | | 认证 | JWT(WebUI/WebAPI/WebSocket 三端统一)+ 刷新令牌(散列入库/可撤销)+ PBKDF2 密码 | | 权限 | RBAC + 权限点(`PermissionCodes`),`[Permission("code")]` 过滤,JWT `perm` Claim | | CRUD | `CrudControllerBase`:每张表派生控制器即得 分页列表/详情/创建/更新/删除 | | 负载模型 | WebSocket `MessageEnvelope`(t/i/ok/error/d/ts,替代 SocketObject);REST `ApiResponse` | | 插件系统 | **始终热重载**:`plugins/`(服务器插件)、`modules/{characters,skills,items}/`(实体模组);影子加载(正式文件不锁定)+ `_staging` 暂存区原子热替换 + 文件监视自动热重载 + 活跃对局引用计数保护 | | 插件能力 | 服务器插件可注册 HTTP 端点(`/plugin/{name}/path`,可热移除)、WS 消息处理器(`example.echo` 等)、对局模式(`HandleGamingMessage`);实体模组经工厂注册(`Factory.RegisterFactory`)与实体 JSON 配置通道平行 | | 回合记录 | 实现 Core v3 `IRoundRecordSink`:归档 `records/{gameId}.zip`(rounds_data.json + statistics.json + characters.json)+ `round_records` 表 + 可选远程 POST(`DefaultRoundRecordSink`) | | 对局宿主 | `GameHostService`:MixGamingQueue 对战循环(AI 决策演示)、`gaming.round` 实时回合推送、`gaming.over` 结算广播、断线重连接口 | | 回放 | `/api/games/{id}/meta|rounds/summary|rounds/{n}|statistics`(与 Testing-v3 归档格式兼容) | | WebSocket | `/ws?access_token={jwt}`,内置 system.ping / system.info / auth.logout + room.*(创建/加入/退出/聊天/开始) + match.*(快速匹配) | | 管理台 | 仪表盘(含 WS 连通性)、用户管理、插件与模组热重载、对局监控、回放中心、服务器日志(server_logs 结构化日志通道) | ## 示例加载项 - `plugins/FunGame.Server.Plugins.Example` —— 示例服务器插件(HTTP 端点 + WS echo + 对局模式),构建后自动进入 `_staging` 由宿主热替换 - `modules/FunGame.Server.Modules.Example` —— 示例角色/技能/物品模组(战士/法师/示例打击/回复药剂),演示工厂注册与热重载 ## 常用命令 ```powershell # 构建 dotnet build FunGame.Server-v3.slnx # EF 迁移(SQLite 为默认 Provider) dotnet dotnet-ef migrations add --project src/FunGame.Server.Infrastructure --output-dir Migrations/Sqlite # 清理开发数据库 Remove-Item src/FunGame.Server.Host/Data/fungame-server.db ``` ## 文档 - [docs/01-v2-功能总结.md](docs/01-v2-功能总结.md) —— v2 服务器功能基线 - [docs/02-v3-Core-变更分析.md](docs/02-v3-Core-变更分析.md) —— Core v3 技术边界 - [docs/03-Server-v3-开发规划.md](docs/03-Server-v3-开发规划.md) —— 早期备选方案 - [docs/04-架构设计.md](docs/04-架构设计.md) —— **v3 架构定稿(开发依据)**