doc(readme): 补热更校验与 Actor 限流规则配置说明

CHANGELOG.md

@@ -18,6 +18,7 @@
 * HTTP 请求管线正确性与响应一致性（C458，GFX-1180，GitHub #926）：ProtoBuf 成功响应写出前更正 Content-Type 为 `application/x-protobuf`（原恒为 JSON，按媒体类型分派的客户端/网关解析二进制体失败）；参数字典改 OrdinalIgnoreCase 并同步把 Query 提取改 TryAdd——大小写差异同名键（Query↔Body、Query↔Query）一律显式 `ParamErr` 拒绝，消除「被校验/被签名的 Query 值被 Body 静默覆盖」窗口；非 JSON 对象 Body（null 字面量/数组/标量/空体）以参数错误拒绝（新键 `Network.Http.RequestBodyNotJsonObject`），不再落入顶层 catch 记服务器错误日志；非 GET 缺 Content-Type 改统一 JSON envelope；DataAnnotations 校验失败业务码由字面量 400 统一为 `GameHttpStatusCode.ParamErr`；Swagger 路由匹配改末段精确比较（互为后缀命令不再错配文档，驼峰路由可匹配）且 GET 参数必填性跟随 `RequiredAttribute`；AOP 拒绝且未自行写响应时管线回写校验失败 envelope（契约写入 `IHttpAopHandler.Run`）；`CheckSign` 缺 sign/timestamp 改本地化消息。对外破坏性：依赖 `code == 400` 判定校验失败的客户端改判 `code == 13`；`HttpStatusMessage.Success`/`NotFoundCommand`/`CheckFailedCommand` 及孤儿键 `Network.Http.NotFoundCommand`/`CheckFailedCommand` 删除（公共 API，下游如有引用需迁移）。
 * Utility 安全修复：配置凭据脱敏、解压炸弹上限、冲突异常 Secret 脱敏与压缩失败显式抛出（C433，GFX-1173，GitHub #919）：①`AppSetting.ToString/ToFormatString` 经浅拷贝掩码后序列化——`DataBasePassword`/`HttpSignSecret`/`InterNodeAuthSecret`/`HttpsCertPassword` 非空值输出 `***`（null/空串原样保留区分「未配置」），四个凭据不再随启动/停止日志明文外发；②`CompressionHelper.Decompress` 新增 `maxOutputLength` 上限重载（旧签名转发 const 默认 64MB），膨胀过程内超限即抛 `InvalidDataException`——Network `DefaultMessageDecompressHandler` 增构造参数上限、RemoteMessaging `IMessageCompressionAlgorithm.Decompress` 接口加参（const 默认值，源码兼容；`DefaultMessageCodec` 显式传 `_maxDecompressedSize`），事后长度检查降级为兜底防线，1MB 高压缩比帧不再可膨胀至 GB 级托管内存；③`SettingFieldConflict` 敏感字段判定扩展 Secret/Token 子串——多 Role 配置冲突异常不再明文携带 `HttpSignSecret`/`InterNodeAuthSecret`；④`RandomHelper` 类文档声明双随机源分级（基础接口 `Random.Shared` 非加密 PRNG 禁用于令牌/验证码/防作弊场景，安全场景用权重系列 CSPRNG 或 `RandomNumberGenerator`）；⑤落地已归档 C349 既定方案：`Compress` 异常原样抛出、`Decompress` 对非法/损坏/截断数据统一抛 `InvalidDataException`（含 SharpZipLib 截断流死循环主动判定），删除「失败静默返回原始字节」回退与 `CompressFailed` 本地化键；⑥`FP.Sqrt/Acos` 越界异常构造器实参换序（本地化消息进 `Message`、`"x"` 进 `ParamName`，修复前 `ParamName == null`）。公共 API 行为变更经本条披露；解压炸弹/脱敏/截断/参数名均有回归用例锁定。
 
