InspIRCd 4.12.1 常用 CLI 命令与工具详解

目标：讲清 InspIRCd 4.12.1 服务器侧的全部命令行工具——管理脚本九个子命令、主程序直接调用与启动失败排障、inspircd-testssl 检测工具，以及操作员（oper）在客户端内使用的核心管理命令（OPER/KILL/GLINE/CONNECT/SQUIT/REHASH 等）。全文命令与回显均在双机 Debian 12 实测环境取得，可直接照做。

一、环境信息

本文使用的实测环境与系列前两篇一致：两台 IRC 服务器（源码编译路线 + 官方 deb 包路线）与一台客户端机器：

服务器 1 的命令行工具盘点（实测回显，源码编译路线）：

$ ls /usr/share/inspircd/
apparmor
deploy-ssl.sh
inspircd
inspircd.openrc
inspircd.service
logrotate

$ which inspircd
/usr/bin/inspircd

服务器 2 的命令行工具盘点（实测回显，deb 包路线）：

$ which inspircd inspircd-testssl
/usr/bin/inspircd
/usr/bin/inspircd-testssl

两条路线的差异：源码编译路线的启停管理脚本在 /usr/share/inspircd/inspircd；deb 包路线以 systemd 服务单元托管（/lib/systemd/system/inspircd.service）并额外附带 inspircd-testssl 检测工具。下文凡涉及 systemd 的命令均需带 systemd 的真机执行。

二、前置条件

1. 两台服务器已按 《Debian 12 安装 InspIRCd 4.12.1 指南》完成安装，配置与 TLS、双机互联背景见 《InspIRCd 4.12.1 配置参数详解》；
2. 一套可用的 oper 账号（本文沿用实测环境：账号 admin、NetAdmin 档位、sha256 口令，/OPER 登录方法见第六章）；
3. 知道运行用户：源码路线 inspircd、deb 路线 irc——管理脚本不做降权，以谁执行就以谁运行（root 直接 restart 的停机陷阱见第七章 Q1）；
4. 客户端可连通服务器的 6667 端口（oper 命令通过 IRC 协议下发，属于「人机接口的 CLI」部分）。

三、命令总览

InspIRCd 4.12.1 的服务器侧命令行工具分四层，总览如下：

前两层解决「服务怎么起怎么停」，第三层解决「起不来怎么查」，第四层解决「跑起来之后怎么管」。以下逐层详解。

四、管理脚本命令详解（源码编译路线）

/usr/share/inspircd/inspircd 是一个 Perl 管理脚本，help 子命令列出全部用法（实测回显）：

$ /usr/share/inspircd/inspircd help
Usage: ./inspircd (stop|version|help|rehash|sslrehash|restart|status|start|cron)
Developer arguments: (valdebug-unattended|valdebug|screendebug|screenvaldebug|debug)

九个子命令逐一说明（除标注外均实测验证，Developer 调试参数本文不展开）：

deb 包路线的等价操作（systemd 托管，真机执行）：

systemctl start inspircd.service
systemctl stop inspircd.service
systemctl restart inspircd.service
systemctl reload inspircd.service   # 等价 rehash（单元 ExecReload=/bin/kill -HUP $MAINPID）
systemctl is-active inspircd.service

4.1 start：启动服务

以运行用户执行（实测回显，完整启动序列）：

su -s /bin/bash inspircd -c "/usr/share/inspircd/inspircd start"

InspIRCd - A high-performance IRCv3 server for UNIX-like and Windows systems.
See /INFO for a list of developers and contributors.

Website:       https://www.inspircd.org
Documentation: https://docs.inspircd.org
Support:       https://docs.inspircd.org/support

InspIRCd is open source and is reliant on your support to stay maintained. Read
https://docs.inspircd.org/contributing to find out how to become a contributor
or https://www.inspircd.org/donate to donate to the project.

[*] Loading module:	m_sha2.so
[*] Loading module:	m_password_hash.so
[*] Loading module:	m_ssl_openssl.so
[*] Loading module:	m_sslinfo.so
[*] Loading module:	m_spanningtree.so
[*] Loading module:	m_filter.so
[*] Loading module:	m_regex_stdlib.so
InspIRCd-4.12.1 [PID 6949] is now running as irc1.example.com [1AB] with 524288 max open sockets

输出依次为：程序横幅 → 逐模块加载行（与配置中 7 个 <module> 块一一对应）→ 运行确认行（版本、PID、服务器名、SID、最大套接字数）。已在运行时再次 start 的回显：

InspIRCd is already running.

⚠️ start/restart 不做用户切换（脚本源码为直接 exec 主程序），root 执行会撞上主程序的 root 拒绝保护（全文回显见第七章 Q1）。安全姿势只有两种：su 到运行用户再执行，或走 systemd 单元（单元内置 User=irc）。

