README.md

Croupier Platform

Croupier 是面向游戏运营与控制场景的 Server / Agent / SDK 平台，默认服务于单一游戏公司内部的多个游戏与多个环境。当前架构已经收敛到“统一 session 传输”方向：

• Agent <-> Server：默认采用 TCP session，默认启用 TLS
• SDK <-> Agent：默认采用 TCP session，默认不启用 TLS，按需开启
• 两条链路共享同一套 session 传输基座，只在首条握手消息和业务语义上区分子协议

Highlights

• 单公司、多游戏、多环境作用域模型：标准业务边界是 game_id + env
• 业务作用域与运行目标分离：scope 表达归属，target 表达部署与执行位置
• 统一的函数注册、调度、调用与作业模型
• 轻量 session 传输：单连接、双向请求、可重连、可背压、可摘流
• JSON payload + protobuf 信封，兼顾跨语言一致性与接入成本
• Formily + JSON Schema 驱动的控制台 UI

SDK 生态

所有官方 SDK 已整合到 monorepo 的 sdks/ 目录下统一维护。

官方 SDK

语言	目录	Build	Coverage	Docs
Go	sdks/go/			README
JS/TS	sdks/js/			README
Python	sdks/python/			README
Java	sdks/java/			README
C#	sdks/csharp/			README
C++	sdks/cpp/			README

当前架构

graph TB
  subgraph "展示层"
    UI[Dashboard<br/>React + Ant Design + Formily]
  end

  subgraph "控制层"
    Server[Server<br/>Registry / Dispatch / RBAC / Audit]
  end

  subgraph "代理层"
    Agent1[Agent 1<br/>Session Client + Local Gateway]
    Agent2[Agent 2<br/>Session Client + Local Gateway]
  end

  subgraph "业务层"
    GS1[Game Server A<br/>SDK / Third-party App]
    GS2[Game Server B<br/>SDK / Third-party App]
    GS3[Game Server C<br/>SDK / Third-party App]
  end

  UI -->|HTTP REST| Server
  Agent1 -->|TCP Session + TLS| Server
  Agent2 -->|TCP Session + TLS| Server
  GS1 -->|TCP Session| Agent1
  GS2 -->|TCP Session| Agent2
  GS3 -->|TCP Session| Agent1

Loading

关键边界说明：

• Server 不再依赖反向直连 Agent 暴露的 rpc_addr
• Agent 本地监听只服务 GameServer / SDK / 第三方应用
• Server -> Agent 的 Invoke / StartTask / CancelTask / Ops 都应复用既有 Agent-Server session

Session 模型

Croupier 当前的核心传输抽象不是 历史消息模式，而是轻量的应用层 session：

• 一条可靠长连接
• 首条消息完成身份与能力协商
• 同一连接上双向发起新请求
• 多个并发 in-flight 请求复用
• heartbeat / reconnect / drain / backpressure

这也是为什么当前文档中会出现两个术语：

• shared session runtime
  • 指共享的传输基座：tcp/tls + framing + mux + reconnect + heartbeat + drain
• subprotocol
  • 指运行在该基座上的不同子协议
  • 例如：
    • sdk-agent subprotocol
    • agent-server subprotocol

subprotocol 不是“个性化配置”，而是“共享同一套 session 运行时，但握手消息、注册内容和路由语义不同的应用层协议变体”。

Scope 模型

Croupier 不采用 SaaS 多租户抽象。标准业务作用域为：

• game_id：游戏标识
• env：逻辑环境标识，如 dev、staging、prod

这里的 env 表达的是生命周期阶段，不直接等于具体数据库、集群或节点。物理部署与运行位置应通过单独的 target、node、agent 等抽象表达，而不是混入 env。

文档入口

• 架构总览：docs/architecture/index.md
• 游戏与环境作用域：docs/architecture/game-environment-scope.md
• SDK-Agent 设计：docs/architecture/sdk-agent-transport-redesign.md
• Agent-Server 设计：docs/architecture/agent-server-session-transport-redesign.md
• Wire 协议：docs/architecture/sdk-wire-protocol.md
• 统一 SDK 文档：docs/sdks/index.md
• SDK 能力矩阵：docs/sdks/sdk-parity-matrix.md
• SDK 规范：docs/sdk/specification.md
• SDK 代码入口：sdks/README.md

发布约定

• Server / Agent 发布标签使用 v*，例如 v0.2.0
• SDK 发布标签使用带语言前缀的格式：
  • sdk-js-v0.1.0
  • sdk-python-v0.1.0
  • sdk-go-v0.1.0
  • sdk-java-v0.1.0
  • sdk-cpp-v0.1.0
• 这样可以避免 monorepo 中一个标签误触发所有发布 workflow

仓库导航

组件	位置	说明
Server / Agent	cmd/, internal/	控制面、代理、调度、审计、注册与作业
Proto	proto/	protobuf 定义与生成入口（单源）
SDKs	sdks/	多语言 SDK（go, js, python, java, csharp, cpp）
Dashboard	web/	Web 控制台（React + Ant Design）
Examples / Tools	examples/, tools/	示例和辅助工具
Docs	docs/	架构、指南、API 与 SDK 文档

快速开始

1. 拉取代码

git clone https://github.com/cuihairu/croupier.git
cd croupier

2. 安装工具链

• Go 1.26+
• Node.js 22+ / pnpm
• buf
• protoc

3. 安装 pre-commit hook（推荐）

cp scripts/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

4. 构建

make dev

5. 启动

./bin/croupier-server --config configs/server.yaml
./bin/croupier-agent --config configs/agent.yaml

6. 查看 Dashboard

cd web
pnpm install
pnpm dev

说明

当前仓库中仍有部分历史文档引用 gRPC、历史 REQ/REP、LocalControl、rpc_addr 或 SDK 本地监听模型。 这些内容正在按“统一 TCP session + subprotocol”设计逐步清理，不应再作为新的实现依据。