UnrealIRCd 6.2.7 配置参数详解

目标：系统梳理 UnrealIRCd 6.2.7 配置文件 unrealircd.conf 的全部 block 与指令，按功能分组、逐段给出代码示例 + 参数解读 + 实测回显，并提供一份生产推荐模板。本文为真实服务器视角，全部指令与回显已在 Ubuntu 22.04 上实测通过（2026-10-27）。

一、环境信息

项目	实测值
UnrealIRCd	6.2.7
安装路径	`/home/unrealircd/unrealircd/`
主配置文件	`conf/unrealircd.conf`
配置语法	块指令（block-based），大括号 `{ }` 包裹、分号 `;` 结尾
配置热重载	`./unrealircd rehash`（大部分 block 生效）
TLS 证书热替换	`./unrealircd reloadtls`（无需重启）

二、前置条件

配置语法基础：所有行以 ; 结尾，大括号 { } 包裹 block；注释支持三种风格 /* */、//、#；
修改前先备份：cp conf/unrealircd.conf conf/unrealircd.conf.bak；
修改后必须跑 ./unrealircd configtest 验证语法，通过后用 ./unrealircd rehash 热重载（或 ./unrealircd restart 硬重启）。

三、参数查看与修改方式

3.1 查看当前配置

cat conf/unrealircd.conf | less          # 直接查看
./unrealircd module-status                # 已加载模块列表（含版本号）
# IRC 客户端内用 /HELPOP 查具体命令帮助：
# /HELPOP CHMODES  /HELPOP OPER  /HELPOP SET

3.2 修改方式

nano conf/unrealircd.conf            # 编辑
./unrealircd configtest               # 验证语法
./unrealircd rehash                   # 热重载生效

3.3 配置热重载范围

block / 指令	rehash 能否生效	备注
me / admin	✅ 能	服务器身份热变（少见）
listen	❌ 不能	需重启
oper / vhost	✅ 能	权限热变
link	✅ 能	链接配置热变
set 大部分指令	✅ 能	大部分
set { cloak-keys }	❌ 不能	需重启
tls 证书	用 `reloadtls` 单独热替换	专用命令
blacklist / deny	✅ 能	热加载

四、参数总览

UnrealIRCd 6.2 的配置文件由 20+ 种 block 组成，按功能可分为以下 7 组：

分组	包含 block	核心作用
身份类	me / admin	服务器是谁、联系信息
认证/权限类	oper / allow / except / link	用户如何接入、谁是管理员
网络/监听类	listen / set{network}	监听哪些端口、网络名
安全/防御类	blacklist / deny / set{anti-flood,spamfilter}	反垃圾、反洪水、黑名单
功能开关类	loadmodule / include / set{modes,options}	模块加载、默认模式
服务器链接类	link	跨服务器网络拓扑
运维/辅助类	vhost / secret	运维辅助

五、核心参数分类详解

5.1 me block：服务器身份（必改）

这是 UnrealIRCd 启动时最先读的 block，定义"我是谁"。错误填写会导致服务器无法启动或网络中身份冲突。

me {
    name "irc.example.org";     # ← 改成你的 FQDN
    info "YourNET IRC Server";   # ← 网络名 + 描述
    sid "001";                   # ← 3 字符服务器 ID
}

指令	必填	默认值	说明
`name`	✅	`irc.example.org`	服务器 FQDN，IRC 网络中全局唯一；生产必须有 DNS A/AAAA 记录
`info`	✅	`ExampleNET Server`	一行描述，/INFO 命令可见
`sid`	✅	`001`	3 字符、数字开头、IRC 网络中全局唯一；多服务器网络每台必须不同

⚠️ SID 硬性约束：sid 必须以数字开头（[0-9][A-Za-z0-9]{2}），不能是纯字母。单机网络保持 001 即可。

5.2 admin block：联系信息（必改）

admin {
    "Bob Smith";           # 管理员真实姓名（/ADMIN 返回）
    "bob";                 # nick 或短名
    "bob@example.org";     # 管理员邮箱
}

三条字符串对应用户 /ADMIN 时看到的三行输出，无语法校验。

5.3 oper block：Oper 管理员账号（必改）

定义谁能通过 /OPER 升级为管理员。UnrealIRCd 禁止明文存密码，必须用 mkpasswd 生成 argon2 hash。

