Spectrum 2.2.1 配置参数详解

目标：以 Spectrum 2.2.1 官方源码树自带的示例配置（spectrum/src/sample.cfg、sample2.cfg、sample2_gateway.cfg）与官方配置文档为口径，逐节详解传输实例配置文件（INI 格式）与 spectrum2_manager.cfg 管理服务配置的全部常用参数，并给出生产配置模板。参数修改与热生效链路已在 Ubuntu 22.04 实测环境验证（IRC 传输实例 irc.localhost 运行中）。

一、环境信息

架构背景（frontend/backend 双层、五种后端）见 《Spectrum 2.2.1 介绍与选型指南》；安装与部署过程见 《Ubuntu 22.04 安装 Spectrum 2.2.1 指南》 与 《Spectrum 2 Docker Compose 部署指南》。

二、前置条件

1. 已按安装篇或部署篇完成 Spectrum 2 安装，存在至少一个传输实例。
2. 理解 gateway-mode（Spectrum 2 作为组件挂到既有 XMPP 服务器）与 server-mode（Spectrum 2 自己就是 XMPP 服务器）两种形态——本文参数详解以 gateway-mode 为主线，server-mode 差异点单独标注。
3. 修改配置需要 root 或对 /etc/spectrum2/ 的写权限。

三、参数查看与修改方式

3.1 配置文件位置与格式

Spectrum 2 的全部配置都是 INI 格式：[节名] 分节、key = value 键值对、# 行注释。传输实例配置放在 /etc/spectrum2/transports/ 目录下，一个 .cfg 文件就是一个传输实例（文件名不参与实例命名，实例身份由文件内的 jid 决定）；管理服务自身的配置固定在 /etc/spectrum2/spectrum_manager.cfg。

3.2 查看当前实例配置

cat /etc/spectrum2/transports/irc.cfg

回显即实例的完整配置（与部署篇 4.1 一致），要点行：

[service]
jid = irc.localhost
password = password
server = prosody
port = 5347
backend=/usr/libexec/spectrum2_libcommuni_backend

3.3 修改与热生效

修改 .cfg 文件后，无需重启实例即可让大部分参数生效——向实例发送 reload 命令（实测回显）：

spectrum2_manager irc.localhost reload

Config reloaded

连接类三要素（jid/password/port）与 backend 路径这类启动期参数，reload 后建议重启实例确认（systemctl restart spectrum2 或 spectrum2_manager restart）。

3.4 在线命令面板：确认实例支持的管理命令

spectrum2_manager <实例JID> commands 列出实例当前支持的全部在线命令（实测回显照抄）：

args - "Shows description of arguments for command" Category: General AccesMode: Admin Context: Global Label: "Command's arguments"
commands - "Shows all the available commands with extended information." Category: General AccesMode: Admin Context: Global Label: "Available commands"
get_oauth2_url - "get_oauth2_code - Get OAUth2 URL" Category: Frontend AccesMode: Admin Context: Global Label: "get_oauth2_url"
has_online_user - "Returns 1 if user is online" Category: Users AccesMode: Admin Context: Global Label: "Has online user"
help - "Shows help message" Category: General AccesMode: Admin Context: Global Label: "Help"
online_users - "Returns list of all online users" Category: Users AccesMode: Admin Context: Global Label: "Online users"
register - "Registers the new user" Category: Users AccesMode: User Context: Global Label: "Register"
reload - "Reloads config file" Category: General AccesMode: Admin Context: Global Label: "Reload Spectrum 2 configuration"
set_oauth2_code - "set_oauth2_code <code> <state> - sets the OAuth2 code and state for this instance" Category: Frontend AccesMode: Admin Context: Global Label: "set_oauth2_code"
unregister - "Unregisters existing user" Category: Users AccesMode: User Context: User Label: "Unregister"
variables - "Shows all the available variables." Category: General AccesMode: Admin Context: Global Label: "Available variables"

每条命令带四个属性：Category（命令域）、AccesMode（Admin/User 可见性）、Context（Global/User 上下文）、Label。这组命令就是配置之外的运行期管理面，逐条用法见本专栏 CLI 命令详解篇。

四、参数总览

传输实例配置共 6 个节。核心 [service] 节参数总表（默认值口径：官方示例配置与官方配置文档）：

其余节速览：[identity] 服务发现身份（3 参数）、[logging] 日志（2 参数）、[database] 数据库（9 参数）、[registration] 注册（5+ 参数）、[backend] 后端行为（2 参数）——均见第五节分类详解。

五、核心参数分类详解

5.1 [service] 运行形态与连接三要素

