Quassel IRC 0.14.0 配置参数详解

目标：逐项讲清 Quassel IRC 0.14.0 服务端（quasselcore）与客户端（quasselclient）的全部配置入口——命令行启动参数、systemd 单元与环境变量、数据目录状态文件——并给出可落地的参数组合。本文为配置篇，所有参数表与文件内容均来自 Ubuntu 22.04.5 实测环境（quassel-core 1:0.14.0-1ubuntu0.22.04.4）的 --help 输出、发行版配置文件与运行日志（实测日期 2026-10-26）。

一、配置体系总览

Quassel 的服务端配置没有「主配置文件」概念，管理面由四层构成（实测梳理）：

两点架构性结论（实测确认）：

• 添加 IRC 网络、配置身份（identity）、高亮/忽略规则等业务配置没有 CLI，只能通过 quasselclient 图形界面完成；命令行参数只覆盖「核心进程自身」的行为。
• 全新安装即有合理默认值（4242 端口、双栈监听、SQLite、强制 TLS），最小部署可以零配置文件完成。

二、服务端启动参数详解（quasselcore）

以下为 Ubuntu 22.04 仓库包 quasselcore --help 实测完整清单，按功能分组注释：

2.1 基础运行参数

2.2 账号与认证参数

2.3 存储后端参数

2.4 TLS 参数

2.5 ident 与代理参数

2.6 可观测性与日志参数

⚠️ 安全红线：--debug-irc、--debug-irc-parsed 的帮助文本明确警告日志包含密码（含 SASL/_nick 口令）。只在排障时短期开启，且必须配合 Debug 级别日志，事后立即关闭并清理日志。

三、systemd 单元与 /etc/default/quasselcore

Ubuntu 包注册的单元 /lib/systemd/system/quasselcore.service 实测全文关键内容：

[Unit]
Description=distributed IRC client using a central core component
Documentation=man:quasselcore(1)
Wants=network-online.target postgresql.service
After=network-online.target postgresql.service

[Service]
User=quasselcore
Group=quassel
WorkingDirectory=/var/lib/quassel
Environment="DATADIR=/var/lib/quassel" "LOGFILE=/var/log/quassel/core.log" "LOGLEVEL=Info" "PORT=4242" "LISTEN=::,0.0.0.0"
EnvironmentFile=-/etc/default/quasselcore
ExecStart=/usr/bin/quasselcore --configdir=${DATADIR} --logfile=${LOGFILE} --loglevel=${LOGLEVEL} --port=${PORT} --listen=${LISTEN} --require-ssl
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure

配套环境变量文件 /etc/default/quasselcore 实测内容：

LOGLEVEL="Info"
PORT="4242"
LISTEN="::,0.0.0.0"

修改方法（发行版推荐路径，不改单元文件本身）：编辑 /etc/default/quasselcore 后执行：

sudo systemctl daemon-reload
sudo systemctl restart quasselcore

💡 解读与注意：

1. EnvironmentFile=- 前导连字符表示文件可选；此处单元先用 Environment= 内置同值默认，用户文件覆盖之。
2. --require-ssl 写死在 ExecStart 中，不在环境变量里——关闭强制 TLS 需要覆写单元（systemctl edit quasselcore 重写 ExecStart），属高危操作。
3. Wants/After=postgresql.service 表明发行版预期 PostgreSQL 存储场景；jammy 构建缺驱动时该依赖空转无害（实测日志仅警告）。
4. Restart=on-failure：进程异常退出自动拉起；kill -HUP（reload）不重载配置文件——Quassel 无 SIGHUP 重载语义，改参数一律 restart。

四、数据目录与状态文件

/var/lib/quassel 实测内容（安装并初始化后）：

quasselcore.conf 实测内容（节选）：

[Config]
Version=1

[Core]
StorageSettings=@Variant(...Backend\0\0\0\f\0S\0Q\0L\0i\0t\0\x65)

即核心状态里记录了所选存储后端为 SQLite。该文件由核心自动维护，手改无意义且危险。

数据库实测表清单（sqlite3 .tables）：backlog（聊天记录）、buffer（缓冲区）、network（IRC 网络）、identity / identity_nick（身份）、ircserver（网络服务器地址）、quasseluser（核心用户）、sender、user_setting、core_state、coreinfo。初始化后 quasseluser 含 admin（UserId 1），network 为空（未在客户端添加网络）。

五、存储后端配置

• 默认 SQLite：首次客户端初始化时选择；实测核心日志输出 SQLite storage backend is ready. Schema version: 32，数据库 schema 随核心版本自动迁移。
• PostgreSQL：jammy 仓库包不可用——启动日志实测警告 PostgreSQL driver plugin not available for Qt. Installed drivers: QSQLITE（Qt SQL 的 PostgreSQL 驱动未随包安装）。需 PostgreSQL 的场景只能换用包含驱动的构建或源码编译。
• 切换与迁移：quasselcore --select-backend <backend> 会尝试迁移既有数据（官方帮助原文：Switch storage backend (migrating data if possible)）。操作前务必停服并备份 configdir。

