Centrifugo 6.10 配置参数详解

目标：系统梳理 Centrifugo v6.10.1 的配置体系——参数查看工具、四层覆盖优先级、顶层参数段总览与核心参数逐段详解，并给出可直接落地的生产配置模板。已在 Ubuntu 22.04.5 LTS（x86_64）+ Centrifugo v6.10.1 服务器实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Centrifugo 版本：v6.10.1（Go version: go1.27.3），二进制路径 /usr/bin/centrifugo
• 配置文件：/etc/centrifugo/config.json（v6 嵌套 JSON 格式）
• 服务监听：0.0.0.0:8130（默认 8000，本机 8000 被占用改为 8130，下文所有示例一致）
• 引擎：memory（单机内置）；扩展引擎为 Redis
• 参数文档生成：centrifugo configdoc（源自官方源码内置定义）

二、前置条件

1. 已按《Ubuntu 22.04 安装 Centrifugo 指南》完成安装并修复配置文件权限（root:centrifugo 640）。
2. 了解 v6 配置格式变化：v5 及更早版本的配置是大量平铺键（如 token_hmac_secret_key、admin_password），v6 改为嵌套 JSON 结构（如 client.token.hmac_secret_key、admin.password）。从旧版本升级时配置必须迁移，不能直接沿用。
3. 掌握配置校验习惯：每次改动先跑 centrifugo checkconfig，升级版本后跑 -s 严格模式。

三、参数查看与修改方式

3.1 生成全量默认配置（defaultconfig）

defaultconfig 子命令输出当前版本全部参数的完整默认值，是参数速查的第一手资料。-d 为 dry-run，只打印不落盘：

centrifugo defaultconfig -d | head -50

实测回显（节选）：