gateway-mode 与 server-mode 由 server_mode 一个开关切换，两种形态下 server/port 的含义完全不同：

💡 技术拓展：Spectrum 2 的两种形态对应两类接入诉求——gateway-mode 把传输域挂到既有 ejabberd/Prosody/Openfire 下，用户管理、账号体系都留在原 XMPP 服务器；server-mode 让 Spectrum 2 直接对外提供 5222 服务，适合没有现成 XMPP 服务器的独立组网。本文实测采用 gateway-mode（官方示例与官方部署文档的主线形态）。

官方示例（sample2_gateway.cfg）的连接段：

[service]
jid = icq.domain.tld
password = secret
server = 127.0.0.1
port = 5347

三要素与 XMPP 服务器侧登记一一对应：jid ↔ Component "irc.example.com"、password ↔ component_secret、port ↔ 组件监听端口。任一不符，组件握手无法完成（部署篇 Q4 的排障即此）。

5.2 [service] 后端进程参数

Spectrum 2 的 backend 是独立进程，主进程按需分裂（fork）后端并把用户会话分摊到其上：

backend_host = 127.0.0.1
#backend_port=10001
users_per_backend=10
backend=/usr/libexec/spectrum2_libcommuni_backend
protocol=prpl-jabber
working_dir=./
pidfile=./test.pid
portfile=./$jid.port

逐项说明：

• backend：后端可执行文件完整路径。换后端即换网络：IRC 用 spectrum2_libcommuni_backend，libpurple 系用 spectrum2_libpurple_backend，XMPP↔XMPP 用 spectrum2_swiften_backend。注意 2.2.0 起官方包的后端路径从 /usr/bin 迁到 /usr/libexec（升级部署需同步改配置）。
• users_per_backend：单后端进程承载的用户数，超过即分裂新后端进程。官方文档默认 100；示例取 10 便于观察多进程行为。取值权衡：值大→进程少、内存省但故障域大；值小→故障隔离好但进程开销多。
• backend_host/backend_port：主进程与后端进程间内部协议的监听地址/端口。backend_port 默认随机分配，注释状态即可。
• protocol：仅 libpurple 后端需要，指定 libpurple 协议 id（prpl-jabber/prpl-icq/prpl-skypeweb/prpl-facebook 等）；特殊值 any 允许用户在 JID 前缀自选协议（格式 prpl-jabber.<user>@<domain>）。
• pidfile/portfile：主进程把 PID 与控制端口写盘，spectrum2_manager 依靠它们找到实例——路径含 $jid 变量时按实例 JID 展开，多实例并存互不覆盖。
• working_dir：进程工作目录，影响示例中 ./test.pid 这类相对路径的实际落点。

5.3 [service] 降权与管理员

#user=spectrum
#group=spectrum
#admin_jid=admin@localhost
admin_password=test

• user/group：进程降权运行身份。官方示例与官方部署形态推荐 www-data；注释状态则以启动身份（通常 root）运行，生产应显式降权。
• admin_jid/admin_password：实例管理面的管理员账号。⚠️ 2.2.0 起管理服务拒绝空密码与历史默认密码 test——生产配置必须落强口令（官方发布说明口径）。

5.4 [service] 文件中转与 IRC 杂项

web_directory=/var/lib/spectrum2/media
web_url=http://localhost/media
irc_server=irc.freenode.org
#enable_remove_buddy=true

• web_directory/web_url：文件传输不走 XMPP 文件代理，而是把文件落到 web_directory 并把 web_url 前缀的链接发给对端；两键成对出现，目录需运行账号可写。
• irc_server：IRC 后端未指定服务器时的默认 IRC 网络（官方示例值如上；接其他网络直接改值）。
• enable_remove_buddy：开启后 XMPP 侧退订会同步删除 legacy 网络好友，默认关闭（保守策略）。

5.5 [identity] 服务发现身份

[identity]
name=Spectrum Jabber Transport
type=xmpp
#category=gateway

这三项决定 XMPP 客户端服务发现（disco）时看到的传输身份：name 是展示名（客户端传输列表里的名字）；type 是网关类型标识（官方注释示例 msn/icq/xmpp，注册表见 XMPP Registrar 的 gateway 类别）；category 默认 gateway。

5.6 [logging] 日志参数与 log4cxx 配置

[logging]
config = /etc/spectrum2/logging.cfg
backend_config = /etc/spectrum2/backend-logging.cfg

• config：主进程日志配置（log4cxx/log4j INI 语法）。
• backend_config：后端进程日志配置；不设则后端日志并入主进程输出。