六、TLS/证书配置

1. 自动证书：核心首次启动在 configdir 生成自签 quasselCert.pem（实测已生成），同时承载证书与私钥，权限 600。
2. 强制 TLS：发行版默认带 --require-ssl，非回环明文连接被拒。实测从另一节点以 openssl 握手验证：Verify return code: 0 (ok)。
3. 替换为可信证书：用 --ssl-cert/--ssl-key 指向 Let's Encrypt 等签发的 PEM（fullchain 与 privkey），或直接替换 quasselCert.pem 后重启。单 PEM 文件需同时含证书链与私钥。
4. 客户端侧：连接自签核心时，客户端会展示证书指纹要求人工信任（一次性确认）。

七、ident 与反向代理

• 一般个人部署：三个 ident 参数都不需要（多数 IRC 网络不强制 ident）。
• 多用户/要求 ident 的网络：--ident-daemon --ident-port 113 --ident-listen 0.0.0.0（或 --oidentd --oidentd-conffile，适合宿主机已跑 oidentd 的场景），并按官方建议加 --strict-ident。
• HAProxy/nginx 反代场景：0.14.0 支持 proxy protocol；用 --proxy-cidr 限定可信反代来源网段（如 10.89.58.0/24），反代侧发送 PROXY 头以保留真实客户端 IP。

八、Prometheus 指标配置

0.14.0 内置指标接口，开启三步：

# /etc/default/quasselcore 追加（需同步修改单元 ExecStart 增加参数，或 systemctl edit 覆写）
# ExecStart 追加：--metrics-daemon --metrics-port 9735 --metrics-listen 127.0.0.1

实测帮助文本确认：--metrics-port/--metrics-listen 仅在 --metrics-daemon 下有意义，帮助未标注默认端口。建议固定监听 127.0.0.1 由 Prometheus 本机抓取，避免指标接口直接暴露。注意：开启 metrics 需修改单元 ExecStart（环境变量只覆盖 PORT/LISTEN/LOGLEVEL 三项），修改后 daemon-reload + restart。

九、日志配置与轮转

• 级别与去向由 -L/--loglevel、-l/--logfile、--syslog 控制（发行版默认 Info + 文件）。
• 包自带 logrotate 配置 /etc/logrotate.d/quassel-core 实测：weekly（每周）、rotate 4（保留 4 份）、compress + delaycompress、copytruncate（复制后截断，适配核心持续持有日志句柄的行为）、missingok、notifempty。默认无需调整。
• 排障临时提级：/etc/default/quasselcore 中 LOGLEVEL="Debug" + restart（完成后改回）。

十、客户端配置参数（quasselclient）

quasselclient --help 实测完整参数（无显示环境需 xvfb-run -a 包裹执行，实测直接运行会 abort）：

客户端配置目录实测产物：quasselclient.conf（[Config] Version=1 VersionMinor=9 + [QtUi] 窗口几何/布局状态，QSettings 格式）与 settings.qss（默认样式）。多账号、网络、身份等业务配置存储在核心侧数据库，客户端本地文件仅承载 UI 状态——这是「客户端可换机器、状态不丢」的原因。

十一、常用参数组合示例

# A. 最小安全默认（发行版即此形态）：双栈 4242 + 强制 TLS + SQLite
ExecStart=/usr/bin/quasselcore --configdir=/var/lib/quassel --require-ssl

# B. 仅本机监听 + 反代终止 TLS（nginx stream/HAProxy，发 proxy protocol）
quasselcore --configdir /var/lib/quassel --listen 127.0.0.1 \
  --proxy-cidr 10.89.58.0/24

# C. ident + oidentd 集成（多用户服务器）
quasselcore --configdir /var/lib/quassel --strict-ident --oidentd \
  --oidentd-conffile /etc/oidentd.conf

# D. Prometheus 指标（本机抓取）
quasselcore --configdir /var/lib/quassel --metrics-daemon \
  --metrics-port 9735 --metrics-listen 127.0.0.1

十二、参考链接

• 服务端参数：quasselcore --help 与 man quasselcore(1)（本文表 2.1–2.6 为 2026-10-26 实测原文）
• 客户端参数：quasselclient --help（2026-10-26 xvfb 环境实测）
• 发行版配置文件（实测路径）：/lib/systemd/system/quasselcore.service、/etc/default/quasselcore、/etc/logrotate.d/quassel-core、/etc/ufw/applications.d/quassel-core.ufw.profile、/etc/apparmor.d/usr.bin.quasselcore
• 官方下载页：https://quassel-irc.org/downloads（查询日期 2026-10-26）
• 同系列：认知篇《Quassel IRC 0.14.0 介绍与选型指南》、部署篇《Quassel IRC 0.14.0 Ubuntu 22.04 安装指南》、命令篇《Quassel IRC 0.14.0 常用命令详解》