Centrifugo（四）配置文件说明

calendar Dec 12, 2019 · 4 min read · 技术 Centrifugo  ·
Share on: linkedin copy

    Centrifugo 支持 JSON、TOML和YAML三种格式的配置文件。

    通过 ./centrifugo -h 命令，可以查看所有的可用选型，如下：

    Centrifugo – real-time messaging server

    Usage:
    [flags] 
    [command]

    Available Commands:
    checkconfig Check configuration file
    genconfig   Generate simple configuration file to start with
    help        Help about any command
    version     Centrifugo version information

    Flags:
    -a, --address string             interface address to listen on 服务的地址
        --admin                      enable admin web interface 是否开启admin的管理界面
        --admin_insecure             use insecure admin mode – no auth required for admin socket admin安全验证, 节点: /, 可直接访问admin管理界面, 默认为false, 登录admin需要admin_password, 反之可直接登录
        --api_insecure               use insecure API mode  后台推送安全验证, 节点: /api. 默认为 false, 此时访问节点需要api_key. 当设置为 true 后, 任何人都将可以访问此节点
        --client_insecure            start in insecure client mode 客户端是否需要安全验证, 默认为false, 客户端必须拥有 JWT token 才能访问
    -c, --config string              path to config file (default "config.json")
        --debug                      enable debug endpoints 是否开启dubug节点, 开启后可访问 /debug/pprof/ 查看一些Centrifugo的网络状态
    -e, --engine string              engine to use: memory or redis (default "memory") 消息存储引擎, 默认为内存, 部署多个实例会造成数据不同步, 因此推荐使用 redis
        --grpc_api                   enable GRPC API server 是否开启grpc api, 默认使用 http_api
    -h, --help                       help for this command
        --internal_port string       custom port for internal endpoints 开启自定义默认端口, 默认为8000, 开启额外的端口为admin访问
        --log_file string            optional log file - if not specified logs go to STDOUT  log输出文件
        --log_level string           set the log level: debug, info, error, fatal or none (default "info") log级别
    -n, --name string                unique node name 命名空间名称, 此空间下的属性会覆盖common部分, 但不会继承
        --pid_file string            optional path to create PID file
    -p, --port string                port to bind HTTP server to (default "8000")  服务端口号
        --prometheus                 enable Prometheus metrics endpoint
        --redis_db int               Redis database (Redis engine)
        --redis_host string          Redis host (Redis engine) (default "127.0.0.1")
        --redis_master_name string   name of Redis master Sentinel monitors (Redis engine)
        --redis_password string      Redis auth password (Redis engine)
        --redis_port string          Redis port (Redis engine) (default "6379")
        --redis_sentinels string     comma-separated list of Sentinel addresses (Redis engine)
        --redis_tls                  enable Redis TLS connection
        --redis_tls_skip_verify      disable Redis TLS host verification
        --redis_url string           Redis connection URL in format redis://:password@hostname:port/db (Redis engine)
        --tls                        enable TLS, requires an X509 certificate and a key file
        --tls_cert string            path to an X509 certificate file
        --tls_key string             path to an X509 certificate key

注意：所有的命令行选项都可以用同样的名字在配置文件中进行设置。此外，所有的可用选项也都可以设置到环境变量中，格式为 CENTRIFUGO_<OPTION_NAME>。

version

centrifugo version

JSON file

Centrifugo 启动时依赖配置文件。最简单的配置文件如下：

{
    "token_hmac_secret_key": "<YOUR-SECRET-STRING-HERE>",
    "api_key": "<YOUR-API-KEY-HERE>"
}

必须的两个选项为 token_hmac_secret_key 和 api_key。token_hmac_secret_key 用来检查 JWT 签名。api_key 用于 Centrifugo API 端点授权。在生产环境你应该将这两个参数设置的足够复杂并且避免外泄。唯二的需要知道这两个参数值的只有 Centrifugo 自身和你的应用程序后端。该值被用来生成客户端连接令牌、调用 API 以及订阅私有频道。

TOML file

Centrifugo 同样支持 TOML 格式的配置文件：

centrifugo --config=config.toml

config.toml 示例：

token_hmac_secret_key = "<YOUR-SECRET-STRING-HERE>"
api_key = "<YOUR-API-KEY-HERE>"
log_level = "debug"

YAML file

Centrifugo 同样支持 TOML 格式的配置文件，config.yaml：

token_hmac_secret_key: "<YOUR-SECRET-STRING-HERE>"
api_key: "<YOUR-API-KEY-HERE>"
log_level: debug

checkconfig command

Centrifugo 有专门的命令用来检查配置文件：

centrifugo checkconfig --config=config.json

genconfig command

centrifugo genconfig -c config.json

该命令会生成最小化的配置文件。

Important options

运行 Centrifugo 时可以配置一些最重要的选项：

  • address - 将 Centrifugo 绑定到特定的接口地址（默认为 ""）
  • port - Centrifugo 的绑定端口（默认为 8000）
  • engine - Centrifugo 使用的引擎：memory 或者 redis（默认为 memory） 注意：命令行参数优先级要大于配置文件选项。