4.2 stop：停止服务

实测回显（restart 序列中的 stop 阶段输出）：

Stopping InspIRCd (pid: 6124)...

停止逻辑：向主进程发 SIGTERM 并等待优雅退出（最多 15 秒），超时输出 InspIRCd not dying quietly -- forcing kill 强杀。双机互联时对端会感知到拆分（日志原文见 6.4 节）。

4.3 restart：停止并启动

restart 内部等价于 stop + 清理 PID 文件 + start。实测暴露的坑：以 root 直接执行 restart，停止成功但重启阶段撞上 root 拒绝保护，服务起不来：

$ /usr/share/inspircd/inspircd restart
Stopping InspIRCd (pid: 6124)...
InspIRCd not dying quietly -- forcing kill
（随后打印 root 拒启横幅与错误，见第七章 Q1）
InspIRCd is not running. (Or PID File not found)

正确做法：分开执行——root 下先 stop，再 su -s /bin/bash inspircd -c "/usr/share/inspircd/inspircd start"；或全流程交给 systemd。

4.4 status：查询运行状态

运行态与停止态的回显及返回码（实测）：

$ /usr/share/inspircd/inspircd status
InspIRCd is running (PID: 7035)

$ /usr/share/inspircd/inspircd status; echo "rc=$?"
InspIRCd is not running. (Or PID File not found)
rc=3

停止态返回码为 3，可直接用于脚本判断（如 status >/dev/null 2>&1 || su -s /bin/bash inspircd -c "/usr/share/inspircd/inspircd start"）。

4.5 rehash / sslrehash / version / cron

rehash 与 version 的实测回显：

$ /usr/share/inspircd/inspircd rehash
InspIRCd rehashed (pid: 7035).

$ /usr/share/inspircd/inspircd version
InspIRCd-4.12.1

• sslrehash：向主进程发 SIGUSR1，只重载 TLS 证书（更换续期证书后免全量 rehash）；
• cron：语义为「未运行则启动、已运行则什么都不做」，配合系统 crontab 做进程保活；
• 配置重载的生效验证与三类异常行为（属性值非法静默忽略、语法错误静默拒绝、属主告警）已在配置篇第三章实测，此处不重复。

五、主程序直接调用与启动失败排障

5.1 主程序参数

/usr/bin/inspircd 支持 --version（两条路线输出不同标签，实测）：

$ inspircd --version
InspIRCd-4.12.1

传入无法识别的参数时的报错（实测）：

$ /usr/bin/inspircd --frobnicate
Error! Unrecognized token: --frobnicate

以 root 直接运行主程序的完整拒绝横幅（实测，root 拒启保护）：

InspIRCd - A high-performance IRCv3 server for UNIX-like and Windows systems.
See /INFO for a list of developers and contributors.

Website:       https://www.inspircd.org
Documentation: https://docs.inspircd.org
Support:       https://docs.inspircd.org/support

InspIRCd is open source and is reliant on your support to stay maintained. Read
https://docs.inspircd.org/contributing to find out how to become a contributor
or https://www.inspircd.org/donate to donate to the project.

Error! You have started as root. Running as root is generally not required
and may allow an attacker to gain access to your system if they find a way to
exploit your IRC server.

If you are sure that you need to run as root then you can pass the --runasroot
option to disable this error.

确有理由以 root 运行时按提示加 --runasroot 可跳过保护（不建议），常规方案始终是运行用户或 systemd。

5.2 启动失败排障：坏配置的权威报错

配置存在语法错误（如标签未闭合）时，start 会失败并给出精确到行号的报错（实测：向配置追加一行未闭合的 <bind address="" port="7001" 后启动）：

Error! There are problems with your configuration file:

Unexpected end-of-file at /etc/inspircd/inspircd.conf:47:1 (inside <bind> tag on line 46)

报错三要素：配置文件路径、出错行列、出错时所在的标签与起始行——inside <bind> tag on line 46 直接指出未闭合标签的位置。排障流程：读报错行 → 修复对应标签 → 重新 start → 确认出现 is now running as 行。同一错误的 REHASH 行为不同（静默拒绝、旧配置继续生效，见配置篇 3.3），启动与重载两条路径都要测。

5.3 PID 文件残留导致的误报

异常停机（如强杀）后 PID 文件残留时，status/start 会误报「已在运行」（实测：停止后 PID 文件仍写着旧进程号 6949，该进程号被残留的僵尸槽位占用，状态检查误判）：

$ /usr/share/inspircd/inspircd start
InspIRCd is already running.

