Spectrum 2.2.1 常用 CLI 命令与工具详解
实测详解 spectrum2_manager 全局与实例级命令：list/status/restart 生命周期回显、register/unregister 注册管理、variables 运行指标全表与内存共享口径、online_users 空实例占位行源码定位，附命令速查表与 master 构建差异说明。
Spectrum 2.2.1 常用 CLI 命令与工具详解
目标：详解 Spectrum 2 的管理入口
spectrum2_manager——全局命令、实例级命令与常用选项，全部输出取自 Ubuntu 22.04 实测环境（IRC 传输实例irc.localhost运行中）逐行照抄；master 构建与 2.2.1 稳定口径的差异点如实标注。文末给出命令速查表。
一、环境信息
| 项目 | 内容 |
|---|---|
| 管理工具 | spectrum2_manager（/usr/bin），配置 /etc/spectrum2/spectrum_manager.cfg |
| 版本口径 | 2.2.1 源码树（spectrum_manager/src/）；实测运行环境为官方构建镜像（master 构建，包版本 1:1-83ba41f-1） |
| 实测实例 | irc.localhost（IRC 后端、gateway-mode），状态 Running |
| 其他 CLI 文件 | /usr/bin/spectrum2（主程序）、/usr/libexec/spectrum2_*_backend（后端进程，由主进程 fork，不手动调用） |
| 日志落盘 | /var/log/spectrum2/<jid>/spectrum2.log（主进程）、/var/log/spectrum2/<jid>/backends/backend-<id>.log（后端） |
⚠️ 版本口径说明：master 构建的
spectrum2_manager --help文本比 2.2.1 稳定文档描述的更精简（无独立版本输出、选项较少）。本文以实测回显为准，涉及 2.2.1 源码口径处单独标注。
架构与部署背景见 《Spectrum 2.2.1 介绍与选型指南》 与 《Spectrum 2 Docker Compose 部署指南》；命令涉及配置文件时对照 《Spectrum 2.2.1 配置参数详解》。
二、前置条件
- 已完成 Spectrum 2 安装，
spectrum2_manager在 PATH 中。 spectrum2_manager依赖两个配置要素发现实例：spectrum_manager.cfg的config_directory（扫描实例配置清单）与各实例的portfile（运行期控制端口登记文件）——实例必须处于 Running 状态，实例级命令才能送达。- 全局命令影响本机全部实例；实例级命令需带实例 JID。
三、全局命令
3.1 帮助与版本
spectrum2_manager --help、--version 与无参调用在实测环境返回同一份用法文本（照抄）：
Usage: spectrum [OPTIONS] <COMMAND>
spectrum [OPTIONS] <instance_JID> <other>
Commands:
start - start all local Spectrum2 instances
stop - stop all local Spectrum2 instances
restart - restart all local Spectrum2 instances
status - status of local Spectrum2 instances
<other> - send command to local Spectrum2 instance and print output
Allowed options:
-h [ --help ] Show help output
-c [ --config ] arg (=/etc/spectrum2/spectrum_manager.cfg)
Spectrum manager config file
--command arg Command
要点：帮助文本首行程序名显示为 spectrum（master 构建的原样输出）；--version 没有独立版本行。查版本的可用方法：包管理器查询（dpkg -l spectrum2，实测输出 1:1-83ba41f-1）或 Web 管理界面首页。
3.2 list 与 status：实例清单与状态
$ spectrum2_manager list
irc.localhost
$ spectrum2_manager status
"/etc/spectrum2/transports/irc.cfg": irc.localhost Running
list 列出 config_directory 下发现的实例 JID；status 逐实例给出状态（Running/Stopped）。
3.3 全局 start/stop/restart：批量生命周期操作
按帮助口径，start/stop/restart 作用于「全部本地实例」，等价于对 list 结果逐实例执行实例级同名命令。单实例的细粒度操作见第四节（生产上更常用）。
四、实例级命令
用法：spectrum2_manager <instance_JID> <command> [args...]。实例支持哪些命令可用 spectrum2_manager <jid> commands 自查（实测清单共 12 条：args、commands、get_oauth2_url、has_online_user、help、online_users、register、reload、set_oauth2_code、unregister、variables——详见配置篇 3.4）。
4.1 状态与生命周期
$ spectrum2_manager irc.localhost status
Running (0 users connected using 1 backends)
$ spectrum2_manager irc.localhost stop
Stopping "/etc/spectrum2/transports/irc.cfg": OK
$ spectrum2_manager status
"/etc/spectrum2/transports/irc.cfg": irc.localhost Stopped
$ spectrum2_manager irc.localhost start
$ spectrum2_manager status
"/etc/spectrum2/transports/irc.cfg": irc.localhost Running
实测说明：stop/start 均按「Stopping/Starting "配置文件路径": OK」回显；实测中 start 单独执行出现过无输出且退出码 1、但实例随即被拉起为 Running 的现象（部署形态内有进程监督在兜底）。推荐用一条 restart 完成启停（实测回显）：
$ spectrum2_manager irc.localhost restart
Stopping "/etc/spectrum2/transports/irc.cfg": OK
Starting "/etc/spectrum2/transports/irc.cfg": OK
$ spectrum2_manager irc.localhost status
Running (0 users connected using 2 backends)
（restart 刚完成时后端计数短暂显示 2——新后端已起、旧后端尚未完全释放，属正常过渡，稍后回落 1。）
4.2 在线用户查询
$ spectrum2_manager irc.localhost online_users_count
0
$ spectrum2_manager irc.localhost online_users
hanzz@njs.netlab.cz "3rd-party network username:" "me"
$ spectrum2_manager irc.localhost has_online_user user@localhost
0
online_users_count：在线用户数。has_online_user <jid>：判断指定用户是否在线，实测返回0（不在线）。online_users：在线用户清单。⚠️ 实测空实例返回了一行hanzz@njs.netlab.cz ...——这不是真实用户，而是源码内置的占位输出（2.2.1 源码libtransport/AdminInterface.cpp第 129 行在无在线用户时硬编码返回该演示行），属上游已知行为，判断在线状态以online_users_count/has_online_user为准。
4.3 注册管理：register / unregister
先看参数表（args 输出照抄，字段名/说明/类型三列）：
$ spectrum2_manager irc.localhost args register
username - "Jabber ID" Example: "" Type: "string"
legacy_username - "3rd-party network username" Example: "" Type: "string"
legacy_password - "3rd-party network password" Example: "" Type: "password"
据此注册与注销（实测回显）：
$ spectrum2_manager irc.localhost register user@localhost myuser mypass
User registered
$ spectrum2_manager irc.localhost unregister user@localhost
User 'user@localhost' unregistered.
register 三参数依次为：XMPP 侧 JID、legacy 网络用户名、legacy 网络密码；注册关系即时落入实例数据库（SQLite 默认 /var/lib/spectrum2/<jid>/database.sql）。unregister 移除注册关系，回显带确认文案。
4.4 配置热更新与变量观测
$ spectrum2_manager irc.localhost reload
Config reloaded
reload 重新加载实例配置文件（生效范围与限制见配置篇 Q1）。
variables 一次性输出实例的全部运行指标（实测照抄，Value 为当时值）：
average_memory_per_user - "(memory_used_without_any_user - res_memory)" Value: "0" Read-only: true Category: Memory AccesMode: Admin Context: Global
backends_count - "Number of active backends" Value: "1" Read-only: true Category: Backends AccesMode: Admin Context: Global
crashed_backends - "Returns IDs of crashed backends" Value: "" Read-only: true Category: Backends AccesMode: Admin Context: Global
crashed_backends_count - "Returns number of crashed backends" Value: "0" Read-only: true Category: Backends AccesMode: Admin Context: Global
messages_from_xmpp - "Returns number of messages received from frontend network" Value: "1" Read-only: true Category: Messages AccesMode: Admin Context: Global
messages_to_xmpp - "Returns number of messages sent to Front network" Value: "0" Read-only: true Category: Messages AccesMode: Admin Context: Global
online_users_count - "Number of online users" Value: "0" Read-only: true Category: Users AccesMode: Admin Context: Global
res_memory - "Total RESident memory Spectrum 2 and its backends use in KB" Value: "25916" Read-only: true Category: Memory AccesMode: Admin Context: Global
shr_memory - "Total SHaRed memory spectrum2 backends share together in KB" Value: "22612" Read-only: true Category: Backends AccesMode: Admin Context: Global
status - "Shows instance status" Value: "Running (0 users connected using 1 backends)" Read-only: true Category: General AccesMode: Admin Context: Global
uptime - "Returns ptime in seconds" Value: "945" Read-only: true Category: General AccesMode: Admin Context: Global
used_memory - "(res_memory - shr_memory)" Value: "3304" Read-only: true Category: Memory AccesMode: Admin Context: Global
每个变量五属性：说明、实时 Value、Read-only、Category、AccesMode/Context。实测值解读：实例总驻留内存 25916KB、后端共享内存 22612KB（多后端共享只读段使边际内存开销极低）、独占 3304KB——used_memory = res_memory - shr_memory 即单用户边际内存，扩容估算（users_per_backend 选型）直接引用该口径。
💡 技术拓展：
variables是 Spectrum 2 的监控对接点——全部变量只读、带类别，监控脚本轮询spectrum2_manager <jid> variables抽取res_memory/online_users_count/crashed_backends_count即可构建指标看板，无需另开诊断接口。
4.5 OAuth2 命令（Frontend 类）
commands 清单中的 get_oauth2_url（获取 OAuth2 授权跳转 URL）与 set_oauth2_code <code> <state>（回填授权码）服务于需要 OAuth2 流程的 legacy 前端（如 Twitter 类连接器）。本篇实测实例为 IRC 后端，不涉及该流程，命令以 commands 清单口径收录。
4.6 logs 与日志文件
spectrum2_manager logs irc.localhost 在实测环境无输出、静默返回（master 构建行为；2.2.1 稳定文档描述的日志查看在当前构建未提供独立命令输出）。日志排查直接读文件：
$ tail -50 /var/log/spectrum2/irc.localhost/spectrum2.log # 主进程日志
$ tail -50 /var/log/spectrum2/irc.localhost/backends/backend-1.log # 1 号后端日志
日志文件命名与滚动策略由 [logging] 指向的 log4cxx 配置决定（见配置篇 5.6）。
五、常用选项
实测帮助文本给出的全部选项：
| 选项 | 说明 |
|---|---|
| -h / --help | 显示帮助输出 |
| -c / --config <path> | 指定 manager 配置文件（默认 /etc/spectrum2/spectrum_manager.cfg） |
| --command arg | 以选项形式传命令（spectrum2_manager --command status 等价于位置参数形式） |
多 manager 配置并存（如多套 config_directory）时用 -c 显式指定。
六、命令速查表
| 命令 | 级别 | 作用 |
|---|---|---|
| spectrum2_manager（无参/--help） | 全局 | 用法帮助（--version 同文本，无独立版本行） |
| list | 全局 | 列出发现的实例 JID |
| status | 全局 | 全部实例状态 |
| start / stop / restart | 全局 | 批量启停/重启全部本地实例 |
| <jid> status | 实例 | 实例状态（Running/Stopped + 用户/后端计数） |
| <jid> start / stop / restart | 实例 | 单实例生命周期（推荐 restart） |
| <jid> online_users_count | 实例 | 在线用户数 |
| <jid> online_users | 实例 | 在线用户清单（空时输出源码内置占位行） |
| <jid> has_online_user <jid2> | 实例 | 指定用户是否在线（0/1） |
| <jid> args <cmd> | 实例 | 查看命令参数表（字段/说明/类型） |
| <jid> register <jid2> <u> <p> | 实例 | 注册 legacy 账号绑定 |
| <jid> unregister <jid2> | 实例 | 注销注册绑定 |
| <jid> reload | 实例 | 热重载配置文件 |
| <jid> variables | 实例 | 全部运行指标（内存/消息/在线/崩溃计数） |
| <jid> commands | 实例 | 实例支持的命令清单 |
| <jid> help | 实例 | 帮助 |
| <jid> get_oauth2_url / set_oauth2_code | 实例 | OAuth2 授权流程（Frontend 类后端） |
七、常见问题（FAQ）
Q1：manager 报找不到实例？
两条线索：spectrum_manager.cfg 的 config_directory 是否指向实际配置目录（决定 list 清单）；实例是否 Running 且 portfile 可访问（决定实例级命令能否送达）。配置文件在、进程没起时 list 有、实例级命令不通。
Q2：<jid> start 退出码 1 但实例却起来了？
实测现象：部署形态内存在进程监督兜底，start 命令本身可能与监督逻辑竞争。稳妥做法：用 <jid> restart 一次性完成（回显 Stopping OK + Starting OK），或用服务层重启（systemctl restart spectrum2）。
Q3：实例级命令卡住无输出？
实例 Stopped 或 portfile 失效时命令可能长时间等待。先 status 确认状态再操作；对假死实例直接用服务层重启。
Q4：online_users 输出了 hanzz@njs.netlab.cz，谁在冒充用户？
源码内置占位行（libtransport/AdminInterface.cpp 129 行，无在线用户时的固定返回），非真实用户。在线判断用 online_users_count / has_online_user。
Q5：/usr/bin/spectrum2 与 /usr/libexec/spectrum2_*_backend 要手动运行吗？
不要。spectrum2 主程序由 systemd 服务/部署入口拉起（按 transports/ 配置逐实例启动）；后端进程由主进程按 users_per_backend 自动 fork/回收。手动调用它们只会绕开管理面（portfile/manager 登记失效）。
八、参考链接
- 官方文档：spectrum2_manager 说明（查询日期 2026-10-27）
- 官方源码：spectrum_manager/src/main.cpp（2.2.1 源码树）（查询日期 2026-10-27）
- 官方源码：libtransport/AdminInterface.cpp（实例命令与变量定义）（查询日期 2026-10-27）
- 《Spectrum 2.2.1 介绍与选型指南》（本专栏认知与选型篇）
- 《Ubuntu 22.04 安装 Spectrum 2.2.1 指南》（本专栏安装篇）
- 《Spectrum 2 Docker Compose 部署指南》（本专栏部署篇）
- 《Spectrum 2.2.1 配置参数详解》（本专栏配置篇）