Quassel IRC 0.14.0 Ubuntu 22.04 安装指南

目标：在 Ubuntu 22.04 上完成 Quassel IRC 服务端（quasselcore）与客户端（quasselclient）的安装、初始化与验证。本文为部署篇，全部步骤在容器化实测环境（quassel-net 网络，三节点拓扑）中逐步执行并记录了真实输出（实测日期 2026-10-26），软件认知与版本溯源见认知篇《Quassel IRC 0.14.0 介绍与选型指南》。

一、实测环境信息

二、安装方式概览与选型

Quassel 0.14.0 在 Ubuntu 22.04 上有三种可获得途径，实测采用发行版 apt 包路线（生产推荐）：

💡 说明：Ubuntu 22.04 的 universe 仓库同时提供 quassel-core（服务端）与 quassel-client（图形客户端）两个包，二者共享 quassel-data 数据包。只在服务器装 core、在桌面机装 client，即为「分离部署」的标准形态。

三、安装服务端 quassel-core

3.1 安装命令

sudo apt update
sudo apt install quassel-core

实测环境（Ubuntu 22.04.5）安装的是 1:0.14.0-1ubuntu0.22.04.4。该包的主要依赖（apt-cache depends 实测摘录）：libc6、libgcc-s1、libstdc++6、zlib1g、libqt5core5a、libqt5network5、libqt5sql5、libqca-qt5-2、libldap-2.5-0、adduser、init-system-helpers（预依赖）。

3.2 安装即自动启动

包安装完成后 systemd 服务自动注册并拉起，实测服务状态：

● quasselcore.service - distributed IRC client using a central core component
     Loaded: loaded (/lib/systemd/system/quasselcore.service; enabled; vendor preset: enabled)
     Active: active (running)
   Main PID: 2918 (quasselcore)
      Tasks: 2
     Memory: 6.3M

首次启动日志（/var/log/quassel/core.log 实测）：

[Warn ] PostgreSQL driver plugin not available for Qt. Installed drivers: QSQLITE
[Warn ] No storage backend selected!
[Info ] Core is currently not configured! Please connect with a Quassel Client for basic setup.
[Info ] Listening for GUI clients on IPv6 :: port 4242 using protocol version 10
[Info ] Listening for GUI clients on IPv4 0.0.0.0 port 4242 using protocol version 10

⚠️ 注意两点实测结论：

1. 「Core is currently not configured!」是正常状态——全新安装后核心尚无管理员账号，必须先完成第四章的初始化。
2. jammy 构建不含 PostgreSQL 驱动（Qt 只装了 QSQLITE 插件），日志会输出 PostgreSQL driver not available 警告。这意味着 Ubuntu 仓库包实际只能用 SQLite 存储；确需 PostgreSQL 的场景只能自行源码编译或使用发行版更全的构建（选型篇已注明官方 Windows/macOS 构建同样不含 PostgreSQL）。

3.3 服务运行身份

包安装自动创建系统用户 quasselcore（属组 quassel），服务以该身份运行（systemd 单元 User=quasselcore / Group=quassel 实测），数据目录 /var/lib/quassel 与日志目录 /var/log/quassel 归属该用户，权限 600，普通用户不可直接读写。

四、初始化核心：创建管理员账号

服务端就绪但「没有账号」，初始化有两种路径，实测采用命令行方式：

sudo -u quasselcore quasselcore --configdir /var/lib/quassel --add-user

该命令进入交互式会话，依次输入用户名与密码（输入两次确认）即完成创建。实测创建的用户名 admin 在数据库中为 UserId 1（客户端连接后核心日志输出 authenticated successfully as "admin" (UserId: 1)）。

⚠️ 注意：--add-user 必须以 quasselcore 用户身份执行（或保证其对 /var/lib/quassel 有写权限），否则会在无权限目录下另建数据库，造成「账号创建成功但服务看不到」的假象。

账号创建后，客户端首次连接时还会引导存储后端确认（jammy 构建实际仅 SQLite 可选，实测数据库 schema version 32）。

五、安装客户端 quassel-client

在桌面机（实测为同网络另一节点 10.89.58.4）执行：

sudo apt install quassel-client

实测会同时安装 quassel-data（共享数据包），版本与服务端一致为 1:0.14.0-1ubuntu0.22.04.4。客户端可执行文件为 /usr/bin/quasselclient（Qt 图形程序）。

💡 实测提示：quasselclient 是 GUI 程序，在无显示环境（headless 容器/纯 SSH 服务器）直接运行 quasselclient --help 会因缺少 X 显示而 abort（实测退出码 134）。纯命令行环境可借助 xvfb-run -a quasselclient --help 获取帮助输出；正常使用需要桌面环境或 X 转发。

如果只需要「网页版客户端」，可另装第三方 quassel-web 前端连接同一 core，不属于本篇 apt 路线范围。

六、客户端首次连接与核心初始化

1. 启动 quasselclient，向导中填写：服务器地址（实测 10.89.58.2）、端口 4242、勾选使用 SSL。
2. 核心对非回环连接强制要求 TLS（发行版默认启动参数含 --require-ssl），自签证书会弹出信任确认，接受指纹即可（实测 openssl s_client 握手 Verify return code: 0 (ok)）。
3. 使用第四章创建的 admin 账号登录，客户端引导完成核心初始化。

