配置指南
中继读取一个 TOML 文件,默认是 /etc/rchat/server.toml(用 --config 更改)。本页介绍大多数运营者会用到的设置。配置参考列出了每个配置项的类型和默认值。
文件如何读取
Section titled “文件如何读取”- 文件缺失、不可读或无效都会导致启动错误。 中继从不悄悄回退到默认值。
- 服务器设置可以放在
[server]下,也可以放在顶层。子表同样两种写法都可以:[server.acme]与[acme]含义相同。 - 未知配置项在任何表中都是启动错误,因此拼写错误会让服务器以
unknown field ...停止。旧模板中的配置项,例如randomization_strength或udp_bind,升级前必须删除。 - 已移除的配置项会被拒绝并给出说明:
message_queue_persist_path(参见离线队列)和trusted_proxy(参见 TCP 前端部署)。 - 资源限制在启动时检查。值为
0或超出范围会让服务器停止,不存在”无限制”设置。
典型的配置文件
Section titled “典型的配置文件”[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"
[server.acme]enabled = truedomains = ["chat.example.com"]cache_dir = "/var/lib/rchat/acme"staging = false
[server.offline_queue]ttl_secs = 259200 # 72 小时persist = false # 仅内存
[server.decoy]enabled = true# root = "/var/www/decoy"rchat-core 仓库中的 rchat/config/server.toml 是带注释的模板,包含每项限制和两种证书方案。rchat/config/server-behind-proxy.toml 是位于 TCP 前端之后的中继所用的模板。
[server.acme](内置 Let’s Encrypt)与 [server.tls](静态证书)必须且只能配置其一。TLS 始终在中继处终止。参见 TLS 与证书。
relay_identity_path 设置中继长期身份密钥的位置(默认:配置文件旁的 relay_identity.key)。用 --init-relay-identity 创建一次。参见中继身份。
WebSocket 路径与伪装网站
Section titled “WebSocket 路径与伪装网站”只有升级到与 websocket_path 完全一致路径的 WebSocket 请求才能到达中继。匹配时忽略查询字符串。其他所有请求都会得到伪装网站,包括普通 HTTP 请求、升级到其他路径的请求以及乱码字节。请求路径从不记录。
设置一个较长的随机路径:
echo "/$(openssl rand -base64 24 | tr '+/' '-_')"然后在每个客户端的服务器 URL 中使用相同路径:wss://chat.example.com/<path>。路径必须以 / 开头,且为纯 ASCII,不含 ?、#、空格或控制字符。
伪装网站([server.decoy]):
| 配置项 | 默认值 | 含义 |
|---|---|---|
enabled | true | 向非中继请求提供伪装网站。设为 false 时,这些请求得到普通的 404。路径检查依然生效。 |
root | 无 | 要提供的静态网站的绝对路径。启动时必须存在。不跟随指向目录外的符号链接。不设置时,提供一个通用的内置小页面。 |
server_header | "nginx/1.24.0" | Server 响应头的值。 |
write_timeout_secs | 30 | 写出一个伪装响应的时间上限。 |
伪装网站每个连接只响应一个请求。它是一种缓解措施,不是伪装:它让随意的扫描看不出端口上运行的是什么,但坚决的探测者可以根据其行为(不支持 keep-alive 或范围请求、TLS 和时间细节)将它与真正的 nginx 区分开。
每个中继一个伪装网站
Section titled “每个中继一个伪装网站”rchat-server --config <path> --render-decoy <dir> [--host <hostname>] 会把一个小型静态网站写入 <dir>,然后退出。该网站是一个虚构产品的登录页(网页邮箱、NAS 管理页、相册、云盘或代码托管)。产品类型、品牌名称、强调色和标志都由主机名决定,因此同一主机总是得到同一个网站,两个中继不会提供完全相同的页面。重新部署中继会生成相同的网站。
sudo -u rchat rchat-server --config /etc/rchat/server.toml --render-decoy /var/lib/rchat/decoy --host chat.example.com然后让中继指向它:
[server.decoy]root = "/var/lib/rchat/decoy"- 主机名。 使用前,主机名会转为小写并去掉末尾的点,因此
Chat.Example.com.和chat.example.com得到同一个网站。未提供--host时,命令使用[server.decoy] host,否则使用配置文件中第一个[server.acme]域名,再否则使用由中继身份密钥派生的种子(此时--config必须指向身份密钥已存在的中继)。 - 目录。
<dir>必须为空或不存在,或是此命令以前生成过的目录。其他情况一律拒绝,并保持原样。不会沿符号链接跳出<dir>,每个文件都先写入临时文件再重命名。 - 自包含。 所有样式、脚本和标志都在网站自己的文件中,不会从外部获取任何内容。登录表单从不提交;它会显示”用户名或密码错误”。
- 缺失的页面。 未知路径返回网站自己的
404.html页面,状态码 404。 - 不含识别信息。 网站从不包含 WebSocket 路径、中继固定值、版本号或项目名称。
- 未设置
root时。 中继提供同类的内置网站,由[server.decoy] host决定,否则由第一个[server.acme]域名决定,再否则由身份密钥决定。两者都未设置时,种子由中继的秘密身份密钥派生,因此该页面仍为此中继独有,且无法从其公开的固定值推算出来。运行--rotate-relay-identity会改变这个内置页面,因为密钥变了。已经生成到磁盘上的网站保持不变,因为它只取决于生成时使用的主机名或种子。
伪装网站让中继在随意的探测面前看起来像一个普通网站。它不能保证抵御坚决的探测者。
发给未连接接收方的消息和消息请求由中继保存,直到送达或过期。它们只按接收方存放;发送方的身份在加密载荷内部。
[server.offline_queue]ttl_secs = 259200 # 72 小时;3600 到 259200(72 小时为上限)knock_budget_bytes = 16777216 # 消息请求的 16 MiB 预算,与消息分开max_bytes_per_recipient = 4194304 # 为单个接收方账号排队 4 MiBmax_messages_per_recipient = 256 # 1 到 4096sender_budget_bytes = 16777216 # 单个连接每个窗口内可为离线接收方排队 16 MiBsender_budget_messages = 1024 # 1 到 65536# sender_window_secs = 259200 # 默认为 ttl_secs;不能短于 ttl_secssender_source_budget_multiplier = 4 # 同一来源地址共享发送方预算的 4 倍persist = false # 仅内存(默认)# persist_path = "/var/lib/rchat/queue.rcq"# persist_key_path = "/run/rchat/queue.key"# allow_persistent_key = false- 默认不写入磁盘。 排队的条目保存在内存中,重启后丢失。
ttl_secs是排队消息的存活时间。无论设置如何,消息请求最多保存 72 小时。- 按接收方和按发送方的限制。
max_bytes_per_recipient和max_messages_per_recipient限制为单个接收方账号排队的内容。sender_budget_bytes和sender_budget_messages限制单个连接在每个sender_window_secs(默认等于ttl_secs,不能更短)内可为离线接收方排队的内容。同一来源地址(IPv4 地址或 IPv6 /48)共享乘以sender_source_budget_multiplier的同样预算。超出任何一项的消息会被拒绝,返回RateLimited且没有确认,已排队的消息不会被驱逐。范围和各类拒绝对应的指标参见限制。 - 已弃用的配置项。
[server]下的offline_queue_max_bytes_per_recipient是max_bytes_per_recipient的旧名称。它在一个版本内仍可解析并在启动时记录警告;两者都设置时以新配置项为准。 - 加密持久化需要主动开启。 设置
persist = true时,队列每 5 分钟以及关闭时以加密形式写入persist_path,并在启动时读回(随后删除)。除非persist_key_path处的密钥文件正好 32 字节、权限为0600或更严格、属于服务用户、与数据位于不同目录且不同文件系统,并且位于内存文件系统上(Linux 的tmpfs或ramfs;FreeBSD 的tmpfs或mfs),否则中继会拒绝启动。这样排队数据可以在服务重启后保留,但机器重启后不会保留。 - 附带的 systemd 单元会保留
/run/rchat(一个 tmpfs,服务重启时保留、机器重启时清除),并在每次开机后缺少/run/rchat/queue.key时创建它,因此模板中的路径可以直接使用。 allow_persistent_key = true只跳过内存文件系统检查,并记录一条警告。设置了它的中继不能再声称其队列密钥会在重启后丢失。
队列的大小上限见资源限制。
--no-tls 提供明文 WebSocket,仅用于本地开发。它要求设置 [server] dev_origin(客户端拨号使用的源),并拒绝非回环地址:
[server]bind_addr = "127.0.0.1:18443"dev_origin = "ws://127.0.0.1:18443"rchat-server --config ./dev.toml --init-relay-identityrchat-server --config ./dev.toml --no-tls没有 TLS 就没有通道绑定:客户端的证明只绑定到 dev_origin 的哈希,这只能防止重放到源不同的中继。切勿暴露 --no-tls 中继。
--log-level(或RCHAT_LOG_LEVEL)设置详细程度,默认是info。日志输出到标准输出;在 systemd 下进入 journal。[logging] log_client_ips = true只在debug行中加入客户端 IP 地址,默认是false。[logging] format和output会被接受,但目前不起作用。
各级别包含的内容见中继记录与存储的内容。
[metrics] 默认在 127.0.0.1:9090 上提供 Prometheus 计数器。该端点没有认证:非回环的 bind_addr 会让中继在启动时停止,除非同时设置 allow_public = true,此时您必须用防火墙保护它。参见指标。
会被接受但不起作用的设置
Section titled “会被接受但不起作用的设置”circuit_ttl_secs会被接受并忽略,启动时给出警告。电路在双方端点都连接时存在,任一方断开或关闭时结束,没有基于时间的过期。redis_url、[logging] format和[logging] output可以解析,但没有效果。