oper admin {
    class opers;                          # 引用的 class（modules.default.conf 预定义）
    mask *@*;                             # 允许哪个 ident@host 升级
    password "$argon2id$v=19$m=6144,t=2,p=2$jt7ZEjbYco5dChq2W4gKKQ$JJv6XnELQ4p12cBGGsDEabh6YCVBSPjG4gwtNBgQ1Ng";
    operclass netadmin;                   # 权限分级
    swhois "is a YourNET Administrator";  # /whois 显示的描述
    // vhost netadmin.yourdomain.com;     # 升级时自动分配的虚拟主机
}

指令	必填	说明
`class`	✅	引用的 class 名，决定 pingfreq/sendq 等参数；默认 `opers` 预定义
`mask`	✅	匹配规则，`@` 允许任何 ident/host；生产应收紧
`password`	✅	argon2id hash；禁止明文
`operclass`	✅	权限分级
`swhois`	❌	升级后 `/whois` 显示的描述字符串
`vhost`	❌	升级后自动赋予的虚拟主机名

密码 hash 生成实测：

./unrealircd mkpasswd
# Enter password to hash: q1w2e3r4
# Encrypted password is: $argon2id$v=19$m=6144,t=2,p=2$jt7ZEjbYco5dChq2W4gKKQ$JJv6XnELQ4p12cBGGsDEabh6YCVBSPjG4gwtNBgQ1Ng

operclass 权限分级对比：

operclass	能做什么
`netadmin`	全部（KILL/DIE/链接服务器/改配置）
`services-admin`	管理服务端链接、TKL、spamfilter
`netmoderator`	杀用户、封禁、管理频道
`chat-admin`	频道管理（+q/+a/+h）
`helper`	基本频道管理（+h/+o）
`IRCop`	仅获得 IRCOp 标识，无额外权限

5.4 listen block：监听端口

# 1. 纯文本端口（测试用）
listen { ip *; port 6667; }

# 2. TLS 客户端端口（**生产唯一推荐对外端口**）
listen { ip *; port 6697; options { tls; } }

# 3. 服务器间链接专用端口（TS6）
listen { ip *; port 6900; options { tls; serversonly; } }

指令	必填	说明
`ip`	✅	绑定的 IP；`*` = 所有 IPv4/IPv6；多网卡 VPS 应指定具体 IP
`port`	✅	监听端口
`options { tls; }`	❌	加上就是 TLS 端口
`options { serversonly; }`	❌	只接受服务器链接，不接受普通客户端
`options { clientsonly; }`	❌	只接受普通客户端
`options { webirc; }`	❌	允许 WebIRC 客户端接入（需 mod_webirc 加载）
`options { websocket; }`	❌	允许 WebSocket 客户端接入

⚠️ listen 不支持 rehash。改了 IP/端口/options 必须重启服务器。

5.5 set block：全局配置（两组）

第一组：网络身份（必改）

set {
    network-name       "YourNET";
    default-server     "irc.yourdomain.com";
    services-server    "services.yourdomain.com";
    stats-server       "stats.yourdomain.com";
    help-channel       "#Help";
    cloak-prefix       "Clk";
    cloak-keys {
        "./unrealircd gencloak 生成的 3 个 80 字符随机串";
    }
}

💡 cloak-keys 实测生成：./unrealircd gencloak 一次性吐出 3 个 80 字符随机串，直接复制粘贴。多服务器网络所有节点必须用同一组 keys。

第二组：服务器行为

set {
    kline-address "admin@yourdomain.com";
    modes-on-connect "+ixw";   # +i=隐藏 +x=主机遮蔽 +w=wallops
    modes-on-oper    "+xws";   # +s=服务器通知
    modes-on-join    "+nt";    # +n=消息不出频道 +t=只有 opers 改主题
    oper-auto-join "#opers";
    options { hide-ulines; show-connect-info; }
    maxchannelsperuser 10;
    anti-spam-quit-message-time 10s;
    anti-flood { channel { default-profile normal; } }
    spamfilter { ban-time 1d; ban-reason "Spam/Advertising"; virus-help-channel "#help"; }
    restrict-commands {
        list   { except { connect-time 60; identified yes; reputation-score 24; } }
        invite { except { connect-time 60; identified yes; } }
        knock  { except { connect-time 60; } }
    }
}