$ /usr/share/inspircd/inspircd status
InspIRCd is running (PID: 6949)

$ ss -ltn | grep 6667
（无输出——实际端口未监听）

处置（实测有效）：确认端口未监听后删除 PID 文件再启动：

rm -f /run/inspircd/inspircd.pid
su -s /bin/bash inspircd -c "/usr/share/inspircd/inspircd start"

判断准则：状态输出与端口监听不一致时，以 ss -ltn 为准。systemd 托管形态（deb 路线真机）由 systemd 跟踪进程，不会出现此类残留。

六、OPER 管理命令实战

以下命令均在 IRC 客户端内执行（前缀 /；本文以 irssi 与裸协议连接实测，回显为服务器原文）。所有命令要求 oper 身份，且命令必须出现在对应 <class> 的 commands 授权里（授权方法与权限快照问题见配置篇 5.6 节）。

6.1 OPER：登录操作员身份

实测回显（/OPER admin q1w2e3r4）：

:irc1.example.com 381 opcmd :You are now a NetAdmin
:irc1.example.com 396 opcmd netadmin.irc1.example.com :is now your displayed host

口令错误时返回数字回复 491（协议原文：:irc1.example.com 491 hashtest :Failed to log into the admin oper account (check the server log for details).），服务器日志同步记录，失败排查三步见配置篇 Q2。

6.2 KILL：强制断开用户

向指定昵称的用户断开连接并附带原因（实测，目标 dummy2）：

/KILL dummy2 :Please reconnect with a registered nickname

服务器日志记录（实测回显）：

Mon 26 Oct 2026 07:47:16 KILL: Local kill by opkill: dummy2!du@client1.example.net (Please reconnect with a registered nickname)

目标用户的连接随即被服务器关闭（退出原因为 KILL 附带的原因文案）。KILL 命令在 BanControl class 中授权。

6.3 GLINE：网络级封禁（语法要点最多的命令）

GLINE 的官方语法为 GLINE <user@host>[,<user@host>]+ [[<duration>] <reason>]，本文把实测出的全部边界行为整理如下：

添加（掩码必须是 user@host 形式，GLINE 10.89.56.99 300 :test 这种只写 IP 的写法实测报 *** Target not found.）：

GLINE *@192.168.1.99 300s :test gline

成功后可用 STATS g 查看（实测回显，列表行的数字回复为 210）：

:irc1.example.com 210 opfinal g *@192.168.1.99 1793000125 0 opcmd3 :test gline
:irc1.example.com 219 opfinal g :End of /STATS report

210 行字段依次为：掩码、设置时间戳（Unix 秒）、时长秒数、设置者、原因。时长为 0 或省略即永久封禁（v4.6.0 起），300 与 300s 两种写法实测等价；时长格式非法时报 *** Invalid duration for G-line.。

删除：只给掩码、不给时长与原因即删除（实测成功回显为 STATS g 中该行消失）：

GLINE *@192.168.1.99

两个实测出的易错点：其一，删除时掩码不存在于列表报 *** G-line -*@192.168.1.99 not found on the list.；其二，减号前缀不是删除语法——GLINE -*@192.168.1.99 会把 -*@192.168.1.99 整体当作掩码（UnrealIRCd 风格的 - 删除写法在 InspIRCd 不适用，实测它报 not found 或在带时长时新增一条以 - 开头的封禁项）；重复添加已有掩码报 ** G-line for *@192.168.1.99 already exists.。UNGLINE 不是有效命令（实测 421 Unknown command）。

验证与生效：被封掩码的客户端连接时被服务器拒绝接入。同族命令 KLINE/ZLINE/QLINE/ELINE/TLINE/RLINE 语法一致（作用范围分别为服务器级 K 线、IP 级 Z 线、昵称 Q 线、例外 E 线等），均由同一套 XLine 机制处理。

6.4 CONNECT / SQUIT / LINKS / MAP：互联管理

CONNECT 发起与对端服务器的互联（命令在 ServerLink class 授权，实测回显）：

*** CONNECT: Connecting to server: irc2.example.com (192.168.1.11:7000)

成功后 /LINKS 列出全网节点、/MAP 以树形展示（实测回显，MAP 的数字回复 015/017/018）：

:irc1.example.com 015 opmap :irc1.example.com (1AB InspIRCd-4.12.1)           2 [66.67%] [Up: 12m57s]
:irc1.example.com 015 opmap :└─irc2.example.com (2CD InspIRCd-4.12.1-deb1)    1 [33.33%] [Up: 5s]
:irc1.example.com 018 opmap :2 servers and 3 users, average 1.5 users per server
:irc1.example.com 017 opmap :End of /MAP

/SQUIT 断开对端（实测，断开后 LINKS 只剩本机）：