+* Core 热更注册契约、装载信任与行为一致性 13 项（C437，GFX-1177，GitHub #923）：`HotfixModule.GetComponentTypeFromAgent` 统一守卫五处泛型基类反推（契约异常替代 IndexOutOfRangeException）并使 `AddEvent` 组件→Actor 反查带上下文抛出；RPC 注册面工厂化（`_rpcHandlerMap` 值改 `Func<IMessageHandler>`，注册期 CreateFactory 校验、同请求重复注册 fail-fast）与 `MessageRpcMappingAttribute` 改 `(Type, Type)` 形态（原接口实例参数因 CS0181 从未可用，属破坏性修正，零存量消费者）；消息号冲突 fail-fast；HTTP 命令字典改 OrdinalIgnoreCase 且全小写命令单次注册；热更依赖装载随模块可收集上下文同生共死（判重只看默认 ALC，热重载亦装载）；热更装载 SHA-256 哈希校验灰度开关（`HotfixVerifyEnabled` 默认 false + `HotfixLoadOptions.ExpectedSha256`，校验在 ALC 创建前，仅覆盖主程序集）；`DelayAsync(long)` 改 Unix 毫秒时间戳 UTC 同基解释；跨天第二段独立计时；组件 RPC 超时回写 TimeOut 响应（孤儿响应终态归还）；ActorLimit 收敛为真实可用（死代码删除、在飞登记 EndCall 移除含空集合回收、`ActorLimitRule` 配置化默认 None、8 调用点拒绝异常化、`WorkWrapper.CallerActorId`）；未登录玩家消息删除随机 ActorId 回退（Fatal+关通道）；`ComponentRegister.InitAsync` 加锁修复并行初始化字典损坏；六本地化键双语。
 * Core 回收链路数据与稳定性修复（C436，GFX-1176，GitHub #922）：`Actor.OnRecycleAsync` 在回收回调后删除 `ScheduleIdSet` 中剩余的 Quartz 任务并清空集合，三条回收路径（空闲回收 / `RemoveAsync` / `RemoveAllAsync`）均覆盖；定时任务触发改为 `isNew: false` 反查，目标 Actor 不在内存时不再重建 Actor（消除周期任务复活已回收 Actor 的循环），记 Warning 并删除该任务。`BaseComponent.InactiveAsync` 以 try/finally 保证 `IsActive` 落为 false，`Actor.InactiveAsync` 逐组件隔离异常（Fatal 日志后继续），单个组件反激活失败不再让 Actor 永驻内存，也不再打断 `RemoveAllAsync` 关服流程。显式移除前对有未落库修改的 Actor 强制回存（失败记 Fatal 不阻断移除）。`StateComponent.TimerSaveAsync` 单个状态类型回存失败不再中断整轮，日志级别 Info → Error。`ActorManager.RemoveAsync` 返回真实完成任务（await 返回即回存 / 反激活 / 回收回调均已执行，隔离 Actor 返回异常任务）并同步删除 `ActiveTimeDic` 条目。行为变化：依赖「定时器唤醒离线 Actor」的业务需在触发前自行加载 Actor；组件反激活异常不再向 `RemoveAllAsync` 调用方抛出。回归 11 例（A/B：还原生产改动后 11/11 必败）。
 * 架构分析器守卫三项收口（C429/C430，GFX-1170，GitHub #916）：GFX0016 候选集从仅 Class 放宽为全部命名类型种类——struct/interface/record 声明面引用 `MongoDbService`/`PostgreSqlDbService`/`MultiDbRegistry` 不再漏报（自行注册 NamedType 符号分析，实现层白名单与豁免不变）；GFX0001 补抽象类豁免（与 GFX0005/0008/0009 一致，非 Apps 程序集的抽象中间状态类不再被误拦）；生成 Wrapper 豁免改为「`GeneratedCodeAttribute` 标记（tool 名精确匹配）+ `.g.cs` 文件路径 + 仅 Hotfix 内名称后缀兜底」三段判定，Hotfix 之外手写 `ComponentAgentWrapper` 后缀类不再同时逃过 GFX0005/GFX0014；WrapperGenerator 生成类头追加 `GeneratedCodeAttribute` 标记（与分析器 `WrapperGeneratorToolName` 同值契约）。
 * 入队与定时撮合解耦（C406，GFX-1104）：删除每次入队的全量撮合及最新票据扫描，复用 `matchmaker-run` 按宿主调度节奏批量处理队列（默认 1000ms）。单轮撮合算法保持不变；桥测试覆盖四名玩家单批次形成两组及批次前取消不参与分配。

GameFrameX.Core/Actors/Actor.cs

@@ -33,6 +33,7 @@
 using GameFrameX.Core.Abstractions.Timer;
 using GameFrameX.Core.Actors.Impl;
 using GameFrameX.Core.Components;
+using GameFrameX.Core.Hotfix;
 using GameFrameX.Core.Timer;
 using GameFrameX.Foundation.Logger;
 using GameFrameX.Foundation.Localization.Core;
