Croupier

Appearance

部署指南 ​

本文档只保留当前仓库已有产物对应的部署方式：Docker 镜像、docker compose 和二进制部署。

推荐组件 ​

  • Server
  • Agent
  • MySQL 或 PostgreSQL
  • Redis
  • 可选：analytics-worker、ingest、ClickHouse

Docker 部署 ​

三份编排按场景分工，别混用：

编排镜像来源适用
docker-compose.quickstart.ymlghcr 预构建快速体验/演示：一条命令最小栈，无需本地构建
docker-compose.yml源码构建本地开发：改代码即改容器
docker-compose.deploy.ymlghcr 预构建生产 HA：双实例 server/agent + haproxy

快速体验（quickstart，开箱即用） ​

预构建镜像（ghcr.io，匿名可拉）起最小栈：postgres + redis + server + agent + dashboard。

bash
cd docker
docker compose -f docker-compose.quickstart.yml up -d
# 验证：五容器全 healthy；curl http://localhost:18780/healthz 应见
# "ok":true 且 registry.agentsHealthy=1（agent 已注册）；Dashboard 在 :8000

常用操作：

bash
# 看日志 / 停止
docker compose -f docker-compose.quickstart.yml logs -f server
docker compose -f docker-compose.quickstart.yml down

# 升级全栈（pull + 重建）
docker compose -f docker-compose.quickstart.yml pull
docker compose -f docker-compose.quickstart.yml up -d

# 清数据（⚠️ 连数据卷一起删：业务库、上传文件全没）
docker compose -f docker-compose.quickstart.yml down -v

可选组件用 profile 拉起，不混进默认最小栈：

bash
# SDK 六语言 + OpenAPI 示例——只想起示例时显式列服务名（见下「隐式全栈更新」坑）
docker compose -f docker-compose.quickstart.yml --profile sdk-examples \
  up -d sdk-demo-go sdk-demo-python sdk-demo-java \
        sdk-demo-js sdk-demo-cpp sdk-demo-csharp

# 分析管道（ClickHouse + ingestion + worker）；置 ANALYTICS_BRIDGE_ENABLED=true
# 后 server 事件才写入分析流
ANALYTICS_BRIDGE_ENABLED=true docker compose -f docker-compose.quickstart.yml \
  --profile analytics up -d

隐式全栈更新坑：--profile sdk-examples pull && up -d 会把 server/agent/dashboard 的 main 镜像一并拉新并级联 recreate，效果等同一次 升级（新功能 + 数据库迁移直接上线）。只想重建示例容器时，pull/up 都显式 限定服务名；接受级联就顺手验证新迁移已落库。secret/端口/多游戏单库切换 等说明见 docker/docker-compose.quickstart.yml 文件头注释。

本地开发（源码构建） ​

bash
docker compose up -d

当前镜像构建入口：

  • docker/Dockerfile.server -> ./cmd/server
  • docker/Dockerfile.agent -> ./cmd/agent
  • docker/Dockerfile.analytics-worker -> ./cmd/analytics-worker
  • docker/Dockerfile.ingest -> ./cmd/ingest

HA 双实例部署（docker-compose.deploy.yml） ​

生产编排 docker/docker-compose.deploy.yml 按 Server 多实例 HA 架构 部署双实例拓扑：

                          ┌─► croupier-server  ── HTTP API 18780 ─┐
浏览器 ──► dashboard nginx ┤                                       ├─► 共享 postgres/redis
（L7 分流）                └─► croupier-server2 ── HTTP API 18780 ─┘

agent/agent2 ── TCP ──► haproxy :19090（L4：leastconn + tcp-check + 运行时重解析）
                          ├─► croupier-server  :19090 ──┐
                          └─► croupier-server2 :19090 ──┴─► 集群互联转发 + 共享目录

sdk-examples ── HTTP ──► agent:19091      haproxy stats ──► :8404（连接分布排查）

