---
title: "Centrifugo"
date: 2023-10-17T16:29:48+07:00
draft: true
---

## What

[Centrifugo](https://github.com/centrifugal/centrifugo) 是一个实时消息服务器。Golang 开发基于 Websocket。

### 命令行

```shell
centrifugo -h

centrifugo genconfig

centrifugo --config=config.toml


```

### 配置

配置优先级
- 命令行参数
- 环境变量
- 配置文件

#### 环境变量

使用 CENTRIFUGO——<OPTION_NAME> 

#### 配置文件

同时支持 JSON, YAML, TOML 格式

- allowed_origins				\[\]			安全 CORS CSRF 相关			\["https://*.example.com"\]
- address						""			监听地址/IP 						"127.0.0.1"
- port 							"8000" 		绑定端口							8000
- engine 						""			memory/redis/taranpool			"redis"
- token_hmac_secret_key
- token_rsa_public_key
- token_ecdsa_public_key
- api_key
- log_level
- client_channel_limit  		128			单客户端最大 channel 订阅数
- channel_max_length			255			channel 名称限制
- client_user_connection_limit	0 			单个IP到服务的连接数限制(0不限制)
- client_connection_limit		0 			HTTP 模式下服务处理的最大连接数
- client_connection_rate_limit 	0 			HTTP 模式服务每秒接受连接数
- client_queue_max_size 		1048576 	客户端接收队列长度(bytes)
- client_concurrency 			bool(0) 	单个客户端的请求是否并行
- client_stale_close_delay		10s 		从连接到验证包的最大时长
- allow_anonymous_connect_without_token bool(false) 	客户端不需要 JWT, 当作匿名用户对待
- disallow_anonymous_connection_tokens bool(false) 		匿名用户即使提供有效 JWT 也不行
- gomaxprocs					0 			服务运行使用的 core 数量
- debug 						true
- health 						false
- swagger 						false
- internal_port 				9000
- websocket_disable
- api_disable
- client_insecure 
- client_insecure_skip_token_signature_verify 
- api_insecure 
- admin_insecure 
- history_ttl 
- usage_stats_disable
- shutdown_timeout 				30(s)
- token_audience 				"centrifugo"
- token_issuer 					"myapp"
- token_issuer_regex			""
- token_audience_regex 			""
- token_jwks_public_endpoint 
- namespaces: [{"name": "facts", "history_size": 10, "history_ttl": "300s"}]

### JWT Claims

- sub: string user ID.
- exp: UNIX timestamp when the token will expire
- iat: UNIX timstamp when token was issued.
- jti: token unique ID
- aud: audience
- iss: issuer
- info: optional. additional information about client.
- b64info: base64 representation of bytes(because of using binary protocol)
- channels: array of strings with server-side channels to subscribe a client to.
- subs: an optional map of channels with options.


### Endpoints

- Websocket
> ws://localhost:8000/connection/websocket
- Bidirectional emulation with HTTP-streaming (disabled by default)
> ws://localhost:8000/connection/http_stream
- Bidirectional emulation with SSE
> ws://localhost:8000/connection/sse
- Bidirectional SockJS 
> http://localhost:8000/connection/sockjs
- Unidirectional EventSource endpoint 
> http://localhost:8000/connection/uni_sse
- Unidirectional HTTP streaming endpoint 
> http://localhost:8000/connection/uni_http_stream
- Unidirectional WebSocket endpoint
> http://localhost:8000/connection/uni_websocket
- Unidirectional SSE 
> http://localhost:8000/connection/uni_sse
- Server HTTP API endpoint
> http://localhost:8000/api
- Admin web UI 
> http://localhost:8000
- Debug
> http://localhost:8000/debug/pprof/
- Health
> http://localhost:8000/health
- Swagger
> http://localhost:8000/swagger
- Prometheus
> http://localhost:8000/metrics

### ServerSide API

[官方文档](https://centrifugal.dev/docs/server/server_api)

- /publish: publishing data into a channel.
- /broadcast: publishing data into many channels.
- /subscribe: allows subscribing active user's sessions to a channel. (server-side mostly)
- /unsubscribe: allows unsubscribing user from a channel.
- /disconnect: allows disconnectiong a user by ID
- /refresh: allows refreshing user connection
- /presence: allows getting channel online presence information(all client currently subscribed on this channel)
- /presence_stats: allows getting short channel presence information
- /history: allows getting channel history information.
- /history_remove: allows removing publications in channel history.
- /channels: active channels.
- /info: getting information about running Centrifugo nodes.
- /batch: allows sending many commands in one requests.


### Channels, Namespaces

**Channel**: 时 publications 的路由器。

Channel 是包含预定义规则的字符串。

- : - namespace 边界符
> public:news
- '#' - user channel 边界符
> new#42
> personal:user#42
> personal:user#42,43
- $ - 私有 channel 前缀
> $personal_news
> $dialogs:gossip
- "* & /" - 保留，未来使用

Channel 不需要创建/删除。第一个发布到来时自动创建，最后一个订阅退出后自动清理

Channel 可以属于一个 Namespace。Namespace 需要在配置文件中预定义。

#### [Channel options](https://centrifugal.dev/docs/server/channels#channel-options)

- presence					boolean(false)
- join_leave				boolean(false)		sending join/leave message when the client subscribe to a channel(unsubscribe from a channel)
- force_push_join_leave		boolean(false)		同 namespace 的客户端都会受到 join/leave 通知
- history_size				int(0)				amount of messages for channels (配合 history_ttl)
- history_ttl 				duration(0s)		how long to keep channel history messages
- history_meta_ttl			duration(30d)		history stream metadata expiration
- force_positioning			boolean(false)		forces all subscriptions in a namespace to be positioned
- force_recovery			bool(false)			forces all subscriptions in a namespace to be recoverable
- allow_subscribe_for_client    bool(false)     non-anonymous clients will be able to subscribe to any channel in a namespace
- allow_subscribe_for_anonymous bool(false)     anonymous clients (with empty user ID) should be able to subscribe on channels in a namespace.
- allow_publish_for_subscriber  bool(false)     client can publish into a channel in namespace directly from the client side over real-time connection but only if client subscribed to that channe
- allow_publish_for_client      bool(false)     allows clients to publish messages into channels directly (from a client-side)
- allow_publish_for_anonymous   bool(false)     anonymous clients should be able to publish into channels in a namespace
- allow_history_for_subscriber  bool(false)     allows clients who subscribed on a channel to call history API from that channel
- allow_history_for_anonymous   bool(false)     anonymous clients should be able to call history from channels in a namespace
- allow_presence_for_subscriber bool(false)     
- allow_presence_for_client     bool(false)
- allow_presence_for_anonymous  bool(false)
- allow_user_limited_channels   bool(false)     allows using user-limited channels in a namespace for checking subscribe permission
- channel_regex             string("")          set a regular expression for channels allowed in the namespace
- proxy_subscribe           bool(false)         
- proxy_publish             bool(false)         
- proxy_sub_refresh         bool(false)
- proxy_subscribe_stream    bool(false)
- subscribe_proxy_name      string("")
- publish_proxy_name        string("")
- sub_refresh_proxy_name    string("")
- subscribe_stream_proxy_name   string("")


### Channel 权限模型

### Channel JWT 认证

### ServerSide 订阅

### 引擎和扩展性

### 历史和恢复

### 在线状态

### 代理事件到后端应用

### 代理订阅数据

### Admin UI

### 服务监控

### TLS

### 负载均衡