跳转到内容

服务器配置参考

根据服务器的配置代码(src/config.rs)整理。[server] 中的配置项也可以写在文件顶层,子表两种写法都可以([server.acme] 或 [acme])。

配置项类型默认值含义与规则
bind_addr套接字地址"0.0.0.0:8443"监听地址。使用 ACME 直连部署时用 "0.0.0.0:443"(或 "[::]:443")。可被 --bind 覆盖。
websocket_path字符串"/"唯一能让 WebSocket 升级到达中继的请求路径,其他请求都得到伪装网站。必须以 / 开头,为 ASCII,不含 ?、#、空格或控制字符。默认值无法抵御探测,请设置较长的随机路径。含有 CHANGE-ME(模板占位符)的路径会被拒绝。
relay_identity_path路径配置文件旁的 relay_identity.key中继的长期身份密钥:32 字节,权限 0600 或更严格,属于服务用户。用 --init-relay-identity 创建。从配置文件运行的中继缺少它时拒绝启动。参见中继身份。
dev_origin字符串无仅限开发。 使用 --no-tls 时必需,使用 TLS 时忽略。客户端拨号使用的小写 scheme://host:port,例如 "ws://127.0.0.1:18443"。
max_connections整数10000同时连接数,从 accept() 起计数。至少为 1。
max_connections_per_ip整数64每个 IPv4 地址或 IPv6 /64 的同时连接数。0 表示关闭,位于 TCP 前端之后时必须为 0。不得超过 max_connections。
max_connections_per_ipv6_48整数256来自同一 IPv6 /48 的同时连接总数。0 表示关闭。不得超过 max_connections。不影响 IPv4。
proxy_protocol布尔false位于本机 TCP(第 4 层)前端之后:每个连接都必须以 PROXY 协议 v2 头开始,其源地址只用于按来源的公平份额。要求回环的 bind_addr,且两个按地址的上限都为 0。非回环对端以及没有有效 v2 头的连接会被拒绝。参见 TCP 前端部署。
rate_limit_bps整数1048576每个连接每秒入站字节数(令牌桶;超出时限速而非断开)。至少 1024。
max_message_bytes整数4194304客户端发送的最大 WebSocket 消息或帧。65536 到 67108864。
connection_timeout_secs整数300连接在这么长时间内没有发送任何数据就关闭。60 到 86400。中继会在连接安静约 262 秒后发送 ping(至少在此超时前 30 秒)。低于 300 时,中继在启动时记录警告:后台应用(约每 240 秒发送一次心跳)此时只能靠中继的 ping 保持连接,低于 90 秒则无法保持。
identification_timeout_secs整数15新连接必须在此时间内完成一次签名的密钥发布,否则关闭。1 到 300,且不超过 connection_timeout_secs。
max_pending_circuit_targets整数18000全中继范围内有待处理会话请求的不同目标数上限。已满时,较轻的来源驱逐最重来源最早的请求。1 到 1000000。
max_pending_per_connection整数32单个连接在 10 分钟内可以有待处理请求的不同目标数上限。重复发往同一目标不计数。1 到 max_pending_circuit_targets。
max_pending_per_source整数1024来自同一来源(一个 IPv4 地址或 IPv6 /48)的待处理请求上限。1 到 max_pending_circuit_targets。位于前端之后时关闭,除非 proxy_protocol = true。
max_circuits_per_connection整数256单个连接可以创建且仍然存在的电路上限,以及单个身份跨重连可以加入的电路上限。1 到 65536。
max_circuits整数200000整个服务器中电路路由条目的上限(每对两个)。已满时,较轻来源的新配对会拆除最重来源最新的配对。2 到 10000000。
max_circuits_per_source整数max_circuits / 64从同一来源发起请求的身份所持有的电路端上限。2 到 max_circuits。位于前端之后时关闭,除非 proxy_protocol = true。
offline_queue_max_total_bytes整数268435456排队消息的总字节数。至少为 max_bytes_per_recipient 以及 sender_budget_bytes × sender_source_budget_multiplier(参见 [server.offline_queue])。
offline_queue_max_bytes_per_recipient整数无已弃用。 [server.offline_queue] max_bytes_per_recipient 的旧名称。在一个版本内仍可解析,并在启动时记录警告;新配置项未设置时它会设定新配置项,两者都设置时以新配置项为准。
tls_handshake_timeout_secs整数10客户端完成 TLS 握手的时间。1 到 120。
circuit_ttl_secs整数无会被接受但忽略,启动时给出警告。电路在任一端断开或关闭时结束。
redis_url字符串无会被接受,但当前服务器不使用。

已移除的配置项。 message_queue_persist_path 和 trusted_proxy 会在启动时被拒绝,并提示替代方案([server.offline_queue] 和 proxy_protocol)。

发给未连接接收方的消息和消息请求。参见离线队列。

