Ubuntu 22.04 部署 Glowing Bear 指南

目标：在一台全新 Ubuntu 22.04 服务器上从零搭好 Glowing Bear：WeeChat 3.5 + relay 插件提供后端，Glowing Bear 0.10.0 前端经 nginx 静态托管与 WebSocket 反代，浏览器里连上 WeeChat 并完成频道消息收发验证。全部命令与回显均在真实服务器实测通过（2026-10-26）。

一、环境信息

项目	值
操作系统	Ubuntu 22.04.5 LTS（jammy），x86_64
WeeChat	3.5-1（Ubuntu 22.04 universe 仓库 apt 版）
relay 插件	随 weechat 包附带（weechat-plugins 依赖），端口 9001（明文）/ 9002（TLS）
Glowing Bear	0.10.0（官方仓 master commit `b53e42f5`，2026-08-06）
前端构建工具	Node.js v20.20.2、npm 10.8.2
Web 服务器	nginx 1.18.0（Ubuntu 官方仓库），监听 80 / 443
前端站点目录	/var/www/glowing-bear（构建产物 3.7 MB）
TLS 证书	自签：/etc/nginx/ssl/gb.crt、/etc/nginx/ssl/gb.key；relay 证书 /var/lib/weechat/.config/weechat/ssl/relay.pem（2790 字节）
常驻方式	tmux 3.2a 会话 `weechat`
演示 relay 密码	q1w2e3r4（演示账号规则，生产环境请换强密码）

💡 说明：Glowing Bear 本身只是一组静态文件，"部署 Glowing Bear" 实际包含两件事：后端把 WeeChat 的 relay 开起来，前端把静态文件托管出去。本文按此顺序展开。

二、前置条件

一台 Ubuntu 22.04 服务器，具备 sudo 权限的账号；本文以 root 执行。
服务器可访问外网（apt 源与 GitHub）。若访问 GitHub 缓慢，走代理：export https_proxy=http://192.168.1.62:7897（本次实测即经代理完成 GitHub 拉取，apt 源走官方源直连）。
端口规划：80/443（nginx 站点）、9001（明文 relay，仅内网/本机用）、9002（TLS relay，公网用）。确认未被占用：

ss -ltn | grep -E ':80 |:443 |:9001 |:9002 '    # 无输出即表示四个端口均空闲

实测（部署前空闲，部署后复查可见四项全部 LISTEN）：

LISTEN 0      511          0.0.0.0:443        0.0.0.0:*
LISTEN 0      511          0.0.0.0:80         0.0.0.0:*
LISTEN 0      4096               *:9002             *:*
LISTEN 0      4096               *:9001             *:*

基础工具：apt-get update && apt-get install -y curl openssl nginx tmux（本文实测环境中 OpenSSL 3.0.2、tmux 3.2a、nginx 1.18.0）。

三、版本选型说明

WeeChat 用 apt 的 3.5：Ubuntu 22.04 universe 仓库自带，apt install weechat 即装即用，且 relay 插件已包含，无需另装插件包。Glowing Bear 官方 README 要求 WeeChat ≥ 2.9（TOTP 支持、WebSocket relay 等），3.5 满足。Ubuntu 22.04 无更新的 weechat 官方包，若需要 4.x 需自行编译，不在本文范围。
前端用官方仓构建产物：Glowing Bear 官方仓不打正式 Release 标签，package.json 版本号 0.10.0，master commit b53e42f5（2026-08-06）。前端获取两条路线：直接用官方托管版（零部署），或 git clone + npm run build 自托管。两条路线后端完全一致，见第六章对比。
nginx 用 Ubuntu 官方仓 1.18：纯静态文件 + 一条 WebSocket 反代路径，1.18 足够，无需第三方源。

四、安装 WeeChat 并开启 relay

4.1 apt 安装 weechat

apt-get update          # 刷新 apt 索引
apt-get install -y weechat tmux    # weechat 主程序 + relay 插件；tmux 用于常驻
apt-cache policy weechat    # 核对安装版本