SQUIT irc2.example.com :Oper demo squit

对端本就不在线时报（实测回显）：

*** SQUIT: The server irc2.example.com does not exist on the network.

互联断开后的重连排障链（本文实测完整经历，值得照抄）：服务器重启后互联不会自动恢复（默认无 autoconnect 行为），执行 CONNECT 重连时若报——

LINK: Connection to 'irc2.example.com' failed with error: CAPAB negotiation failed. Required modules incorrectly matched on these servers. Not loaded on the remote server: filter.

含义是本机加载了 filter 模块而对端没有，协议能力协商失败。处置：在对端配置补加载同名模块并重载，再执行 CONNECT，LINKS/MAP 恢复两节点。这类「单侧加载模块导致互联失败」只在（重）握手时检查——已建立的连接不受影响，所以平时 REHASH 加模块没事、重启后连不上时要先查两边模块集是否一致。

6.5 REHASH / MKPASSWD / STATS：远程维护三件套

oper 远程触发配置重载（实测回显）：

:irc1.example.com 382 rehashtest inspircd.conf :Rehashing irc1.example.com
:irc1.example.com NOTICE rehashtest :*** Successfully rehashed server.

MKPASSWD 生成 oper 口令哈希（需 password_hash 模块，实测回显）：

06:49 !irc1.example.com sha256 hashed password for q1w2e3r4 is
          13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9

STATS 查询服务器状态（子码区分：STATS g 封禁列表、STATS o oper 账号列表、STATS U 信任服务器列表等），回显以 219 结束。权限不足时给出精确提示（实测，普通用户）：

06:45 -!- Permission Denied - STATS o requires the servers/auspex
          priv.

命令权限未授权时同样精确到命令名（实测，oper 未授权 FILTER 命令）：

06:56 -!- Permission Denied - Oper type NetAdmin does not have access
          to command FILTER

七、常见问题

Q1：以 root 执行 restart 后服务起不来？

管理脚本不做用户切换，restart 的启动阶段以 root 拉起主程序，撞上 root 拒绝保护（完整横幅见 5.1 节）。处置：root 下 stop 确认停止，然后以运行用户 start（su -s /bin/bash inspircd -c "/usr/share/inspircd/inspircd start"，deb 路线为 su -s /bin/bash irc -c "/usr/bin/inspircd" 或直接走 systemd）。日常启停建议全部走 systemd（单元内置 User=），脚本路线只在无 systemd 环境使用。

Q2：GLINE 加了不生效 / 删不掉？

三个实测原因：掩码必须 user@host 形式（只写 IP 报 *** Target not found.）；删除语法是只给掩码（带 - 前缀会被当成掩码本身，实测报 not found 或误加）；删除已存在掩码时若报 already exists 说明刚才那次是添加。列表核对用 STATS g（210 行，字段含义见 6.3 节）。

Q3：重启后 /CONNECT 报 CAPAB negotiation failed. Required modules incorrectly matched on these servers. Not loaded on the remote server: filter. 这类错误？

两机模块集不一致（本文实测为单侧后加载 filter 引起，报错末尾的模块名即缺失方）。在对端配置补加载该模块并重载配置，再 CONNECT。检查项：两机 <module> 块清单必须一致（互联相关的 capability 按模块匹配）。

Q4：status 显示 running 但端口没监听 / start 误报 already running？

PID 文件残留（异常停机后）。以 ss -ltn 为准判断真实状态，rm -f /run/inspircd/inspircd.pid 后重新启动（详见 5.3 节）。

Q5：inspircd-testssl 对 TLS 端口报 server dropped the connection before sending anything？

这是工具对 v4 端口行为的已知局限（本文实测）：脚本先做明文探测，期待服务器先发数据；InspIRCd 4 的 TLS 端口在等 TLS 握手、不会先发任何字节，工具停在明文检测段无法走到 TLS 协商段。TLS 端口的可靠验证方法是 openssl s_client -connect <host>:<port>（完整流程与 671 验证回显见配置篇 5.7 节），testssl 适合验证「明文端口确实明文」这类反向确认。

八、参考链接

• v4 官方命令文档：https://docs.inspircd.org/4/commands/
• v4 常用命令（GLINE 语法出处）：https://docs.inspircd.org/4/commands/#gline-userhostuserhost-duration-reason
• inspircd-testssl 说明：https://docs.inspircd.org/4/installation/debian/
• 站内配置篇（REHASH 与各配置块详解）：《InspIRCd 4.12.1 配置参数详解》
• 站内安装篇：《Debian 12 安装 InspIRCd 4.12.1 指南》
• 站内认知篇：《InspIRCd 4.12.1 介绍与选型指南》