485 lines
21 KiB
Markdown
485 lines
21 KiB
Markdown
# 服务端运行中热更去锁（字节加载 + 内容指纹失效）实现计划
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 同版本覆盖重发不再被文件锁挡住且发布即生效——DLL 字节加载（不锁文件）+ Registry 按磁盘内容指纹自动失效重载。
|
||
|
||
**Architecture:** `GameModuleAlc` 两处 `LoadFromAssemblyPath` 改 `File.ReadAllBytes`+`LoadFromStream`（无文件句柄）；`GameModuleRegistry` 加内容指纹：`Acquire` 命中缓存时重算磁盘指纹，变化则旧条目退役（`_retired`，旧房间打完引用归零即卸载）、加载新内容。生产环境版本不可变、指纹恒命中，行为零变化。
|
||
|
||
**Tech Stack:** .NET 10（Server.Host）、xUnit、复用 `XWorld.PublishTool.Md5Util`（Server.Host 已引用 PublishTool）。
|
||
|
||
**Spec:** `docs/superpowers/specs/2026-07-07-minigame-publish-pipeline-design.md` §4.3.2
|
||
|
||
**约定：无 git（不提交，commit 步骤替换为验证 checkpoint）。仓库根 `<repo>` = `D:\UD\AI\AIC#Project`，所有命令在 `<repo>` 下执行。基线：`dotnet test Server/Server.sln` = 182 通过 / 0 失败（若 `Server/Server.Host.Tests/TestGames/` 不存在，先跑 `bash Server/build-test-games.sh`）。测试注意：`TestGames.Root` 是共享只读夹具——**涉及改写文件的测试必须先拷到临时 gamesRoot，不许原地改**。**
|
||
|
||
---
|
||
|
||
### Task 1: GameModuleAlc 字节加载（去文件锁），TDD
|
||
|
||
**Files:**
|
||
- Create: `Server/Server.Host.Tests/ModuleFileLockTests.cs`
|
||
- Modify: `Server/Server.Host/GameModuleAlc.cs`
|
||
|
||
- [ ] **Step 1.1: 写失败测试** `ModuleFileLockTests.cs`：
|
||
|
||
```csharp
|
||
using System;
|
||
using System.IO;
|
||
using Xunit;
|
||
using XWorld.Server.Host;
|
||
|
||
namespace XWorld.Server.Host.Tests
|
||
{
|
||
// 字节加载去锁：模块加载期间磁盘 DLL 可被覆盖/删除（同版本覆盖重发的前提）
|
||
public class ModuleFileLockTests
|
||
{
|
||
// 把共享只读夹具 rps/1 拷到独立临时 gamesRoot（不许改 TestGames.Root 原件）
|
||
private static string CopyRps1ToTempRoot()
|
||
{
|
||
string root = Path.Combine(Path.GetTempPath(), "games_" + Guid.NewGuid().ToString("N"));
|
||
string dst = Path.Combine(root, "rps", "1");
|
||
Directory.CreateDirectory(dst);
|
||
string src = Path.Combine(TestGames.Root, "rps", "1");
|
||
foreach (var f in Directory.GetFiles(src))
|
||
File.Copy(f, Path.Combine(dst, Path.GetFileName(f)));
|
||
return root;
|
||
}
|
||
|
||
[Fact]
|
||
public void LoadedModule_DoesNotLockDlls_OverwriteAndDeleteSucceed()
|
||
{
|
||
string root = CopyRps1ToTempRoot();
|
||
var module = new GameModuleLoader().Load(root, "rps", 1);
|
||
try
|
||
{
|
||
string serverDll = Path.Combine(root, "rps", "1", "RPS.Server.dll");
|
||
string coreDll = Path.Combine(root, "rps", "1", "RPS.Core.dll");
|
||
|
||
// 加载期间覆盖写入 —— LoadFromAssemblyPath 会锁文件抛 IOException，字节加载应成功
|
||
byte[] original = File.ReadAllBytes(serverDll);
|
||
File.WriteAllBytes(serverDll, original);
|
||
|
||
// 加载期间删除
|
||
File.Delete(coreDll);
|
||
Assert.False(File.Exists(coreDll));
|
||
|
||
// 模块本体仍可用（IL 已在内存）
|
||
var room = module.CreateRoom();
|
||
Assert.NotNull(room);
|
||
}
|
||
finally
|
||
{
|
||
module.Unload();
|
||
try { Directory.Delete(root, true); } catch { }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 1.2: 跑测试确认失败**
|
||
|
||
Run: `cd "D:/UD/AI/AIC#Project" && dotnet test Server/Server.Host.Tests -nologo --filter ModuleFileLockTests 2>&1 | tail -6`
|
||
Expected: FAIL，`IOException`（文件正由另一进程使用）——Windows 上 `LoadFromAssemblyPath` 锁定 DLL。
|
||
|
||
- [ ] **Step 1.3: 实现字节加载** —— `GameModuleAlc.cs` 整文件替换为：
|
||
|
||
```csharp
|
||
using System.IO;
|
||
using System.Reflection;
|
||
using System.Runtime.Loader;
|
||
|
||
namespace XWorld.Server.Host
|
||
{
|
||
// 可卸载上下文：框架契约走默认上下文（类型标识跨界一致），小游戏私有 DLL 载入本上下文。
|
||
// DLL 一律字节加载（LoadFromStream）：不持有文件句柄，同版本覆盖重发不被文件锁挡住。
|
||
// 代价：字节加载的 Assembly.Location 为空——小游戏 DLL 不得依赖它。
|
||
internal sealed class GameModuleAlc : AssemblyLoadContext
|
||
{
|
||
private readonly string _moduleDir;
|
||
|
||
public GameModuleAlc(string name, string moduleDir) : base(name, isCollectible: true)
|
||
{
|
||
_moduleDir = moduleDir;
|
||
}
|
||
|
||
protected override Assembly Load(AssemblyName assemblyName)
|
||
{
|
||
// 设计 §4.2：框架契约类型必须在默认 ALC，不随小游戏卸载。
|
||
// 约束：XWorld.Framework.Shared 只能依赖 BCL（System.*）；若将来加第三方依赖，需同步扩展下面白名单。
|
||
if (assemblyName.Name == "XWorld.Framework.Shared")
|
||
return null;
|
||
|
||
// BCL / 运行时程序集始终走默认上下文，防止游戏目录里同名文件遮蔽（类型标识错乱）
|
||
string n = assemblyName.Name;
|
||
if (n != null && (n.StartsWith("System.", System.StringComparison.Ordinal) ||
|
||
n.StartsWith("Microsoft.", System.StringComparison.Ordinal) ||
|
||
n == "System" || n == "netstandard" || n == "mscorlib"))
|
||
return null;
|
||
|
||
// 小游戏私有程序集放在版本目录里，载入本可卸载上下文
|
||
string candidate = Path.Combine(_moduleDir, assemblyName.Name + ".dll");
|
||
if (File.Exists(candidate))
|
||
return LoadBytes(candidate);
|
||
|
||
return null; // 其余交默认上下文
|
||
}
|
||
|
||
public Assembly LoadEntry(string serverDllPath) => LoadBytes(serverDllPath);
|
||
|
||
private Assembly LoadBytes(string path)
|
||
{
|
||
using (var ms = new MemoryStream(File.ReadAllBytes(path)))
|
||
return LoadFromStream(ms);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 1.4: 跑测试确认通过 + Server.Host.Tests 全量**
|
||
|
||
Run: `dotnet test Server/Server.Host.Tests -nologo 2>&1 | tail -4`
|
||
Expected: 全 PASS（51 原有 + 1 新 = 52；`AlcUnloadTests` 的弱引用 GC 断言对 LoadFromStream 同样成立）。
|
||
|
||
---
|
||
|
||
### Task 2: GameModuleRegistry 内容指纹自动失效，TDD
|
||
|
||
**Files:**
|
||
- Create: `Server/Server.Host.Tests/RegistryContentInvalidationTests.cs`
|
||
- Modify: `Server/Server.Host/GameModuleRegistry.cs`（整文件替换）
|
||
|
||
- [ ] **Step 2.1: 写失败测试** `RegistryContentInvalidationTests.cs`：
|
||
|
||
```csharp
|
||
using System;
|
||
using System.IO;
|
||
using System.Runtime.CompilerServices;
|
||
using Xunit;
|
||
using XWorld.Server.Host;
|
||
|
||
namespace XWorld.Server.Host.Tests
|
||
{
|
||
// 同 (gameId,version) 磁盘内容变化（覆盖重发）→ Registry 自动失效重载；
|
||
// 旧房间打完旧代码（退役条目引用归零即卸载），新房间用新代码。
|
||
public class RegistryContentInvalidationTests
|
||
{
|
||
private static string CopyRps1ToTempRoot()
|
||
{
|
||
string root = Path.Combine(Path.GetTempPath(), "games_" + Guid.NewGuid().ToString("N"));
|
||
string dst = Path.Combine(root, "rps", "1");
|
||
Directory.CreateDirectory(dst);
|
||
string src = Path.Combine(TestGames.Root, "rps", "1");
|
||
foreach (var f in Directory.GetFiles(src))
|
||
File.Copy(f, Path.Combine(dst, Path.GetFileName(f)));
|
||
return root;
|
||
}
|
||
|
||
// 改变内容指纹（game.json 在指纹范围内；追加空白不影响 JSON 解析）
|
||
private static void TouchContent(string root)
|
||
{
|
||
string gameJson = Path.Combine(root, "rps", "1", "game.json");
|
||
File.AppendAllText(gameJson, " ");
|
||
}
|
||
|
||
[Fact]
|
||
public void SameContent_ReturnsCachedInstance()
|
||
{
|
||
string root = CopyRps1ToTempRoot();
|
||
var reg = new GameModuleRegistry(new GameModuleLoader(), root);
|
||
var a = reg.Acquire("rps", 1);
|
||
var b = reg.Acquire("rps", 1);
|
||
Assert.Same(a, b);
|
||
Assert.Equal(2, reg.RefCount("rps", 1));
|
||
}
|
||
|
||
[Fact]
|
||
public void ContentChange_AfterRefZero_ReloadsNewInstance()
|
||
{
|
||
string root = CopyRps1ToTempRoot();
|
||
var reg = new GameModuleRegistry(new GameModuleLoader(), root);
|
||
var a = reg.Acquire("rps", 1);
|
||
reg.Release(a); // 引用归零，未淘汰 → 保留缓存
|
||
TouchContent(root);
|
||
var b = reg.Acquire("rps", 1);
|
||
Assert.NotSame(a, b); // 内容变了 → 新模块实例
|
||
Assert.Equal(1, reg.RefCount("rps", 1));
|
||
Assert.True(reg.IsLoaded("rps", 1));
|
||
}
|
||
|
||
[Fact]
|
||
public void ContentChange_WhileOldActive_OldAndNewCoexist_ReleaseBothCorrect()
|
||
{
|
||
string root = CopyRps1ToTempRoot();
|
||
var reg = new GameModuleRegistry(new GameModuleLoader(), root);
|
||
var oldM = reg.Acquire("rps", 1); // 旧房间在打
|
||
TouchContent(root);
|
||
var newM = reg.Acquire("rps", 1); // 新房间 → 新内容
|
||
Assert.NotSame(oldM, newM);
|
||
Assert.Equal(1, reg.RefCount("rps", 1)); // RefCount 只统计当前条目
|
||
|
||
reg.Release(oldM); // 旧房间结束：退役条目按实例识别释放，不抛
|
||
reg.Release(newM);
|
||
Assert.Equal(0, reg.RefCount("rps", 1));
|
||
Assert.True(reg.IsLoaded("rps", 1)); // 当前条目未被淘汰 → 保留复用
|
||
}
|
||
|
||
[Fact]
|
||
public void ContentChange_RetiredModule_UnloadsAndReclaims()
|
||
{
|
||
string root = CopyRps1ToTempRoot();
|
||
var weak = AcquireChangeReleaseOld(root);
|
||
for (int i = 0; i < 12 && weak.IsAlive; i++)
|
||
{
|
||
GC.Collect();
|
||
GC.WaitForPendingFinalizers();
|
||
}
|
||
Assert.False(weak.IsAlive, "退役模块的 ALC 未被回收 —— 存在泄漏引用");
|
||
}
|
||
|
||
// 独立方法确保局部强引用随返回消失（同 AlcUnloadTests 套路）
|
||
[MethodImpl(MethodImplOptions.NoInlining)]
|
||
private static WeakReference AcquireChangeReleaseOld(string root)
|
||
{
|
||
var reg = new GameModuleRegistry(new GameModuleLoader(), root);
|
||
var oldM = reg.Acquire("rps", 1);
|
||
TouchContent(root);
|
||
var newM = reg.Acquire("rps", 1); // oldM 退役
|
||
var weak = new WeakReference(oldM);
|
||
reg.Release(oldM); // 退役 + 归零 → 卸载
|
||
reg.Release(newM);
|
||
return weak;
|
||
}
|
||
|
||
[Fact]
|
||
public void MissingDir_ServesCachedEntry()
|
||
{
|
||
string root = CopyRps1ToTempRoot();
|
||
var reg = new GameModuleRegistry(new GameModuleLoader(), root);
|
||
var a = reg.Acquire("rps", 1);
|
||
string dir = Path.Combine(root, "rps", "1");
|
||
string away = dir + ".away";
|
||
Directory.Move(dir, away); // 模拟覆盖交换的瞬间窗口
|
||
try
|
||
{
|
||
var b = reg.Acquire("rps", 1); // 指纹算不出 → 用缓存兜底
|
||
Assert.Same(a, b);
|
||
}
|
||
finally { Directory.Move(away, dir); }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2.2: 跑测试确认失败**
|
||
|
||
Run: `dotnet test Server/Server.Host.Tests -nologo --filter RegistryContentInvalidationTests 2>&1 | tail -6`
|
||
Expected: `SameContent/MissingDir` 可能通过（旧实现即缓存），`ContentChange_*` 三个 FAIL（`Assert.NotSame` 失败——旧实现不看内容）。
|
||
|
||
- [ ] **Step 2.3: 实现** —— `GameModuleRegistry.cs` 整文件替换为：
|
||
|
||
```csharp
|
||
using System;
|
||
using System.Collections.Generic;
|
||
using System.IO;
|
||
using System.Linq;
|
||
using System.Text;
|
||
|
||
namespace XWorld.Server.Host
|
||
{
|
||
// (gameId,version) -> 已加载模块；按引用计数获取/释放。
|
||
// 淘汰有两个来源：①同 gameId 更高版本加载成功；②同 (gameId,version) 磁盘内容指纹变化（覆盖重发）。
|
||
// 被淘汰且引用归零即卸载；内容变化时新旧模块并存至旧房间结束（_retired，Release 按实例识别）。
|
||
// 生产环境版本不可变、指纹恒命中缓存，行为与旧实现一致。
|
||
public sealed class GameModuleRegistry
|
||
{
|
||
private sealed class Entry
|
||
{
|
||
public LoadedGameModule Module;
|
||
public int RefCount;
|
||
public bool Superseded;
|
||
public string Fingerprint;
|
||
}
|
||
|
||
private readonly GameModuleLoader _loader;
|
||
private readonly string _gamesRoot;
|
||
private readonly Dictionary<string, Entry> _current = new Dictionary<string, Entry>();
|
||
private readonly List<Entry> _retired = new List<Entry>();
|
||
|
||
public GameModuleRegistry(GameModuleLoader loader, string gamesRoot)
|
||
{
|
||
_loader = loader; _gamesRoot = gamesRoot;
|
||
}
|
||
|
||
private static string Key(string gameId, int version) => $"{gameId}@{version}";
|
||
private string ModuleDir(string gameId, int version) => Path.Combine(_gamesRoot, gameId, version.ToString());
|
||
|
||
public LoadedGameModule Acquire(string gameId, int version)
|
||
{
|
||
string key = Key(gameId, version);
|
||
if (_current.TryGetValue(key, out var e))
|
||
{
|
||
// 覆盖重发检测：磁盘内容指纹变化 → 旧条目退役、加载新内容。
|
||
// 指纹算不出（目录处于覆盖交换的瞬间窗口/被删）→ 视为未变化，用缓存兜底。
|
||
string fp = ComputeFingerprintOrNull(ModuleDir(gameId, version));
|
||
if (fp == null || fp == e.Fingerprint)
|
||
{
|
||
e.RefCount++;
|
||
return e.Module;
|
||
}
|
||
|
||
var reloaded = LoadEntry(gameId, version); // 失败直接抛出：旧条目原样保留，不污染状态
|
||
Retire(e);
|
||
_current[key] = reloaded;
|
||
SupersedeOlderVersions(gameId, version);
|
||
reloaded.RefCount++;
|
||
return reloaded.Module;
|
||
}
|
||
|
||
var loaded = LoadEntry(gameId, version);
|
||
_current[key] = loaded;
|
||
SupersedeOlderVersions(gameId, version);
|
||
loaded.RefCount++;
|
||
return loaded.Module;
|
||
}
|
||
|
||
public void Release(LoadedGameModule module)
|
||
{
|
||
string key = Key(module.GameId, module.Version);
|
||
if (_current.TryGetValue(key, out var e) && ReferenceEquals(e.Module, module))
|
||
{
|
||
if (e.RefCount <= 0)
|
||
throw new InvalidOperationException($"重复释放模块 {module.GameId}@{module.Version}");
|
||
e.RefCount--;
|
||
if (e.RefCount <= 0 && e.Superseded)
|
||
{
|
||
_current.Remove(key);
|
||
module.Unload();
|
||
}
|
||
return;
|
||
}
|
||
|
||
// 退役条目：同版本被覆盖重发淘汰后仍被旧房间持有，按实例识别
|
||
for (int i = 0; i < _retired.Count; i++)
|
||
{
|
||
if (!ReferenceEquals(_retired[i].Module, module)) continue;
|
||
var r = _retired[i];
|
||
if (r.RefCount <= 0)
|
||
throw new InvalidOperationException($"重复释放模块 {module.GameId}@{module.Version}");
|
||
r.RefCount--;
|
||
if (r.RefCount <= 0)
|
||
{
|
||
_retired.RemoveAt(i);
|
||
module.Unload();
|
||
}
|
||
return;
|
||
}
|
||
// 未知模块的释放忽略（与旧实现对不存在 key 直接 return 的行为一致）
|
||
}
|
||
|
||
public int RefCount(string gameId, int version)
|
||
=> _current.TryGetValue(Key(gameId, version), out var e) ? e.RefCount : 0;
|
||
|
||
public bool IsLoaded(string gameId, int version) => _current.ContainsKey(Key(gameId, version));
|
||
|
||
private Entry LoadEntry(string gameId, int version)
|
||
{
|
||
// 指纹在加载前采样：加载成功即与所载内容对应（单线程 tick actor 下无并发写窗口）
|
||
string fp = ComputeFingerprintOrNull(ModuleDir(gameId, version));
|
||
var loaded = _loader.Load(_gamesRoot, gameId, version);
|
||
return new Entry { Module = loaded, RefCount = 0, Superseded = false, Fingerprint = fp };
|
||
}
|
||
|
||
private void SupersedeOlderVersions(string gameId, int version)
|
||
{
|
||
foreach (var kv in _current)
|
||
if (kv.Value.Module.GameId == gameId && kv.Value.Module.Version < version)
|
||
kv.Value.Superseded = true;
|
||
}
|
||
|
||
private void Retire(Entry e)
|
||
{
|
||
e.Superseded = true;
|
||
if (e.RefCount <= 0) e.Module.Unload();
|
||
else _retired.Add(e);
|
||
}
|
||
|
||
// 目录内容指纹：全部 *.dll + game.json 按名 Ordinal 排序拼 name=md5; 再整体 md5；
|
||
// 读不到（目录不存在/IO 竞态）返回 null 由调用方兜底
|
||
private static string ComputeFingerprintOrNull(string dir)
|
||
{
|
||
try
|
||
{
|
||
if (!Directory.Exists(dir)) return null;
|
||
var names = Directory.GetFiles(dir, "*.dll")
|
||
.Select(Path.GetFileName)
|
||
.Append("game.json")
|
||
.Where(n => File.Exists(Path.Combine(dir, n)))
|
||
.Distinct()
|
||
.OrderBy(n => n, StringComparer.Ordinal);
|
||
var sb = new StringBuilder();
|
||
foreach (var n in names)
|
||
sb.Append(n).Append('=')
|
||
.Append(XWorld.PublishTool.Md5Util.OfFile(Path.Combine(dir, n))).Append(';');
|
||
return XWorld.PublishTool.Md5Util.OfBytes(Encoding.UTF8.GetBytes(sb.ToString()));
|
||
}
|
||
catch (IOException) { return null; }
|
||
catch (UnauthorizedAccessException) { return null; }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2.4: 跑新测试 + Server.Host.Tests 全量**
|
||
|
||
Run: `dotnet test Server/Server.Host.Tests -nologo 2>&1 | tail -4`
|
||
Expected: 全 PASS（52 + 5 新 = 57）。既有 `GameModuleRegistryTests` 5 个必须原样通过（`Acquire_SameVersionTwice`/`Release_ToZero`/`NewVersion_Supersedes`/`FailedNewVersionLoad`/`Release_MoreThanAcquired`——公共 API 与语义未变）。
|
||
|
||
- [ ] **Step 2.5: Checkpoint——全解决方案回归**
|
||
|
||
Run: `dotnet test Server/Server.sln -nologo 2>&1 | tail -8`
|
||
Expected: 0 失败（182 基线 + 6 新 = 188 左右；Gateway 的 RoomHost/ServerLoop 只用 Acquire/Release，零改动）。
|
||
|
||
---
|
||
|
||
### Task 3: 文档同步 + 终验
|
||
|
||
**Files:**
|
||
- Modify: `Tools/PcMiniGameSmoke/README.md`（「运行中热更」小节）
|
||
|
||
- [ ] **Step 3.1: 改 README 注意事项**——把
|
||
|
||
```markdown
|
||
注意：网关运行中且某版本已被房间加载时，**覆盖重发同版本**会因 DLL 文件锁失败——
|
||
运行中更新一律发新版本号（新版本自动淘汰旧版本，旧房间打完即卸载）。
|
||
```
|
||
|
||
改为：
|
||
|
||
```markdown
|
||
**同版本覆盖重发也支持**：服务器 DLL 为字节加载（不锁文件），覆盖落位总能成功；
|
||
网关按磁盘内容指纹自动失效——下一个新房间即用新代码，已入房玩家打完旧代码后旧模块自动卸载。
|
||
（生产环境仍建议版本号递增，便于客户端 AB 与服务器 DLL 的版本对应关系可追溯。）
|
||
```
|
||
|
||
- [ ] **Step 3.2: 终验**
|
||
|
||
Run:
|
||
```bash
|
||
cd "D:/UD/AI/AIC#Project"
|
||
dotnet test Server/Server.sln -nologo 2>&1 | tail -8
|
||
```
|
||
Expected: 0 失败。
|
||
|
||
- [ ] **Step 3.3: 人工核对项（交给用户）**：网关运行中（Editor Play 或命令行起 `Gateway.Runner --gamesRoot deploy/minigame`），菜单对同版本"覆盖重发"RPS——落位成功（无文件锁报错）；不重启网关再匹配进一局，日志可见模块重新加载（新 ALC）。
|
||
|
||
---
|
||
|
||
## Self-Review 记录
|
||
|
||
- **Spec 覆盖**：§4.3.2 字节加载（Task 1）、指纹失效/退役并存/Release 按实例（Task 2）、README 语义更新（Task 3）✓
|
||
- **占位符**：无；每步含完整代码/命令 ✓
|
||
- **类型一致性**：`Entry.Fingerprint`、`_current/_retired`、`ComputeFingerprintOrNull` 在测试与实现间一致；`Md5Util` 来自 Server.Host 已有的 PublishTool 引用（`GameModuleLoader.VerifySignature` 已在用）✓
|
||
- **测试隔离**：全部改写文件的测试用临时 gamesRoot 拷贝，不碰共享 `TestGames.Root` ✓
|
||
- **无 git**：commit 步骤替换为验证 checkpoint ✓
|