配置项类型默认值含义与规则
ttl_secs整数259200(72 小时)排队消息的存活时间。3600 到 259200(72 小时为上限;更大的值会导致启动失败)。消息请求最多保存 72 小时。
knock_budget_bytes整数16777216排队消息请求(每个 5120 字节,16 MiB 约可容纳 3,276 个)的字节数,与消息分开计算。单个来源最多占 1/16。
max_bytes_per_recipient整数4194304(4 MiB)为单个接收方账号排队的字节数。至少为 max_message_bytes,至多为 offline_queue_max_total_bytes。超过时消息被拒绝(offline_recipient_cap)。
max_messages_per_recipient整数256为单个接收方账号排队的消息数。1 到 4096。等长的稳定流量消息最多占其一半。超过时消息被拒绝(offline_recipient_cap)。
sender_budget_bytes整数16777216(16 MiB)单个连接在每个 sender_window_secs 内可为离线接收方排队的字节数。至少为 max_message_bytes,至多为 offline_queue_max_total_bytes。超过时消息被拒绝(offline_sender_budget)。
sender_budget_messages整数1024单个连接在每个 sender_window_secs 内可为离线接收方排队的消息数。1 到 65536。
sender_window_secs整数ttl_secs(259200)发送方预算的滚动窗口。至少为 ttl_secs,至多 259200;更短的值会导致启动失败。
sender_source_budget_multiplier整数4同一来源地址(IPv4 地址或 IPv6 /48)的所有连接合计共享发送方预算乘以该值。至少为 1;sender_budget_bytes × 该值必须不超过 offline_queue_max_total_bytes。超过时消息被拒绝(offline_source_budget)。来源未知时(max_connections_per_ip = 0 且未启用 proxy_protocol)不适用,启动时会警告。
persist布尔false以加密形式在重启后保留排队条目。为 false 时不写入磁盘。
persist_path路径无加密的队列文件。persist = true 时必需。
persist_key_path路径无32 字节的密钥文件。必须位于内存文件系统(tmpfs、ramfs 或 mfs)上,与 persist_path 位于不同的文件系统和目录,属于服务用户,权限 0600 或更严格。persist = true 时必需。
allow_persistent_key布尔false跳过内存文件系统检查(仅限开发或特殊情况;会记录警告)。
held_copy_max_bytes_per_connection整数4194304(4 MiB)单个连接可保留的暂存副本字节数:已转发给它、但其应用尚未确认的消息。至少为 max_message_bytes,至多为 held_copy_max_total_bytes。
held_copy_max_total_bytes整数67108864(64 MiB)所有连接的暂存副本总字节数。独立于离线队列的预算。至多 64 GiB。

内置 Let’s Encrypt,在 443 端口上使用 TLS-ALPN-01。未知配置项会被拒绝。与 [server.tls] 互斥。

配置项类型默认值含义与规则
enabled布尔false开启 ACME。
domains字符串列表[]开启时必需。小写的完整域名;不含通配符、IP 地址、协议、端口或路径;最多 253 个字符。
contacts字符串列表[]可选的电子邮件地址;缺少时自动添加 mailto:;其他协议会被拒绝。
cache_dir路径"/var/lib/rchat/acme"账户密钥与证书存储。必须为绝对路径且不是符号链接。以 0700 创建;文件以 0600 写入。
staging布尔false使用 Let’s Encrypt 测试环境(证书不受信任)。

静态证书。未知配置项会被拒绝;min_version 和 tls13_only 会被拒绝并给出说明。与 [server.acme] 互斥。

配置项类型默认值含义
cert_path路径必需PEM 证书链,叶证书在前。
key_path路径必需PEM 私钥(PKCS#8、PKCS#1 或 SEC1)。必须与证书匹配。

两个文件都会在收到 SIGHUP 时重新读取。

配置项类型默认值含义与规则
enabled布尔true向非中继请求提供伪装网站。为 false 时返回普通的 404。
root路径无静态网站的绝对路径。启动时必须存在且为目录。不设置时提供内置页面。
server_header字符串"nginx/1.24.0"Server 响应头。非空的可打印 ASCII。
write_timeout_secs整数30写出一个伪装响应的时间上限。大于 0。
配置项类型默认值含义
log_client_ips布尔false在 debug 日志行中加入客户端 IP 地址。从不影响 info、warn 或 error。
format字符串"json"会被接受,但不使用。日志是输出到标准输出的纯文本。
output字符串"stdout"会被接受,但不使用。
配置项类型默认值含义
enabled布尔true通过 HTTP 提供 Prometheus 指标。
bind_addr套接字地址"127.0.0.1:9090"指标监听地址。该端点没有认证。无法绑定时记录错误,中继继续运行。
allow_public布尔false允许非回环的 bind_addr。不设置时,非回环地址会让中继在启动时停止。设置后请用防火墙保护该端点。
  • 未知配置项在任何表中都会被拒绝,因此拼错或过时的配置项(例如 udp_bind 或 [decoy] randomization_strength)会让服务器在启动时停止。
  • 除非使用 --no-tls,否则 [server.acme](且 enabled = true)与 [server.tls] 必须且只能配置其一。
  • TLS 必须在中继处终止。 密钥认证绑定到中继自己的 TLS 会话。
  • 校验在启动时进行。任何失败都会以指出配置项名称的消息停止服务器。
[server]
bind_addr = "0.0.0.0:443"
websocket_path = "/Zk3q-replace-with-32-random-url-safe-chars"
relay_identity_path = "/var/lib/rchat/relay_identity.key"
max_connections = 10000
max_connections_per_ip = 64
rate_limit_bps = 1048576
max_message_bytes = 4194304
connection_timeout_secs = 300
tls_handshake_timeout_secs = 10
[server.offline_queue]
ttl_secs = 259200
persist = false
[server.acme]
enabled = true
domains = ["chat.example.com"]
contacts = ["mailto:[email protected]"]
cache_dir = "/var/lib/rchat/acme"
staging = false
[server.decoy]
enabled = true
server_header = "nginx/1.24.0"
[logging]
log_client_ips = false
[metrics]
bind_addr = "127.0.0.1:9090"