set 指令	默认值	说明
`kline-address`	`"set.this.to.email.address"`	被 K-line 封禁用户看到的联系邮箱
`modes-on-connect`	`+ixw`	用户刚连上时赋予的 usermode
`modes-on-oper`	`+xws`	Oper 升级时追加的 usermode
`modes-on-join`	`+nt`	新频道创建时的默认 channelmode
`maxchannelsperuser`	10	单用户最大频道数
`anti-flood::channel::default-profile`	normal	频道反洪水：normal（适中）/relaxed（宽松）/off（关闭）
`best-practices { hide-all; }`	—	隐藏 configtest 中的非关键 advice 提示

5.6 blacklist block：DNS 黑名单封禁

blacklist dronebl {
    dns { name dnsbl.dronebl.org; type record; reply { 3; 5; 6; 7; 8; 9; 10; 11; 12; 13; 14; 15; 16; } }
    action gline;       # gline = 全网封禁；block = 仅拒绝连接
    ban-time 24h;
    reason "Proxy/Drone detected. Check https://dronebl.org/lookup?ip=$ip";
}

⚠️ blacklist block 会触发外网 DNS 查询，企业代理/严格防火墙环境可能超时阻塞 configtest。若 configtest 卡住 15 秒以上，临时注释掉所有 blacklist block 再测。

5.7 link block：跨服务器链接

link irc.yourdomain.com
{
    incoming { mask *@*; }
    outgoing {
        bind-ip *;
        hostname irc.yourdomain.com;
        port 6900;
        options { tls; }
    }
}

生成对端配置：./unrealircd genlinkblock <对端 servername>。

5.8 allow block：允许访问

allow {
    mask *@*;
    maxperip 3;
}

单 IP 最多 3 个并发连接。

5.9 include 指令：模块化拆分

include "modules.default.conf";    # 约 150 个官方模块全开
include "operclass.default.conf";  # Oper 权限分级
include "help/help.conf";          # /HELPOP 帮助系统
include "badwords.conf";           # +G 脏话过滤
//include "spamfilter.conf";       # 按需启用

5.10 loadmodule / blacklist-module

loadmodule "cloak_sha256";          # 显式加载
// blacklist-module chanmodes { 'G'; 'S'; }   # 禁用特定频道模式

5.11 tls 证书配置

UnrealIRCd 6 的 TLS 证书不在独立 block——路径固定为 conf/tls/ 目录下：

文件	作用
`conf/tls/server.cert.pem`	服务器公钥证书
`conf/tls/server.key.pem`	服务器私钥
`conf/tls/dh.pem`	Diffie-Hellman 参数
`conf/tls/curl-ca-bundle.crt`	CA 根证书

六、生产推荐配置模板

适用：16GB 内存、NVMe SSD、50-200 在线用户的小型生产 IRC 网络。安全加固全部启用，明文端口已关闭。

include "modules.default.conf";
include "operclass.default.conf";
include "help/help.conf";
include "badwords.conf";
include "snomasks.default.conf";
loadmodule "cloak_sha256";

/* 身份 */
me {
    name "irc.yourdomain.com";
    info "YourNET — A friendly IRC community";
    sid "001";
}
admin { "YourNET Admin"; "admin"; "admin@yourdomain.com"; }

/* Oper 权限（mask 收紧为 admin@yourdomain.com）*/
oper admin {
    class opers;
    mask admin@yourdomain.com;
    password "$argon2id$v=19$m=6144,t=2,p=2$...$...";
    operclass netadmin;
    swhois "is YourNET Network Administrator";
    vhost netadmin.yourdomain.com;
}

/* 监听（仅 TLS！明文 6667 已注释掉）*/
//listen { ip *; port 6667; }
listen { ip *; port 6697; options { tls; } }
listen { ip *; port 6900; options { tls; serversonly; } }

/* DroneBL 黑名单（生产必开）*/
blacklist dronebl {
    dns { name dnsbl.dronebl.org; type record; reply { 3; 5; 6; 7; 8; 9; 10; 11; 12; 13; 14; 15; 16; } }
    action gline; ban-time 24h;
    reason "Proxy/Drone detected. Check https://dronebl.org/lookup?ip=$ip";
}

/* 网络身份 */
set {
    network-name "YourNET";
    default-server "irc.yourdomain.com";
    services-server "services.yourdomain.com";
    stats-server "stats.yourdomain.com";
    cloak-prefix "Clk";
    cloak-keys { "80字符串1"; "80字符串2"; "80字符串3"; }
}

