Glowing Bear 0.10.0 配置参数详解
Glowing Bear 0.10.0 全链路配置参数详解：WeeChat relay 侧 17 个 relay.network 参数逐项解读（认证/TOTP/端口/并发/TLS/压缩/backlog）、前端连接页参数、nginx 反代与 HTTPS 站点配置，每项配实测生效验证与生产模板。
Glowing Bear 0.10.0 配置参数详解
目标：把 Glowing Bear 一条链路上的全部配置参数讲透——WeeChat relay 侧（relay.conf 与 /relay 指令）、前端连接页、nginx 反代站点，每项给出配置片段与生效验证。全部取值在 Ubuntu 22.04 + WeeChat 3.5 + Glowing Bear 0.10.0 实测环境采集（2026-10-26）。
一、环境信息
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS（jammy），x86_64 |
| WeeChat | 3.5-1（relay 配置文件 /var/lib/weechat/.config/weechat/relay.conf） |
| relay 实例 | weechat = 9001（明文）、ssl.weechat = 9002（TLS） |
| Glowing Bear | 0.10.0（master commit b53e42f5），静态站点 /var/www/glowing-bear |
| Web 服务器 | nginx 1.18.0，80/443，/weechat 路径反代 relay |
| relay 证书 | /var/lib/weechat/.config/weechat/ssl/relay.pem（2790 字节） |
| 演示 relay 密码 | q1w2e3r4（演示账号规则） |
部署过程见本专栏《Ubuntu 22.04 部署 Glowing Bear 指南》（ https://www.quzuo.net/document/f16RyM65090X ），本文在其产出的可用环境上展开参数层。
二、前置条件
- 已按部署指南完成：WeeChat 运行中（tmux 会话
weechat）、relay 9001/9002 在监听、nginx 站点 80/443 可达。 - 能进入 WeeChat（
tmux attach -t weechat，或用tmux send-keys -t weechat '<命令>' Enter注入——本文回显均以此方式采集）。 - 浏览器可打开站点连接页。
三、参数查看与修改方式
Glowing Bear 的"配置"分布在三层，修改方式各不相同：
第 1 层：WeeChat relay 侧（本文重点）。三种手段：
/set relay.network.<参数> <值>——逐项修改，立即生效（个别需重连）；/fset relay.network.*——打开交互式过滤视图，一次看全 17 个参数的类型/默认值/当前值，光标选中回车进入编辑；- 直接改 relay.conf——官方在文件头警告"不建议手改，尤其 WeeChat 运行中"，应改用
/set或/fset，/save落盘。
第 2 层：relay 实例管理，由 /relay 指令族负责。/help relay 实测输出的用法与示例（原文照抄，注意官方原文中 "Succesfully" 为官方拼写原样保留）：
/relay list
/relay add <name> <port>
/relay add [-config <config>] [-port <port>] <name> [<socket-path>]
/relay del <name>
/relay raw
/relay sslcertkey
weechat protocol:
/relay add weechat 9000
weechat protocol with SSL:
/relay add ssl.weechat 9001
weechat protocol with SSL, using only IPv4:
/relay add ipv4.ssl.weechat 9001
weechat protocol over UNIX domain socket:
/relay add unix.weechat ${weechat_runtime_dir}/relay_socket
irc proxy, for server "libera", with SSL:
/relay add ssl.irc.libera 8001
irc proxy, for all servers (client will choose), with SSL:
/relay add ssl.irc 8002
relay 名格式 [ipv4.][ipv6.][ssl.]<协议>：协议 weechat 供 Glowing Bear 前端使用，irc.<名称> 把 relay 变成 IRC bouncer；ssl. 前缀启用 TLS；ipv4./ipv6./unix. 控制监听形态。修改实例后 /save 落盘到 relay.conf 的 [port] 段（实测值）：
[port]
ssl.weechat = 9002
weechat = 9001
第 3 层：前端连接页与 nginx 站点，分别见第六、七章。
四、参数总览
/fset relay.network.* 实测回显（WeeChat 3.5，17 项全量，右侧为当前值，均为 2026-10-26 实采）：
relay.network.allow_empty_password boolean off
relay.network.allowed_ips string ""
relay.network.auth_timeout integer 60
relay.network.bind_address string ""
relay.network.clients_purge_delay integer 0
relay.network.compression integer 20
relay.network.ipv6 boolean on
relay.network.max_clients integer 5
relay.network.nonce_size integer 16
relay.network.password string "q1w2e3r4"
relay.network.password_hash_algo string "*"
relay.network.password_hash_iterations integer 100000
relay.network.ssl_cert_key string "${weechat_config_dir}/ssl/relay.pem"
relay.network.ssl_priorities string "NORMAL:-VERS-SSL3.0"
relay.network.totp_secret string ""
relay.network.totp_window integer 0
relay.network.websocket_allowed_origins string ""
同表在 relay.conf [network] 段的落盘形态（实测文件摘录）：
[network]
allow_empty_password = off
allowed_ips = ""
auth_timeout = 60
bind_address = ""
clients_purge_delay = 0
compression = 20
ipv6 = on
max_clients = 5
nonce_size = 16
password = "q1w2e3r4"
password_hash_algo = "*"
password_hash_iterations = 100000
ssl_cert_key = "${weechat_config_dir}/ssl/relay.pem"
ssl_priorities = "NORMAL:-VERS-SSL3.0"
totp_secret = ""
totp_window = 0
websocket_allowed_origins = ""
与 relay 行为相关的还有 [irc] 段 6 项 backlog 参数与 [look] 段 2 项（auto_open_buffer = on、raw_messages = 256，后者对应 /relay raw 抓包缓冲长度），见 5.6。
五、核心参数分类详解
5.1 认证与密码
| 参数 | 实测值 | 说明 |
|---|---|---|
| password | q1w2e3r4 | relay 登录密码，前端连接页 Password 项必须与此一致；官方 fset 描述允许空密码但默认拒绝空密码 |
| allow_empty_password | off | 官方描述："allow empty password in relay (it should be enabled only for tests or local network)"，保持 off |
| password_hash_algo | * | 客户端密码握手时允许的哈希算法集，* 表示全部可用（relay 协议握手阶段客户端与服务端协商） |
| password_hash_iterations | 100000 | PBKDF2 迭代次数，默认 10 万轮 |
| nonce_size | 16 | 握手 nonce 字节数（16 字节），属协议层防重放参数，默认即可 |
| totp_secret | "" | TOTP 共享密钥；非空时前端需在连接页打开 TOTP 开关并输入动态口令 |
| totp_window | 0 | TOTP 校验容忍窗口，0=默认严格校验 |
| auth_timeout | 60 | 客户端连接后完成认证的时限（秒），实测日志时序 connected (waiting auth) → connected/authenticated 在该窗口内完成 |
密码安全落盘的推荐写法（避免 relay.conf 明文）：
/secure passphrase q1w2e3r4
/secure set relay_password q1w2e3r4
/set relay.network.password ${sec.data.relay_password}
/save
生效验证：/save 后 relay.conf 中 password = "${sec.data.relay_password}"（secure 已启用时）；未启用 secure 时实测落盘为明文 password = "q1w2e3r4"。
TOTP 叠加（可选）：/secure set relay_totp_secret <BASE32密钥> → /set relay.network.totp_secret ${sec.data.relay_totp_secret}。前端连接页有对应开关 "Use Time-based One-Time Password"（Glowing Bear 官方托管版连接页实选项）。
5.2 端口与 relay 实例
| 参数/命令 | 实测值 | 说明 |
|---|---|---|
| [port] weechat | 9001 | 明文 relay 实例（/relay add weechat 9001 落盘） |
| [port] ssl.weechat | 9002 | TLS relay 实例（/relay add ssl.weechat 9002 落盘） |
| bind_address | "" | relay 绑定地址，空=全部网卡；只想内网监听可设 127.0.0.1 或内网 IP |
| ipv6 | on | 同时监听 IPv6；实测 ss -ltn 显示 *:9001（IPv4+IPv6 双栈） |
新增/删除实例后验证：
ss -ltn | grep -E ':9001 |:9002 '
LISTEN 0 4096 *:9002 *:*
LISTEN 0 4096 *:9001 *:*
5.3 并发与访问控制
| 参数 | 实测值 | 说明 |
|---|---|---|
| max_clients | 5 | 每端口最大并发客户端。官方描述："maximum number of clients connecting to a port (0 = no limit)"，取值范围 0–2147483647 |
| allowed_ips | "" | 来源 IP 白名单，空=不限；填写如 "10.0.0.0/8" 可限内网访问 |
| websocket_allowed_origins | "" | WebSocket Origin 白名单（只影响 websocket 形态的连接）；空=不限 |
| clients_purge_delay | 0 | 断开客户端信息的清理延迟，0=立即清理（/relay raw 视图中的过期记录） |
max_clients 超限行为有实测日志（第 6 个客户端连入 9001 被拒，WeeChat 核心 buffer 原样照抄）：
relay: client 5/weechat/127.0.0.1 connected/authenticated
=!= relay: client not allowed (max 5 clients are allowed at same time)
relay: disconnected from client 1/weechat/127.0.0.1
relay: disconnected from client 2/weechat/127.0.0.1
relay: disconnected from client 3/weechat/127.0.0.1
relay: disconnected from client 4/weechat/127.0.0.1
relay: disconnected from client 5/weechat/127.0.0.1
relay: no connected client for relay
⚠️ 注意：超限时 WeeChat 不仅拒绝第 6 个连接，还会断开既有客户端（实测日志可见 5 个连接被全部断开、
no connected client for relay）。多端使用的环境要么调大 max_clients（/set relay.network.max_clients 10），要么减少常驻连接。
💡 技术拓展：relay 的连接形态有三种——浏览器经 nginx 反代（Origin 是站点自身）、浏览器直连 relay 端口、纯 WebSocket 工具直连。
websocket_allowed_origins只对第三类 WebSocket 握手的 Origin 头生效：收紧为本站域名后，走 nginx 同源反代的连接不受影响（反代转发时 Origin 即为本站），而外部页面用浏览器 JS 直接构造跨源 WebSocket 会被拒。公网部署建议：/set relay.network.websocket_allowed_origins "<你的站点域名>"，并配合 5.2 的 bind_address 把 relay 限定到内网地址，只留 nginx 对外。
5.4 TLS
| 参数 | 实测值 | 说明 |
|---|---|---|
| ssl_cert_key | ${weechat_config_dir}/ssl/relay.pem | TLS relay 的证书+私钥合体文件路径；实测文件 2790 字节 |
| ssl_priorities | NORMAL:-VERS-SSL3.0 | GnuTLS 优先级串，默认剔除 SSL3.0 |
自签证书生成与装载（req -x509 把证书与私钥写入同一 PEM）：
openssl req -nodes -newkey rsa:2048 -keyout /var/lib/weechat/.config/weechat/ssl/relay.pem \
-x509 -days 3650 -out /var/lib/weechat/.config/weechat/ssl/relay.pem \
-subj "/CN=gb.example.internal"
chmod 600 /var/lib/weechat/.config/weechat/ssl/relay.pem
/relay add ssl.weechat 9002
/relay sslcertkey
生效验证：证书替换后必须再执行一次 /relay sslcertkey 重载；ss -ltn | grep 9002 确认 TLS relay 在监听，浏览器直连 9002 勾选 Encryption 可完成 TLS 握手。
5.5 传输压缩
compression = 20（整数，单位为百分比语义的压缩阈值配置，0=禁用）。前端侧印证：Glowing Bear package.json 依赖 zlibjs（浏览器端 zlib 实现），即前端具备解压 relay 压缩消息的能力，链路开启压缩后大 buffer 的 backlog 传输体积明显下降。默认 20 保持即可。
5.6 历史回放（backlog）
relay.conf [irc] 段实测值：
[irc]
backlog_max_minutes = 0
backlog_max_number = 1024
backlog_since_last_disconnect = on
backlog_since_last_message = off
backlog_tags = "irc_privmsg"
backlog_time_format = "[%H:%M] "
| 参数 | 值 | 说明 |
|---|---|---|
| backlog_max_number | 1024 | 断线重连后单 buffer 最多补放的消息条数 |
| backlog_max_minutes | 0 | 时间上限（分钟），0=不限时间只看条数 |
| backlog_since_last_disconnect | on | 只补放"上次断开后"的消息（多端切换不重复刷屏的关键） |
| backlog_since_last_message | off | 与上一项互补的补放基准开关 |
| backlog_tags | irc_privmsg | 补放哪些标签的消息（默认只补聊天正文，不补 join/part 噪音） |
| backlog_time_format | [%H:%M] | 补放消息的时间戳格式 |
实测行为（浏览器重连后频道 buffer 顶部出现）：
<-- peer (~peer@localhost) has quit (Client closed connection)
=?= ========== End of backlog (18 lines) ==========
--> gbuser (~weechat@localhost) has joined #test
End of backlog (18 lines) 即重连补放边界：18 条以内按 backlog_max_number/since_last_disconnect 策略回放，边界之后为实时消息。
六、前端连接参数详解
Glowing Bear 前端本身零配置文件，连接参数全部在连接页（首次使用）或 localStorage（之后）。实测连接页参数项：
| 连接项 | 说明 | 对应 relay 侧 |
|---|---|---|
| WeeChat host | relay 所在服务器地址（IP/域名） | relay 监听地址 |
| Port | relay 端口：443（走 nginx HTTPS 反代）或 9002（直连 TLS relay） | [port] 段实例 |
| Password | relay 密码 | relay.network.password |
| Encryption | 勾选后用 wss:// TLS 连接 | ssl relay 或 HTTPS 反代 |
| Use Time-based One-Time Password | 打开后输入 TOTP 动态口令 | relay.network.totp_secret |
| Save Password | 密码保存在浏览器 localStorage | —（本地行为） |
| Automatically connect | 打开站点自动重连 | —（本地行为） |
关于编码：连接页不提供编码切换项——relay 协议消息统一 UTF-8 传输，WeeChat 侧字符集由 IRC 服务器配置（/set irc.server.<名>.charset）决定，前端按 UTF-8 渲染，因此"乱码问题去 WeeChat 侧查"，前端无需配置。
连接失败的快速判定（前端表现 → 侧别）：
- 一直 "Connecting…"：网络/TLS 层问题（查 nginx、端口、证书）；
- 连上后立即断开并要求密码：认证层问题（查 password/TOTP）；
- 连上但 buffer 为空：relay 握手后协议层问题（查
/relay raw抓包视图）。
七、nginx 反代与 HTTPS 站点配置
站点配置（实测生效版本，/etc/nginx/sites-available/glowing-bear，两个 server 块分别承载 HTTP/HTTPS，HTTPS 块为公网推荐形态）：
server {
listen 443 ssl default_server;
listen [::]:443 ssl default_server;
server_name _;
ssl_certificate /etc/nginx/ssl/gb.crt;
ssl_certificate_key /etc/nginx/ssl/gb.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_session_cache shared:SSL:10m;
root /var/www/glowing-bear;
index index.html;
location / {
try_files $uri $uri/ /index.html; # 单页应用回退
}
location /weechat {
proxy_pass http://127.0.0.1:9001; # 反代到本机 relay（不出服务器）
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade; # WebSocket 升级三件套
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 3600s; # relay 长连接保活（默认 60s 必断）
proxy_send_timeout 3600s;
}
}
逐项要点：
proxy_http_version 1.1+Upgrade/Connection头：WebSocket 协议升级的最低要求，缺一不可（缺了浏览器停在 "Connecting…"）；proxy_read_timeout 3600s：relay 连接是长连且空闲期只有心跳级流量，默认 60s 会周期性掐断（前端表现"每分钟转圈重连"）；proxy_pass指向 9001 明文 relay：浏览器↔nginx 已是 TLS，nginx↔relay 走回环明文不出机器；若 relay 侧也要 TLS，可改为https://127.0.0.1:9002并加proxy_ssl_verify off（自签场景）；ssl_protocols TLSv1.2 TLSv1.3：与 relay 侧ssl_priorities剔除 SSL3.0 的思路一致，禁旧版协议。
生效验证三连（实测回显）：
nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
systemctl reload nginx
curl -sSk -o /dev/null -w "%{http_code} %{size_download}\n" https://127.0.0.1/
200 39961
relay 侧看到的反代来源（WebSocket 经 nginx 进来，来源为回环地址）：
relay: new client on port 9001
relay: websocket client 1/weechat/127.0.0.1 (waiting auth)
relay: client 1/weechat/127.0.0.1 has real IP address "10.89.73.1"
relay: client 1/weechat/127.0.0.1 connected/authenticated
（has real IP address 由 X-Real-IP 头透传，relay 日志可核对访问来源。）
八、生产配置模板
场景：单用户公网自用，2 核 4GB 内存、40GB 磁盘的小型云主机，WeeChat 常驻 + nginx HTTPS 反代，前端自托管。以下为推荐参数集（默认值为主的"最小改动"风格）：
/set relay.network.password ${sec.data.relay_password}
/set relay.network.max_clients 10
/set relay.network.allowed_ips ""
/set relay.network.websocket_allowed_origins "chat.example.com"
/set relay.network.bind_address ""
/set relay.network.auth_timeout 60
/set relay.network.compression 20
/set relay.network.backlog_max_number 1024
/set relay.network.backlog_since_last_disconnect on
/save
nginx 侧保持第七章模板，重点保住 proxy_read_timeout 3600s；资源占用上 WeeChat + nginx + 静态前端在该规格下无压力（无数据库、无后台任务），瓶颈只会出现在 relay 的 backlog 回放（首次连接多/多 buffer 时一次 1024 条回放），保持默认即可。
九、常见问题（FAQ）
Q1：/set 改了参数为什么前端行为没变？
部分参数只对新连接生效（如 max_clients、websocket_allowed_origins），改完 /save 后断开前端重连即可；确认方法再看 /fset relay.network.* 中当前值是否已更新。
Q2：relay.conf 里密码是明文，怎么变成引用？
走 secure：/secure passphrase → /secure set relay_password <密码> → /set relay.network.password ${sec.data.relay_password} → /save（见 5.1）。
Q3：公网要不要直接暴露 9001？ 不要。公网形态二选一：nginx HTTPS 反代（只暴露 443，relay 留回环/内网），或浏览器直连 9002 TLS relay。明文 9001 仅限本机/内网调试。
Q4：多设备同时在线被踢？
max_clients 上限行为是"拒绝新连接并断开既有连接"（5.3 实测日志），调大该值或减少常驻连接（关闭多余标签页）。
Q5：重连后消息少了或重复了？
检查 backlog 组参数：backlog_since_last_disconnect = on 保证只补断开后的消息；backlog_max_number 控制条数上限；两者配合仍不够回看历史，用 WeeChat 自身日志（/logger 插件）而非调大 backlog。
十、参考链接
- WeeChat 官方站点（relay 文档）：https://weechat.org
- Glowing Bear 官方仓库（前端连接参数与 FAQ）：https://github.com/glowing-bear/glowing-bear
- Glowing Bear 官方托管版连接页（前端参数实测来源）：https://www.glowing-bear.org
- 官方 wiki：Web 服务器反代 relay（https://github.com/glowing-bear/glowing-bear/wiki/Proxying-WeeChat-relay-with-a-web-server ）
- 本专栏同系列：《Glowing Bear 0.10.0 介绍与选型指南》（ https://www.quzuo.net/document/0tVAjR41666Y ）、《Ubuntu 22.04 部署 Glowing Bear 指南》（ https://www.quzuo.net/document/f16RyM65090X ）