@@ -154,7 +155,7 @@ public List<IComponentAgent> GetActiveComponentAgents()
     /// <returns>返回指定类型的组件代理实例</returns>
     public async Task<IComponentAgent> GetComponentAgentAsync(Type agentType, bool isNew = true)
     {
-        var compType = agentType.BaseType.GetGenericArguments()[0];
+        var compType = HotfixModule.GetComponentTypeFromAgent(agentType);
         BaseComponent component;
         if (isNew)
         {

GameFrameX.Core/Actors/ActorManager.cs

@@ -532,6 +532,9 @@ async Task Work()
         var globalCost = (DateTime.Now - begin).TotalMilliseconds;
         // Localization: Core.ActorManager.GlobalCompCrossDayCompleteLog - ActorManager.CrossDayAsync 全局comp跨天完成 , 耗时: {0}ms , 消息: 全局comp跨天完成 耗时：{1}ms
         LogHelper.Info(LocalizationService.GetString(Localization.Keys.Core.ActorManager.GlobalCompCrossDayCompleteLog, globalCost, globalCost));
+
+        // 第二段（非玩家段）投递前重置等待基准：跨天预算按段独立计量，不复用第一段已消耗的 begin
+        begin = DateTime.Now;
         a = 0;
         b = 0;
         foreach (var actor in ActorMap.Values)
@@ -562,7 +565,7 @@ async Task Work()
             await Task.Delay(TimeSpan.FromMilliseconds(10));
         }
 
-        var otherCost = (DateTime.Now - begin).TotalMilliseconds - globalCost;
+        var otherCost = (DateTime.Now - begin).TotalMilliseconds;
         // Localization: Core.ActorManager.NonPlayerCompCrossDayCompleteLog - ActorManager.CrossDayAsync 非玩家comp跨天完成 , 耗时: {0}ms , 消息: 非玩家comp跨天完成 耗时：{1}ms
         LogHelper.Info(LocalizationService.GetString(Localization.Keys.Core.ActorManager.NonPlayerCompCrossDayCompleteLog, otherCost, otherCost));
     }

GameFrameX.Core/Actors/Impl/ActorLimit.cs

@@ -58,7 +58,6 @@ public enum RuleType
 
 
     private static IRule _rule;
-    private static readonly Dictionary<ushort, int> LevelDic = new(128);
 
     /// <summary>
     /// 初始化
