客户端游戏 TCP（game.client-tcp.port，默认示例 9091）：CommandSource.Client_TCP
连跨服的出站 TCP 长连接（cross.host / cross.port，示例 9200）：由 CrossTcpClient 维护，ProtoRegistry 中对应逻辑仍按跨服协议，但 连接发起在区服
HTTP（server.port，默认 8080）：Demo API、探针、静态探测页

总体数据流

flowchart TB
  subgraph External["外部"]
    GAME[游戏客户端 TCP]
    BROWSER[浏览器 / HTTP 客户端]
  end
  subgraph Server["ServerModule"]
    CTS[ClientTcpServer :9091]
    HTTP[HTTP :8080]
    REG[ServerCommandRegistry]
    C2[TcpPath2 等命令]
    CC[CrossTcpClient 长连接]
  end
  subgraph Cross["CrossModule :9200"]
    XT[Cross TCP]
  end
  GAME --> CTS --> REG --> C2
  BROWSER --> HTTP
  C2 --> CC --> XT

1. 客户端 TCP（主入口）

ClientTcpServer：ApplicationReadyEvent 后绑定端口（@Order 较早，保证先于跨服预热）。
ClientTcpChannelInitializer：解码器 + CmdRpcTcpFrameHandler（linkSource = Client_TCP，注入 ServerCommandRegistry 与 CrossTcpClient 作为 CrossRpcInvoker）。

sequenceDiagram
  participant C as 客户端
  participant S as ClientTcpServer
  participant R as ServerCommandRegistry
  participant Cmd as GameCommand
  participant X as CrossTcpClient
  C->>S: 帧: CmdRpcEnvelope
  S->>R: resolve(service, method)
  R->>Cmd: execute
  opt 路径2/3
    Cmd->>X: roundTrip(跨服信封)
    X-->>Cmd: 跨服响应
  end
  Cmd-->>S: 响应 CmdRpcEnvelope
  S-->>C: 帧

三条路径（概念对照）

路径	Client TCP service/method	是否调跨服	说明
1	Service_1 / Method1	否	Echo
2	Service_2 / Method2	是	`CrossProxy` → 转 `CrossForward` → 跨服 → 回写 `CrossProxyStc`（含 `server_note`）
3	Service_3 / Method3	是	信封对客户端为 S3，payload 为 `CrossForwardCts`；区服只转发跨服

实现类：TcpPath1LocalEchoCommand、TcpPath2CrossThenServerCommand、TcpPath3CrossRelayCommand。

2. 区服 → 跨服：`CrossTcpClient`

单连接长连：ensureConnected() 建链；断线后 linkRegistered=false，下次业务或心跳会重建。
注册：Service_4 + Register，载荷 CrossLinkRegisterCts（cross.server-id、cross.token）。
心跳：CrossTcpHeartbeatTask 按 cross.heartbeat-interval-ms（默认 15000）调用 sendHeartbeat()（Service_4 + Heartbeat）。
多路复用：每次 roundTrip 分配 link_seq，在 pendingBySeq 中挂 CompletableFuture；入站 dispatchInbound 按 link_seq 完成 Future。

stateDiagram-v2
  [*] --> Disconnected
  Disconnected --> Connected: ensureConnected
  Connected --> Registered: Service_4 Register OK
  Registered --> Registered: roundTrip / Heartbeat
  Registered --> Disconnected: 断链 / 心跳失败

预热：CrossTcpClient.warmupCrossLink() 监听 ApplicationReadyEvent（@Order 较低，在 ClientTcpServer 绑定之后），提前建链+注册。

配置示例见根目录 README.md 或本模块 application.yml：

cross.host、cross.port（须与 CrossModule cross.tcp.port 一致）
cross.server-id、cross.token、cross.heartbeat-interval-ms

3. HTTP

/api/ping（PingController）：探活。
/api/config/client-tcp（ClientTcpConfigController）：返回 game.client-tcp.port。
/api/demo/*：Mongo / Redis / 事件 / 模块 tick 等演示接口（见 DemoApiController）。

4. 其它 Demo（非网络核心）

MongoDB / Redis / 事件 / 玩家模块 tick 等：见 com.huangzj.server 下 web、mongo、redis、module 等包。

5. 本机命令行压测三条 TCP 路径

com.huangzj.server.demo.TcpPathsDemo：与客户端相同帧格式，默认 127.0.0.1:9091。

java -cp ... com.huangzj.server.demo.TcpPathsDemo [host] [port]

6. 日志

app.logging.dir：默认 logs/ServerModule
logback-spring.xml：info.log（INFO+WARN，不含 ERROR）与 error.log（仅 ERROR）

7. 启动顺序建议

启动 CrossModule（端口 9200）。
启动 ServerModule（HTTP 8080，客户端 TCP 9091）。
用 TcpPathsDemo 或自建 TCP 客户端按路径 2 组帧，可验证经区服到跨服的全链路。

README.md Unescape Escape

ServerModule