The Lounge 4.5.2 Ubuntu 22.04 安装指南

The Lounge 4.5.2 在 Ubuntu 22.04 的双路线安装实测：官方 .deb 包（自动 systemd 托管）与 Yarn 全局安装（含 npm 路线失败规避），账号创建、连接自建 ngIRCd 端到端验证与常见问题排障（2026-10-27 实测）。

The LoungeThe LoungeIRC即时通讯Node.js2026/10/27

The Lounge 4.5.2 Ubuntu 22.04 安装指南

目标：在 Ubuntu 22.04 LTS 上以两种官方路线安装 The Lounge 4.5.2（自托管 Web IRC 客户端）——方案 A：官方 .deb 包（推荐） 与 方案 B：Yarn 全局安装（Node.js 路线）——并完成账号创建、systemd 服务托管、连接自建 IRC 服务器（ngIRCd）的端到端验证。全部步骤在实测环境完成并记录真实回显（验证日期 2026-10-27）。

一、环境信息

  • 实测环境：Ubuntu 22.04 LTS（systemd 基座，x86_64），验证日期 2026-10-27
  • 软件版本：The Lounge v4.5.2（官网 https://thelounge.chat，仓库 https://github.com/thelounge/thelounge，v4.5.2 发布于 2026-07-11）
  • 运行时要求：Node.js ≥ 22.13.0（来自 .deb 包依赖声明实查；v4.5.0 起最低要求 Node.js 22）
  • IRC 后端（联网验证用）：ngIRCd 1.0.2-3（Ubuntu 22.04 仓库版本，监听 6667 端口）
  • 网络说明：实测环境经代理 http://192.168.1.62:7897 访问 GitHub/npm（国内直连 GitHub 不稳定，命令中的代理环境变量按需省略）
  • 说明：本文所有 sudo 操作以 root 权限执行；The Lounge 的管理命令必须以 thelounge 系统用户身份运行（详见 6.2 节的实测警告）

二、方案选择与前置准备

2.1 两种安装路线对比（实测结论）

对比项方案 A：官方 .deb 包方案 B：Yarn 全局安装
安装命令apt install ./thelounge_4.5.2_all.debyarn global add thelounge
systemd 服务✅ 安装即自动注册并启用❌ 需手写单元文件
专用系统用户✅ 自动创建 thelounge 用户❌ 需手动创建
运行时依赖依赖 apt 的 nodejs (>= 22.13.0)（Ubuntu 22.04 自带版本过旧，需先装 NodeSource 源）需先装 Node.js 22+ 与 yarn
数据目录/etc/thelounge（默认）需用 THELOUNGE_HOME 显式指定
实测结果一次成功一次成功（npm 路线实测失败，见 5.3）
适用场景Ubuntu/Debian 生产环境首选非 Debian 系或不便用 dpkg 的环境

结论：Ubuntu 22.04 优先选方案 A（.deb 包），两条路线都绕不开先准备 Node.js 22+ 环境（.deb 包依赖声明实查为 Depends: nodejs (>= 22.13.0), bash, init-system-helpers）。

2.2 前置准备：Node.js 22 源与基础工具（两条路线通用）

实测环境默认仓库无 Node 22，用 NodeSource 官方脚本安装（实际安装版本 22.23.4，由后续服务启动日志确认）：

sudo apt update
sudo apt install -y curl ca-certificates gnupg
curl -fsSL https://deb.nodesource.com/setup_22.x -o /tmp/setup_22.x
sudo bash /tmp/setup_22.x        # 配置 NodeSource 源（脚本可先审查再执行）
sudo apt install -y nodejs
node --version                   # 实测输出：v22.23.4（The Lounge 服务日志同报 Node.js 22.23.4）

💡 技术拓展：若内网无法直连 deb.nodesource.com，可为 apt 配置代理（写入 /etc/apt/apt.conf.d/95proxy：Acquire::http::Proxy "http://代理地址:端口";），实测可正常拉取 NodeSource 源。

