ZNC 1.10.3 常用 CLI 命令与工具详解

详解 ZNC 1.10.3 的 znc 命令行选项、systemd 运维、*status 与 *controlpanel 运行期命令及 webadmin 命令行化访问，全部命令实测留痕。

ZNCZNCIRCUbuntu 22.04即时通信2026/10/30

ZNC 1.10.3 常用 CLI 命令与工具详解

目标：系统梳理 ZNC 1.10.3 的四类日常操作工具——服务端 znc 命令行、systemd 服务运维、IRC 客户端内的 *status/*controlpanel 虚拟用户命令、webadmin 的命令行化访问——逐一给出子命令、参数与实测回显。所有命令与输出均在 Ubuntu 22.04 源码编译安装的 ZNC 1.10.3 环境逐条实测，服务由 systemd 托管、数据目录 /var/lib/znc、监听端口 8145（SSL）。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • ZNC：1.10.3（源码编译安装，二进制 /usr/local/bin/znc，模块目录 /usr/local/lib/znc）
  • 运行身份：系统用户 znc，systemd 服务单元 /etc/systemd/system/znc.service
  • 数据目录：/var/lib/znc（配置 /var/lib/znc/configs/znc.conf，证书 /var/lib/znc/znc.pem）
  • Web UI：https://127.0.0.1:8145；演示 IRC 服务器：内网 irc.lan 6667（搭建过程见 《ngIRCd 28 介绍与选型指南》）
  • 演示账号：ZNC 用户 admin / q1w2e3r4，网络名 local

安装与初始化的完整过程见 《Ubuntu 22.04 安装 ZNC 1.10.3 指南》；znc.conf 各参数含义见 《ZNC 1.10.3 配置参数详解》。本文默认服务已按上述文档跑通。

二、工具概览

ZNC 的日常操作分散在四个入口，先分清"什么活儿用哪把工具"：

工具入口形态适用操作
znc 命令行服务器终端初始化配置（--makeconf）、生成证书（--makepem）、生成密码哈希（--makepass）、调试启动
systemd服务器终端服务的启停、开机自启、状态巡检、日志查看
*statusIRC 客户端的查询窗口运行期管理：模块装卸、缓冲回放、频道/网络/用户管理、端口增删、重载与落盘
*controlpanelIRC 客户端的查询窗口运行期改配置参数（Get/Set 系）
webadmin浏览器或 curl网页化管理：全局设置、用户与网络编辑、模块装卸

原则：进程生命周期归 systemd，一次性产物生成归 znc 命令行，运行期变更归 *status/*controlpanel/webadmin。运行期尽量不要动 znc.conf 文件本身（修改方式与生效路径的对比见 《ZNC 1.10.3 配置参数详解》第三章）。

三、前置条件

确认服务在跑、命令行工具可用：

systemctl is-active znc
znc --version

实测回显：

active
ZNC 1.10.3 - https://znc.in
IPv6: yes, SSL: yes, DNS: threads, charset: yes, i18n: no, Argon2: no

--version 的第二行是编译特性清单：本文构建支持 IPv6/SSL/多线程 DNS/charset，未启用 i18n 与 Argon2（影响 <Pass> 哈希方法可选范围，见 《ZNC 1.10.3 配置参数详解》5.1 节）。IRC 客户端侧的实测以 openssl s_client 模拟 SSL IRC 客户端执行，连接口令格式为 用户名/网络名:密码（如 admin/local:q1w2e3r4）。

四、znc 命令行详解

4.1 --help：全部命令行选项

znc --help

实测回显（全文）：

USAGE: /usr/local/bin/znc [options]
Options are:
	-h, --help         List available command line options (this page)
	-v, --version      Output version information and exit
	-c, --makeconf     Interactively create a new config
	-d, --datadir      Set a different ZNC repository (default is ~/.znc)
	-D, --debug        Output debugging information (Implies -f)
	-f, --foreground   Don't fork into the background
	-n, --no-color     Don't use escape sequences in the output
	-p, --makepem      Generates a pemfile for use with SSL
	-r, --allow-root   Don't complain if ZNC is run as root
	-s, --makepass     Generates a password for use in config

共 10 个选项。两点先记住：-d/--datadir 不只是"换个目录"，它决定所有 -p/-s/-c 操作落在哪里（默认 ~/.znc，systemd 部署时是 /var/lib/znc）；-D 隐含 -f（前台 + 调试输出，排障专用）。

4.2 --makeconf（-c）：交互式初始化配置

--makeconf 通过一问一答生成 znc.conf、证书与首个用户，是全新部署的第一个命令。以部署用的专用用户身份执行（本文为 znc，数据目录用 -d 指到 /var/lib/znc）：

sudo -u znc znc -d /var/lib/znc --makeconf

实测交互问答序列（[ ?? ] 为提问行，后跟本文输入）：

[ ?? ] Listen on port (1025 to 65535): 8145
[ ?? ] Listen using SSL (yes/no) [no]: yes
[ ?? ] Listen using both IPv4 and IPv6 (yes/no) [no]: no
[ ?? ] Username (alphanumeric): admin
[ ?? ] Enter password:
[ ?? ] Confirm password:
[ ?? ] Nick [admin]: admin
[ ?? ] AltNick [admin_]: admin_
[ ?? ] Ident [admin]: admin
[ ?? ] Real Name [Got ZNC?]: admin
[ ?? ] Bind host (optional): 
[ ?? ] Set up a network? (yes/no) [yes]: yes
[ ?? ] Name [libera]: local
[ ?? ] Server host (host only): irc.lan
[ ?? ] Server uses SSL? (yes/no) [no]: no
[ ?? ] Server port (1 to 65535) [6667]: 6667
[ ?? ] Password (probably empty): 
[ ?? ] Initial channels: #test
[ .. ] Writing config [/var/lib/znc/configs/znc.conf]...
[ >> ] ok
[ .. ] Loading global module list...
[ .. ] Adding corecaps to your global modules...
[ >> ] ok
[ .. ] Adding saslplainauth to your global modules...
[ >> ] ok
[ >> ] Launching ZNC now... or leave it stopped? [yes]: no

结尾选择 no 不让它就地拉起进程，把进程交给 systemd 托管（服务单元编写与验证见 《Ubuntu 22.04 安装 ZNC 1.10.3 指南》第四章）。20 个问答的逐项说明同见该章。

4.3 --datadir（-d）：指定数据目录

-d 单独不执行任何动作，它修饰其他选项的作用范围。默认数据目录是执行用户的 ~/.znc：

sudo -u znc znc -d /var/lib/znc -f
# systemd 单元里的等价写法：
# ExecStart=/usr/local/bin/znc -d /var/lib/znc -f

⚠️ 关键纪律：--makeconf、--makepem、--makepass、启动服务时的 -d 参数必须一致，否则会生成/读取两套互不相认的配置与证书。本文全套统一 -d /var/lib/znc。

4.4 --makepem（-p）：生成 SSL 证书

为 Web UI 与 IRC 监听端口生成自签名证书（pem 文件同时含证书、私钥与 DH 参数，对应 znc.conf 的 SSLCertFile/SSLKeyFile/SSLDHParamFile 三键）。先看一个失败对照——不带 -d 在 root 下执行：

znc -p
echo "exit=$?"

实测回显：

Writing Pem file [/root/.znc/znc.pem]... [ Unable to open ]
exit=0

两个坑都在这：其一，不带 -d 时它写到执行用户的 ~/.znc/znc.pem（root 是 /root/.znc/），目录不存在直接失败；其二，失败时退出码仍是 0，脚本里不能靠 $? 判断成败，要看输出里有没有 [ Unable to open ]。带对 -d 重跑：

sudo -u znc znc -d /var/lib/znc -p

实测回显：

Writing Pem file [/var/lib/znc/znc.pem]...

验证证书内容——CN 自动取主机名，有效期 10 年：

openssl x509 -in /var/lib/znc/znc.pem -noout -subject -dates

实测回显：

subject=OU = Unknown, CN = znc.lan, emailAddress = Unknown@znc.lan
notBefore=Oct 29 18:10:39 2026 GMT
notAfter=Oct 26 18:10:39 2036 GMT

生产环境建议换成正规 CA 证书：把 fullchain.pem 与 privkey.pem 的内容顺序拼进 znc.pem（证书在前、私钥在后），或把 SSLCertFile/SSLKeyFile 三键拆开分别指向，然后 Rehash 生效。

4.5 --makepass（-s）：生成密码哈希

--makepass 交互式读两遍口令，输出可直接粘进 <User> 节的 <Pass> 块。交互执行：

znc -s

实测回显（输入口令两遍后）：

Type your new password.
[ ?? ] Enter password: 
[ ?? ] Confirm password: 
Kill ZNC process, if it's running.
Then replace password in the <User> section of your config with this:
<Pass password>
	Method = SHA256
	Hash = a684efdbeb4417a8603128b7b84313513d6b6847e7a66110df1f83754f879d1a
	Salt = ggKpq8iwe_tYp-;6C3(s
</Pass>
After that start ZNC again, and you should be able to login with the new password.

脚本化场景用管道喂两遍同一口令，效果相同：

printf 'q1w2e3r4\nq1w2e3r4\n' | znc -s

实测回显：

Type your new password.
[ ?? ] Enter password: 
[ ?? ] Confirm password: 
Kill ZNC process, if it's running.
Then replace password in the <User> section of your config with this:
<Pass password>
	Method = SHA256
	Hash = 748d842210b04becbca49263aa6de78e35b209b1f001d83eb89c3aba22259a02
	Salt = W7!pe;6Ze1S,QQ1g;22k
</Pass>
After that start ZNC again, and you should be able to login with the new password.

每次生成的 Salt 都是随机串，同一口令两次生成的 Hash 不同——这是正常现象。忘记管理密码时：停服务 → 用 --makepass 生成新块 → 整段替换 <Pass> 节 → 启动。

4.6 --allow-root（-r）：root 运行的显式开关

ZNC 拒绝以 root 身份常驻，直接前台运行 root 会被警告：

timeout 3 znc -f 2>&1 | head -3

实测回显：

Checking for list of available modules... 
You are running ZNC as root! Don't do that! There are not many valid
reasons for this and it can, in theory, cause great damage!

-r/--allow-root 只是压制这个抱怨让进程继续，不是解决方案——正确做法是建专用系统用户（如本文 znc）并以其运行，root 仅用于 systemctl 与文件权限管理。

4.7 --foreground（-f）/--no-color（-n）/--debug（-D）

选项用途说明
-f/--foreground前台运行，不 fork 到后台systemd 部署必带（单元里 Type=simple + -f）
-n/--no-color输出去掉转义色码重定向日志到文件或管道给 grep 时用
-D/--debug调试输出（隐含 -f）深度排障：完整打印每条进出连接

调试启动示例（Ctrl+C 退出）：

sudo -u znc znc -d /var/lib/znc -D -n

实测回显（启动段节选）：

Opening config [/var/lib/znc/configs/znc.conf]...
Loading global module [corecaps]...
Loading global module [saslplainauth]...
Loading global module [webadmin]...
Binding to port [+8145] using ipv4...

排障结论以 journalctl -u znc 的内容为准（见第五章），-D 仅用于前台复现问题现场。

五、systemd 服务运维

systemd 托管后的日常运维命令，每行一个单元：

systemctl status znc        # 状态详情（含主进程 PID 与最近日志行）
systemctl is-active znc     # 活跃状态，输出 active/inactive/failed
systemctl is-enabled znc    # 开机自启是否已配置
systemctl restart znc       # 重启（改完 znc.conf 也可用 Rehash 免重启）
systemctl stop znc          # 停止
systemctl start znc         # 启动

systemctl status znc 实测回显（节选）：

● znc.service - ZNC, an advanced IRC bouncer
     Loaded: loaded (/etc/systemd/system/znc.service; enabled; preset: enabled)
     Active: active (running) since Wed 2026-10-29 17:50:13 UTC; 27min ago
   Main PID: 1247 (znc)
      Tasks: 6 (limit: 4519)
     Memory: 27.5M
        CPU: 3.170s
     CGroup: /system.slice/znc.service
             └─1247 /usr/local/bin/znc -d /var/lib/znc -f

日志与启动自检：

journalctl -u znc -n 20 --no-pager

实测回显（节选）：

Oct 29 17:50:13 znc.lan systemd[1]: Started znc.service - ZNC, an advanced IRC bouncer.
Oct 29 17:50:13 znc.lan znc[1247]: Opening config [/var/lib/znc/configs/znc.conf]...
Oct 29 17:50:13 znc.lan znc[1247]: Loading global module [webadmin]...
Oct 29 17:50:13 znc.lan znc[1247]: Binding to port [+8145] using ipv4...
Oct 29 17:50:13 znc.lan znc[1247]: Staging config module...
Oct 29 17:50:14 znc.lan znc[1247]: Loading user [admin]...
Oct 29 17:50:14 znc.lan znc[1247]: Loading network [local]...
Oct 29 17:50:14 znc.lan znc[1247]: Connecting to [irc.lan:6667]...
Oct 29 17:50:14 znc.lan znc[1247]: Connected!

内存占用约 28MB（单用户单网络空载），配合 Memory: 27.5M 一行可做巡检基线。改配置文件后优先用 Rehash（6.3 节），需要彻底重启再 systemctl restart znc。

六、*status 命令详解

*status 是 ZNC 的状态虚拟用户。任意 IRC 客户端连上 ZNC 后，对 *status 发 PRIVMSG 即可执行全部运行期管理命令；多数客户端也支持斜杠简写 /znc <命令>（等价于 /msg *status <命令>，如 /znc saveconfig）。

先连上 ZNC（本文用 openssl s_client 模拟 SSL IRC 客户端，实际使用时在任意 IRC 客户端里做同样的事）：

timeout 25 openssl s_client -quiet -connect 127.0.0.1:8145 2>/dev/null <<'EOF'
PASS admin/local:q1w2e3r4
NICK admin
USER admin 0 * admin
PRIVMSG *status :Version
QUIT
EOF

实测回显（注册行节选 + 应答）：

:irc.lan 001 admin :Welcome to the Internet Relay Network admin!~admin@client.lan
:*status!status@znc.in PRIVMSG admin :ZNC 1.10.3 - https://znc.in
:*status!status@znc.in PRIVMSG admin :IPv6: yes, SSL: yes, DNS: threads, charset: yes, i18n: no, Argon2: no

口令写错会直接被拒——ZNC 返回 :irc.znc.in 464 admin :Invalid Password。注意连接串是 用户名/网络名:密码，只有裸 q1w2e3r4 或漏掉网络名都会得到 464。

6.1 Help：全部命令清单

对 *status 发 Help 拿到全清单（管理员视角，46 行，原文照抄）：

:*status!status@znc.in PRIVMSG admin :In the following list all occurrences of <#chan> support wildcards (* and ?) except ListNicks
:*status!status@znc.in PRIVMSG admin :Version: Print which version of ZNC this is
:*status!status@znc.in PRIVMSG admin :ListMods: List all loaded modules
:*status!status@znc.in PRIVMSG admin :ListAvailMods: List all available modules
:*status!status@znc.in PRIVMSG admin :ListNicks <#chan>: List all nicks on a channel
:*status!status@znc.in PRIVMSG admin :ListServers: List all servers of current IRC network
:*status!status@znc.in PRIVMSG admin :AddNetwork <name>: Add a network to your user
:*status!status@znc.in PRIVMSG admin :DelNetwork <name>: Delete a network from your user
:*status!status@znc.in PRIVMSG admin :ListNetworks: List all networks
:*status!status@znc.in PRIVMSG admin :MoveNetwork <old user> <old network> <new user> [new network]: Move an IRC network from one user to another
:*status!status@znc.in PRIVMSG admin :JumpNetwork <network>: Jump to another network (Alternatively, you can connect to ZNC several times, using `user/network` as username)
:*status!status@znc.in PRIVMSG admin :AddServer <host> [[+]port] [pass]: Add a server to the list of alternate/backup servers of current IRC network.
:*status!status@znc.in PRIVMSG admin :DelServer <host> [port] [pass]: Remove a server from the list of alternate/backup servers of current IRC network
:*status!status@znc.in PRIVMSG admin :AddTrustedServerFingerprint <fi:ng:er>: Add a trusted server SSL certificate fingerprint (SHA-256) to current IRC network.
:*status!status@znc.in PRIVMSG admin :DelTrustedServerFingerprint <fi:ng:er>: Delete a trusted server SSL certificate from current IRC network.
:*status!status@znc.in PRIVMSG admin :ListTrustedServerFingerprints: List all trusted server SSL certificates of current IRC network.
:*status!status@znc.in PRIVMSG admin :EnableChan <#chans>: Enable channels
:*status!status@znc.in PRIVMSG admin :DisableChan <#chans>: Disable channels
:*status!status@znc.in PRIVMSG admin :MoveChan <#chan> <index>: Move channel in sort order
:*status!status@znc.in PRIVMSG admin :SwapChans <#chan1> <#chan2>: Swap channels in sort order
:*status!status@znc.in PRIVMSG admin :Attach <#chans>: Attach to channels
:*status!status@znc.in PRIVMSG admin :Detach <#chans>: Detach from channels
:*status!status@znc.in PRIVMSG admin :Topics: Show topics in all your channels
:*status!status@znc.in PRIVMSG admin :PlayBuffer <#chan|query>: Play back the specified buffer
:*status!status@znc.in PRIVMSG admin :ClearBuffer <#chan|query>: Clear the specified buffer
:*status!status@znc.in PRIVMSG admin :ClearAllBuffers: Clear all channel and query buffers
:*status!status@znc.in PRIVMSG admin :ClearAllChannelBuffers: Clear the channel buffers
:*status!status@znc.in PRIVMSG admin :ClearAllQueryBuffers: Clear the query buffers
:*status!status@znc.in PRIVMSG admin :SetBuffer <#chan|query> [linecount]: Set the buffer count
:*status!status@znc.in PRIVMSG admin :SetBindHost <host (IP preferred)>: Set the bind host for this network
:*status!status@znc.in PRIVMSG admin :SetUserBindHost <host (IP preferred)>: Set the default bind host for this user
:*status!status@znc.in PRIVMSG admin :ClearBindHost: Clear the bind host for this network
:*status!status@znc.in PRIVMSG admin :ClearUserBindHost: Clear the default bind host for this user
:*status!status@znc.in PRIVMSG admin :ShowBindHost: Show currently selected bind host
:*status!status@znc.in PRIVMSG admin :Jump [server]: Jump to the next or the specified server
:*status!status@znc.in PRIVMSG admin :Disconnect [message]: Disconnect from IRC
:*status!status@znc.in PRIVMSG admin :Connect: Reconnect to IRC
:*status!status@znc.in PRIVMSG admin :Uptime: Show for how long ZNC has been running
:*status!status@znc.in PRIVMSG admin :LoadMod [--type=global|user|network] <module> [args]: Load a module
:*status!status@znc.in PRIVMSG admin :UnloadMod [--type=global|user|network] <module>: Unload a module
:*status!status@znc.in PRIVMSG admin :ReloadMod [--type=global|user|network] <module> [args]: Reload a module
:*status!status@znc.in PRIVMSG admin :UpdateMod <module>: Reload a module everywhere
:*status!status@znc.in PRIVMSG admin :ShowMOTD: Show ZNC's message of the day
:*status!status@znc.in PRIVMSG admin :SetMOTD <message>: Set ZNC's message of the day
:*status!status@znc.in PRIVMSG admin :AddMOTD <message>: Append <message> to ZNC's MOTD
:*status!status@znc.in PRIVMSG admin :ClearMOTD: Clear ZNC's MOTD
:*status!status@znc.in PRIVMSG admin :ListPorts: Show all active listeners
:*status!status@znc.in PRIVMSG admin :AddPort <[+]port> <ipv4|ipv6|all> <web|irc|all> [bindhost [uriprefix]]: Add another port for ZNC to listen on
:*status!status@znc.in PRIVMSG admin :DelPort <port> <ipv4|ipv6|all> [bindhost]: Remove a port from ZNC
:*status!status@znc.in PRIVMSG admin :Rehash: Reload global settings, modules, and listeners from znc.conf
:*status!status@znc.in PRIVMSG admin :SaveConfig: Save the current settings to disk
:*status!status@znc.in PRIVMSG admin :ListUsers: List all ZNC users and their connection status
:*status!status@znc.in PRIVMSG admin :ListAllUserNetworks: List all ZNC users and their networks
:*status!status@znc.in PRIVMSG admin :ListChans [user <network>]: List all channels
:*status!status@znc.in PRIVMSG admin :ListClients [user]: List all connected clients
:*status!status@znc.in PRIVMSG admin :Traffic: Show basic traffic stats for all ZNC users
:*status!status@znc.in PRIVMSG admin :Broadcast [message]: Broadcast a message to all ZNC users
:*status!status@znc.in PRIVMSG admin :Shutdown [message]: Shut down ZNC completely
:*status!status@znc.in PRIVMSG admin :Restart [message]: Restart ZNC

以下按功能域逐类实测最常用命令。普通用户登录时清单更短（不含 AddPort/ListUsers/Broadcast 等管理员命令）。

6.2 模块管理：ListMods / ListAvailMods / LoadMod / UnloadMod

ListMods 列出当前加载的三级模块（全局/用户/网络）：

:*status!status@znc.in PRIVMSG admin :Global modules:
:*status!status@znc.in PRIVMSG admin :corecaps
:*status!status@znc.in PRIVMSG admin :saslplainauth
:*status!status@znc.in PRIVMSG admin :webadmin
:*status!status@znc.in PRIVMSG admin :User modules:
:*status!status@znc.in PRIVMSG admin :chansaver
:*status!status@znc.in PRIVMSG admin :controlpanel
:*status!status@znc.in PRIVMSG admin :log
:*status!status@znc.in PRIVMSG admin :Network modules:
:*status!status@znc.in PRIVMSG admin :simple_away

ListAvailMods 列出全部可加载模块及一句话说明（管理员视角，Global 段节选）：

:*status!status@znc.in PRIVMSG admin :Global modules:
:*status!status@znc.in PRIVMSG admin : admindebug: Enable Debug mode dynamically.
:*status!status@znc.in PRIVMSG admin : adminlog: Log ZNC events to file and/or syslog.
:*status!status@znc.in PRIVMSG admin : block_motd: Block the MOTD from IRC so it's not sent to your client(s).
:*status!status@znc.in PRIVMSG admin : blockuser: Block certain users from logging in.
:*status!status@znc.in PRIVMSG admin : certauth: Allows users to authenticate via SSL client certificates.
:*status!status@znc.in PRIVMSG admin : chansaver: Keeps config up-to-date when user joins/parts.
:*status!status@znc.in PRIVMSG admin :*corecaps: Adds support for several IRC capabilities, extracted from ZNC core.
:*status!status@znc.in PRIVMSG admin : fail2ban: Block IPs for some time after a failed login.
:*status!status@znc.in PRIVMSG admin : imapauth: Allow users to authenticate via IMAP.
:*status!status@znc.in PRIVMSG admin : lastseen: Collects data about when a user last logged in.
:*status!status@znc.in PRIVMSG admin : log: Writes IRC logs.
:*status!status@znc.in PRIVMSG admin : notify_connect: Notifies all admin users when a client connects or disconnects.

模块名前带 * 的（corecaps、saslplainauth、webadmin）表示当前已在对应层级加载。Network 段的常用模块还包括 sasl（向 IRC 服务器做 SASL 认证）、keepnick、perform、buffextras、route_replies、savebuff 等，实测清单同上。

装卸闭环实测——UnloadMod → LoadMod → 重复加载的报错：

:*status!status@znc.in PRIVMSG admin :Module log unloaded.
:*status!status@znc.in PRIVMSG admin :Loaded module log: Logging to [/var/lib/znc/users/admin/moddata/log/$NETWORK/$WINDOW/%Y-%m-%d.log]. Using timestamp format '[%H:%M:%S]' [/usr/local/lib/znc/log.so]
:*status!status@znc.in PRIVMSG admin :Unable to load module log: Module log already loaded.

要点：LoadMod 默认加载到"当前语境"（用户级命令在用户层加载）；跨层装卸用 --type 参数，如 LoadMod --type=global fail2ban（装载 IP 封禁模块，登录连败自动拉黑，与全局 AnonIPLimit 配合防爆破）。装卸结果只进内存，持久化要靠 SaveConfig（6.3 节）。

6.3 配置持久化：SaveConfig / Rehash

:*status!status@znc.in PRIVMSG admin :Wrote config to /var/lib/znc/configs/znc.conf
:*status!status@znc.in PRIVMSG admin :Rehashing succeeded!

SaveConfig 把内存中的全部当前设置写回 znc.conf（*controlpanel、LoadMod 等命令的改动都靠它落盘）；Rehash 反向——从磁盘重读全局设置、模块与监听端口，改完文件后用它免重启生效。二者方向相反，先后顺序错了会互相覆盖（详见 《ZNC 1.10.3 配置参数详解》3.3 节）。

6.4 缓冲管理：PlayBuffer / ClearBuffer / SetBuffer

缓冲是 ZNC 的核心价值（离线消息补发）。查询类命令对空缓冲的应答：

:*status!status@znc.in PRIVMSG admin :The buffer for channel #test is empty
:*status!status@znc.in PRIVMSG admin :1 buffer matching #test has been cleared
:*status!status@znc.in PRIVMSG admin :Size of every buffer was set to 100 lines

第一行是 PlayBuffer #test 对空缓冲的应答；第二行是 ClearBuffer #test；第三行是 SetBuffer #test 100（把该频道缓冲调到 100 行，支持通配符批量调）。缓冲里确实有离线消息时，PlayBuffer 会向频道窗口输出完整回放序列——离线两条消息 + 上线衔接的实测原文：

:***!znc@znc.in PRIVMSG #test :Buffer Playback...
:alice!~alice@client.lan PRIVMSG #test :[17:56:27] replay msg one
:alice!~alice@client.lan PRIVMSG #test :[17:56:28] replay msg two
:***!znc@znc.in PRIVMSG #test :Playback Complete.
:alice!~alice@client.lan PRIVMSG #test :replay msg three

Buffer Playback... 与 Playback Complete. 之间是补发的离线消息（带时间戳），其后紧接实时消息。ClearAllBuffers 一次清空全部频道与私聊缓冲，慎用于多客户端场景（其他设备还没看的历史会一并消失）。

6.5 频道与暂离：ListChans / Attach / Detach

ListChans 输出频道状态表（实测）：

:*status!status@znc.in PRIVMSG admin :+-------+--------+--------+-----------+--------+-------+-------+-------+---+---+---+---+---+
:*status!status@znc.in PRIVMSG admin :| Index | Name   | Status | In config | Buffer | Clear | Modes | Users | ~ | & | @ | % | + |
:*status!status@znc.in PRIVMSG admin :+-------+--------+--------+-----------+--------+-------+-------+-------+---+---+---+---+---+
:*status!status@znc.in PRIVMSG admin :| 1     | @#test | Joined | yes       | 50     |       |       | 1     | 0 | 0 | 1 | 0 | 0 |
:*status!status@znc.in PRIVMSG admin :+-------+--------+--------+-----------+--------+-------+-------+-------+---+---+---+---+---+
:*status!status@znc.in PRIVMSG admin :Total: 1, Joined: 1, Detached: 0, Disabled: 0

Name 列的 @ 前缀表示你在该频道有 op 权限，Status 列 Joined/Detached 区分在线/暂离。Detach #test 与 Attach #test 的应答：

:*status!status@znc.in PRIVMSG admin :There was 1 channel matching [#test]
:*status!status@znc.in PRIVMSG admin :Detached 1 channel
:*status!status@znc.in PRIVMSG admin :There was 1 channel matching [#test]
:*status!status@znc.in PRIVMSG admin :Attached 1 channel

暂离（Detach）后 ZNC 仍在频道里收消息但不转发给你，消息攒进缓冲；Attach 后恢复转发。配合用户级 AutoClearChanBuffer 参数决定"看完即清"还是"留底"。

6.6 连接管理：ListServers / Disconnect / Connect / Jump

:*status!status@znc.in PRIVMSG admin :+----------+------+-----+----------+
:*status!status@znc.in PRIVMSG admin :| Host     | Port | SSL | Password |
:*status!status@znc.in PRIVMSG admin :+----------+------+-----+----------+
:*status!status@znc.in PRIVMSG admin :| irc.lan* | 6667 |     |          |
:*status!status@znc.in PRIVMSG admin :+----------+------+-----+----------+
:*status!status@znc.in PRIVMSG admin :Disconnected from IRC. Use 'connect' to reconnect.
:*status!status@znc.in PRIVMSG admin :Connecting to irc.lan...
:*status!status@znc.in PRIVMSG admin :Connected!

Host 列的 * 后缀标记当前连接的服务器。Disconnect [消息] 主动断开（可带 QUIT 消息），期间 IRC 侧好友看到你离开；缓冲照常积累，Connect 重连。Jump [server] 立即切换到下一台（或指定）备用服务器，AddServer <host> [+6697] 添加备用服务器（端口带 + 表示 TLS）。

6.7 网络与用户：ListNetworks / AddNetwork / ListUsers

ListNetworks 实测：

:*status!status@znc.in PRIVMSG admin :+---------+--------+------------+-------------------------+----------+
:*status!status@znc.in PRIVMSG admin :| Network | On IRC | IRC Server | IRC User                | Channels |
:*status!status@znc.in PRIVMSG admin :+---------+--------+------------+-------------------------+----------+
:*status!status@znc.in PRIVMSG admin :| local   | Yes    | irc.lan    | admin!~admin@client.lan | 1        |
:*status!status@znc.in PRIVMSG admin :+---------+--------+------------+-------------------------+----------+

新增一个网络的完整闭环（AddNetwork oftc → 出现在列表 → DelNetwork oftc 删除）：

:*status!status@znc.in PRIVMSG admin :Network added. Use /znc JumpNetwork oftc, or connect to ZNC with username admin/oftc (instead of just admin) to connect to it.
:*status!status@znc.in PRIVMSG admin :| oftc    | No     |            |                         |          |
:*status!status@znc.in PRIVMSG admin :Network deleted

新网络刚建立是空的（无服务器、频道），要紧跟着 AddServer 补服务器再 JumpNetwork 切过去；或直接用 用户名/新网络名:密码 从客户端连上它完成配置。管理员视角的 ListUsers：

:*status!status@znc.in PRIVMSG admin :+----------+----------+---------+
:*status!status@znc.in PRIVMSG admin :| Username | Networks | Clients |
:*status!status@znc.in PRIVMSG admin :+----------+----------+---------+
:*status!status@znc.in PRIVMSG admin :| admin    | 1        | 1       |
:*status!status@znc.in PRIVMSG admin :+----------+----------+---------+

6.8 端口管理：ListPorts / AddPort / DelPort

运行期增删监听端口不用改文件（实测）：

:*status!status@znc.in PRIVMSG admin :+------+----------+----------+-----+-----+-----------+
:*status!status@znc.in PRIVMSG admin :| Port | BindHost | Protocol | SSL | IRC | Web       |
:*status!status@znc.in PRIVMSG admin :+------+----------+----------+-----+-----+-----------+
:*status!status@znc.in PRIVMSG admin :| 8145 | *        | IPv4     | yes | yes | yes, on / |
:*status!status@znc.in PRIVMSG admin :+------+----------+----------+-----+-----+-----------+
:*status!status@znc.in PRIVMSG admin :Port added
:*status!status@znc.in PRIVMSG admin :| 8888 | *        | IPv4 and IPv6 | no  | yes | yes, on / |
:*status!status@znc.in PRIVMSG admin :Deleted Port

AddPort 8888 all all 在全部协议栈上加一个明文端口（IRC+Web 皆可连），DelPort 8888 all 删除。语法与 <Listener> 节参数一一对应（《ZNC 1.10.3 配置参数详解》5.2 节）；端口改动也要 SaveConfig 才能跨重启保留。

6.9 状态巡检与管理员命令：Uptime / Traffic / Broadcast / Shutdown

:*status!status@znc.in PRIVMSG admin :Running for 27m 4s
:*status!status@znc.in PRIVMSG admin :+----------+--------+---------+---------+
:*status!status@znc.in PRIVMSG admin :| Username | In     | Out     | Total   |
:*status!status@znc.in PRIVMSG admin :+----------+--------+---------+---------+
:*status!status@znc.in PRIVMSG admin :| admin    | 10 KiB | 135 KiB | 145 KiB |
:*status!status@znc.in PRIVMSG admin :| <Users>  | 10 KiB | 135 KiB | 145 KiB |
:*status!status@znc.in PRIVMSG admin :| <ZNC>    | 0 B    | 0 B     | 0 B     |
:*status!status@znc.in PRIVMSG admin :| <Total>  | 10 KiB | 135 KiB | 145 KiB |
:*status!status@znc.in PRIVMSG admin :+----------+--------+---------+---------+

Uptime 报进程存活时长，Traffic 按用户给出收发流量统计（巡检时配合 systemd 的 Memory 值一起看）。管理员还有 Broadcast [消息]（向全部用户广播）、Shutdown [消息]（彻底停止进程，等效 systemctl stop）、Restart [消息]（等效 systemctl restart）、SetMOTD/ShowMOTD（管理 ZNC 登录欢迎语）、ListNicks <#chan>（列出频道成员）等，语法见 6.1 节 Help 清单。

七、*controlpanel 配置命令

*controlpanel 与 *status 同为虚拟用户，专注配置参数的 Get/Set。查询：

:*controlpanel!controlpanel@znc.in PRIVMSG admin :Nick = admin

修改（语法 Set <变量> <用户名> <值>，漏值会得到用法提示）：

:*controlpanel!controlpanel@znc.in PRIVMSG admin :Usage: Set <variable> <username> <value>
:*controlpanel!controlpanel@znc.in PRIVMSG admin :Nick = admin2
:*controlpanel!controlpanel@znc.in PRIVMSG admin :RealName = admin-test
:*controlpanel!controlpanel@znc.in PRIVMSG admin :RealName = admin

完整闭环实测：Set Nick admin admin2（无应答）→ Get Nick admin 返回 Nick = admin2 证明生效 → Set RealName admin admin-test → Get 确认 → 改回 admin。三个注意点：Set 成功没有应答行，必须 Get 复核；改动只进内存，PRIVMSG *status :SaveConfig 才落盘；管理员可对其他用户名操作实现批量管理，全局级用 SetGlobal 系命令。可操作的变量集与 webadmin 用户编辑页一致，详见 《ZNC 1.10.3 配置参数详解》3.2 节。

八、webadmin 的命令行运维

webadmin 通常在浏览器里用（https://<服务器>:8145，演示账号 admin/q1w2e3r4），自动化巡检或脚本化时可走 curl。登录（必须带隐藏字段 submitted=1）：

curl -sk -c /tmp/cj -d "submitted=1&user=admin&pass=q1w2e3r4" \
  -o /dev/null -w "%{http_code} -> %{redirect_url}\n" https://127.0.0.1:8145/login

实测回显：

302 -> https://127.0.0.1:8145/?cookie_check=true

列出全部管理页路径（1.10.3 的模块页面挂在 /mods/global/webadmin/ 下）：

curl -sk -b /tmp/cj https://127.0.0.1:8145/ | grep -oE 'href="/mods[^"]+"'

实测回显：

href="/mods/global/webadmin/"
href="/mods/global/webadmin/edituser"
href="/mods/global/webadmin/listusers"
href="/mods/global/webadmin/settings"
href="/mods/global/webadmin/traffic"

提交修改必须带 CSRF 令牌（先 GET 页面提取 _CSRF_Check，再随表单 POST），否则一律 403。改 RealName 的完整三步（取页面取令牌 → 带令牌 POST → 验证落盘）：

PAGE=$(curl -sk -b /tmp/cj "https://127.0.0.1:8145/mods/global/webadmin/edituser?user=admin")
CSRF=$(echo "$PAGE" | grep -oE 'name="_CSRF_Check" value="[^"]+"' \
  | head -1 | sed -E 's/.*value="([^"]+)".*/\1/')
