UnrealIRCd 6.2.7 常用 CLI 命令详解

UnrealIRCd 6.2.7 本地 CLI 子命令与 IRC 内 Oper 命令族的完整实测详解。

UnrealIRCdUnrealIRCd网络2026/10/27

UnrealIRCd 6.2.7 常用 CLI 命令与工具详解

目标:系统梳理 UnrealIRCd 6.2.7 的所有运维命令,分为**本地 CLI(unrealircd 子命令)**和 IRC 内 Oper 命令族两大类,每条命令给出实测回显、参数说明与典型用法。真实服务器视角,全部命令已在 Ubuntu 22.04 上实测(2026-10-27)。

一、环境信息

项目实测值
UnrealIRCd 版本6.2.7
安装用户unrealircd(运行身份)
可执行文件路径/home/unrealircd/unrealircd/unrealircd
帮助风格子命令模式(unrealircd <subcommand>),不支持 flag 风格(--help 会报错)
systemd 托管若用 systemd,start/stop/restart 子命令应改用 systemctl

二、工具概览

UnrealIRCd 的运维命令分两大体系:

体系触发方式作用域
本地 CLI 子命令./unrealircd <subcommand>服务器运维(启动/停止/重载/版本/模块/证书/密码)
IRC 内 Oper 命令族IRC 客户端输入 /OPER 升级后执行 /REHASH /KILL /STATS 等在线运维(频道管理、封禁、服务器治理)

完整的本地 CLI 帮助实测输出:

./unrealircd     # 不带任何参数

实测回显:

Unrecognized parameter '--help'. Use:
unrealircd configtest    Test the configuration file
unrealircd start         Start the IRC Server
unrealircd stop          Stop (kill) the IRC Server
unrealircd rehash        Reload the configuration file
unrealircd reloadtls     Reload the SSL/TLS certificates
unrealircd restart       Restart the IRC Server (stop+start)
unrealircd status        Show current status of the IRC Server
unrealircd module-status Show all currently loaded modules
unrealircd upgrade       Upgrade UnrealIRCd to the latest version (or the next available
                         release candidate if the --rc argument is used)
unrealircd mkpasswd      Hash a password
unrealircd mkcert        Create or replace the self-signed TLS certificate
                         (optionally pass a path prefix; normal path rules apply)
unrealircd version       Display the UnrealIRCd version
unrealircd module        Install and uninstall 3rd party modules
unrealircd croncheck     For use in crontab: this checks if the server
                         is running. If not, the server is started.
unrealircd genlinkblock  Generate link { } block for the other side.
unrealircd gencloak      Display 3 random cloak keys
unrealircd spkifp        Display SPKI Fingerprint

⚠️ 注意:不支持 --help / -h / --version flag。这些 flag 会返回 Unrecognized parameter 错误并列出帮助信息——把它当帮助用就行,但 exit code 是非零的。

三、前置条件

  1. 运行身份:所有命令以安装用户(如 unrealircd)身份执行,禁止 root;
  2. 工作目录:大部分命令需要在 ~/unrealircd/ 目录下执行(因为要读写 conf/、logs/、data/ 子目录);
  3. systemd 用户:若已用 systemd 托管,start/stop/restart 子命令被禁用,改用 systemctl {start|stop|restart} unrealircd。但 configtest/rehash/status/module-status 这些仍用 CLI 子命令。

四、本地 CLI 子命令详解(17 条)

4.1 version — 显示版本号

./unrealircd version

实测回显:

UnrealIRCd-6.2.7

用于快速确认版本,upgrade 后跑一次验证。

4.2 configtest — 语法验证(修改配置后必跑)

./unrealircd configtest

实测通过回显:

 _   _                      _ ___________  _____     _ 