Channel options

频道（channel）是一个实体，客户端可以订阅发布到相应频道的消息。下面几个选项可以控制频道的一些行为：

  • **publish：**允许客户端直接发布消息到频道，而不经过应用程序后端。一般情况下，消息都是由应用程序后端通过 Centrifugo API 发布到 Centrifugo 服务器的。这个参数适用于没有后端或者 demo 的快速构建。~~需要注意的一点是客户端只有成功订阅了频道之后才能发布消息到该频道。~~本参数默认值为 false。

  • **subscribe_to_publish：**当 publish 选项启用后，客户端可以发布消息到频道中而无需订阅。使用此选项，客户端会在发布到频道之前自动检查是否已订阅该频道。

  • **anonymous：**该参数允许匿名访问（在连接参数中使用空字符串作为 user ID，JWT token 中 sub 为空）。通常情况下，应用程序的用户都需要登录认证，因此客户端建立连接时可以使用用户名作为唯一标识。如果你需要提供公共的实时消息服务，你可以在相应的频道上开启本参数。本参数默认值为 false。

  • **presence：**是否开启 presence 信息，presence 为当前订阅本频道的客户端信息。本参数默认是为 false，即不开启。

  • presence_disable_for_client：（v2.2.3 之后版本有效）presence 在客户端不可用。默认值为 false，即同时允许客户端和服务端 API 访问 presence 信息。

  • **join_leave：**当有用户订阅/取消订阅频道时，是否发送相关信息到频道中。本参数默认值为 false。

  • history_size：频道历史消息数量。因为 Centrifugo 将所有的消息存储在内存中，因此限制每个频道保留的历史消息数量是非常重要的。本参数默认值为 0，这意味着频道不会保留历史消息。启用本参数后，Centrifugo 会为命名空间中的每条频道保留指定数量的历史消息，直到消息过期，关于消息过期详见参数 history_lifetime。

  • **history_lifetime：**频道历史消息的过期时间，单位为秒。本参数默认值为 0，这意味着频道不会保留历史消息。如果要保留历史消息，需要同时配置 history_size 与 history_lifetime，并设置合理的参数值。

  • **history_recover：**是否恢复丢失的消息。如果开启本参数，当客户端重新连接时（如因网络原因断线重连），Centrifugo 将试图重新恢复丢失的消息。本参数默认值为 false。这个参数的启用要配合历史消息相关参数（history_size 和 histroy_lifetime），毕竟消息的恢复依靠的是频道历史消息记录。请注意，并非所有实时事件消息都需要开启此功能，因此在需要时请慎重考虑。启用此选项后，你的应用程序需要考虑消息去重。

  • history_disable_for_client：（v2.2.3 之后版本有效）历史消息在客户端不可用。默认为 false，即历史消息在客户端与服务端均可用。该参数是否启用不会影响历史消息恢复机制。

参数配置示例：

{
    "token_hmac_secret_key": "my-secret-key",
    "api_key": "secret-api-key",
    "anonymous": true,
    "publish": true,
    "subscribe_to_publish": true,
    "presence": true,
    "join_leave": true,
    "history_size": 10,
    "history_lifetime": 300,
    "history_recover": true
}
  • **namespaces：**namespaces 是可选参数，如果设置的话，需要设置成 namespace 数组的形式。通过 namespaces 可以针对 namespace 下的频道配置自定义参数。每个 namespace 都有自己的 name，并且拥有上面所有的针对频道的参数。name 必须唯一，并且由字母、数字、下划线或连接符组成，长度必须大于2（^[-azA-Z0-9_]{2,}$）。

namespaces 相关配置文件示例：

{
"token_hmac_secret_key": "very-long-secret-key",
"api_key": "secret-api-key",
"anonymous": true,
"publish": true,
"presence": true,
"join_leave": true,
"history_size": 10,
"history_lifetime": 30,
"namespaces": [
    {
      "name": "public",
      "publish": true,
      "anonymous": true,
      "history_size": 10,
      "history_lifetime": 300,
      "history_recover": true
    },
    {
      "name": "gossips",
      "presence": true,
      "join_leave": true
    }
]

}

在以上配置下：
  - 频道 news 将使用全局参数配置。
  - 频道 public:news 将使用 public 命名空间的参数配置。
  - 频道 gossips:news 将使用 gossips 命名空间的参数配置。

注意：频道（channel）相关的选项在命名空间（namespaces）中不存在继承关系。例如，你在配置文件的顶层配置了 presence: true，在命名空间中，频道的 presence 选项不会继承 true，你必须在命名空间中显式的启用。

Advanced configuration