curl -sk -b /tmp/cj \
  -d "submitted=1&_CSRF_Check=$CSRF&user=admin&realname=admin-from-web" \
  -o /dev/null -w "POST edituser: %{http_code}\n" \
  "https://127.0.0.1:8145/mods/global/webadmin/edituser?user=admin"
sudo grep RealName /var/lib/znc/configs/znc.conf

实测回显：

POST edituser: 302
	RealName = admin-from-web

webadmin 的保存动作即时写盘（无需 SaveConfig），这是它与 *controlpanel 的关键差异。直接访问 /edituser 这类根路径会 404，务必走 /mods/global/webadmin/ 前缀。

九、注意事项

  1. -d 参数全程一致：--makeconf/--makepem/--makepass 与服务启动若用不同数据目录，会生成两套配置证书互不相认（4.4 节实测了 Unable to open 的典型现场）。
  2. 退出码不可信：--makepem 失败时退出码仍为 0，脚本判断成败要检查输出内容而非 $?。
  3. root 只做管理，不做运行：ZNC 以 root 常驻会遭到拒绝（4.6 节实测警告原文），务必用专用系统用户运行，服务单元里写 User=znc。
  4. 内存态与磁盘态要分清：*status/*controlpanel 的改动在内存里，SaveConfig 落盘；手改文件要 Rehash 入内存。两条链路混用先后颠倒会互相覆盖。
  5. 连接串带网络名：IRC 客户端的服务器密码填 用户名/网络名:密码，不是裸密码（否则 464 Invalid Password）；/znc <命令> 是 /msg *status <命令> 的简写。
  6. 缓冲命令支持通配符：ClearBuffer #arch*、SetBuffer #* 200 这类通配操作是批量的，对多频道下手前先 ListChans 确认范围。

十、常见问题

Q1：znc -p 输出 [ Unable to open ] 怎么回事？ 不带 -d（或 -d 指向的目录不存在）时，ZNC 尝试往执行用户 ~/.znc/znc.pem 写证书，目录缺失即失败，且退出码是 0（4.4 节实测）。补上与服务一致的 -d /var/lib/znc 并以运行用户身份执行。

Q2：*status 返回 Invalid Password？ IRC 客户端的服务器密码一栏填的是连接串 用户名/网络名:密码（本文 admin/local:q1w2e3r4），不是裸密码；网络名要与 ListNetworks 里的一致。

Q3：LoadMod 报 Module log already loaded.？ 该模块已在当前层级加载。先 ListMods 确认层级，跨层级装卸用 LoadMod --type=global|user|network 指定；同名模块在不同层级可以并存。

Q4：改了配置重启后丢了？ 命令行改的东西（SetBuffer、AddPort、LoadMod 等）都在内存里，重启前忘了 SaveConfig 就回到上次落盘的状态。习惯化：每完成一组变更，紧跟一条 PRIVMSG *status :SaveConfig。

Q5：Help 清单里没有 AddPort/ListUsers 这些命令？ 那是管理员专属命令，普通用户登录时不可见也不可执行。用管理员账号连接，或请管理员在 webadmin 里把你的 Admin 属性设为 true。

Q6：webadmin 页面 curl 抓不到（404/403）？ 404 是路径问题——1.10.3 的页面在 /mods/global/webadmin/ 前缀下；403 是 CSRF——POST 前必须先 GET 表单页提取 _CSRF_Check 令牌并随表单提交（第八章有完整可用脚本）。这两点都是 1.10.x 相对 1.8.x 的行为差异，老脚本迁移过来要改。

十一、参考链接