InspIRCd 4.12.1 配置参数详解
InspIRCd 4.12.1 配置篇：inspircd.conf 的标签语法与 REHASH 生效机制（含三类实测异常行为），server/bind/connect/oper/sslprofile/link/keyword 等全部核心配置块逐项拆解，附双机互联与 TLS 实测回显及生产配置模板。
InspIRCd 4.12.1 配置参数详解
目标：讲清 InspIRCd 4.12.1 主配置文件
/etc/inspircd/inspircd.conf的组织方式与全部核心配置块的参数含义，覆盖操作员体系、TLS 加密、双机互联、消息过滤、服务对接六大进阶场景，并沉淀 REHASH 生效机制与典型配置故障的实测处置。全文配置与回显均在双机 Debian 12 实测环境取得，可直接照做。
一、环境信息
本文使用的实测环境为一台 IRC 服务器（源码编译路线，承担全部配置演示）、一台第二服务器（deb 包路线，仅用于双机互联验证）与一台客户端机器：
| 角色 | 主机名 | IP 地址 | 系统 | 软件版本 | 说明 |
|---|---|---|---|---|---|
| IRC 服务器 1 | irc1.example.com | 192.168.1.10 | Debian GNU/Linux 12 (bookworm) | InspIRCd-4.12.1（源码编译） | 本文配置演示主力，SID 1AB |
| IRC 服务器 2 | irc2.example.com | 192.168.1.11 | Debian GNU/Linux 12 (bookworm) | InspIRCd-4.12.1-deb1（官方 deb 包） | 双机互联对端，SID 2CD |
| IRC 客户端 | client1.example.net | 192.168.1.100 | Debian GNU/Linux 12 (bookworm) | irssi 1.4.3 | 连接验证与 OPER 命令测试 |
服务器 1 的版本与配置目录实测回显：
$ inspircd --version
InspIRCd-4.12.1
$ ls /etc/inspircd/
cert.pem help.txt inspircd.conf key.pem motd.txt
服务器 2 的版本实测回显：
$ inspircd --version
InspIRCd-4.12.1-deb1
本文行文约定：服务器 1 上的操作直接给出命令与回显；两台服务器的差异处会明确标注路线（源码编译 / deb 包）。两台服务器均属同一内网 192.168.1.0/24，组成 IRC 网络 ExampleNet。
二、前置条件
- 两台服务器已按 《Debian 12 安装 InspIRCd 4.12.1 指南》完成安装并处于运行状态（
inspircd --version能返回版本号）； /etc/inspircd/inspircd.conf已存在最小可连配置（服务器身份 + 管理员 + 监听 + 连接类 + 日志五块，全文如下，与安装指南中的最小配置一致）：
<server name="irc1.example.com" description="InspIRCd 4.12.1 Demo Server" network="ExampleNet" id="1AB">
<admin name="Server Admin" nick="admin" email="admin@example.com">
<bind address="" port="6667" type="clients">
<connect allow="*" name="default" pingfreq="120" timeout="60" localmax="10" globalmax="10" commandrate="1000" fakelag="on">
<log method="file" level="normal" type="* -USERINPUT -USEROUTPUT" target="inspircd.log">
- 知道本机 InspIRCd 进程的运行用户：源码编译路线为
inspircd（uid 999），deb 包路线为irc（uid 39），后续修改配置文件后需保证属主一致（属主不匹配的真实告警见第七章 Q1）； - 管理脚本可用：源码编译路线为
/usr/share/inspircd/inspircd（支持rehash子命令）；deb 包路线为 systemd 服务（支持systemctl reload inspircd.service）。
三、参数查看与修改方式
3.1 配置文件与语法
InspIRCd 的全部配置集中在单一主文件 /etc/inspircd/inspircd.conf，采用 XML 风格标签语法：每个配置块是一个尖括号标签（如 <bind address="" port="6667" type="clients">），属性以 name="value" 形式书写，值为双引号包裹的字符串。语法要点：
| 语法元素 | 写法 | 说明 |
|---|---|---|
| 配置块 | <bind address="" port="6667" type="clients"> | 一个标签一个块，无需闭合标签，独立成行 |
| 整行注释 | # 这里是注释 | 行首 # 开头 |
| 装饰性分隔注释 | -#-#-#- 标题 -#-#-#- | 官方示例配置惯用排版，无语法作用 |
| 模块加载 | <module name="spanningtree"> | 模块能力的开启方式，模块文件位于 /usr/lib/inspircd/ |
| 同类多块 | 多个 <bind>、多个 <class> 各占一行 | 同名块可以出现多次（如多个监听端口） |
快速统计当前配置里都有哪些块（实测回显）：
$ grep -oE '^<[a-z]+' /etc/inspircd/inspircd.conf | sort | uniq -c
1 <admin
3 <bind
5 <class
1 <connect
1 <dns
1 <files
1 <keyword
1 <link
1 <log
7 <module
1 <oper
1 <server
1 <sslprofile
1 <type
1 <uline
这份统计就是本文最终配置的全貌：15 种块、共 27 个标签行，后文第五章逐类拆解。
官方还提供了完整的示例配置，两条安装路线路径相同（dpkg -L inspircd 或安装产物盘点可证实）：
$ ls /usr/share/doc/inspircd/examples/
codepages
filter.example.conf
help.example.conf
inspircd.example.conf
links.example.conf
modules.example.conf
motd.example.txt
opermotd.example.txt
opers.example.conf
providers
quotes.example.txt
services
sql
💡 说明：
inspircd.example.conf是主配置全量示例（带逐参数注释），opers.example.conf、links.example.conf、modules.example.conf、filter.example.conf分别对应操作员、互联、模块、过滤四个专题。遇到本文未覆盖的属性时优先查这几份文件，注释即文档。
3.2 REHASH：配置生效的唯一途径
InspIRCd 只在启动时读取一次配置文件。修改 inspircd.conf 后必须执行 REHASH（重新加载配置）才能生效，服务不中断。触发方式有三种，均实测验证：
方式一：管理脚本（源码编译路线，实测首选；脚本九个子命令的完整用法见 《InspIRCd 4.12.1 常用 CLI 命令与工具详解》）
/usr/share/inspircd/inspircd rehash
实测回显：
InspIRCd rehashed (pid: 6124).
方式二：系统信号（两路线通用）
kill -HUP $(cat /run/inspircd/inspircd.pid)
deb 包路线在 systemd 真机上推荐用单元自带的 reload（ExecReload=/bin/kill -HUP $MAINPID，与方式二等价）：
systemctl reload inspircd.service
⚠️
systemctl reload inspircd.service需要带 systemd 的真机执行；无 systemd 环境用方式二的kill -HUP（本文在 deb 包服务器上以 kill -HUP 实测生效，日志见下方验证）。
方式三：OPER 命令（远程触发，需操作员权限）
已登录的操作员在 IRC 客户端内直接执行 /REHASH（权限要求与实测回显见 5.6 节）：
:irc1.example.com 382 rehashtest inspircd.conf :Rehashing irc1.example.com
:irc1.example.com NOTICE rehashtest :*** Successfully rehashed server.
生效验证：REHASH 是否成功看日志，成功时日志固定出现四行（实测）：
Mon 26 Oct 2026 06:43:30 REHASH: Rehashing due to SIGHUP
Mon 26 Oct 2026 06:43:31 CONFIG: New configuration has been read, applying...
Mon 26 Oct 2026 06:43:31 CONFIG: Switching to new configuration...
Mon 26 Oct 2026 06:43:31 REHASH: *** Successfully rehashed server.
tail -5 /var/log/inspircd/inspircd.log
deb 包路线的 kill -HUP 生效实测（服务器 2 日志，重载时同样的配置检查告警会重新输出）：
Mon 26 Oct 2026 06:52:05 core_dns: WARNING: <dns:server> not defined, attempting to find working server in /etc/resolv.conf...
Mon 26 Oct 2026 06:52:05 core_dns: <dns:server> set to '192.168.1.1' as first resolver in /etc/resolv.conf.
Mon 26 Oct 2026 06:52:05 core_info: Unable to read motd for connect class "default" at /etc/inspircd/inspircd.conf:7:2: No such file or directory
3.3 REHASH 的失败与异常行为（实测）
REHASH 并非「执行了就生效」，本文实测出三类必须知道的异常行为：
行为一：文件属主不匹配——告警但生效。配置文件属组与运行用户不一致时，日志出现 CONFIG: Possible configuration error 告警，配置仍会生效（实测与修复见第七章 Q1）。
行为二：属性值非法——静默忽略。给 <bind> 写一个非法端口（port="notaport"）后 REHASH，日志照常显示成功，但该监听不会建立：
$ tail -5 /var/log/inspircd/inspircd.log
Mon 26 Oct 2026 07:01:00 REHASH: Rehashing due to SIGHUP
Mon 26 Oct 2026 07:01:00 CONFIG: New configuration has been read, applying...
Mon 26 Oct 2026 07:01:00 CONFIG: Switching to new configuration...
Mon 26 Oct 2026 07:01:00 REHASH: *** Successfully rehashed server.
Mon 26 Oct 2026 07:01:00 MODE: No default <maxlist> entry was found for the ban mode; defaulting to 100
$ ss -ltn | grep -E '6667|6692|7000'
LISTEN 0 4096 *:7000 *:*
LISTEN 0 4096 *:6692 *:*
LISTEN 0 4096 *:6667 *:*
非法端口对应的监听缺席，其余端口不受影响。REHASH 成功不等于每条配置都生效，改监听类配置必须用 ss -ltn 复核。
行为三：语法错误——静默拒绝，旧配置继续生效。向配置追加一行未闭合的标签（<bind address="" port="7001"，缺少右侧 >）后 REHASH，等待十分钟日志无任何新增记录（日志末尾停留在上一次成功 REHASH 的 07:02:57 行）；修正语法后再 REHASH，日志恢复输出：
$ date
Mon Oct 26 07:12:47 UTC 2026
$ tail -2 /var/log/inspircd/inspircd.log
Mon 26 Oct 2026 07:02:57 REHASH: *** Successfully rehashed server.
Mon 26 Oct 2026 07:02:57 MODE: No default <maxlist> entry was found for the ban mode; defaulting to 100
（修正语法后再次 REHASH）
Mon 26 Oct 2026 07:13:18 REHASH: Rehashing due to SIGHUP
Mon 26 Oct 2026 07:13:18 CONFIG: New configuration has been read, applying...
Mon 26 Oct 2026 07:13:18 CONFIG: Switching to new configuration...
Mon 26 Oct 2026 07:13:18 REHASH: *** Successfully rehashed server.
语法错误期间运行中的服务不受影响（连接、既有监听全部正常），但新配置不会生效且文件日志没有任何失败提示——这是最隐蔽的一类坑，改完配置必须确认日志出现当次时间戳的成功四行。
四、参数总览
InspIRCd 4.12.1 的核心配置块按职能分为六组，总览如下（「依赖模块」列中的模块需以 <module name="spanningtree"> 形式先行加载）：
| 配置块 | 职能 | 关键属性 | 依赖模块 |
|---|---|---|---|
<server> | 服务器身份 | name、description、network、id | 无（核心） |
<admin> | 管理员联系信息 | name、nick、email | 无（核心） |
<bind> | 监听端口 | address、port、type、sslprofile | TLS 口需 ssl_openssl |
<connect> | 连接类（客户端准入策略） | allow、name、pingfreq、timeout、localmax、globalmax、commandrate、fakelag | 无（核心） |
<log> | 日志输出 | method、level、type、target | 无（核心） |
<files> | MOTD 等文本文件挂载 | motd | 无（核心） |
<dns> | DNS 解析器 | server、timeout | 无（核心） |
<class> | 操作员命令权限组 | name、commands、privs、snomasks | 无（核心） |
<type> | 操作员类型（权限组组合） | name、classes、vhost | 无（核心） |
<oper> | 操作员账号 | name、password、hash、host、type | hash 值需 sha2 + password_hash |
<sslprofile> | TLS 配置档 | name、provider、certfile、keyfile | ssl_openssl（或 ssl_gnutls） |
<link> | 服务器互联对端 | name、ipaddr、port、allowmask、sendpass、recvpass、timeout | spanningtree |
<uline> | 服务端信任标记 | server | 无（核心） |
<keyword> | 消息过滤规则 | pattern、reason、action | filter + 任一 regex_* 引擎 |
关键差异：<server>/<bind>/<connect>/<log> 是服务能启动的底线配置；<oper> 体系与 TLS 是生产环境强烈建议项；<link>/<uline>/<keyword> 按需追加。下面逐类详解，每类均给出本文实测的完整配置与验证回显。
五、核心参数分类详解
5.1 服务器身份与管理员（<server> 与 <admin>）
<server> 定义本机在网络中的身份，<admin> 定义 /ADMIN 命令返回的管理员信息。本文实测配置：
<server name="irc1.example.com" description="InspIRCd 4.12.1 Demo Server" network="ExampleNet" id="1AB">
<admin name="Server Admin" nick="admin" email="admin@example.com">
逐项说明：
| 属性 | 实测值 | 说明 |
|---|---|---|
name | irc1.example.com | 本服务器域名，必须能被本机解析（/etc/hosts 或 DNS），互联时对端 <link name> 必须与此值完全一致 |
description | InspIRCd 4.12.1 Demo Server | 服务器描述，WHOIS 与 /MAP 中展示 |
network | ExampleNet | 网络名称，客户端欢迎横幅中展示 |
id | 1AB | 本服务器 SID，固定三个字符且第一个字符必须是数字；双机互联时全局唯一（对端用 2CD） |
<admin> 三属性（name/nick/email）在客户端执行 /ADMIN 时原样返回（实测回显）：
:irc1.example.com 256 admt irc1.example.com :Administrative info
:irc1.example.com 257 admt :Server Admin
:irc1.example.com 259 admt :admin@example.com
<server> 的 name 与 description 在客户端 WHOIS 中的展示（irssi 实测回显，server 行同时给出名称与 description）：
06:46 -!- hostname : admin@client1.example.net
192.168.1.100
06:46 -!- channels : @#test
06:46 -!- server : irc1.example.com [InspIRCd 4.12.1 Demo Server]
06:46 -!- : NetAdmin
06:46 -!- modes : +io
💡 技术拓展：SID（Server ID）是 IRC 服务器互联体系中的节点标识，同一网络内必须唯一且首字符为数字。单机部署时 SID 只在本机日志与协议里出现，随便取一个合法值即可；规划多机网络时建议按「首位数字区分机房/线路、后两位区分主机」的方式预先分配（如 1AB、1AC、2AB），避免后续冲突。本文实测网络即按此约定取
1AB与2CD。
5.2 监听 <bind>
<bind> 定义监听端口，type 决定端口用途。本文实测配置共三个监听：
<bind address="" port="6667" type="clients">
<bind address="" port="6692" type="clients" sslprofile="clients">
<bind address="" port="7000" type="servers">
逐项说明：
| 属性 | 实测值 | 说明 |
|---|---|---|
address | ""（空串） | 监听地址，空串表示监听全部网卡；也可写具体 IP 只监听内网 |
port | 6667 / 6692 / 7000 | 监听端口，支持逗号分隔多值（如 6660,6667） |
type | clients / servers | clients 为客户端接入口，servers 为服务器互联口（互联口只有加载 spanningtree 模块后才有意义） |
sslprofile | clients | 引用 5.7 节定义的 <sslprofile> 名称，配置后该端口要求客户端先完成 TLS 握手再走 IRC 协议 |
三个监听的实测结果：
$ ss -ltn | grep -E '6667|6692|7000'
LISTEN 0 4096 *:7000 *:*
LISTEN 0 4096 *:6692 *:*
LISTEN 0 4096 *:6667 *:*
端口规划建议：6667（明文客户端口）与 6692（TLS 客户端口，惯例端口之一）对外，7000（服务器互联口）只对互联对端网段开放防火墙。
5.3 连接类 <connect>
<connect> 定义「连接类」，是客户端准入策略的最小单位：来源匹配同一类的连接共享一套频率与并发限制。本文实测配置：
<connect allow="*" name="default" pingfreq="120" timeout="60" localmax="10" globalmax="10" commandrate="1000" fakelag="on">
逐项说明：
| 属性 | 实测值 | 说明 |
|---|---|---|
allow | * | 允许接入的来源网段，支持 CIDR（如 192.168.1.0/24）；可配多个 <connect> 用不同 allow 划分内外网连接类 |
name | default | 连接类名称，日志与统计中引用 |
pingfreq | 120 | 空闲 ping 间隔（秒），用于检测死连接 |
timeout | 60 | 注册超时（秒）：客户端必须在时限内完成 NICK/USER 握手，否则断开 |
localmax | 10 | 同一 IP 在本机的最大并发连接数 |
globalmax | 10 | 同一 IP 在全网（互联时）的最大并发连接数 |
commandrate | 1000 | 每秒命令速率上限 |
fakelag | on | 超速时延迟处理而非立即断开；off 则超速直接断连（对机器人更严格） |
连接类的实际效果在接入日志中可见（客户端连接时的实测日志行）：
Mon 26 Oct 2026 06:32:21 CONNECT: Client connecting on port 6667 (class default): admin!admin@client1.example.net (192.168.1.100) [admin]
括号中的 class default 即命中的连接类。
💡 说明：本文为演示取
localmax="10"；公开服务器建议按预期人群收紧或放宽，并可通过增加按网段划分的多个<connect>块为不同来源（办公网、家庭宽带、VPN 出口）配置差异化限额。
5.4 日志 <log> 与 DNS 解析 <dns>
日志：<log> 定义日志输出通道，本文实测配置：
<log method="file" level="normal" type="* -USERINPUT -USEROUTPUT" target="inspircd.log">
| 属性 | 实测值 | 说明 |
|---|---|---|
method | file | 输出方式：file 写文件；另有 stderr/stdout 适合前台调试 |
level | normal | 日志级别，normal 覆盖常规运维信息 |
type | * -USERINPUT -USEROUTPUT | 记录类别：* 全部，-USERINPUT -USEROUTPUT 表示排除用户消息原文（聊天内容不入日志，兼顾隐私） |
target | inspircd.log | 文件名，相对路径落在 /var/log/inspircd/ 下 |
日志文件与典型内容（实测首尾节选）：
$ tail -1 /var/log/inspircd/inspircd.log
Mon 26 Oct 2026 07:13:18 REHASH: *** Successfully rehashed server.
$ grep STARTUP /var/log/inspircd/inspircd.log
Mon 26 Oct 2026 06:29:48 STARTUP: Startup complete as 'irc1.example.com'[1AB], 524288 max open sockets
DNS：<dns> 配置 InspIRCd 自身使用的解析器（用于主机名反查与互联对端域名解析）。本文实测配置：
<dns server="192.168.1.1" timeout="5s">
| 属性 | 实测值 | 说明 |
|---|---|---|
server | 192.168.1.1 | DNS 服务器 IP（必须是 IP，不能是域名）；不配置时 InspIRCd 自动读取 /etc/resolv.conf 的第一个 resolver 并打 WARNING |
timeout | 5s | 解析超时 |
不配置 <dns> 时的启动告警（实测，两台服务器均出现）：
Mon 26 Oct 2026 06:21:24 core_dns: WARNING: <dns:server> not defined, attempting to find working server in /etc/resolv.conf...
Mon 26 Oct 2026 06:21:24 core_dns: <dns:server> set to '192.168.1.1' as first resolver in /etc/resolv.conf.
显式配置后该 WARNING 消失。自动探测的结果通常就是 /etc/resolv.conf 里的第一个 nameserver，但显式声明可以固定预期、消除告警。
5.5 MOTD 文件 <files>
MOTD（Message of the Day）是用户接入后自动展示、/MOTD 命令可随时查看的公告文本，通过 <files> 块挂载。本文实测两步：
第一步，创建 MOTD 文件并赋权（属主与运行用户一致，否则出现 Q1 的属主告警）：
cat > /etc/inspircd/motd.txt <<'EOF'
Welcome to the ExampleNet IRC Network!
This server runs InspIRCd 4.12.1 for demonstration.
Enjoy your stay.
EOF
chown inspircd:inspircd /etc/inspircd/motd.txt
第二步，在 inspircd.conf 中挂载并 REHASH：
<files motd="motd.txt">
| 属性 | 实测值 | 说明 |
|---|---|---|
motd | motd.txt | MOTD 文件路径，相对路径基于 /etc/inspircd/；<files> 块还可挂载其他命名文件供模块引用 |
配置生效后客户端接入即展示 MOTD（irssi 实测回显）：
06:43 -!- irc1.example.com message of the day:
06:43 -!- Welcome to the ExampleNet IRC Network!
06:43 -!- This server runs InspIRCd 4.12.1 for demonstration.
06:43 -!- Enjoy your stay.
06:43 -!-
06:43 -!- End of message of the day.
未配置 MOTD 时的启动告警（实测，配置 <files motd> 后消失）：
Mon 26 Oct 2026 06:29:48 core_info: Unable to read motd for connect class "default" at /etc/inspircd/inspircd.conf:7:2: No such file or directory
⚠️ 这条告警的
inspircd.conf:7:2指向<connect>块所在行——MOTD 按「连接类」查找文件，默认类找不到motd.txt时报在 connect 行位置，容易误以为是 connect 块写错了；按本节两步补上<files motd>即可消除。
5.6 操作员体系（<class>、<type>、<oper>）
操作员（oper）是 IRC 服务器的管理角色，采用三层模型：<class> 定义单条命令权限组，<type> 把若干 class 组合成权限档位，<oper> 定义具体账号并挂到某个 type 上。
第一层：<class> 命令权限组（本文实测配置，五个组）：
<class name="SACommands" commands="SAJOIN SAPART SANICK SAQUIT SATOPIC SAKICK SAMODE OJOIN REHASH">
<class name="ServerLink" commands="CONNECT SQUIT RCONNECT RSQUIT MKPASSWD ALLTIME SWHOIS" usermodes="*" chanmodes="*" privs="servers/auspex" snomasks="Cc">
<class name="BanControl" commands="KILL GLINE KLINE ZLINE QLINE ELINE TLINE RLINE CHECK NICKLOCK NICKUNLOCK SHUN CBAN" usermodes="*" chanmodes="*" snomasks="Xx">
<class name="OperChat" commands="WALLOPS GLOBOPS" usermodes="*" chanmodes="*" privs="users/mass-message" snomasks="Gg">
<class name="HostCloak" commands="SETHOST SETIDENT SETIDLE CHGNAME CHGHOST CHGIDENT" usermodes="*" chanmodes="*" privs="users/auspex">
| 属性 | 说明 |
|---|---|
commands | 该组授权的 IRC 命令清单，空格分隔 |
privs | 授权的特权（priv）项，如 servers/auspex（查看服务器敏感统计）、users/auspex（查看用户敏感信息） |
snomasks | 授权的服务器通知掩码（ oper 登录后可订阅的实时事件流） |
usermodes / chanmodes | 可设置的用户/频道模式通配 |
⚠️ 命令授权必须在 class 的
commands里显式列出：本文实测把REHASH追加进 SACommands 前，oper 执行/REHASH直接被拒（对比回显见下文）。
第二层：<type> 权限档位（本文实测配置）：
<type name="NetAdmin" classes="SACommands OperChat BanControl HostCloak ServerLink" vhost="netadmin.irc1.example.com">
| 属性 | 实测值 | 说明 |
|---|---|---|
name | NetAdmin | 档位名称，<oper> 的 type 属性引用它 |
classes | 五个组全部 | 组合的 class 清单；最小授权原则下可只给需要的组 |
vhost | netadmin.irc1.example.com | oper 登录后自动获得的显示主机名 |
官方示例（opers.example.conf）还提供 maxchans（oper 可加入频道数上限）等可选属性，按需追加。
第三层：<oper> 账号（本文实测配置，口令使用 sha256 哈希）：
<module name="sha2">
<module name="password_hash">
<oper name="admin" password="13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9" hash="sha256" host="*@*" type="NetAdmin">
| 属性 | 实测值 | 说明 |
|---|---|---|
name | admin | oper 登录名（/OPER admin <password> 的第一个参数），区分大小写 |
password | 13a5c2…f2f9 | 口令哈希；明文写法省略 hash 属性即可（不推荐） |
hash | sha256 | 口令哈希算法；必须同时加载 sha2 与 password_hash 两个模块（缺一即登录失败，受控实测见下） |
host | @ | 允许使用该账号的来源掩码（用户名@主机 格式，空格分隔多个，支持 CIDR）；*@* 不限来源，生产建议收敛为具体网段 |
type | NetAdmin | 挂载的档位 |
口令哈希的生成（实测回显，echo -n 去掉换行符后再哈希）：
$ echo -n q1w2e3r4 | sha256sum
13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9 -
服务端也可以用 MKPASSWD 命令直接生成（需 password_hash 模块，oper 登录后执行，实测回显）：
06:49 !irc1.example.com sha256 hashed password for q1w2e3r4 is
13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9
hash="sha256" 的模块依赖（受控实测）：本文在验证过程中做了一组对照实验——只加载 password_hash 或只加载 sha2 时，/OPER 全部失败（客户端 491）；两个模块同时在位后才成功。结论：hash="sha256" 的校验由 sha2 提供算法、password_hash 提供校验入口，两者缺一不可，且必须与 REHASH 间隔数秒（见第七章 Q2 的竞态问题）。
登录验证（irssi 实测，/OPER admin q1w2e3r4）：
06:46 -!- Mode change [+o] for user admin
06:46 -!- You are now a NetAdmin
06:46 -!- netadmin.irc1.example.com is now your displayed host
协议层回显（裸连接实测）：
:irc1.example.com MODE hashtest :+o
:irc1.example.com 381 hashtest :You are now a NetAdmin
:irc1.example.com 396 hashtest netadmin.irc1.example.com :is now your displayed host
口令错误时的失败回显（实测，客户端与服务器日志两侧）：
（客户端）
06:44 -!- Failed to log into the admin oper account (check the server
log for details).
（服务器日志）
Mon 26 Oct 2026 06:44:28 OPER: admin (admin@client1.example.net) [192.168.1.100] failed to log into the admin oper account because they specified the wrong password.
协议层的失败数字回复为 491：
:irc1.example.com 491 hashtest :Failed to log into the admin oper account (check the server log for details).
权限体系的实测验证：oper 登录后并非万能，命令与特权都由 class 决定。两个真实拒绝案例（实测回显）：
（NetAdmin 未授权 FILTER 命令）
06:56 -!- Permission Denied - Oper type NetAdmin does not have access
to command FILTER
（普通用户执行敏感统计命令，拒绝消息直接指出了所需特权）
06:45 -!- Permission Denied - STATS o requires the servers/auspex
priv.
REHASH 命令的授权前后对比（实测）：SACommands 的 commands 中加入 REHASH 之前：
06:59 -!- Permission Denied - Oper type NetAdmin does not have access
to command REHASH
加入并 REHASH 配置后，新建立的 oper 会话执行成功：
:irc1.example.com 381 rehashtest :You are now a NetAdmin
:irc1.example.com 396 rehashtest netadmin.irc1.example.com :is now your displayed host
:irc1.example.com 382 rehashtest inspircd.conf :Rehashing irc1.example.com
:irc1.example.com NOTICE rehashtest :*** Successfully rehashed server.
⚠️ 权限快照问题：oper 的权限在
/OPER登录那一刻快照。已登录的 oper 不会因为 REHASH 追加了命令授权而自动获得——本文实测旧会话两次被拒（06:58、06:59），重新登录（07:00 新会话）才生效。改完权限后，提醒所有 oper 重新/OPER一次。
5.7 TLS 加密监听（<sslprofile> + ssl_openssl 模块）
TLS 监听需要三件事：证书与私钥文件、<sslprofile> 配置档、带 sslprofile 引用的 <bind>。本文以 OpenSSL 模块实现（v4 另有 ssl_gnutls 模块，两者与客户端的兼容性等价，选一即可）。
第一步，生成自签证书（生产环境可替换为 Let's Encrypt 等正规证书，文件路径不变）：
openssl req -x509 -newkey rsa:2048 -sha256 -days 365 -nodes \
-keyout /etc/inspircd/key.pem -out /etc/inspircd/cert.pem \
-subj "/CN=irc1.example.com"
chown inspircd:inspircd /etc/inspircd/key.pem /etc/inspircd/cert.pem
实测产物（私钥权限 600）：
$ ls -la /etc/inspircd/*.pem
-rw-r--r-- 1 inspircd inspircd 1131 Oct 26 06:51 /etc/inspircd/cert.pem
-rw------- 1 inspircd inspircd 1704 Oct 26 06:51 /etc/inspircd/key.pem
第二步，配置模块、配置档与 TLS 监听口（本文实测配置）：
<module name="ssl_openssl">
<module name="sslinfo">
<sslprofile name="clients" provider="openssl" certfile="/etc/inspircd/cert.pem" keyfile="/etc/inspircd/key.pem">
<bind address="" port="6692" type="clients" sslprofile="clients">
| 块/属性 | 实测值 | 说明 |
|---|---|---|
<module name="ssl_openssl"> | — | OpenSSL TLS 实现（源码编译路线需在 configure 阶段启用 ssl_openssl extra，deb 包路线已内置） |
<module name="sslinfo"> | — | 向 WHOIS 等命令暴露 TLS 连接信息（671 回复由它提供） |
sslprofile name | clients | 配置档名，被 <bind sslprofile> 引用 |
provider | openssl | TLS 后端，与所加载的模块对应 |
certfile / keyfile | /etc/inspircd/cert.pem、/etc/inspircd/key.pem | 证书链与私钥路径，私钥须仅运行用户可读 |
REHASH 后的加载日志（实测）：
Mon 26 Oct 2026 06:51:14 REHASH: The m_ssl_openssl.so module was loaded.
Mon 26 Oct 2026 06:51:14 MODULE: New module introduced: m_sslinfo.so (version InspIRCd-4.12.1, properties -V---)
Mon 26 Oct 2026 06:51:14 REHASH: The m_sslinfo.so module was loaded.
Mon 26 Oct 2026 06:51:14 REHASH: *** Successfully rehashed server.
Mon 26 Oct 2026 06:51:14 m_ssl_openssl: clients server context options: 374554624
Mon 26 Oct 2026 06:51:14 m_ssl_openssl: clients client context options: 374554624
第三步，客户端验证。先用 openssl s_client 检查证书（实测）：
$ openssl s_client -connect irc1.example.com:6692 </dev/null 2>/dev/null | grep -E 'subject=|issuer=|Verify return'
subject=CN = irc1.example.com
issuer=CN = irc1.example.com
Verify return code: 18 (self-signed certificate)
Verify return code: 18 是自签证书的预期结果（无法链到公共 CA）；客户端侧通常以「信任该指纹」方式处理。再走完整 IRC over TLS 登录（实测回显，001 欢迎与 671 安全连接标记）：
$ { printf 'NICK tlstest\r\nUSER tl 0 * :TLS Test\r\n'; sleep 3; printf 'WHOIS tlstest\r\n'; sleep 2; printf 'QUIT :bye\r\n'; } | \
timeout 10 openssl s_client -connect irc1.example.com:6692 -quiet 2>/dev/null | grep -E '001|671|ERROR'
:irc1.example.com 001 tlstest :Welcome to the ExampleNet IRC Network tlstest!tl@client1.example.net
:irc1.example.com 671 tlstest tlstest :is using a secure connection
ERROR :Closing link: (tl@client1.example.net) [bye]
671 is using a secure connection 即 TLS 生效的权威标记。服务器版本对应的 OpenSSL 库版本（实测）：
$ openssl version
OpenSSL 3.0.22 25 Aug 2026 (Library: OpenSSL 3.0.22 25 Aug 2026)
💡 说明：REHASH 后日志会出现一条
Can't read CA list from /etc/inspircd/ca.pem提示——未部署 CA 列表时的正常现象，服务器日志原文也明确写了「仅当需要校验客户端证书时才是问题」，可放心忽略；若要启用客户端证书认证，再把 CA 列表放到该路径即可。
5.8 服务器互联（<link> + spanningtree 模块）
两台 InspIRCd 通过 m_spanningtree 模块组成树状网络：用户、频道状态在两机间实时同步，任一台上的用户都能与另一台同频道聊天。互联需要两台服务器各自配置对端 <link> 块，且 sendpass/recvpass 与对端交叉一致。
服务器 1（irc1.example.com）的互联配置：
<module name="spanningtree">
<bind address="" port="7000" type="servers">
<link name="irc2.example.com" ipaddr="192.168.1.11" port="7000" allowmask="192.168.1.0/24" timeout="30s" sendpass="net-link-pass-2026" recvpass="net-link-pass-2026">
服务器 2（irc2.example.com）的互联配置（与上面对端互补，name/ipaddr 指向服务器 1）：
<module name="spanningtree">
<bind address="" port="7000" type="servers">
<link name="irc1.example.com" ipaddr="192.168.1.10" port="7000" allowmask="192.168.1.0/24" timeout="30s" sendpass="net-link-pass-2026" recvpass="net-link-pass-2026">
逐项说明：
| 属性 | 实测值 | 说明 |
|---|---|---|
name | irc2.example.com | 对端的 <server name>，必须与其完全一致 |
ipaddr | 192.168.1.11 | 对端 IP（也可写可解析的域名） |
port | 7000 | 对端上 type="servers" 的监听端口 |
allowmask | 192.168.1.0/24 | 允许对端连入的来源网段，超出即拒绝 |
sendpass / recvpass | net-link-pass-2026 | 本机发往对端的认证口令 / 本机要求对端出示的口令；两机交叉一致（本例双向同口令） |
timeout | 30s | 连接握手超时 |
两台分别 REHASH 后确认 7000 监听建立（两机 ss -ltn 均含 *:7000），然后在任一台的 oper 会话发起连接（CONNECT 命令在 ServerLink class 中授权，实测回显）：
06:52 !irc1.example.com *** CONNECT: Connecting to server:
irc2.example.com (192.168.1.11:7000)
连接建立过程中的昵称防冲突（netburst 同步时两机同昵称的用户会被强制改名，SID 作前缀，实测回显）：
06:52 -!- You're now known as 2CDAAAAAA
互联成功的两个权威验证（oper 会话实测回显）：
$ /LINKS
06:52 -!- irc2.example.com irc1.example.com 1 InspIRCd 4.12.1 Demo
Server 2
06:52 -!- irc1.example.com irc1.example.com 0 InspIRCd 4.12.1 Demo
Server
06:52 -!- * End of /LINKS list.
$ /MAP
06:52 -!- irc1.example.com (1AB InspIRCd-4.12.1) 1 [50.00%]
[Up: 31s]
06:52 -!- +-irc2.example.com (2CD InspIRCd-4.12.1-deb1) 1 [50.00%]
[Up: 16s]
06:52 -!- 2 servers and 2 users, average 1 users per server
06:52 -!- End of /MAP
/LINKS 列出全网服务器及上游关系；/MAP 以树形展示拓扑，括号内为 SID 与版本——1AB InspIRCd-4.12.1（源码路线）与 2CD InspIRCd-4.12.1-deb1（deb 路线）同网共存，验证了两条安装路线的协议互通。
💡 技术拓展：IRC 服务器互联除 spanningtree 树状拓扑外，也有网络选择「单机 + Services」或网状协议（如部分 IRCd 实现的 TS6/netjson），InspIRCd v4 的官方方案即 spanningtree（hub-leaf 树状结构）。树状的取舍是拓扑简单、故障域清晰，代价是 hub 单点——生产多机网络建议 hub 只做路由不做客户端接入，本文两机对等直连为最小演示形态。
5.9 消息过滤（<keyword> + filter 模块）
m_filter 模块按规则拦截频道/私聊消息，规则由 <keyword> 块定义。本文实测配置：
<module name="filter">
<module name="regex_stdlib">
<keyword pattern="gamble-site" reason="Blocked by demo policy" action="block">
逐项说明：
| 属性 | 实测值 | 说明 |
|---|---|---|
pattern | gamble-site | 匹配消息内容的正则表达式（不是通配符），命中的消息按 action 处理 |
reason | Blocked by demo policy | 拦截时反馈给用户的原因文案 |
action | block | 处置动作，官方定义：warn（放行并告警 oper）、block（拦截并告知 oper）、silent（只拦截不告警）、none（仅记录）、kill（断开用户）、gline/zline/shun（按 duration 封禁） |
两个实测出的前置条件：
其一，必须加载一个正则引擎模块。只有 filter 没有引擎时，REHASH 成功但过滤整体禁用（实测日志）：
Mon 26 Oct 2026 06:53:35 FILTER: WARNING: No regex engine loaded - Filter functionality disabled until this is corrected.
可用引擎模块实测有三种：regex_stdlib（C++ 标准库正则）、regex_posix（POSIX 正则）、regex_glob（通配符风格）；依赖 PCRE2/RE2 的 regex_pcre2、regex_re2 为编译期 extra 模块。
其二，pattern 必须是合法正则。通配符写法会被拒绝（实测日志，*gamble-site* 报错）：
Mon 26 Oct 2026 06:54:15 m_filter: Error in regular expression '*gamble-site*': Error in regex '*gamble-site*': Mismatched '(' and ')' in regular expression
Mon 26 Oct 2026 06:54:15 m_filter: Filter '*gamble-site*' could not be added: Error in regex '*gamble-site*': Mismatched '(' and ')' in regular expression
改成纯正则（本例关键词本身即合法正则）后规则注册成功，拦截效果实测——普通用户发送命中消息被服务器拒绝（协议层 404 回复，裸连接实测回显）：
:irc1.example.com 404 plainuser #test :Your message to this channel was blocked: Blocked by demo policy.
频道内其他用户完全看不到被拦截的消息； oper 发送的同内容消息豁免放行（同一频道 oper 回显照常显示），这是 filter 的默认特权设计，测试拦截效果时请用非 oper 连接验证。
5.10 服务对接预留（<uline>）
<uline> 把某台服务器标记为「U-line 信任服务器」，是 Anope/Atheme 等 Services 接入前的必备预留配置：被标记服务器发出的协议指令（如频道注册、账号操作）被本机无条件信任。本文实测配置：
<uline server="services.example.com">
| 属性 | 实测值 | 说明 |
|---|---|---|
server | services.example.com | Services 的 <server name>；本文为后续接入预留，实际部署时改为 Services 真实服务器名 |
生效验证用 STATS U（oper 会话实测回显）：
06:53 -!- U services.example.com
06:53 -!- U End of /STATS report
💡 说明：
<uline>指向的服务器无需真实在线——它只是信任声明，Services 进程按<link>块的地址端口接入时即继承该信任。本文未实际部署 Services，此块仅完成配置级验证。
六、生产配置模板
以下为本文实测服务器最终生效配置整理出的完整 /etc/inspircd/inspircd.conf（15 种块、27 个标签行，与 3.1 节统计一致），适用于：2 核 CPU / 4GB 内存 / NVMe SSD、内网或 ≤100 并发用户、双机（hub+leaf 或对等直连）演示与中小团队生产网络。单机部署时删除 spanningtree 相关的三块（<module name="spanningtree">、<bind type="servers">、<link>）即可，其余原样保留：
<server name="irc1.example.com" description="InspIRCd 4.12.1 Demo Server" network="ExampleNet" id="1AB">
<admin name="Server Admin" nick="admin" email="admin@example.com">
<bind address="" port="6667" type="clients">
<connect allow="*" name="default" pingfreq="120" timeout="60" localmax="10" globalmax="10" commandrate="1000" fakelag="on">
<log method="file" level="normal" type="* -USERINPUT -USEROUTPUT" target="inspircd.log">
<files motd="motd.txt">
<dns server="192.168.1.1" timeout="5s">
<class name="SACommands" commands="SAJOIN SAPART SANICK SAQUIT SATOPIC SAKICK SAMODE OJOIN REHASH">
<class name="ServerLink" commands="CONNECT SQUIT RCONNECT RSQUIT MKPASSWD ALLTIME SWHOIS" usermodes="*" chanmodes="*" privs="servers/auspex" snomasks="Cc">
<class name="BanControl" commands="KILL GLINE KLINE ZLINE QLINE ELINE TLINE RLINE CHECK NICKLOCK NICKUNLOCK SHUN CBAN" usermodes="*" chanmodes="*" snomasks="Xx">
<class name="OperChat" commands="WALLOPS GLOBOPS" usermodes="*" chanmodes="*" privs="users/mass-message" snomasks="Gg">
<class name="HostCloak" commands="SETHOST SETIDENT SETIDLE CHGNAME CHGHOST CHGIDENT" usermodes="*" chanmodes="*" privs="users/auspex">
<type name="NetAdmin" classes="SACommands OperChat BanControl HostCloak ServerLink" vhost="netadmin.irc1.example.com">
<module name="sha2">
<module name="password_hash">
<oper name="admin" password="13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9" hash="sha256" host="*@*" type="NetAdmin">
<module name="ssl_openssl">
<module name="sslinfo">
<sslprofile name="clients" provider="openssl" certfile="/etc/inspircd/cert.pem" keyfile="/etc/inspircd/key.pem">
<bind address="" port="6692" type="clients" sslprofile="clients">
<module name="spanningtree">
<bind address="" port="7000" type="servers">
<link name="irc2.example.com" ipaddr="192.168.1.11" port="7000" allowmask="192.168.1.0/24" timeout="30s" sendpass="net-link-pass-2026" recvpass="net-link-pass-2026">
<module name="filter">
<module name="regex_stdlib">
<keyword pattern="gamble-site" reason="Blocked by demo policy" action="block">
<uline server="services.example.com">
模板加载的 7 个功能模块清单：
| 模块 | 作用 | 单机部署 |
|---|---|---|
| sha2 | SHA-2 哈希算法（oper 口令校验依赖） | 保留 |
| password_hash | oper 口令校验入口、MKPASSWD 命令 | 保留 |
| ssl_openssl | OpenSSL TLS 实现 | 保留 |
| sslinfo | WHOIS 暴露 TLS 信息（671 回复） | 保留 |
| spanningtree | 服务器互联 | 单机删除 |
| filter | 消息过滤框架 | 保留 |
| regex_stdlib | filter 的正则引擎 | 保留 |
上线前必改清单：<server> 的 name/network/id、<oper> 口令哈希（用 MKPASSWD 重新生成）、<link> 的 ipaddr 与 sendpass/recvpass、<sslprofile> 证书路径（换正规证书）、<connect> 的 allow 网段与限额、<dns> 指向本网真实 resolver。改完 REHASH 并按 3.2/3.3 节验证日志与监听。
七、常见问题
Q1：日志报 CONFIG: Possible configuration error: /etc/inspircd/inspircd.conf is owned by group 39 but the server is running as group 999？
文件属组与运行用户的组不一致（39 是 deb 包路线的 irc 用户组，999 是源码路线的 inspircd 组，通常是把文件从另一路线复制过来的场景）。配置能生效但每次 REHASH 都刷告警。修复为与运行用户一致并 REHASH（实测告警消失）：
chown inspircd:inspircd /etc/inspircd/inspircd.conf /etc/inspircd/motd.txt /etc/inspircd/help.txt
/usr/share/inspircd/inspircd rehash
（修复后的成功日志，不再有 CONFIG 告警）
Mon 26 Oct 2026 06:43:31 CONFIG: New configuration has been read, applying...
Mon 26 Oct 2026 06:43:31 CONFIG: Switching to new configuration...
Mon 26 Oct 2026 06:43:31 REHASH: *** Successfully rehashed server.
deb 包路线的对应属主为 irc:irc。
Q2：/OPER 返回 491 Failed to log into the admin oper account？
按序排查三个实测原因：
- 口令确实错误——看服务器日志（完整回显见 5.6 节）：
OPER: admin (admin@client1.example.net) [192.168.1.100] failed to log into the admin oper account because they specified the wrong password.； hash="sha256"但模块不全——必须同时加载sha2与password_hash，本文受控实测只加载其一必失败；- REHASH 与 /OPER 同秒提交的竞态——本文实测同秒操作时口令正确仍报 491（日志记为 wrong password），等待 2 秒后重试即成功。改完 oper 配置后稍候再测是稳妥习惯。
Q3：oper 执行 /REHASH（或其他管理命令）报 Permission Denied - Oper type NetAdmin does not have access to command REHASH？
该命令未在 oper 档位引用的任何 <class> 的 commands 中授权。把命令追加进对应 class（如 SACommands）并 REHASH；注意 5.6 节的权限快照问题——已登录的 oper 需要重新 /OPER 才能拿到新权限（本文实测旧会话连续被拒、新会话成功）。
Q4：改了配置不生效？
三种实测情况：一是忘了 REHASH（见 3.2）；二是 REHASH 因语法错误被静默拒绝——文件日志不会出现当次时间戳的成功四行（见 3.3 行为三），修正语法重来；三是属性值非法被静默忽略（如非法端口，见 3.3 行为二）——REHASH 成功但效果缺席，监听类改动必须 ss -ltn 复核。
Q5：启动或 REHASH 时报 Unable to read motd for connect class "default"？
未配置 <files motd> 或 motd 文件不存在/不可读。按 5.5 节创建文件、赋权、挂载、REHASH 即消除；告警中的 inspircd.conf:7:2 行号指向 <connect> 块，属正常定位（MOTD 按连接类查找），不代表 connect 写错。
Q6：filter 规则不生效？
先看日志有无 No regex engine loaded WARNING（引擎模块缺失，按 5.9 节补 regex_stdlib 等）；再确认 pattern 是合法正则而非通配符（*gamble-site* 写法实测报 Mismatched '(' and ')'）；最后用非 oper 连接测试（oper 消息默认豁免）。
Q7：<link> 连不上？
三处对齐逐一核对（本文配置即两机实测互通的基准）：对端 name 与其 <server name> 完全一致；本端 port 指向对端 type="servers" 的监听端口（ss -ltn 两机都应有 *:7000）；sendpass/recvpass 与对端交叉一致且来源 IP 落在对端 allowmask 网段内。满足后 oper 执行 /CONNECT irc2.example.com 触发，用 /LINKS、/MAP 确认（回显见 5.8 节）。
八、参考链接
- v4 官方配置文档：https://docs.inspircd.org/4/configuration/
- 模块文档索引：https://docs.inspircd.org/4/modules/
- spanningtree 模块：https://docs.inspircd.org/4/modules/spanningtree/
- ssl_openssl 模块：https://docs.inspircd.org/4/modules/ssl_openssl/
- filter 模块：https://docs.inspircd.org/4/modules/filter/
- 官方示例配置（本机）：
/usr/share/doc/inspircd/examples/ - 站内前置：《Debian 12 安装 InspIRCd 4.12.1 指南》
- 站内认知篇：《InspIRCd 4.12.1 介绍与选型指南》
- 站内命令篇：《InspIRCd 4.12.1 常用 CLI 命令与工具详解》