实测回显：

weechat:
  Installed: 3.5-1
  Candidate: 3.5-1
  Version table:
 *** 3.5-1 500
        500 http://archive.ubuntu.com/ubuntu jammy/universe amd64 Packages

💡 说明：weechat 包在 Ubuntu 22.04 中自带 relay 插件（weechat-plugins 由包依赖自动带入），无需单独安装 relay 包。可用 ls /usr/lib/x86_64-linux-gnu/weechat/plugins/ | grep relay 复核，输出 relay.so 即在位。

4.2 用 tmux 常驻 WeeChat

WeeChat 是交互式终端程序，用 tmux 让它在后台常驻，断开 SSH 也不退出。建议用专用系统账号跑 WeeChat（新建可用 useradd -r -m -d /var/lib/weechat -s /bin/bash weechat）：

su - weechat -s /bin/bash -c "tmux new -d -s weechat 'weechat'"   # 以专用系统账号 weechat 启动后台会话
su - weechat -s /bin/bash -c "tmux ls"    # 确认会话存在

实测回显：

weechat: 1 windows (created Mon Oct 26 00:35:17 2026)

日常进入/退出：tmux attach -t weechat（进入后 Ctrl+b 再按 d 分离回终端，WeeChat 继续后台运行）。本文后续所有 WeeChat 内命令，既可 attach 进会话手敲，也可用 tmux send-keys -t weechat '<命令>' Enter 远程注入；正文统一给出命令本体，回显用 send-keys 方式采集。

4.3 开启明文 relay（内网/本机调试用）

在 WeeChat 中执行：

/relay add weechat 9001
/set relay.network.password q1w2e3r4
/save

/relay add weechat 9001 中的 weechat 是 relay 协议名（浏览器前端必须用它），9001 是监听端口。生效后配置落盘，/var/lib/weechat/.config/weechat/relay.conf 的 [port] 段：

[port]
ssl.weechat = 9002
weechat = 9001

[network] 段的密码项（明文存储，因为尚未启用 secure 加密，见 4.4）：

[network]
allow_empty_password = off
password = "q1w2e3r4"
max_clients = 5

验证 relay 在监听：

ss -ltn | grep 9001

LISTEN 0      4096               *:9001             *:*

⚠️ 注意：明文 relay 上所有数据（含密码、聊天内容）都是明文传输，只允许内网或经 Web 服务器同源反代使用；要暴露公网必须用 4.4 的 TLS relay，或走第七章的 HTTPS 站点反代。

4.4 开启 TLS relay（公网直连用）

TLS relay 需要一张证书。先给 relay 设置密码（推荐用 WeeChat 的 secure 机制存密码，避免配置文件明文）：

/secure passphrase q1w2e3r4
/secure set relay_password q1w2e3r4
/set relay.network.password ${sec.data.relay_password}

生成自签证书（WeeChat 约定路径 ${weechat_config_dir}/ssl/relay.pem，即 /var/lib/weechat/.config/weechat/ssl/relay.pem）：

mkdir -p /var/lib/weechat/.config/weechat/ssl
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"
chown -R weechat:weechat /var/lib/weechat/.config/weechat/ssl
chmod 600 /var/lib/weechat/.config/weechat/ssl/relay.pem

在 WeeChat 中添加 TLS relay 并重载证书：

/relay add ssl.weechat 9002
/relay sslcertkey
/save

实测证书落盘回显：

total 12
drwx------ 2 weechat weechat 4096 Oct 26 00:20 .
drwx------ 1 weechat weechat 4096 Oct 26 00:35 ..
-rw------- 1 weechat weechat 2790 Oct 26 00:22 relay.pem

监听复核：

ss -ltn | grep 9002

LISTEN 0      4096               *:9002             *:*

