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

76 lines
4.6 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.
# 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<TEntity, TKey>`:每张表派生控制器即得 分页列表/详情/创建/更新/删除 |
| 负载模型 | WebSocket `MessageEnvelope`(t/i/ok/error/d/ts,替代 SocketObject);REST `ApiResponse<T>` |
| 插件系统 | **始终热重载**:`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 <Name> --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 架构定稿(开发依据)**