| | | |                    | |_   _| ___ \/  __ \   | |
| | | |_ __  _ __ ___  __ _| | | | | |_/ /| /  \/ __| |
| | | | '_ \| '__/ _ \/ _` | | | | |    / | |    / _` |
| |_| | | | | | |  __/ (_| | |_| |_| |\ \ | \__/\ (_| |
 \___/|_| |_|_|  \___|\__,_|_|\___/\_| \_| \____/\__,_|
                           v6.2.7

UnrealIRCd is using the following libraries:
* OpenSSL 3.0.2 15 Mar 2022
* libsodium 1.0.18
* c-ares 1.18.1
* PCRE2 10.39 2021-10-29
* jansson 2.15.0

This server can handle 16384 concurrent sockets (16134 clients + 250 reserve)

[info] Loading IRCd configuration..
[info] Testing IRCd configuration..
[advice] You have at least one IRC plaintext port open to users (such as 6667).
[info] Configuration loaded
[advice] Your config has NO errors, but you received some best practices tips above.
[advice] It is recommended for you to follow best practices
[info] Configuration test passed OK

带错误回显示例(配置里漏了分号):

[info] Loading IRCd configuration..
[error] /home/unrealircd/unrealircd/conf/unrealircd.conf:42: 
        Expected directive, got 'irc.test.local'. Perhaps a missing ';' after the previous line?
[error] Could not load configuration file
返回码含义
0✅ 语法通过(即便有 [advice] 也算通过)
非 0❌ 语法错误(有 [error])

💡 最佳实践:任何时候改 conf/unrealircd.conf,先 configtest 再 rehash/restart。这能帮你在启动前就发现括号不匹配、漏分号等低级错误。

4.3 start — 启动服务器

./unrealircd start

实测回显:

[info] UnrealIRCd is now listening on the following addresses/ports:
[info] IPv4: *:6900(TLS), *:6697(TLS), *:6667
[info] IPv6: *:6900(TLS), *:6697(TLS), *:6667
[info] Unix Sockets: <none>
[info] UnrealIRCd started.

⚠️ systemd 用户:start/stop/restart 改用 systemctl start unrealircd。

4.4 stop — 停止服务器

./unrealircd stop

实测回显:

Killing UnrealIRCd with pid 12356...
UnrealIRCd stopped.

服务器未运行时:

UnrealIRCd is not running (no PID file).

4.5 restart — 重启服务器(stop + start)

./unrealircd restart

内部等价于 stop && start。适用于 cloak-keys 改了、listen block 改了、TLS 证书手动替换等需要完整重启的场景。

4.6 status — 查看服务器状态(最常用健康检查)

./unrealircd status

实测运行中回显:

servername irc.test.local
unrealircd_version UnrealIRCd-6.2.7
libssl_version OpenSSL 3.0.2 15 Mar 2022
libsodium_version 1.0.18
libcares_version 1.18.1
libpcre2_version PCRE2 10.39 2021-10-29
libjansson 2.15.0
global_clients 0
local_clients 0
operators 0
servers 1
channels 0
UnrealIRCd is up and running.

服务器未运行:

UnrealIRCd is not running.

字段解读:

字段含义
servernameme.name 值
unrealircd_version编译版本号
libssl_version / libsodium_version / ...编译时链接的运行时库版本
global_clients整个 IRC 网络的总客户端数
local_clients当前服务器本地连接的客户端数
operators当前在线 oper 数
servers当前网络的服务器数(单机 = 1)
channels当前存在的频道数

4.7 rehash — 热重载配置

./unrealircd rehash

实测回显:

[info] Loading IRCd configuration..
[info] Testing IRCd configuration..
[advice] You have at least one IRC plaintext port open to users (such as 6667).
[info] Configuration loaded
[advice] Your config has NO errors, but you received some best practices tips above.
Rehashed successfully.

改了 oper.mask、set.modes-on-connect、blacklist 等后 rehash 即可生效。cloak-keys 和 listen 块不支持 rehash,需 restart。

4.8 reloadtls — 热替换 TLS 证书

./unrealircd reloadtls

实测回显:

[info] Reloading TLS configuration...
[info] TLS configuration reloaded successfully.

Let's Encrypt 续期后用这条命令替换证书,不需要重启服务器。

4.9 module-status — 查看已加载模块

./unrealircd module-status

实测回显(节选,完整约 150 条):

history_backend_mem 2.0 - History backend: memory - by UnrealIRCd Team 
channeldb 1.0 - Stores and retrieves channel settings for persistent (+P) channels - by UnrealIRCd Team 
tkldb 1.10 - Stores active TKL entries persistently/across IRCd restarts - by UnrealIRCd Team 
geoip_mmdb 5.2 - GEOIP using mmdb databases - by UnrealIRCd Team 
webirc 5.0 - WebIRC/CGI:IRC Support - by UnrealIRCd Team 
maxperip 2.0.0 - Limit user connections based on ip address - by UnrealIRCd Team 
connthrottle 2.0.0 - Connection throttler - by Syzop - by UnrealIRCd Team 
...

每行格式:<模块名> <版本> - <描述> - <作者>。带 [PERM] 后缀的表示加载后不能卸载(需重启)。

4.10 mkpasswd — 生成密码 hash

./unrealircd mkpasswd
# Enter password to hash: q1w2e3r4
# Encrypted password is: $argon2id$v=19$m=6144,t=2,p=2$jt7ZEjbYco5dChq2W4gKKQ$JJv6XnELQ4p12cBGGsDEabh6YCVBSPjG4gwtNBgQ1Ng
参数支持
输入交互式,回车后输入明文密码
输出argon2id hash 字符串
用途写入 oper block 的 password "..." 字段

4.11 mkcert — 生成自签 TLS 证书

./unrealircd mkcert
# 交互式,会问 Country Name / State / Locality / Organization / Common Name

推荐用一条 openssl 命令绕过全部交互:

openssl req -x509 -newkey rsa:2048 \
  -keyout conf/tls/server.key.pem \
  -out conf/tls/server.cert.pem \
  -days 3650 -nodes \
  -subj "/C=US/ST=State/L=City/O=YourNET/CN=irc.yourdomain.com"

4.12 gencloak — 生成 3 个随机 cloak-keys

./unrealircd gencloak

实测回显:

Here are 3 random cloak keys that you can copy-paste to your configuration file:

set {
	cloak-keys {
		"R310L35XhN6aspsRXqW42TM2NG27qvL1ihI1UHDxd3hRNTJyYX60sM7DGODrEgkKS78p78uOkIJkE8hS";
		"vVONy8CL0pJV12DOo2r8SdA4UjbB46uLB6Ev88tBGvQ5rlS7XYl782vLh1X18JG3WLM1506yO0IVU6xj";
		"cB7b6J3d8a1laOotW6FgUfgVsQA8HhwmM0eKog65xOokK2412kjD06nYBEk3wH2KjiHrAlgT5by1cy13";
	}
}

直接把输出粘贴到 set { cloak-keys { } } 里。多服务器网络所有节点必须用同一组 keys。

在 A 服务器配好 link block 后,跑这条命令吐出 B 服务器需要配的对称 link block:

./unrealircd genlinkblock irc.server-A.com

4.14 spkifp — 显示 TLS 证书的 SPKI 指纹

./unrealircd spkifp
# SPKI Fingerprint for /home/unrealircd/unrealircd/conf/tls/server.cert.pem:
# sha256:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

用于服务器链接时的证书指纹验证(比 CA 验证更安全)。

4.15 croncheck — 给 crontab 用的存活检测

# crontab 每分钟检查,若挂了自动拉起
* * * * * /home/unrealircd/unrealircd/unrealircd croncheck

脚本内部等价于:status 检测 → 若未运行则 start。这是官方推荐的无 systemd 环境下的守护方案。

4.16 upgrade — 一键升级到最新版

./unrealircd upgrade           # 升级到当前主线最新稳定版
./unrealircd upgrade --rc      # 升级到下一版 Release Candidate

内部逻辑:下载 latest.tar.gz → Config → make → make install → 保留 conf/logs/data → 提示重启。升级后跑 ./unrealircd version 验证。

4.17 module — 第三方模块管理

./unrealircd module install <github-url-or-name>
./unrealircd module uninstall <name>
./unrealircd module list

第三方模块仓库:https://modules.unrealircd.org


五、IRC 内 Oper 命令族

升级为 IRCOp 后(/OPER admin q1w2e3r4),可在 IRC 客户端执行以下管理员命令。完整命令表见官方文档(参考链接),以下按功能分组列出高频运维命令。

5.1 服务器治理

命令作用模块
/REHASH热重载配置文件(等同于 CLI rehash)built-in
/RELOADDNS清空 DNS 缓存(强制下次重新解析)built-in
/DIE [password] <reason>关闭整个服务器built-in
/RESTART重启服务器built-in
/CLOSE关闭所有半开的连接built-in
/CONNECT <servername>主动链接到另一台服务器connect
/JUMPSERVER <host:port> NEW|ALL <reason>重定向所有用户到另一台服务器jumpserver

5.2 用户与频道管理

命令作用模块
/KILL <nick> <reason>强制断开指定用户built-in
/GLINE <user@host> <duration> <reason>全网封禁(1h/7d/perm)tkl
/KLINE <user@host> <duration> <reason>当前服务器封禁tkl
/ELINE <user@host> <bantypes> <expiry> <reason>封禁例外(E-line 豁免 K/G-line)tkl
/CHGHOST <nick> <newhost>在线修改用户 hostchghost
/CHGIDENT <nick> <newident>修改 ident/usernamechgident
/CHGNAME <nick> <newgecos>修改 real namechgname

5.3 统计与查询

命令作用模块
/STATS <letter>服务器统计(见下 STATS 子命令表)stats
/LUSERS在线用户/频道/服务器总数lusers
/MAP网络拓扑树(当前服务器视角)map
/HELPOP [command]在线帮助(/HELPOP CHMODES 列所有频道模式)help
/INFO服务器版本/开发者信息built-in
/ADMINadmin block 定义的三行联系信息admin
/IRCPS当前在线 oper 列表(需加载 ircops 模块,默认未加载)ircops
/DNS [l|i|无参数]DNS 解析器状态built-in

5.4 STATS 子命令表

/STATS 是 IRC 协议内置的一组服务器统计子命令,不同字母代表不同查询:

STATS 字母作用
a所有已连接用户的详细信息(oper-only)
c当前服务器配置的所有 connect {} 块
dDNS 黑名单(blacklist)配置
e所有 except {} 块
f频道反洪水配置
g活跃 G-line 封禁
h服务器描述信息
iallow {} / deny {} 块
k活跃 K-line 封禁
l网络全部链接状态
m已加载模块及其版本(等同于 CLI module-status)
o所有 oper {} 块(含密码 hash)
p监听端口(listen 块)
q频道 ban(+b)和 invite(+I)列表
sspamfilter 规则
tMOTD 文本
u服务器在线时长(uptime)
z服务器内存/CPU/连接数统计

5.5 Oper 间通讯

命令作用模块
/GLOBOPS <message>向网络所有服务器上的所有 IRCOp 发送全局通知globops
/LOCOPS <message>仅向当前服务器的 IRCOp 发通知locops
/WALLOPS <message>向所有开启了 user mode +w 的用户发通知built-in

六、注意事项

  1. 禁止 root 运行:所有 CLI 子命令必须以 unrealircd 用户执行;
  2. flag 风格一律无效:别写 ./unrealircd --status——会报 Unrecognized parameter。正确写法是 ./unrealircd status;
  3. 修改配置后必跑 configtest:任何时候改 conf/unrealircd.conf,先 configtest 再 rehash;
  4. cloak-keys 改了必须 restart:set { cloak-keys } 不支持 rehash;
  5. listen block 改了必须 restart:端口/IP 监听配置变化必须完整重启;
  6. IRC 内 OPER 命令需先 /OPER 升级:/OPER <nick> <password> 成功后才有 oper 权限;
  7. systemd 用户 start/stop 改用 systemctl:只有 configtest/rehash/status/version/module-status 这些用 CLI。

七、常见问题

Q1: status 报 UnrealIRCd is not running 但我刚才 start 了

多半是 start 失败了但你没注意错误输出。回头看 ./unrealircd start 的完整回显找 [error] 行。常见原因:配置文件语法错、TLS 证书不存在、listen 端口被占。

Q2: rehash 报 [error] ... block with missing closing brace

某个 block 少了闭合 }。定位方法:grep -c '{' conf/unrealircd.conf 和 grep -c '}' conf/unrealircd.conf——两个数应该相等,差几个就是缺几个。

Q3: IRC 客户端里 /REHASH 报 You do not have IRCop permission

先 /OPER admin q1w2e3r4 升级,再试。升级成功后客户端会收到 You are now an IRCop 系统消息。

Q4: /STATS o 输出里能看到 oper 密码 hash——安全吗?

安全。那是 argon2id 单向 hash,无法反推出明文。但如果某个 oper 用了明文密码(生产禁止),那这里会直接暴露。跑 /STATS o 后若看到 password "plaintext" 立即改掉。

Q5: upgrade 后版本没变

./unrealircd upgrade 会下载最新 tar.gz、编译、make install,但保留 conf/logs/ 不动,并且需要你手动 restart 才能新版本生效:

./unrealircd restart
./unrealircd version

Q6: systemd 托管下 configtest 还是用 CLI 子命令吗?

是的!configtest / module-status / rehash / status / version / mkpasswd / gencloak 这些永远用 CLI 子命令执行(以 unrealircd 用户身份)。只有 start/stop/restart 三个被 systemd 接管。

八、参考链接

资源链接
官方 User & Oper Commands 完整表https://www.unrealircd.org/docs/User_%26_Oper_commands
HELPOP 在线帮助系统IRC 端 /HELPOP
STATS 子命令详解https://www.unrealircd.org/docs/Stats
Operclass 权限分级https://www.unrealircd.org/docs/Operclass_permissions
升级指南https://www.unrealircd.org/docs/Upgrading
Cron job 守护方案https://www.unrealircd.org/docs/Cron_job
第三方模块仓库https://modules.unrealircd.org

本文所有 17 条 CLI 子命令均已在 UnrealIRCd-6.2.7 上实测跑通并记录回显(2026-10-27)。IRC 内 Oper 命令族语法参考官方文档,完整参数与更精确的帮助请在 IRC 客户端用 /HELPOP <command> 查询。