服务端日志实测记录了这一过程：

[Info ] Client connected from 10.89.58.4
[Info ] Client 10.89.58.4 initialized and authenticated successfully as "admin" (UserId: 1).

⚠️ 注意：添加 IRC 网络没有命令行入口——必须在客户端图形界面中完成（File → Networks → Configure Networks，填写 IRC 服务器地址如 10.89.58.3:6667）。实测确认数据库 network 表在未配置前为空，这是 Quassel「管理面 = 启动参数 + 客户端 GUI」设计决定的。

七、防火墙与端口开放

quassel-core 包自带 UFW 应用描述文件（/etc/ufw/applications.d/quassel-core.ufw.profile 实测内容：ports=4242/tcp），放行方式：

sudo ufw allow Quassel        # 使用包自带 profile，等价于放行 4242/tcp
# 或显式指定端口：
sudo ufw allow 4242/tcp

仅需对外开放 4242/TCP（客户端协议）。core 到 IRC 网络的出站连接（如到 Ergo 的 6667/6697）为出站方向，默认无需额外放行；ident（10113）与 metrics 端口仅在使用对应功能参数时才监听。

⚠️ 安全建议：4242 端口直接暴露公网时务必保持发行版默认的 --require-ssl（强制 TLS），或使用支持 HAProxy proxy protocol 的反向代理（0.14.0 支持）以保留真实客户端 IP。

八、安装验证清单

全部命令在实测环境执行通过：

# 1. 服务状态：active (running)
systemctl status quasselcore

# 2. 监听端口：0.0.0.0:4242 与 [::]:4242
ss -tlnp | grep 4242

# 3. 版本确认
quasselcore --version        # quassel v0.14.0 (dist-da9c1c9)

# 4. 数据目录三件套
ls -la /var/lib/quassel/
# quassel-storage.sqlite（数据库）、quasselCert.pem（自签证书）、quasselcore.conf

# 5. TLS 握手验证（客户端视角）
echo | openssl s_client -connect <服务器IP>:4242 | grep "Verify return code"

# 6. 数据库账号确认（可选）
sqlite3 /var/lib/quassel/quassel-storage.sqlite "SELECT userid,username FROM quasseluser;"

九、升级与卸载

# 升级（jammy 源内 0.14.0 为最终版本，主要是安全补丁版本号变化）
sudo apt update && sudo apt upgrade quassel-core quassel-client

# 卸载服务端（保留数据）
sudo apt remove quassel-core
# 彻底卸载并删除数据（不可逆，含全部聊天记录）
sudo apt purge quassel-core && sudo rm -rf /var/lib/quassel /var/log/quassel

💡 升级注意：Quassel 客户端/核心协议跨版本兼容性极好（官方声明 0.14.x 客户端兼容 0.5.x 以上核心，反之亦然），升级顺序无需严格先core后client；SQLite 数据库带版本化 schema，核心启动时自动迁移。

十、常见安装问题（FAQ）

Q1：日志出现「PostgreSQL driver plugin not available for Qt. Installed drivers: QSQLITE」？ 正常。jammy 仓库构建只带 SQLite 驱动，服务会回退 SQLite 并正常工作（实测即如此）。若必须 PostgreSQL，需换用含 Qt SQL PostgreSQL 驱动的构建。

Q2：客户端连不上 4242？ 按序排查：systemctl status 是否 running → ss 是否监听 4242 → UFW/云安全组是否放行 4242/tcp → 客户端是否勾选 SSL（require-ssl 下明文连接被拒）。

Q3：--add-user 创建了账号但客户端登录提示不存在？ 多半以 root 身份在错误目录创建了另一个数据库。用 sudo -u quasselcore quasselcore --configdir /var/lib/quassel --add-user 重做，并用 sqlite3 查 quasseluser 表核对。

Q4：能像 ZNC 一样用普通 IRC 客户端（HexChat/irssi）直连 4242 吗？ 不能。4242 是 Quassel 私有二进制协议（实测日志显示 protocol version 10），必须使用 quasselclient / Quasseldroid / quassel-web 等专属客户端。

Q5：数据都在哪里、包含什么？ /var/lib/quassel/quassel-storage.sqlite（全部用户、网络、缓冲区、backlog 聊天记录）+ quasselCert.pem（TLS 证书）+ quasselcore.conf（核心状态）。备份即停服后拷贝整个目录。

十一、参考链接

• 官方下载页：https://quassel-irc.org/downloads（查询日期 2026-10-26）
• Ubuntu 软件源索引：jammy-updates/universe，quassel-core 1:0.14.0-1ubuntu0.22.04.4（2026-10-26 apt-cache policy 实测）
• 发行版配置文件（实测）：/lib/systemd/system/quasselcore.service、/etc/default/quasselcore、/etc/ufw/applications.d/quassel-core.ufw.profile、/etc/logrotate.d/quassel-core、/etc/apparmor.d/usr.bin.quasselcore
• 手册页：man quasselcore(1)（服务端参数详见配置篇）
• 同系列：认知篇《Quassel IRC 0.14.0 介绍与选型指南》、配置篇《Quassel IRC 0.14.0 配置参数详解》、命令篇《Quassel IRC 0.14.0 常用命令详解》