跳转到内容

配置指南

中继读取一个 TOML 文件,默认是 /etc/rchat/server.toml(用 --config 更改)。本页介绍大多数运营者会用到的设置。配置参考列出了每个配置项的类型和默认值。

  • 文件缺失、不可读或无效都会导致启动错误。 中继从不悄悄回退到默认值。
  • 服务器设置可以放在 [server] 下,也可以放在顶层。子表同样两种写法都可以:[server.acme] 与 [acme] 含义相同。
  • 未知配置项在任何表中都是启动错误,因此拼写错误会让服务器以 unknown field ... 停止。旧模板中的配置项,例如 randomization_strength 或 udp_bind,升级前必须删除。
  • 已移除的配置项会被拒绝并给出说明: message_queue_persist_path(参见离线队列)和 trusted_proxy(参见 TCP 前端部署)。
  • 资源限制在启动时检查。值为 0 或超出范围会让服务器停止,不存在”无限制”设置。
[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 = true
domains = ["chat.example.com"]
contacts = ["mailto:[email protected]"]
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_path 完全一致路径的 WebSocket 请求才能到达中继。匹配时忽略查询字符串。其他所有请求都会得到伪装网站,包括普通 HTTP 请求、升级到其他路径的请求以及乱码字节。请求路径从不记录。

设置一个较长的随机路径:

Terminal window
echo "/$(openssl rand -base64 24 | tr '+/' '-_')"

然后在每个客户端的服务器 URL 中使用相同路径:wss://chat.example.com/<path>。路径必须以 / 开头,且为纯 ASCII,不含 ?、#、空格或控制字符。

伪装网站([server.decoy]):

配置项默认值含义
enabledtrue向非中继请求提供伪装网站。设为 false 时,这些请求得到普通的 404。路径检查依然生效。
root无要提供的静态网站的绝对路径。启动时必须存在。不跟随指向目录外的符号链接。不设置时,提供一个通用的内置小页面。
server_header"nginx/1.24.0"Server 响应头的值。
write_timeout_secs30写出一个伪装响应的时间上限。

伪装网站每个连接只响应一个请求。它是一种缓解措施,不是伪装:它让随意的扫描看不出端口上运行的是什么,但坚决的探测者可以根据其行为(不支持 keep-alive 或范围请求、TLS 和时间细节)将它与真正的 nginx 区分开。

rchat-server --config <path> --render-decoy <dir> [--host <hostname>] 会把一个小型静态网站写入 <dir>,然后退出。该网站是一个虚构产品的登录页(网页邮箱、NAS 管理页、相册、云盘或代码托管)。产品类型、品牌名称、强调色和标志都由主机名决定,因此同一主机总是得到同一个网站,两个中继不会提供完全相同的页面。重新部署中继会生成相同的网站。

Terminal window
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 MiB
max_messages_per_recipient = 256 # 1 到 4096
sender_budget_bytes = 16777216 # 单个连接每个窗口内可为离线接收方排队 16 MiB
sender_budget_messages = 1024 # 1 到 65536
# sender_window_secs = 259200 # 默认为 ttl_secs;不能短于 ttl_secs
sender_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"
Terminal window
rchat-server --config ./dev.toml --init-relay-identity
rchat-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,此时您必须用防火墙保护它。参见指标。

  • circuit_ttl_secs 会被接受并忽略,启动时给出警告。电路在双方端点都连接时存在,任一方断开或关闭时结束,没有基于时间的过期。
  • redis_url、[logging] format 和 [logging] output 可以解析,但没有效果。