💡 技术拓展：/relay add 的 relay 名支持一组前缀组合，格式为 [ipv4.][ipv6.][ssl.]{weechat|irc.<名称>}。ssl. 前缀表示这条 relay 用 TLS；ipv4./ipv6. 限定地址族；unix. 前缀改用 UNIX 域套接字；协议名除 weechat（给 Glowing Bear 这类前端用）外还可以是 irc.<服务器名>（把 WeeChat 当 IRC bouncer 供普通 IRC 客户端连）。官方 /help relay 给出的示例包括 /relay add ssl.weechat 9001、/relay add ipv4.ipv6.ssl.weechat 9001、/relay add ssl.irc.libera 8001、/relay add unix.weechat ${weechat_runtime_dir}/relay_socket。本文浏览器直连场景只用 weechat 与 ssl.weechat 两种。

五、获取 Glowing Bear 前端

5.1 方案 A：使用官方托管版（零部署）

不部署任何前端文件，浏览器直接打开 https://www.glowing-bear.org （稳定版）或 https://latest.glowing-bear.org （开发版，落地页自带 Let's Encrypt 向导）。官方 README 明确说明托管版由 GitHub Pages 提供、随官方仓自动更新，且"浏览器直连 WeeChat，托管在哪不影响安全边界"。后端（第四章）照常需要。此方案无本地文件，跳到第七章只做 relay 反代部分即可。

5.2 方案 B：自构建静态目录（本文实测路线）

安装构建链并拉取官方源码：

apt-get install -y git nodejs npm    # 构建链：git 拉源码、node/npm 构建
node --version && npm --version
export https_proxy=http://192.168.1.62:7897    # GitHub 访问慢时走代理，可连通则省略
git clone https://github.com/glowing-bear/glowing-bear.git
cd glowing-bear
git log -1 --format='%h %ci %s'     # 记录版本基线

实测回显（Node 与版本基线）：

v20.20.2
10.8.2
b53e42f5 Mon Aug 6 03:37:34 2026 +0800 Update version to 0.10.0

安装依赖并构建：

npm install      # 拉取 AngularJS/Bootstrap 等依赖
npm run build    # 产出 build/ 静态目录

构建完成后把产物落到站点目录：