Centrifugo 还提供了更多的配置选项，一般情况下，你不需要配置他们，使用默认值即可。

  • client_channel_limit
    Default: 128
    设置单个客户端可以拥有的不同频道订阅的最大数量。

  • channel_max_length
    Default: 255 设置频道名称的最大长度。

  • client_user_connection_limit
    Default: 0
    同一用户（不包含匿名用户）连接到 Centrifugo 节点的最大连接数。默认值 0 表示不限制。

  • client_request_max_size
    Default: 65536
    客户端请求的最大允许长度，按字节计。

  • client_queue_max_size
    Default: 10485760
    客户端消息队列的最大大小，以字节计。默认大小为 10mb。（超出长度后缓慢的读取连接会被关闭？）

  • client_anonymous
    Default: false
    是否允许客户端匿名连接。如果设置为 true，则所有客户端可以在没有 JWT 令牌的情况下连接到 Centrifugo。在这种情况下，没有令牌的连接会被视为匿名（user ID 为空），并且只能订阅开启了 anonymous 选项的频道。

  • sockjs_heartbeat_delay
    Default: 25
    SockJS 心跳检测时间间隔，单位为秒。

  • websocket_compression
    Default: fasle 是否开启 websocket 压缩。

  • gomaxprocs
    Default: 0
    默认情况下，Centrifugo 会在所有可用 CPU 内核上执行，本选项可以用来限制 Centrifugo 同时可利用的 CPU 内核数。

Advanced endpoint configuration

启动 Centrifugo 后，你会有几个可用的端点（endpoint），如果你没有提供额外的选项，你默认会有 3 个端点。

  • Default endpoints

主端点是原生的 Websocket 端口，用来支持纯 Websocket 协议的客户端连接：ws://localhost:8000/connection/websocket

SockJS 端点，用来服务使用 SockJS library 连接的客户端：http://localhost:8000/connection/sockjs

最后，API 端点，用来发布消息到频道以及执行其他可用的 API 指令：http://localhost:8000/api

所有的端点默认使用 8000 端口，可以通过 port 选项修改：

{
    "port": 9000
}

在生产环境中，你的域名将替代上面 URL 中的 localhost。如果你的 Centrifugo 服务器位于代理或者负载均衡服务器之后，则 URL 中可能没有端口号。

  • Admin endpoints 启用管理端点：
{
    ...
    "admin": true,
    "admin_password": "<password>",
    "admin_secret": "<secret>"
}

以上配置，使管理端点可用：http://localhost:8000
通过上面的地址，你可以看到管理界面，通过上面配置的 admin_password 登录。

  • Debug endpoints 当 Centrifugo 以 debug 模式启动时，debug 端点将可用。
{
    ...
    "debug": true
}

端点 URL: http://localhost:8000/debug/pprof/
通过上面的地址，你可以看到 Centrifugo 实例的内部状态信息，这些信息在故障排除时会非常有用。

  • Healthcheck endpoint 使用 health 选项（默认值为 false）来启用健康检查端点，该端点路径为 /health。同样，也可以在启动命令通过标记来启用健康检查端点：
./centrifugo -c config.json --health
  • Custom internal ports 我们强烈建议，不要将 API、admin、debug 以及 prometheus 端点暴露到互联网，这些端点被视为内部的：
    • API 端点（/api）: 针对 HTTP API 请求
    • Admin web interface endpoints（/, /admin/auth, /admin/api）: used by web interface
    • Prometheus endpoint(/metrics): 用于以 Prometheus 格式公开服务器指标
    • Healthcheck endpoint(/health): 用来进行健康检查
    • Debug endpoints(/debug/pprof): 用于检测服务器内部状态

这些内部端点，最好使用防火墙保护起来。
可以通过 internal_port 选项来自定义内部端点的端口：

{
    ...
    "internal_port": 9000
}

  • Disable default endpoints 以下选项在 v2.4.0 版本后有效：websocket_disable、sockjs_disable、api_disable，这些选项默认值均为 true。

  • Customize handler endpoinds
    从 Centrifugo v2.2.5 开始，可以自定义 HTTP 处理程序端点，有如下几个选项可用：

    • admin_handler_prefix（默认值为 ""）: 控制台 URL 前缀。
    • websocket_handler_prefix（默认值为 /connection/websocket）: WebSocket URL前缀。
    • sockjs_handler_prefix（默认值为 /connection/sockjs）: SockJS URL 前缀。
    • api_handler_prefix（默认值为 /api）: HTTP API URL 前缀。
    • prometheus_handler_prefix（默认值为 /metrics）: Prometheus URL 前缀。
    • health_handler_prefix（默认值为 /health）: 健康检查 URL 前缀。

other options

下面几个参数在新版本中是否仍可使用，未验证

    connection_lifetime 参数用来设置客户端连接的过期时间，单位为秒。如果该参数设置为0，表示该客户端连接永不过期。

{
    "secret": "very-long-secret-key",
    "connect_lifetime": 0
}

频道（Channel）相关的选项：

watch：Centrifugo 会同时发生消息到 admin channel，这些消息可以在 admin 管理界面的 messages tab 下查看。这个参数要慎用，特别是针对消息发布频率比较高的频道，以免超出 admin client 的处理能力。本参数默认值为 fasle。

history_drop_inactive：是否丢弃不活跃的历史消息。本参数可以大幅降低资源消耗（内存、消息传播次数）。简单来说，该参数开启后，Centrifugo 会主动丢弃不需要的历史消息。本参数默认值为 false。