默认 logging.cfg 全文（官方源码树）：

log4j.rootLogger=debug, R

log4j.appender.R=org.apache.log4j.RollingFileAppender
log4j.appender.R.File=/var/log/spectrum2/${jid}/spectrum2.log

log4j.appender.R.MaxFileSize=10000KB
# Keep one backup file
log4j.appender.R.MaxBackupIndex=1

log4j.appender.R.layout=org.apache.log4j.PatternLayout
log4j.appender.R.layout.ConversionPattern=%d %-5p %c: %m%n

逐项说明：rootLogger=debug, R——默认级别 debug（生产建议改 info 降噪）；File=/var/log/spectrum2/${jid}/spectrum2.log——${jid} 由主进程按实例 JID 展开，多实例日志按域分目录；MaxFileSize=10000KB/MaxBackupIndex=1——10MB 滚动、保留 1 个备份；ConversionPattern——日期、级别、组件、消息四段格式。

后端日志 backend-logging.cfg 与之同构，差异两点：文件名带后端实例号 ${id}（backends/backend-${id}.log），格式串多一个 ${pid} 前缀（ConversionPattern=${pid}: %d %-5p %c: %m%n），便于区分同一后端类型的多个进程。

5.7 [database] 数据库参数

[database]
type = sqlite3
database = users.sqlite
#type = mysql
#database = test
#server = localhost
#port = 0
#user = spectrum
#password = secret
#prefix = jabber_
#encryption_key = hanzzik
#connectionstring = host=localhost user=specturm password=secret

逐项说明：

• type：sqlite3 / mysql / pqxx（PostgreSQL）/ none（不落库，用户注册关系不持久）。官方示例注释里也保留了 or "none" without database backend 的提示。
• database：SQLite 时是数据库文件（不设则默认 /var/lib/spectrum2/$jid/database.sql，实测部署后 data/irc.localhost/database.sql 按此落盘）；MySQL/PostgreSQL 时是库名。
• server/port/user/password：仅 MySQL/PostgreSQL 使用（port=0 表示协议默认端口）。
• prefix：多实例共用一个库时的表名前缀，避免冲突。
• encryption_key：本地加密键（用于注册信息的本地加密存储）。
• connectionstring：仅 pqxx 生效的完整连接串；一旦设置，除 type/prefix 外的其他数据库参数都被忽略（官方注释明确此规则）。

💡 技术拓展：四种存储后端的取舍——

类型	原理/特点	适用场景
sqlite3	单文件嵌入式，零运维	单实例、中小规模（官方默认）
mysql	独立数据库服务，多实例可共库	已有 MySQL、多实例统一管理
pqxx	PostgreSQL 连接串接入	已有 PostgreSQL 环境
none	不持久化注册关系	临时验证、无注册需求的纯转发

本文实测与官方示例主线采用 sqlite3：单文件即备份单位，/var/lib/spectrum2/ 整目录拷走即可迁移。

5.8 [registration] 注册参数

[registration]
enable_public_registration=1
#username_label=Jabber JID (e.g. user@server.tld):
#instructions=Enter your remote jabber JID and password as well as your local username and password
#require_local_account=1
#local_username_label=Local username (without @server.tld):
#local_account_server=localhost
#local_account_server_timeout=10000

• enable_public_registration：1 允许任意 XMPP 用户向传输域注册 legacy 账号；0 关闭公开注册（仅管理员经管理面开户）。
• username_label/instructions：注册表单的字段标签与说明文字（客户端表单展示）。
• require_local_account 组：开启后注册者必须在上游 local_account_server 拥有本地账号才放行（官方注释给出的场景是「向其他服务器的用户开放注册、但要求已有本地账号」），local_account_server_timeout 为校验超时毫秒数。

5.9 [backend] 后端行为参数

[backend]
#default_avatar=catmelonhead.jpg
#no_vcard_fetch=true

• default_avatar：后端向 legacy 网络展示的默认头像图片文件。
• no_vcard_fetch：true 时不抓取 legacy 网络的 vCard 头像资料，可显著降低低质量网络下的请求量。

5.10 spectrum_manager.cfg 管理服务参数

[service]
config_directory=/etc/spectrum2/transports/
admin_username=admin
admin_password=
#bind=localhost
port=8080
base_location=/

[database]
type=sqlite3
database=/var/lib/spectrum2_manager/database.sql

[servers]
server=localhost

逐项说明：