@@ -68,30 +67,13 @@ public static void Init(RuleType type)
     {
         switch (type)
         {
-            /*case RuleType.ByLevel:
-            {
-                _rule = new ByLevelRule();
-                try
-                {
-                    foreach (ActorTypeLevel foo in Enum.GetValues(typeof(ActorTypeLevel)))
-                    {
-                        var actorType = (ushort)foo;
-                        LevelDic.Add(actorType, (int)foo);
-                    }
-                }
-                catch (Exception exception)
-                {
-                    LogHelper.Fatal(exception);
-                    throw;
-                }
-            }
-                break;*/
             case RuleType.NoBidirectionCall:
                 {
                     _rule = new NoBidirectionCallRule();
                 }
                 break;
             case RuleType.None:
+                _rule = null;
                 break;
             default:
                 // Localization: Core.ActorLimit.UnsupportedRuleType - 不支持的rule类型:{0}
@@ -101,75 +83,54 @@ public static void Init(RuleType type)
     }
 
     /// <summary>
-    /// 是否允许调用
+    /// 是否允许调用：规则激活时检查并在放行时登记「self → target」在飞调用。
     /// </summary>
     /// <param name="target">目标</param>
     /// <returns>返回是否调用</returns>
     public static bool AllowCall(long target)
     {
-        if (_rule != null)
+        var rule = _rule;
+        if (rule != null)
         {
-            return _rule.CanCall(target);
+            return rule.CanCall(target);
         }
 
         return true;
     }
 
-    private interface IRule
+    /// <summary>
+    /// 结束一次在飞调用：工作单元终态（执行完毕/入队失败/取消/超时放弃）时移除登记，内存天然有界。
+    /// </summary>
+    /// <param name="self">调用方Actor ID</param>
+    /// <param name="target">目标Actor ID</param>
+    public static void EndCall(long self, long target)
     {
-        bool CanCall(long target);
+        _rule?.EndCall(self, target);
     }
 
-
-    #region ByLevelRule
-
-    private class ByLevelRule : IRule
+    private interface IRule
     {
-        /// <summary>
-        /// 判断是否允许调用
-        /// </summary>
-        /// <param name="target">目标</param>
-        /// <returns></returns>
-        bool IRule.CanCall(long target)
-        {
-            var actorId = RuntimeContext.CurrentActor;
-            // 从其他线程抛到actor，不涉及入队行为
-            if (actorId == 0)
-            {
-                return true;
-            }
-
-            var currentType = ActorIdGenerator.GetActorType(actorId);
-            var targetType = ActorIdGenerator.GetActorType(target);
-            if (LevelDic.TryGetValue(targetType, out var targetValue) && LevelDic.TryGetValue(currentType, out var currentValue))
-            {
-                //等级高的不能【等待】调用等级低的
-                if (currentValue > targetValue)
-                {
-                    // Localization: Core.ActorLimit.InvalidCallPath - 不合法的调用路径:{0}==&gt;{1}
-                    LogHelper.Error(LocalizationService.GetString(Localization.Keys.Core.ActorLimit.InvalidCallPath, currentType, targetType));
-                    return false;
-                }
-            }
+        bool CanCall(long target);
 
-            return true;
-        }
+        void EndCall(long self, long target);
     }
 
-    #endregion
-
 
     #region NoBidirectionCallRule
 
     private class NoBidirectionCallRule : IRule
     {
-        private readonly ConcurrentDictionary<long, ConcurrentDictionary<long, bool>> _crossDic = new();
+        /// <summary>
+        /// 并发在飞调用计数登记：self → { target → 在飞计数 }。
+        /// 同一 caller→target 的并发调用按次数累加、按终态递减，全部结束后回收边与外壳键，内存天然有界。
+        /// </summary>
+        private readonly ConcurrentDictionary<long, ConcurrentDictionary<long, InFlightCounter>> _crossDic = new();
 
         /// <summary>
         /// 是否允许调用
         /// </summary>
         /// <param name="target">目标</param>
-        /// <returns>返回是否调用</returns>
+        /// <returns></returns>
         bool IRule.CanCall(long target)
         {
             var actorId = RuntimeContext.CurrentActor;
@@ -198,12 +159,52 @@ private bool CanCall(long self, long target)
                 return false;
             }
 
-            var selfSet = _crossDic.GetOrAdd(self, k => new ConcurrentDictionary<long, bool>());
-            selfSet.TryAdd(target, false);
+            var selfSet = _crossDic.GetOrAdd(self, k => new ConcurrentDictionary<long, InFlightCounter>());
+            var counter = selfSet.GetOrAdd(target, k => new InFlightCounter());
+            Interlocked.Increment(ref counter.Count);
 
             return true;
         }
+
+        /// <summary>
+        /// 终态递减在飞计数：计数归零时回收边，边集合清空后原子回收外层键。
+        /// 调用方以工作单元携带的登记所有权标志守卫——未登记路径（discard/checkLock 跳过、Tell）不得递减他人计数。
+        /// </summary>
+        /// <param name="self">调用方Actor ID</param>
+        /// <param name="target">目标Actor ID</param>
+        void IRule.EndCall(long self, long target)
+        {
+            // IO 上下文与自调用未登记，无需移除
+            if (self == 0 || self == target)
+            {
+                return;
+            }
+
+            if (_crossDic.TryGetValue(self, out var set) && set.TryGetValue(target, out var counter))
+            {
+                if (Interlocked.Decrement(ref counter.Count) <= 0)
+                {
+                    // 仅当仍为当前计数实例时移除边（原子引用比较）：并发重入者会命中同实例并使计数大于零，
+                    // 不会进入本分支；被并发替换的实例残留由其自身路径的终态递减清理
+                    set.TryRemove(new KeyValuePair<long, InFlightCounter>(target, counter));
+
+                    if (set.IsEmpty)
+                    {
+                        _crossDic.TryRemove(new KeyValuePair<long, ConcurrentDictionary<long, InFlightCounter>>(self, set));
+                    }
+                }
+            }
+        }
+
+        /// <summary>
+        /// 在飞调用计数器（同 caller→target 并发调用按次数累加，首个终态不再清边）。
+        /// </summary>
+        private sealed class InFlightCounter
+        {
+            /// <summary>当前在飞计数。</summary>
+            public int Count;
+        }
     }
 
     #endregion
-}
+}

GameFrameX.Core/Actors/Impl/WorkWrapper.cs

@@ -52,6 +52,18 @@ public abstract class WorkWrapper
     /// </summary>
     public long CallChainId { get; set; }
 
+    /// <summary>
+    /// 调用方Actor ID（入队时捕获 RuntimeContext.CurrentActor）。
+    /// ActorLimit 在飞登记移除用：工作单元终态时以其定位「caller → target」登记项。
+    /// </summary>
+    public long CallerActorId { get; set; }
+
+
+    /// <summary>
+    /// 本工作单元是否持有 ActorLimit 在飞登记（入队时经 AllowCall 放行且实际登记为 true）。
+    /// 未登记路径（discard/checkLock 跳过、Tell）不得在终态移除他人登记。
+    /// </summary>
+    public bool LimitRegistered { get; set; }
     /// <summary>
     /// 调用方传入的取消令牌。
     /// 入队阶段用于取消排队；执行阶段与超时合并为执行期取消源（见 <see cref="BeginExecution"/>）。