代码初始化

2026-05-07 15:54:43 +08:00
parent a078ca46e5
commit 3522f1011f
274 changed files with 15704 additions and 0 deletions
@@ -0,0 +1,101 @@
+# CrossModule
+
+**跨服独立进程**：仅启动 **一个 CmdRpc TCP 服务**（默认 **9200**），处理来源为 **`CommandSource.CROSS_TCP`** 的命令。  
+区服通过 **`CrossTcpClient`**（在 ServerModule）作为 **TCP 客户端** 连到本进程。
+
+## 进程职责
+
+| 职责 | 说明 |
+|------|------|
+| 监听 TCP | `CrossTcpServer` 在 `ApplicationReadyEvent` 后 `bind(cross.tcp.port)` |
+| Pipeline | `CrossTcpChannelInitializer`：`LengthPrefixedProtobuf` 解码 + `CmdRpcTcpFrameHandler` |
+| 命令路由 | `CrossGameCommandRegistry` 只注册 `@Cmd(source=CROSS_TCP)` 的 Bean |
+| 链路安全（可选） | `CrossLinkAcceptProperties`：`cross.link.expected-token` 非空时校验注册 token |
+
+## 网络拓扑
+
+```mermaid
+flowchart LR
+  subgraph Zone["ServerModule"]
+    CC[CrossTcpClient]
+  end
+  subgraph Cross["CrossModule :9200"]
+    XT[CrossTcpServer]
+    PL[pipeline]
+    REG[CrossGameCommandRegistry]
+  end
+  CC <-->|单 TCP 长连接 长度前缀+CmdRpcEnvelope| XT
+  XT --> PL --> REG
+```
+
+## 入站 Pipeline（与 BaseModule 一致）
+
+```text
+Socket
+  → LengthFieldBasedFrameDecoder（由 LengthPrefixedProtobuf 配置）
+  → CmdRpcTcpFrameHandler
+        → CmdRpcChannelDispatch（linkSource = CROSS_TCP）
+        → GameCommand.execute
+  → 编码响应帧写回
+```
+
+跨服侧 **`CrossRpcInvoker` 传 `null`**：跨服命令里 **不应** 再同步 `roundTrip` 回调区服（Demo 未实现跨服主动调区服）。
+
+## 已实现的 `CROSS_TCP` 命令
+
+### 业务：Service_2 / Method2
+
+- **`CrossForwardCommand`**（`AbstractTypedPbCommand`）  
+  - 入参：`CrossForwardCts`  
+  - 出参：`CrossForwardStc`  
+  - Demo 逻辑：给 `trace` 加前缀并写入 `cross_time_ms`。
+
+### 链路：Service_4（注册 / 心跳）
+
+| method | 命令类 | 作用 |
+|--------|--------|------|
+| Register | `CrossLinkRegisterCommand` | 校验 `server_id`、可选 `expected-token` |
+| Heartbeat | `CrossLinkHeartbeatCommand` | 回显 `client_time_ms`，写入 `cross_time_ms` |
+
+```mermaid
+sequenceDiagram
+  participant Z as 区服 CrossTcpClient
+  participant X as CrossModule
+  Z->>X: Service_4 Register + link_seq + CrossLinkRegisterCts
+  X-->>Z: 同 link_seq + CrossLinkRegisterStc(ok/message)
+  loop 每 heartbeat-interval-ms
+    Z->>X: Service_4 Heartbeat + link_seq
+    X-->>Z: CrossLinkHeartbeatStc
+  end
+  Z->>X: Service_2 Method2 + link_seq + CrossForwardCts
+  X-->>Z: CrossForwardStc
+```
+
+## 配置（`src/main/resources/application.yml`）
+
+```yaml
+cross:
+  tcp:
+    port: 9200          # Netty 监听端口
+  link:
+    expected-token: ""  # 非空则须与区服 cross.token 一致
+app:
+  logging:
+    dir: logs/CrossModule
+```
+
+## 启动
+
+主类：`com.huangzj.cross.CrossModuleApplication`  
+
+建议 **先于区服** 启动，否则区服 `CrossTcpClient` 预热与心跳会失败（日志告警），待跨服起来后下次业务或心跳会重连。
+
+## 日志
+
+`logback-spring.xml`：控制台 + 按级别分文件（`info.log` / `error.log`），目录由 `app.logging.dir` 指定。
+
+## 扩展跨服 RPC
+
+1. 在 **ProtoBufModule** 增加 `service/method` 与消息体。  
+2. 在本模块新增 `@Cmd(source=CROSS_TCP, ...)` 的 `GameCommand` 或 `AbstractTypedPbCommand`。  
+3. 若需强类型自动解码，使用 **`AbstractTypedPbCommand`**；启动时 **`ProtoRegistryAutoConfigurer`** 会为跨服进程注册对应 `ProtoInfo`。