openapi-provider-demo ── TCP ──► haproxy :19090（内嵌 Agent，providers.yaml 注册函数）
  • 双 Server（server/server2，YAML anchor 共享配置）：集群成员表 + owner 转发自动协同；任一实例故障，另一实例接管调用（Agent 断连重连经 LB 分发至存活实例，架构文档 §6 故障语义）
  • 双 Agent（agent/agent2）：上游统一走 haproxy:19090 L4 LB；configs/agent2.yaml 区分 Agent ID 与 httpAddr（该文件不入库，部署时复制 configs/agent.yaml 修改差异项生成）
  • 两层负载均衡各司其职（nginx 管人，HAProxy 管机器）：
    • dashboard nginx（L7）：split_clients 按请求哈希分流到两实例 18780 + docker DNS resolver 运行时解析（10s，实例重建换 IP 不 502）；SSE 已关缓冲
    • haproxy（L4）：Agent 自行开发 transport TCP 长连接 leastconn 打散 + tcp-check 主动健康检查 + resolvers 运行时重解析（实例重建自动跟随）+ stats 页（:8404）
  • 宿主端口只由每组实例 1 发布（server: 8443→19090 transport / 18780 HTTP、agent: 19091）；实例 2 仅集群内可达
  • openapi-provider-demo（sdk-examples profile，随 enable_sdk_examples=true 部署）：examples/openapi-provider 的常驻容器（镜像 croupier-openapi-provider-demo），内嵌 Agent 经 providers.yaml 把 players API 注册进 server——Dashboard「OpenAPI Sources → 运行时导入」区块的数据源，scope 跟随 CROUPIER_SDK_EXAMPLE_GAME_ID/ENV
bash
cd docker
docker compose -f docker-compose.deploy.yml up -d
# 验证：Dashboard「运维中心 → 集群拓扑」应显示两实例在线 + agent 归属分布

历史注意：曾用 dashboard nginx 的 stream 块承担 Agent L4（upstream 仅启动时解析，实例重建换 IP 需 --force-recreate dashboard）；现由独立 haproxy 服务承担（运行时重解析 + 主动健康检查），该限制不再存在。

负载均衡方案选型 ​

Agent 的 L4 入口与 Dashboard 的 L7 入口均可按部署环境替换，详细对比（nginx stream vs HAProxy vs keepalived+LVS）、配置示例与迁移路径见独立篇 负载均衡。速记：

方案层级适用
HAProxy（本仓库默认）L4Agent 接入 LB：运行时 DNS 重解析 + 主动健康检查 + stats 可观测
nginx streamL4 TCP备选：复用 dashboard 镜像零新增组件，但 upstream 仅启动时解析（实例重建需 reload）、无主动健康检查
keepalived + LVS/nginx/HAProxyVRRP + L4LB 自身高可用（VIP 漂移）；公有云等价物是云 NLB
Kubernetes ServiceL4K8s 环境无需自建 LB 层

无论哪种方案，Agent 侧无需任何改动：单地址连接 + 断线重连 + 重新注册（架构文档 §6.2 故障转移时间线）。

单独构建镜像 ​

bash
docker build -t croupier-server:latest -f docker/Dockerfile.server .
docker build -t croupier-agent:latest -f docker/Dockerfile.agent .

二进制部署 ​

Server ​

bash
make server
./bin/croupier-server --config configs/server.yaml

Agent ​

bash
make agent
./bin/croupier-agent --config configs/agent.yaml

Analytics 链路 ​

bash
make worker
make ingest
./bin/analytics-worker
ANALYTICS_INGEST_SECRET=dev-secret ./bin/ingest --addr :8088 --secret dev-secret

服务安装脚本 ​

仓库已提供：

  • scripts/install-systemd.sh
  • scripts/install-launchd.sh
  • scripts/install-windows-service.ps1

健康检查 ​

bash
curl http://localhost:18780/healthz
curl http://localhost:8088/healthz

部署建议 ​

  1. 数据库和 Redis 使用外部托管实例，不与应用容器共存储。
  2. 生产环境不要直接使用仓库默认的 configs/*.yaml，应复制后按环境落地。
  3. 通过环境变量注入 DATABASE_URL、JWT_SECRET、对象存储密钥等敏感项。
  4. Server 对外暴露 HTTP 入口；Agent 经 L4 负载均衡入口接入（见上文「负载均衡方案选型」），不要直连单个 Server 实例。

下一步 ​