Croupier

什么是 Croupier ​

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

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

系统架构 ​

入口按受众分为两个独立的面，不要合并成一个「负载均衡层」：

• Web 控制台面（面向运营/管理员，公网或办公网）：L7 dashboard nginx， 按请求分流 HTTP API / SSE 到 Server 的 :18780
• Agent 面（内网，面向游戏 VPC 出站连接）：L4 haproxy（:19090）， 按 TCP 长连接打散到 Server 的 control listener；连接语义是「断线重连即漂移」， 与 HTTP 的按请求分流完全不同

两个入口面互不共享：Web 面的 nginx 不碰 Agent 流量，Agent 面的 haproxy 不碰 HTTP。L4/L7 选型与 VRRP 消除 LB 单点的论证见 负载均衡。

Server 支持多实例高可用部署（cluster.enabled）：成员发现走共享存储（无 seed、无静态 peers），请求落到非 owner 实例时经实例互联转发（一跳限制 + epoch fencing）。单实例部署默认关闭集群，零开销。详见 Server 多实例高可用设计。

关键边界说明：

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

核心能力 ​

函数管理 ​

• OpenAPI 驱动注册：通过 OpenAPI 规范快速注册函数
• JSON Schema 表单展示：根据函数契约生成字段与校验，JSON Schema form adapter 统一渲染调用、查询、创建、编辑与动作表单
• Resource/PageSpec 编排：CRUD Resource、独立操作、分页表格、报表和任务页由强类型 PageSpec 组合多个函数
• 统一调用链路：控制面通过 Agent session 路由调用，本地接入通过 Agent gateway 完成

权限与安全 ​

权限判定基于 Casbin 的 RBAC/ABAC 混合模型，角色之外还能按属性放行或拦截。政策分两层：YAML 给默认值，数据库覆盖策略在线调整。操作按低/中/高/危险四级定风险，高危操作自动进审批流程，其中双人审批规则要求多人确认才放行。

作用域模型 ​

• 单公司多游戏：不引入 SaaS 多租户抽象，标准业务边界是 game_id
• 多环境治理：env 表达 dev/test/staging/prod 等逻辑环境
• 归属与部署分离：scope 表达业务归属，target 表达运行位置

可观测性 ​

所有操作写审计日志，记录之间用哈希链关联，改一条就断链，事后能查出来。密码、token 等敏感字段在日志与响应里自动脱敏。

运维工具 ​

• 工单系统：玩家问题工单流转
• 反馈管理：收集玩家反馈
• 公告系统：游戏公告发布
• 数据分析：玩家行为、留存、支付等数据分析

快速开始 ​

安装 ​

# 克隆仓库
git clone https://github.com/cuihairu/croupier.git
cd croupier

# 下载依赖
go mod download

# 构建服务
make build

启动服务 ​

# 启动 Server
./bin/croupier-server --config configs/server.yaml

# 启动 Agent
./bin/croupier-agent --config configs/agent.yaml

验证安装 ​

# 检查 Server 健康状态
curl http://localhost:18780/healthz

# 查看 API 文档
curl http://localhost:18780/api/v1/

文档导航 ​

按使用路径组织：

历史设计与迁移文档归入 架构 - 提案与迁移（侧栏已折叠），不作为接入主路径。

技术栈 ​

• 后端：Go 1.26，HTTP 框架 Gin，ORM 为 GORM（MySQL / PostgreSQL / SQLite / SQL Server）
• 权限判定：Casbin（RBAC/ABAC）
• 内部链路：自建 TCP session，长度前缀分帧 + protobuf 信封
• 控制台：Umi Max + React + Ant Design Pro / ProComponents
• 文档站点：VitePress

路线图 ​

• [x] 基础函数注册与调用
• [x] RBAC 权限控制
• [x] 审批流程
• [x] 审计日志
• [x] 双层政策架构
• [x] Dashboard vNext：函数注册自动生成页面（Proposal Inbox / Page Studio / Resource Catalog / Console 动态菜单）
• [ ] 插件市场
• [ ] 更多 SDK 语言支持

开源协议 ​

Apache-2.0 License