三、方案 A：官方 .deb 包安装（推荐）

3.1 下载并校验

从 GitHub Releases 下载官方 .deb 包并校验 SHA-256（包大小 5,375,232 字节 ≈ 5.1 MB）：

cd /opt
curl -LO https://github.com/thelounge/thelounge/releases/download/v4.5.2/thelounge_4.5.2_all.deb
sha256sum thelounge_4.5.2_all.deb

实测校验值：

b0312313cb3fa2bc1a3f4180ec3f52ba08edff1a76f8577f92395174f8599249  thelounge_4.5.2_all.deb

3.2 安装（自动注册 systemd 服务）

sudo apt install -y ./thelounge_4.5.2_all.deb

⚠️ 注意：必须使用 ./ 或绝对路径前缀（如 /opt/thelounge_4.5.2_all.deb）。实测中若直接写文件名且当前目录不在文件所在位置，apt 会按包名检索软件源而报「Unable to locate package」。

安装完成后核对关键事实（实测回显）：

id thelounge
# 实测输出：uid=113(thelounge) gid=118(thelounge) groups=118(thelounge)   ← 安装器自动创建的专用系统用户

dpkg -s thelounge | grep -E '^(Package|Version|Depends)'
# 实测输出：
# Package: thelounge
# Version: 4.5.2
# Depends: nodejs (>= 22.13.0), bash, init-system-helpers

systemd 单元文件位于 /lib/systemd/system/thelounge.service（实测内容要点）：

[Service]
User=thelounge
Group=thelounge
Type=simple
ExecStart=/usr/bin/thelounge start
ProtectSystem=yes
ProtectHome=yes
NoNewPrivileges=yes
PrivateTmp=yes

💡 技术拓展：单元自带 systemd 沙箱加固（ProtectSystem=yes 以只读挂载 /usr、/boot、/etc，PrivateTmp=yes 私有 /tmp），数据目录 /etc/thelounge 由 The Lounge 进程以 thelounge 用户身份写入。

3.3 启动服务并核对监听

sudo systemctl start thelounge
systemctl is-active thelounge        # 实测输出：active
ss -ltn | grep 9000                  # 实测输出：LISTEN 0 511 *:9000

服务启动日志（journalctl -u thelounge -n 8 --no-pager 实测摘录）：

The Lounge v4.5.2 (Node.js 22.23.4 on linux x64)
Configuration file: /etc/thelounge/config.js
Available at http://[::]:9000/ in private mode
User root loaded

3.4 创建管理员账号

The Lounge 的管理命令必须以 thelounge 系统用户身份运行，否则报错（实测警告见 6.2 节）。private 模式下创建账号：

sudo apt install -y sudo                       # 若系统无 sudo
sudo -u thelounge thelounge add root --password '你的密码' --save-logs
# 实测输出：
# 2026/10/27 05:02:17 [INFO] User root added
# 2026/10/27 05:02:17 [INFO] User file located at /etc/thelounge/users/root.json
# 2026/10/27 05:02:17 [INFO] User root has no client certificate to generate
# 2026/10/27 05:02:17 [INFO] Saved network list for user root

⚠️ 注意：--save-logs 启用消息历史落盘（SQLite，位于 /etc/thelounge/logs/）；不指定该参数则历史仅存内存。--password 缺省时进入交互输入（脚本自动化场景务必显式传参）。

账号数据实查：/etc/thelounge/users/root.json 为单一 JSON 文件，包含 password（bcrypt 哈希）、sessions、clientSettings、networks 等键——v4.5.2 的网络配置内嵌在用户文件中（每个网络一个对象，含 nick、host、port、tls、sasl 等字段），消息历史单独存于 /etc/thelounge/logs/<用户名>.sqlite3。

3.5 浏览器登录验证