mkdir -p /var/www/glowing-bear
cp -r build/* /var/www/glowing-bear/
ls /var/www/glowing-bear | head    # 复核产物
du -sh /var/www/glowing-bear

实测回显：

assets
css
directives
embed-demo.html
emojione.min.js
emojione.min.js.LICENSE.txt
fonts
index.html
linkify-string.min.js
linkify.min.js
3.7M	/var/www/glowing-bear

六、方案对比与选择建议

维度	方案 A：官方托管版	方案 B：自构建托管
前端部署工作量	零（无本地文件）	git clone + npm 构建 + 站点目录
版本更新	随官方仓自动更新	手动 git pull + 重新构建
版本锁定	不可控（跟随官方）	可锁 commit（如 b53e42f5）
是否可内网使用	否（前端文件来自公网站点）	是（静态文件全在本地 nginx）
与后端的关系	完全一致（浏览器仍直连 relay）	完全一致
适用场景	个人快速用起来	内网隔离环境、需锁定版本、要改前端代码

选择建议：能出公网、图省事选 A；内网部署或要锁定版本（本文按 0.10.0/b53e42f5 落地）选 B。两条方案的后端配置（第四、七章）完全相同，前端方案不影响 relay 配置。

七、nginx 静态托管与 WebSocket 反代

7.1 站点 TLS 证书

浏览器到 nginx 之间用 HTTPS（公网部署的强制项，官方反复强调明文 relay 不能出公网）：

mkdir -p /etc/nginx/ssl
openssl req -nodes -newkey rsa:2048 -keyout /etc/nginx/ssl/gb.key \
  -x509 -days 3650 -out /etc/nginx/ssl/gb.crt \
  -subj "/CN=gb.example.internal"

💡 说明：生产环境建议用 Let's Encrypt 等公网可信证书替换自签证书（官方开发版落地页自带向导）；浏览器对自签证书会弹一次安全告警，测试环境可继续。

7.2 站点配置

写入 /etc/nginx/sites-available/glowing-bear，两个 server 块分别承载 HTTP（内网调试）与 HTTPS（公网）：

server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name _;

    root /var/www/glowing-bear;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;    # 单页应用回退到 index.html
    }

    location /weechat {
        proxy_pass http://127.0.0.1:9001;    # 反代到明文 relay；浏览器到 nginx 走 HTTPS，nginx 到 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;
    }
}

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;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        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;
        proxy_send_timeout 3600s;
    }
}

要点：location /weechat 是整个方案的枢纽——浏览器把 WebSocket 连到 wss://<站点>/weechat，nginx 升级协议后转发到本机 9001 的 relay，对外只暴露 80/443，relay 端口无需出公网；proxy_read_timeout 3600s 必须调大，否则空闲 relay 连接 60 秒即被 nginx 掐断（Glowing Bear 界面会转圈重连）。

7.3 启用与验证

ln -sf /etc/nginx/sites-available/glowing-bear /etc/nginx/sites-enabled/glowing-bear
rm -f /etc/nginx/sites-enabled/default     # 回收默认站点，避免 80 端口冲突
nginx -t                                   # 语法检查
systemctl reload nginx                     # 生效

nginx -t 实测回显：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

页面可达性验证（HTTP 与 HTTPS 双链路）：

curl -sS -o /dev/null -w "%{http_code} %{size_download}\n" http://127.0.0.1/
curl -sSk -o /dev/null -w "%{http_code} %{size_download}\n" https://127.0.0.1/

实测回显（两次都拿到 index.html，39961 字节）：

200 39961
200 39961

WebSocket 反代链路验证：从站点域名反代到 relay 后，relay 的日志会记录 websocket client 与经过 nginx 的真实 IP（见第八章 8.3 的 relay 侧回显）。

八、浏览器连接与频道收发验证

8.1 连接页填写

浏览器打开 https://<服务器IP或域名>/（自签证书点"继续前往"即可），在连接页填入：

连接项	值	说明
WeeChat host	服务器 IP 或域名	浏览器到 relay 的目标地址
Port	443	走 HTTPS 站点反代时填 443（加密勾选打开）
Password	q1w2e3r4	4.3/4.4 设置的 relay 密码
Encryption	勾选	TLS 加密开关
Save Password / Automatically connect	按需	密码存本地浏览器、下次自动连

💡 说明：两种连法都可行——勾选加密连 443（推荐，公网可用），或关掉加密连 80（仅内网调试）。若直连 9002 的 TLS relay（不经 nginx），host 填服务器 IP、Port 填 9002、Encryption 勾选，效果等价。

8.2 连接成功判定

点 Connect 后界面从连接页切换为 WeeChat 工作台：左侧出现 buffer 列表（weechat、local、频道、relay.relay.list 等），顶部显示 WeeChat 版本横幅（实测显示 WeeChat 3.5 (C) 2003-2022 - https://weechat.org/），右下输入框可用。此时浏览器到 WeeChat 的 WebSocket 链路（经 nginx /weechat 反代）已建立，relay 侧日志同步出现：

relay: new client on port 9001
relay: websocket client 1/weechat/127.0.0.1 connected (waiting auth)
relay: client 1/weechat/127.0.0.1 connected/authenticated

（waiting auth → connected/authenticated 即密码握手通过；127.0.0.1 是 nginx 反代后 relay 看到的来源。）

8.3 频道收发实测

在 WeeChat 中加入测试频道（/join #test），再到浏览器侧点击左侧 #test buffer，在输入框输入 hello-from-glowing-bear 回车。实测（HTTP 与 HTTPS 两条链路各跑一遍，2026-10-26）：

08:39:04   -->  gbuser (~weechat@localhost) has joined #test
08:39:07  @gbuser  hello-from-glowing-bear
08:39:07     peer  hello-from-irc

三行含义：gbuser 加入频道（WeeChat 侧 IRC 服务器回显）；浏览器发出的 hello-from-glowing-bear（@gbuser 发言，证明浏览器→relay→IRC 全链路写通）；peer hello-from-irc（另一台 IRC 客户端在同一频道的回声，证明浏览器能实时收到别人发的消息）。实测过程中还验证了断线重连：主动断开 relay 后界面显示重连提示，恢复后 buffer 状态与未读标记原样保留（backlog 按 backlog_since_last_disconnect 策略补齐）。

九、配置说明

部署完成后可调的常规项（逐项详解与生效验证见本专栏《Glowing Bear 0.10.0 配置参数详解》）：

relay 密码与 TOTP：/set relay.network.password（建议 ${sec.data.relay_password} 形式）+ relay.network.totp_secret，对应前端连接页的 TOTP 开关。
并发客户端上限：relay.network.max_clients（默认 5），超出时 relay 拒绝新连接。
WebSocket 来源白名单：relay.network.websocket_allowed_origins（默认空=不限；走 nginx 同源反代时可收紧为本站 origin）。
历史回放策略：relay.network.backlog_* 组（断线重连后补多少历史）。
nginx 侧：proxy_read_timeout（长连接保活）、HTTPS 证书与 TLS 版本。

十、常见问题（FAQ）

Q1：点 Connect 后一直 "Connecting…" 不动？ 按序排查：① 浏览器开发者工具 Network/WS 面板看 /weechat 的 WebSocket 是否 101 升级成功；② nginx nginx -t 与 proxy_read_timeout 配置；③ relay 是否在监听 ss -ltn | grep 9001；④ 密码是否与 /set relay.network.password 一致（官方 README 也提示检查 host、端口与防火墙放行 relay 端口）。

Q2：连上几分钟后频繁断开重连？ 典型原因是 nginx 未调大 proxy_read_timeout（默认 60s 空闲断连），改为 3600s 后 reload。

Q3：relay 密码在 relay.conf 里是明文怎么办？ 按 4.4 启用 secure：/secure passphrase 设置加密口令，/secure set relay_password <密码> 后用 /set relay.network.password ${sec.data.relay_password} 引用，/save 落盘后 relay.conf 中即为 sec.data 引用而非明文。

Q4：公网裸连 9001 行不行？ 不行。官方 README 原文明确："You should not use this over the internet. We strongly recommend that you set up encryption." 公网走 HTTPS 反代（443）或 TLS relay（9002）。

Q5：官方托管版打不开或想在内网用？ 内网隔离环境用第五章方案 B 自构建静态目录 + 本地 nginx；官方托管版依赖公网可达 GitHub Pages。

十一、卸载与清理

su - weechat -s /bin/bash -c "tmux kill-session -t weechat"   # 停 WeeChat 常驻会话
rm -f /etc/nginx/sites-enabled/glowing-bear && systemctl reload nginx    # 下线站点
rm -rf /var/www/glowing-bear            # 删前端产物
apt-get purge -y weechat && apt-get autoremove -y    # 卸载 WeeChat（连同配置提醒）
rm -rf /var/lib/weechat                 # 删 WeeChat 配置与 relay 证书（确认无保留数据后）
rm -rf /etc/nginx/ssl/gb.crt /etc/nginx/ssl/gb.key    # 删站点证书

卸载后复核：ss -ltn | grep -E ':9001 |:9002 ' 无输出、浏览器访问站点返回 404 即清理干净。

十二、参考链接

Glowing Bear 官方 README（快速开始/How it Works/代理指南）：https://github.com/glowing-bear/glowing-bear
Glowing Bear 官方托管版：https://www.glowing-bear.org （开发版 https://latest.glowing-bear.org ）
WeeChat 官方站点与 relay 文档：https://weechat.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 ）