/* 服务器行为 */
set {
    kline-address "admin@yourdomain.com";
    modes-on-connect "+ixw";
    modes-on-oper "+xws";
    modes-on-join "+nt";
    oper-auto-join "#opers";
    options { hide-ulines; show-connect-info; }
    maxchannelsperuser 10;
    anti-spam-quit-message-time 10s;
    anti-flood { channel { default-profile normal; } }
    spamfilter { ban-time 1d; ban-reason "Spam/Advertising"; virus-help-channel "#help"; }
    restrict-commands {
        list   { except { connect-time 60; identified yes; reputation-score 24; } }
        invite { except { connect-time 60; identified yes; } }
        knock  { except { connect-time 60; } }
        motd   { except { connect-time 10; } }
    }
    best-practices { hide-all; }
}

/* 允许同一 IP 最多 3 并发连接 */
allow { mask *@*; maxperip 3; }

已做的关键安全加固：

✅ 关闭明文 6667
✅ oper.mask 收紧为具体域名
✅ 开启 DroneBL 黑名单
✅ best-practices { hide-all; } 屏蔽 configtest advice
✅ chmod 600 conf/unrealircd.conf（不对外泄露 cloak-keys 和密码 hash）

七、常见问题

Q1: configtest 报 `unknown directive connect`

UnrealIRCd 6 移除了顶级 connect {} block。连接分级通过 oper { class opers; } 里的 class 名引用实现，class 内部由 modules.default.conf 预定义。

Q2: 改了 cloak-keys 但 /whois 显示的遮蔽主机没变

cloak-keys 是启动时读入的，不支持 rehash 热重载。改完后必须 ./unrealircd restart。

Q3: 如何禁用某个频道/用户模式？

blacklist-module chanmodes { 'G'; 'S'; }   # 禁用 +G 和 +S
blacklist-module usermodes { 'g'; }         # 禁用用户模式 +g

Q4: 配置文件里写中文注释会乱码吗？

不会——UnrealIRCd 内部用 UTF-8，nano 默认保存也是 UTF-8，中文注释和 MOTD 都能正常显示。

八、参考链接

资源	链接
官方 Configuration 文档总览	https://www.unrealircd.org/docs/Configuration
Configuration file syntax	https://www.unrealircd.org/docs/Configuration_file_syntax
set block（全部子项）	https://www.unrealircd.org/docs/Set_block
Anti-flood	https://www.unrealircd.org/docs/Anti-flood_settings
Blacklist block	https://www.unrealircd.org/docs/Blacklist_block
Link block	https://www.unrealircd.org/docs/Link_block
Spamfilter	https://www.unrealircd.org/docs/Spamfilter
JSON-RPC API	https://www.unrealircd.org/docs/JSON-RPC

本文按官方文档 6.2.x 配置体系组织，所有指令与回显基于 UnrealIRCd-6.2.7 实测（2026-10-27）。配置文件语法硬性要求：所有行以分号 ; 结尾、大括号 { } 必须闭合，遗漏任何一处都会导致服务器无法启动。

UnrealIRCd 6.2.7 配置参数详解

UnrealIRCd 6.2.7 配置参数详解

一、环境信息

二、前置条件

三、参数查看与修改方式

3.1 查看当前配置

3.2 修改方式

3.3 配置热重载范围

四、参数总览

五、核心参数分类详解

5.1 me block：服务器身份（必改）

5.2 admin block：联系信息（必改）

5.3 oper block：Oper 管理员账号（必改）

5.4 listen block：监听端口

5.5 set block：全局配置（两组）

第一组：网络身份（必改）

第二组：服务器行为

5.6 blacklist block：DNS 黑名单封禁

5.7 link block：跨服务器链接

5.8 allow block：允许访问

5.9 include 指令：模块化拆分

5.10 loadmodule / blacklist-module

5.11 tls 证书配置

六、生产推荐配置模板

七、常见问题

Q1: configtest 报 unknown directive connect

Q2: 改了 cloak-keys 但 /whois 显示的遮蔽主机没变

Q3: 如何禁用某个频道/用户模式？

Q4: 配置文件里写中文注释会乱码吗？

八、参考链接

Q1: configtest 报 `unknown directive connect`