浏览器打开 http://服务器IP:9000，实测页面标题为 The Lounge，输入 3.4 节创建的账号密码登录后进入主界面（左侧网络/频道列表 + 右侧消息窗格）。此时账号尚无网络，点击「Connect」表单或左侧「+」创建 IRC 网络连接。

3.6 端到端验证：连接自建 IRC 服务器

准备一个 IRC 后端（以内网最常见的自建 ngIRCd 为例；连接公网网络如 Libera.Chat 时跳过此步）：

sudo apt install -y ngircd        # 实测版本 1.0.2-3
sudo systemctl start ngircd
ss -ltn | grep 6667               # 实测输出：LISTEN 0 5 *:6667

在 The Lounge 网页「Connect」表单中填入：昵称 lounge1、服务器 127.0.0.1、端口 6667、频道 #lounge，提交后实测：

  1. 「Local ngircd」网络出现在左侧列表，#lounge 频道自动加入，成员列表可见自己；
  2. 频道内发送消息 hello from The Lounge 4.5.2，消息回显发送者 lounge1（self 标记正确）；
  3. 消息落盘取证：/etc/thelounge/logs/root.sqlite3 的 messages 表实查到该消息记录（network 为网络 UUID、channel 为 #lounge、type 为 message）；
  4. 永在线取证：浏览器全部关闭后，实测环境中 The Lounge 进程（node）与 ngIRCd 的 TCP 连接仍为 ESTAB 状态（ss -tnp | grep 6667 可见 node 与 ngircd 双向 ESTABLISHED）——服务端代持 IRC 连接，这正是 Web IRC 客户端相对纯前端方案（如 Kiwi IRC 直连模式）的核心差异，见《The Lounge 4.5.2 介绍与选型指南》。

⚠️ 实测发现：连接 ngIRCd 时昵称超过 9 个字符会被服务端改名（ngIRCd 默认 NICKLEN=9，实测昵称 loungeuser 10 字符时连接异常，改用 lounge1 后正常）。连接公网大型网络时同样注意各网络的昵称长度限制。

四、方案 B：Yarn 全局安装（Node.js 路线）

适用于不便使用 dpkg 的环境。先完成第 2.2 节的 Node.js 22 准备，再执行本节。

4.1 安装 yarn 并全局安装 thelounge

sudo npm install -g yarn
yarn config set proxy http://192.168.1.62:7897 -g     # 走代理时需要；yarn 的 https 代理键为 https-proxy
yarn config set https-proxy http://192.168.1.62:7897 -g
yarn global add thelounge

实测输出要点：

[1/4] Resolving packages...
[2/4] Fetching packages...
[3/4] Linking dependencies...
[4/4] Building fresh packages...
success Saved 1 new dependency.

验证（实测输出）：

which thelounge
# 实测输出：/usr/local/bin/thelounge
thelounge --version
# 实测输出：v4.5.2

4.2 数据目录与专用用户

Yarn 路线安装的 The Lounge 数据目录需用环境变量 THELOUNGE_HOME 显式指定（官方文档说明非 .deb 安装默认使用执行用户主目录下的 .lounge，生产环境建议统一定位）。实测创建专用用户与目录：

sudo useradd -r -m -d /var/opt/thelounge -s /usr/sbin/nologin thelounge
sudo mkdir -p /var/opt/thelounge && sudo chown -R thelounge:thelounge /var/opt/thelounge

以 thelounge 用户身份创建账号（实测输出）：

printf '你的密码\n你的密码\n' | sudo -u thelounge -H bash -c 'THELOUNGE_HOME=/var/opt/thelounge thelounge add root'
# 实测输出：
# 2026/10/27 04:48:25 [INFO] User root added
# 2026/10/27 04:48:25 [INFO] User file located at /var/opt/thelounge/users/root.json