• config_directory：管理服务扫描的实例配置目录，spectrum2_manager start/stop/status 的实例清单即来源于此。
• admin_username/admin_password：Web 管理界面登录账号。⚠️ 官方注释明确：空密码与历史默认密码 test 会被拒绝（2.2.0 起策略）。
• bind/port/base_location：Web 界面监听地址（默认仅 localhost）、端口（默认 8080）与 URL 前缀（设 /spectrum/ 则从该路径访问）。
• [database]：管理服务自身的 SQLite（记录受管实例与统计），默认落 /var/lib/spectrum2_manager/database.sql。
• [servers]：受管主机列表，单机写 server=localhost；多行 server= 可纳管多台主机。

六、生产配置模板

适用场景：自有 XMPP 域（Prosody/ejabberd）接入 IRC；16GB 内存、NVMe SSD；数百至千级 XMPP 用户；gateway-mode、SQLite 存储。骨架取自官方示例值，生产关注点已逐项标注：

[service]
jid = irc.example.com
password = <与 XMPP 服务器 component_secret 一致的强密钥>
server = 127.0.0.1
port = 5347
server_mode = 0
backend_host = 127.0.0.1
users_per_backend = 100
backend = /usr/libexec/spectrum2_libcommuni_backend
working_dir = /var/lib/spectrum2/irc.example.com
user = www-data
group = www-data
admin_password = <强口令，禁用 test 与空值>
web_directory = /var/lib/spectrum2/media
web_url = https://irc.example.com/media
irc_server = irc.example.org

[identity]
name = IRC Transport
type = irc
category = gateway

[logging]
config = /etc/spectrum2/logging.cfg
backend_config = /etc/spectrum2/backend-logging.cfg

[database]
type = sqlite3

[registration]
enable_public_registration = 1

生产要点：

• users_per_backend=100（官方默认）：IRC 后端单进程开销低，100 用户/进程在 16GB 内存下支撑千级用户仅需十余个后端进程；若换 libpurple 后端（单进程内存更高），建议降至 25–50。
• working_dir 落到实例专属数据目录，pidfile/portfile 等相对路径随之收敛，多实例不互踩。
• 日志级别按 5.6 把 logging.cfg 的 rootLogger 改为 info，避免 debug 级别写爆磁盘。
• 用户规模再上一个量级或多实例共库时，把 [database] 切到 mysql/pqxx 并配 prefix（见 5.7）。
• 三要素（jid/password/port）必须与 XMPP 服务器侧登记严格一致，这是部署篇端到端验证的第一检查点。

七、常见问题（FAQ）

Q1：reload 后参数没生效？ reload 对运行期参数即时生效（实测回显 Config reloaded），但连接三要素（jid/password/port）、backend 路径等启动期参数需要重启实例（systemctl restart spectrum2 或 spectrum2_manager restart）。分不清归属时，改完重启一次最稳妥。

Q2：注册的账号数据存在哪？怎么迁移？ SQLite 默认 /var/lib/spectrum2/<jid>/database.sql（实测部署后该文件即出现）；迁移就是停实例后拷走整个 /var/lib/spectrum2/ 目录。切换到 MySQL/PostgreSQL 时先建库再改 [database] 节，注册关系需要重新导入。

Q3：backend_port 需要配置吗？端口冲突怎么办？ 默认随机分配、无需配置（官方注释原话 "By default Spectrum chooses random backend port"）；仅在后端回连需要穿透边界设备时才固定端口，固定后注意避开宿主机其他服务。

Q4：日志文件在写满磁盘？ 默认 rootLogger=debug + 10MB×2 滚动（5.6），多实例多后端并发时 debug 量可观：降级为 info，并确认 /var/log/spectrum2/ 所在分区余量。

Q5：server-mode 和 gateway-mode 怎么选？ 已有 XMPP 服务器选 gateway-mode（本文主线，组件挂接零侵入）；没有 XMPP 服务器、想让 Spectrum 2 直接对用户提供 5222 服务选 server-mode（注意配 cert 启用 TLS）。两者参数差异见 5.1 对照表。

八、参考链接

1. 官方文档：Configuration file description（查询日期 2026-10-27）
2. 官方源码示例配置 sample2_gateway.cfg（SpectrumIM/spectrum2，2.2.1 源码树）（查询日期 2026-10-27）
3. 官方源码示例配置 sample2.cfg（server-mode 全量注释示例）（查询日期 2026-10-27）
4. 《Spectrum 2.2.1 介绍与选型指南》（本专栏认知与选型篇）
5. 《Ubuntu 22.04 安装 Spectrum 2.2.1 指南》（本专栏安装篇）
6. 《Spectrum 2 Docker Compose 部署指南》（本专栏部署篇）