{
  "http_server": {
    "address": "",
    "port": 8000,
    "internal_address": "",
    "internal_port": "",
    "tls": {
      "enabled": false,
      "cert_pem": "",
      "key_pem": "",
      "server_ca_pem": "",
      "client_ca_pem": "",
      "insecure_skip_verify": false,
      "server_name": ""
    },
    "tls_autocert": {
      "enabled": false,
      "host_whitelist": null,
      "cache_dir": "",
      "email": "",
      "server_name": "",
      "http": false,
      "http_addr": ":80"
    },
    "tls_external": false,
    "internal_tls": {
      "enabled": false,
      "cert_pem": "",
      "key_pem": "",
      "server_ca_pem": "",
      "client_ca_pem": "",
      "insecure_skip_verify": false,
      "server_name": ""
    },
    "http3": {
      "enabled": false
    },
    "h2c_external": false
  },
  "log": {
    "level": "info",
    "file": ""
  },

去掉 -d 并指定 -c 路径则把全量配置写成文件，可在此基础上精简。全量输出共 1095 行，覆盖 37 个顶层段。

3.2 生成环境变量清单（defaultenv）

每个配置参数都有对应的 CENTRIFUGO_* 环境变量。defaultenv 输出全量变量与默认值（共 855 行）：

centrifugo defaultenv | head -12
centrifugo defaultenv | wc -l

实测回显：

CENTRIFUGO_ADMIN_ENABLED=false
CENTRIFUGO_ADMIN_EXTERNAL=false
CENTRIFUGO_ADMIN_HANDLER_PREFIX=""
CENTRIFUGO_ADMIN_INSECURE=false
CENTRIFUGO_ADMIN_PASSWORD=""
CENTRIFUGO_ADMIN_SECRET=""
CENTRIFUGO_ADMIN_WEB_PATH=""
CENTRIFUGO_ADMIN_WEB_PROXY_ADDRESS=""
CENTRIFUGO_BROKER_ENABLED=false
CENTRIFUGO_BROKER_NATS_ALLOW_WILDCARDS=false
CENTRIFUGO_BROKER_NATS_DIAL_TIMEOUT=1s
CENTRIFUGO_BROKER_NATS_PREFIX="centrifugo"
...
855

命名规则一目了然：嵌套路径转大写下划线（admin.enabled → CENTRIFUGO_ADMIN_ENABLED）。环境变量适合容器/云平台注入场景，deb 包的 systemd 单元也预留了 EnvironmentFile=/etc/default/centrifugo。

3.3 内置参数文档（configdoc）

configdoc 直接从二进制内嵌的参数定义生成文档，与运行的版本严格一致。带 -m 输出 Markdown（共 10085 行），-s 按顶层段过滤，-p 指定端口起本地网页版：

centrifugo configdoc -m -s admin | head -14

实测回显：

# `admin`

Type: `Admin` object

Configures the admin web UI and its API endpoints.

## `admin.enabled`

Type: `bool`

Env: `CENTRIFUGO_ADMIN_ENABLED`

Enables the admin web UI and admin API endpoints.

每个参数条目固定给出 Type（类型）、Env（环境变量）、默认值与语义说明，这是查参数含义最权威的离线途径。

3.4 四层覆盖优先级与生效方式

Centrifugo 按以下优先级合并配置（高者优先）：命令行 flags > 环境变量 > 配置文件 > 内置默认值。实测验证两处覆盖：环境变量 CENTRIFUGO_HTTP_SERVER_PORT=8131 启动（配置文件写的是 8130）：

CENTRIFUGO_HTTP_SERVER_PORT=8131 centrifugo -c /etc/centrifugo/config.json

实测回显（启动日志行）：

serving websocket, http_stream, sse, emulation, api, admin, prometheus, health, swagger endpoints on 0.0.0.0:8131

命令行 -p 8132（等价 --http_server.port）覆盖启动：

centrifugo -c /etc/centrifugo/config.json -p 8132

实测回显（启动日志行）：

serving websocket, http_stream, sse, emulation, api, admin, prometheus, health, swagger endpoints on 0.0.0.0:8132

生效方式三选一：

sudo systemctl restart centrifugo   # 重启进程，全部配置生效
sudo systemctl reload centrifugo    # SIGHUP 热重载，不断开现有连接
sudo kill -HUP <主进程PID>           # 等价 reload 的手工形态

热重载成功时日志出现确认行（实测）：

Oct 21 15:25:52 centrifugo-server centrifugo[4746]: {"level":"info","time":"2026-10-21T15:25:52Z","message":"configuration successfully reloaded"}

💡 说明：并非所有参数都支持热重载——监听端口、引擎类型这类启动期参数仍需重启；密钥、频道命名空间、日志级别等运行期参数可热加载。改完不确定时用 reload 看日志确认，行为未变再 restart。

3.5 配置校验（checkconfig 与严格模式）

基础校验对合法配置静默通过；坏 JSON 报解析错误：

echo '{bad json' > /tmp/bad.json
centrifugo checkconfig -c /tmp/bad.json; echo "rc=$?"

实测回显：

error getting config: error reading config file /tmp/bad.json: While parsing config: invalid character 'b' looking for beginning of object key string
rc=1

普通模式忽略未知字段；-s/--strict 严格模式把未知字段当错误，用于跨版本升级兜底：

printf '{"client":{"token":{"hmac_secret_key":"x"}},"typo_key":1}' > /tmp/unk.json
centrifugo checkconfig -c /tmp/unk.json; echo "rc_loose=$?"
centrifugo checkconfig -s -c /tmp/unk.json; echo "rc_strict=$?"

实测回显：

rc_loose=0
unknown keys in config: typo_key
rc_strict=1

四、参数总览（顶层参数段）

执行 centrifugo defaultconfig -d 可见的顶层段共 37 个，按用途归类如下：

解读：日常单机部署只涉及 http_server、log、client、channel、http_api、admin 与若干 enabled 开关段；engine/broker/consumers 等大段只在水平扩展或接消息队列时启用。下文第五章按使用频率详解核心段。

五、核心参数分类详解

5.1 http_server：监听与 TLS

💡 技术拓展：TLS 证书的获取方式不止 autocert 一种。常见方案对比——

方案	原理	适用场景
tls_autocert（内置 ACME）	服务自己向 Let's Encrypt 签发续期	服务器直接暴露 80/443
tls 静态证书	自备 cert_pem/key_pem	已有商业/自签证书
反向代理终结 TLS	Nginx/Caddy 挂证书，回源 http	多服务共用网关，Centrifugo 走内网明文

本文方案采用「反向代理终结 TLS」路线（Web 服务普遍已有网关），Centrifugo 监听内网明文端口即可；若 Centrifugo 独占公网入口则 tls_autocert 最省心。

5.2 log：日志

5.3 client：连接鉴权与连接治理（重点）

鉴权令牌（JWT）

💡 技术拓展：JWT 签名算法不止 HMAC 一种。常见对比——

算法族	原理	取舍
HS256/384/512（HMAC）	共享对称密钥	最简单；签发方与验证方需共享密钥
RS256/ES256 系（RSA/ECDSA）	私钥签发、公钥验证	签发方可分散；公钥可公开发放
JWKS	动态拉取验证公钥集合	对接 IdP（如 Keycloak）时免手工同步公钥

本文采用默认 HS256（gentoken 命令默认即 HMAC SHA-256 JWT），单团队后端持有密钥签发最直接。

连接策略

连接生命周期

客户端能力开关（默认全部收紧）

channel_limit（单连接订阅数，128）、history_max_publication_limit/recovery_max_publication_limit（单次拉历史/恢复上限，300）、presence_update_interval（27s）、concurrency（0=串行处理命令）。这些默认值对多数场景够用，不展开。

5.4 channel：频道模型与命名空间（重点）

全局命名规则

频道选项（without_namespace 为无命名空间默认值；namespaces 数组内每个命名空间可独立覆盖同名选项）

命名空间示例（本文实验环境实际使用，已验证）：chat 命名空间允许客户端订阅并保留 10 条 1 小时历史：

"channel": {
  "namespaces": [
    {
      "name": "chat",
      "allow_subscribe_for_client": true,
      "history_size": 10,
      "history_ttl": "1h"
    }
  ]
}

⚠️ 注意：开启 history_size 后，HTTP API 的 history 方法才能取到消息。实测向 chat:main 发布两条后查询：{"result":{"publications":[{"data":{"msg":1},"offset":1},{"data":{"msg":2},"offset":2}],"epoch":"aGWjhIal","offset":2}}——offset 单调递增、epoch 标识流纪元，这两个字段正是断线恢复（recovery）的对照依据。

5.5 http_api 与 grpc_api：后端调用入口

API 方法族（POST {"method":"...","params":{...}}）：publish、broadcast、subscribe、unsubscribe、disconnect、presence、presence_stats、history、history_remove、channels、info、refresh 等。info 返回节点列表与运行指标（实测节选）：

{"result":{"nodes":[{"uid":"eda3d08d-dc8f-414d-8f9b-2ac5539ae33c","name":"centrifugo-server_8130","version":"6.10.1 OSS","num_clients":0,"num_users":0,"num_channels":0,"uptime":60,"metrics":{...}}]}}

5.6 admin：管理界面

登录认证实测（表单编码，JSON Content-Type 会 400）：

curl -s -X POST -d "password=q1w2e3r4" http://127.0.0.1:8130/admin/auth -w " http:%{http_code}"

实测回显：

{"token":"MTc5MjU5NjE2M3xEUXdBQ21GMWRHaHZjbWw2WldRPXwM9uF9x5Qow2Zc18L9ltHegUzAwwjgmi5MYbyjdk9flg=="} http:200

5.7 传输端点：websocket / sse / http_stream / webtransport

💡 技术拓展：客户端接入传输不止 WebSocket 一种。主要选项对比——

传输	双向	原理/特点	适用场景
WebSocket	是	全双工单连接，主流选择	绝大多数实时应用
SSE（双向版）	是	HTTP 长连接下行+POST 上行，自动重连内建	代理环境对 WS 不友好时
HTTP-stream	是	fetch 流式读取，纯 HTTP 栈	受限网络/老代理
WebTransport	是	HTTP/3 之上，多路复用低延迟	新一代浏览器高要求场景
uni_* 单向	否	只下行，无命令上行	大屏/通知墙等只读页面

本文开启 websocket（默认）+ sse + http_stream 三种做验证；生产按客户端环境选择，SDK（centrifuge-js 等）会在 WebSocket 失败时自动降级到 SSE/HTTP-stream。

5.8 engine 与 broker：单机到集群

单机内存引擎零依赖即开即用；节点数 >1 时必须 redis（或 nats）承载跨节点消息分发，多节点部署与故障演练属集群主题，本文不展开。

5.9 可观测性端点

5.10 运维杂项

六、生产配置模板

6.1 小规模单机模板（2 核 4 GB、NVMe SSD、日活 ≤1 万的站内实时通道）

{
  "http_server": {
    "address": "0.0.0.0",
    "port": 8000
  },
  "log": {
    "level": "info"
  },
  "client": {
    "token": {
      "hmac_secret_key": "<与后端共享的随机 64 位密钥，用 openssl rand -base64 48 生成>"
    },
    "allowed_origins": ["https://app.example.com"]
  },
  "http_api": {
    "key": "<openssl rand -base64 48 生成>"
  },
  "admin": {
    "enabled": true,
    "external": false,
    "password": "q1w2e3r4",
    "secret": "<openssl rand -base64 48 生成>"
  },
  "health": { "enabled": true },
  "prometheus": { "enabled": true },
  "channel": {
    "namespaces": [
      { "name": "chat", "allow_subscribe_for_client": true, "history_size": 100, "history_ttl": "24h" },
      { "name": "notify", "allow_subscribe_for_client": true }
    ]
  }
}

要点：内存引擎、密钥全部落配置文件（权限 root:centrifugo 640）；Origin 收敛到精确域名；admin 不暴露外网端口（配合 SSH 隧道或内网访问）；<...> 占位按注释方法生成后替换为实际值。

6.2 Redis 水平扩展变体（2+ 节点）

在 6.1 基础上替换引擎段：

"engine": {
  "type": "redis",
  "redis": {
    "address": ["redis://10.0.0.11:6379", "redis://10.0.0.12:6379"],
    "password": "<Redis 密码>"
  }
}

要点：多节点共享同一配置与密钥（JWT 任意节点可验）；history/presence 数据落到 Redis，节点无状态可水平扩容；node.name 留空自动生成即可，API info 方法可逐节点观测。

七、常见问题

Q1：改了配置不生效？ 确认走的是 restart/reload；热重载只覆盖运行期参数（端口、引擎等启动期参数必须 restart）。reload 后看日志是否有 configuration successfully reloaded。

Q2：checkconfig 通过但 -s 严格模式报 unknown keys in config？ 配置里存在当前版本不认识的字段——可能是从旧版本/教程抄来的 v5 平铺键，或拼写笔误。严格模式正是升级版本后迁移配置的核对工具（实测：unknown keys in config: typo_key）。

Q3：环境变量和配置文件同时设置时哪个生效？ 优先级 flags > 环境变量 > 配置文件（3.4 节实测：配置 8130，env 8131 生效为 8131，flag 8132 再覆盖）。排查「明明改了配置却行为异常」时先查进程环境里有没有 CENTRIFUGO_* 变量。

Q4：客户端订阅被拒 error 103？ 见安装篇 FAQ Q5：默认策略拒绝客户端订阅，命名空间需 allow_subscribe_for_client: true，且频道名必须带命名空间前缀（chat:main 而非 chat）。

Q5：allowed_origins 设 ["*"] 有警告？ 服务端日志输出 usage of allowed_origins * is discouraged for security reasons, consider setting exact list of origins。生产环境请写精确 Origin 列表。

Q6：配置文件权限要求？ 程序以 0600 写出（保护密钥），但服务以 centrifugo 用户运行，需手工调整为 root:centrifugo 640——否则报误导性的 config file not found（安装篇 4.5 节实测）。

八、参考链接

• 官方配置文档总览：https://centrifugal.dev/docs/server/configuration
• 服务器配置指南：https://centrifugal.dev/docs/server/server-configuration
• 频道与命名空间：https://centrifugal.dev/docs/server/channels
• 认证与鉴权：https://centrifugal.dev/docs/server/authentication
• 站内相关：《Ubuntu 22.04 安装 Centrifugo 指南》、《Centrifugo 6.10 常用 CLI 命令详解》、《Centrifugo 6.10 介绍与选型指南》