⚠️ 实测发现：非交互创建账号时若只重定向一次密码输入，CLI 还会追问「Save logs? (y/n)」交互确认导致脚本挂起——add 命令可用 --password <密码> --save-logs 参数完全非交互化（见 3.4 节），交互式仅适用于人工操作场景。

4.3 手写 systemd 单元并启用

创建 /etc/systemd/system/thelounge.service（实测可用版本）：

[Unit]
Description=The Lounge web IRC client
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=thelounge
Environment=THELOUNGE_HOME=/var/opt/thelounge
ExecStart=/usr/local/bin/thelounge start
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

启用并验证（实测输出）：

sudo systemctl daemon-reload
sudo systemctl enable --now thelounge
systemctl is-active thelounge        # 实测输出：active
curl -sI http://127.0.0.1:9000 | head -1
# 实测输出：HTTP/1.1 200 OK

后续账号管理、网页登录与联网验证与方案 A 完全一致（见 3.4–3.6 节，命令中数据目录按 THELOUNGE_HOME 替换）。

五、常见问题与排障

5.1 npm 全局安装失败（真实失败点记录）

现象：npm install -g thelounge 安装依赖阶段报错退出，关键回显：

npm error code 127
npm error command sh -c install
npm error /usr/lib/node_modules/thelounge/node_modules/irc-framework: npm-run-all: not found

原因：The Lounge 的依赖树含 git 依赖（如 irc-framework 锁定特定 commit），npm 全局安装会触发包内 install 生命周期脚本构建链，实测该链在依赖 npm-run-all 的环节断裂（git 克隆阶段还要求环境可直连 GitHub）。

规避：官方文档《Install and upgrade》明确推荐 Yarn 路线（yarn global add thelounge），实测一次通过（见 4.1 节）。若必须用 npm，需排查并补齐构建链工具链，生产环境不建议。

5.2 以 root 运行 CLI 的警告

现象：直接以 root 执行 thelounge 管理命令时实测输出警告：

[WARN] You are currently running The Lounge as root. We highly discourage running as root!
[WARN] Config file owner does not match the user you are currently running The Lounge as.

规避：一律用 sudo -u thelounge thelounge <子命令>（.deb 路线）或在手写单元/脚本中固定 User=thelounge。/usr/bin/thelounge help 的实测输出末尾还提示了 THELOUNGE_HOME 环境变量与默认值 /etc/thelounge。

5.3 apt 安装报「Unable to locate package thelounge_4.5.2_all.deb」

现象：apt install -y thelounge_4.5.2_all.deb（无路径前缀且文件不在当前目录）报 E: Unable to locate package。

原因：apt 把该字符串当作软件源中的包名检索，而非本地 deb 文件。

规避：显式带路径：apt install -y ./thelounge_4.5.2_all.deb 或绝对路径（见 3.2 节实测）。

5.4 昵称被 IRC 服务器拒绝/改名

见 3.6 节实测发现：昵称长度超过 IRC 服务器限制（ngIRCd 默认 9 字符）时连接异常。规避：昵称控制在目标网络 NICKLEN 限制内，或在网络设置中配置 SASL 后按网络规范注册。

六、参考链接

  1. 官方安装文档《Install and upgrade》：https://thelounge.chat/docs/install-and-upgrade（Yarn 路线与 .deb 路线说明，查询日期 2026-10-27）
  2. 官方指南《Using the correct system user》：https://thelounge.chat/docs/usage#using-the-correct-system-user
  3. v4.5.2 下载页：https://github.com/thelounge/thelounge/releases/tag/v4.5.2（含 .deb 包与 SHA-256 校验值，查询日期 2026-10-27）
  4. NodeSource 安装脚本：https://deb.nodesource.com/setup_22.x
  5. 站内相关篇目：《The Lounge 4.5.2 介绍与选型指南》；本专栏《The Lounge 4.5.2 Docker Compose 部署指南》《The Lounge 4.5.2 配置参数详解》《The Lounge 4.5.2 常用命令详解》（发布于同一专栏）