第 3 章：核心配置详解
第 3 章：核心配置详解
配置文件是 IRC 服务器的灵魂。本章以 UnrealIRCd 为主、其他服务端为辅，逐项解析核心配置。
3.1 配置文件结构概览
3.1.1 UnrealIRCd 配置文件层次
conf/
├── unrealircd.conf # 主配置文件（入口）
├── modules.default.conf # 默认模块加载
├── modules.optional.conf # 可选模块
├── operclass.default.conf # 默认操作类
├── help/ # 帮助文本
└── tls/ # TLS 证书目录
├── server.crt
└── server.key
UnrealIRCd 使用 include 指令来组织配置：
/* 主配置文件引用其他文件 */
include "modules.default.conf";
include "operclass.default.conf";
include "conf/aliases.conf";
include "conf/oper.conf";
include "conf/link.conf";
3.1.2 InspIRCd 配置文件层次
conf/
├── inspircd.conf # 主配置
├── links.conf # 服务器互联
├── opers.conf # 管理员配置
├── modules.conf # 模块加载
└── motd.txt # 每日消息
使用 <include> 指令：
<include file="conf/opers.conf">
<include file="conf/links.conf">
<include file="conf/modules.conf">
3.1.3 Ergo 配置文件
Ergo 使用单一 YAML 配置文件 ergo.yaml，结构更简洁：
server:
name: "irc.example.com"
# ...
listeners:
# ...
accounts:
# ...
channels:
# ...
3.2 监听端口配置
3.2.1 端口规划
| 端口 | 协议 | 用途 | 建议 |
|---|---|---|---|
| 6667 | TCP | IRC 明文连接 | 仅限本地/测试 |
| 6668 | TCP | IRC 明文连接（备用） | 仅限本地/测试 |
| 6669 | TCP | IRC TLS（旧习惯） | 可选 |
| 6697 | TCP | IRC TLS（标准） | 生产环境推荐 |
| 6690 | TCP | IRC TLS（备用） | 可选 |
| 8080 | TCP | WebSocket | Web 客户端 |
| 8443 | TCP | WebSocket TLS | Web 客户端推荐 |
| 6900 | TCP | 服务器互联 | Server-to-Server |
3.2.2 UnrealIRCd 端口配置
/* 标准客户端端口 */
listen {
ip 127.0.0.1; /* 仅本地（通过反向代理） */
port 6667;
options { clients; }
}
/* TLS 客户端端口 */
listen {
ip *;
port 6697;
options { clients; tls; }
}
/* WebSocket 端口 */
listen {
ip *;
port 8080;
options { clients; websocket; }
}
/* WebSocket TLS */
listen {
ip *;
port 8443;
options { clients; websocket; tls; }
}
/* 服务器互联端口 */
listen {
ip *;
port 6900;
options { serversonly; tls; }
}
3.2.3 InspIRCd 端口配置
<!-- 标准端口 -->
<bind address="0.0.0.0" port="6667" type="clients">
<!-- TLS 端口 -->
<bind address="0.0.0.0" port="6697" type="clients" ssl="openssl">
<!-- WebSocket -->
<module name="websocket">
<bind address="0.0.0.0" port="8080" type="clients" websocket="true">
<!-- 服务器互联 -->
<bind address="0.0.0.0" port="6900" type="servers" ssl="openssl">
3.2.4 Ergo 端口配置
listeners:
# 本地明文端口（仅调试用）
"127.0.0.1:6667":
# 不推荐生产使用
# TLS 端口
":6697":
tls:
cert: "/home/ergo/certs/server.crt"
key: "/home/ergo/certs/server.key"
# WebSocket TLS
":8443":
websocket: true
tls:
cert: "/home/ergo/certs/server.crt"
key: "/home/ergo/certs/server.key"
# Tor 隐藏服务端口（可选）
"127.0.0.1:6668":
tor: true
3.2.5 反向代理配置
生产环境中，建议在 IRC 服务器前放置 Nginx/Caddy 做反向代理（主要适用于 WebSocket）：
# /etc/nginx/sites-available/irc-websocket
server {
listen 8443 ssl;
server_name irc.example.com;
ssl_certificate /etc/letsencrypt/live/irc.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/irc.example.com/privkey.pem;
location /webirc {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 86400;
}
}
3.3 服务器信息配置
3.3.1 服务器标识
/* UnrealIRCd */
me {
name "irc.example.com"; /* 服务器域名 */
info "My IRC Server"; /* 服务器描述 */
sid "001"; /* 服务器 ID（3 位，网络唯一） */
}
<!-- InspIRCd -->
<server name="irc.example.com"
description="My IRC Server"
id="001"
network="MyIRCNet">
# Ergo
server:
name: "irc.example.com"
# sid 在 Ergo 中自动生成
SID（Server ID）规则:
| 位置 | 字符集 | 说明 |
|---|---|---|
| 第 1 位 | 数字 (0-9) 或字母 (A-Z, a-z) | 标识位 |
| 第 2-3 位 | 数字 (0-9) | 编号 |
示例：001, 0AB, A1B
3.3.2 网络信息
/* UnrealIRCd */
network {
name "MyIRCNet"; /* 网络名称 */
default-server 127.0.0.1; /* 默认服务器 */
services-server "services.example.com"; /* 服务包服务器 */
# hidden "*.hidden.example.com"; /* 隐藏服务器列表 */
/* 模式 */
modes-on-join "+nt"; /* 新频道默认模式 */
# cloak-keys { "key1"; "key2"; "key3"; } /* 隐藏主机密钥 */
}
3.3.3 MOTD（每日消息）
/* UnrealIRCd */
/* 方法 1：直接包含文件 */
include "conf/motd.txt";
/* 方法 2：指定文件 */
set {
motd "conf/motd.txt";
smotd "conf/smotd.txt"; /* 短 MOTD */
opermotd "conf/opermotd.txt"; /* 管理员 MOTD */
rules "conf/rules.txt";
}
MOTD 文件示例 (conf/motd.txt):
_ _ ____ ___ _____
| | | | _ \ / _ \| ___|
| | | | |_) | | | | |_
| |_| | _ <| |_| | _|
\___/|_| \_\\___/|_|
欢迎来到 MyIRCNet！
============================================
服务器时间: %T
您的主机: %u@%h
============================================
规则：
1. 尊重他人
2. 禁止垃圾消息
3. 禁止恶意软件传播
============================================
3.3.4 性能参数
/* UnrealIRCd */
set {
/* 连接限制 */
maxchannelsperuser 25; /* 每用户最大加入频道数 */
maxdccallow 10; /* DCC 白名单数 */
/* 超时设置 */
pingpong 60; /* Ping 间隔（秒） */
# 其他超时在 set::modes-on-connect 等处配置 */
}
# Ergo
server:
# 速率限制
casemapping: "ascii"
relaymsg:
# relay 消息配置
limits:
# 连接限制
max-nick-len: 32
ident-len: 20
channel-len: 64
away-len: 390
kick-reason-len: 390
topic-len: 390
away-count: 5
whowas-entries: 10
monitor-entries: 100
channels-per-client: 100
3.4 管理员（Oper）配置
3.4.1 权限模型
IRC 服务器的管理员被称为 Oper（Operator）。不同服务端的权限模型略有不同：
| 服务端 | 权限模型 | 说明 |
|---|---|---|
| UnrealIRCd | Operclass 系统 | 预定义权限类 + 自定义 |
| InspIRCd | 权限标志 | 基于 <type> 标签的权限组合 |
| Ergo | 内置权限 | 基于账户的分级权限 |
3.4.2 UnrealIRCd Oper 配置
/* 步骤 1：定义操作类 */
operclass netadmin {
parent netadmin; /* 继承默认的 netadmin 类 */
permissions {
/* 可以自定义额外权限 */
kill { ban; };
channel { override; };
}
}
/* 步骤 2：定义 Oper 账户 */
oper alice {
class clients;
operclass netadmin; /* 使用的操作类 */
/* 密码（使用 ./unrealircd mkpasswd 生成） */
password "$argon2id$v=19$m=65536,t=3,p=1$...";
/* 允许从哪些 IP 连接 */
mask {
*@127.0.0.1;
*@192.168.1.0/24;
*@203.0.113.0/24;
}
/* 登录后的虚拟主机 */
vhost "staff.example.com";
/* WHOIS 信息 */
swhois "Server Administrator";
/* 自动加入的频道 */
# auto-join "#opers #admin";
}
# 生成密码哈希
cd /home/unrealircd/unrealircd
./unrealircd mkpasswd
# 输入密码后会输出类似:
# $argon2id$v=19$m=65536,t=3,p=1$...
3.4.3 InspIRCd Oper 配置
<!-- 步骤 1：定义权限类型 -->
<type name="NetAdmin"
classes="OperChat BanControl HostCloak Shutdown ServerLink"
vhost="staff.example.com"
override="KICK MODE BAN TOPIC">
<!-- 步骤 2：定义 Oper 账户 -->
<oper name="alice"
hash="bcrypt"
password="$2a$10$..."
host="*@127.0.0.1 *@192.168.1.*"
type="NetAdmin"
# autologon="yes"
>
3.4.4 Ergo Oper 配置
Ergo 使用基于账户的管理员系统，没有传统的 Oper 机制：
# Ergo 中，账户管理员通过以下方式获取权限
opers:
alice:
# 账户名
account: "alice"
# 密码（可以使用 hashed 版本）
# password: "plaintext-password"
# 权限
class: "server-admin"
hidden: true # 隐藏 oper 状态
# 或者通过 API/命令行授予
# ./ergo oper add alice
3.4.5 Oper 登录与使用
/* 在 IRC 客户端中登录为 Oper */
/OPER alice <password>
/* 成功后会收到 */
:irc.example.com 381 yournick :You are now an IRC operator
/* Oper 专用命令 */
/REHASH /* 重载配置 */
/KILL <nick> <reason> /* 断开用户连接 */
/KLINE <user@host> <duration> :<reason> /* 临时封禁 */
/GLINE <user@host> <duration> :<reason> /* 全局封禁 */
/DIE <reason> /* 关闭服务器（极其危险！） */
/RESTART <reason> /* 重启服务器 */
/CONNECT <server> /* 连接到其他服务器 */
/SQUIT <server> /* 断开服务器连接 */
3.5 连接类（Class）配置
3.5.1 UnrealIRCd Class 配置
/* 服务器类（用于服务器互联） */
class servers {
pingfreq 90; /* Ping 频率（秒） */
connfreq 30; /* 重连间隔（秒） */
maxclients 10; /* 最大服务器数 */
sendq 20M; /* 发送队列大小 */
recvq 200k; /* 接收队列大小 */
}
/* 客户端类 */
class clients {
pingfreq 60; /* Ping 频率 */
maxclients 5000; /* 最大客户端数 */
sendq 300k; /* 发送队列 */
recvq 8k; /* 接收队列 */
}
/* 操作员类 */
class opers {
pingfreq 60;
maxclients 100;
sendq 1M;
recvq 32k;
}
3.5.2 允许/拒绝连接
/* 允许所有客户端 */
allow {
mask *@*;
class clients;
maxperip 3; /* 每个 IP 最多 3 个连接 */
# password "optional";
}
/* 特定 IP 范围的规则 */
allow {
mask *@192.168.1.0/24;
class clients;
maxperip 10; /* 内网用户可以更多连接 */
}
/* 拒绝特定 IP */
deny {
mask *@203.0.113.0/24;
reason "Banned network";
}
/* 拒绝旧客户端版本（安全防护） */
deny {
mask *@*;
version "<3.0"; /* 拒绝过于旧的客户端 */
reason "Your client is too old. Please update.";
}
3.6 Cloaking（主机掩码）
Cloaking 将用户的真实 IP 地址转换为看起来随机的主机名，保护用户隐私。
3.6.1 UnrealIRCd Cloaking 配置
/* 加载 cloaking 模块 */
loadmodule "cloak";
/* Cloaking 配置 */
set {
cloak-keys {
"KeyOne123456789"; /* 密钥 1（随机生成） */
"KeyTwo987654321"; /* 密钥 2 */
"KeyThree5678901234"; /* 密钥 3 */
}
cloak-method "ip"; /* 基于 IP 的掩码 */
}
# 生成随机密钥
openssl rand -hex 20
# 输出示例: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
效果:
真实 IP: 192.168.1.100
掩码后主机名: R3DKqB9Y7.example.com
3.6.2 Ergo Cloaking 配置
# Ergo 的 IP cloaking
server:
ip-cloaking:
enabled: true
netname: "example" # 掩码前缀
# 密钥在首次运行时自动生成
# 或手动指定:
# secret: "your-secret-key-here"
3.7 配置文件语法检查
修改配置后，务必先验证语法再重启：
# UnrealIRCd
/home/unrealircd/unrealircd/unrealircd configtest
# InspIRCd
/opt/inspircd/bin/inspircd --configtest
# Ergo（Go 二进制会在启动时自动检查）
./ergo validate
3.8 热重载配置
无需重启服务器即可应用大部分配置更改：
/* UnrealIRCd */
/REHASH /* 重载所有配置 */
/REHASH -global /* 所有服务器重载 */
/* InspIRCd */
/RELOAD /* 重载配置 */
/* Ergo */
/DIE /* Ergo 不支持热重载，需要重启 */
/* 建议使用 systemd restart */
# Ergo 优雅重启
sudo systemctl restart ergo
3.9 完整配置文件模板
3.9.1 UnrealIRCd 最小生产配置
/* === 模块加载 === */
loadmodule "cloak";
loadmodule "sasl";
loadmodule "websocket";
/* === 服务器信息 === */
me {
name "irc.example.com";
info "Production IRC Server";
sid "001";
}
admin {
"Alice <[email protected]>";
"Server Admin";
}
/* === 网络信息 === */
network {
name "ExampleNet";
modes-on-join "+nt";
cloak-keys { "key1abc123"; "key2def456"; "key3ghi789"; }
}
/* === 监听端口 === */
listen { ip *; port 6697; options { clients; tls; } }
listen { ip *; port 8443; options { clients; tls; websocket; } }
listen { ip *; port 6900; options { serversonly; tls; } }
/* === TLS === */
tls {
certificate "/etc/letsencrypt/live/irc.example.com/fullchain.pem";
key "/etc/letsencrypt/live/irc.example.com/privkey.pem";
protocols "TLSv1.2 TLSv1.3";
}
/* === 类定义 === */
class servers { pingfreq 60; maxclients 10; sendq 20M; }
class clients { pingfreq 60; maxclients 5000; sendq 300k; }
class opers { pingfreq 60; maxclients 100; sendq 1M; }
/* === 连接规则 === */
allow { mask *@*; class clients; maxperip 3; }
/* === 管理员 === */
oper alice {
class opers;
operclass netadmin;
password "$argon2id$...";
mask { *@127.0.0.1; *@203.0.113.10; };
vhost "staff.example.com";
}
/* === 全局设置 === */
set {
kline-address "[email protected]";
modes-on-join "+nt";
default-bantime 86400;
}
/* === 日志 === */
log { source { *; } destination { file "logs/unrealircd.log"; } }
/* === 包含其他配置 === */
include "modules.default.conf";
include "operclass.default.conf";
3.10 ⚠️ 常见配置错误
| 错误 | 原因 | 解决方案 |
|---|---|---|
Cannot bind to port | 端口被占用 | ss -tlnp | grep :6697，杀死占用进程 |
TLS certificate not found | 证书路径错误 | 检查文件路径和权限 |
SID already in use | SID 重复 | 每个服务器使用唯一的 SID |
Password mismatch | Oper 密码错误 | 使用正确的密码哈希工具 |
No permissions | 权限不足 | 检查 operclass 权限定义 |
Configuration error | 语法错误 | 运行 configtest 定位错误 |
扩展阅读
- 📖 UnrealIRCd Configuration Docs
- 📖 InspIRCd Configuration Docs
- 📖 Ergo Configuration Docs
- 📖 Let’s Encrypt 证书申请
下一章: 第 4 章：频道管理 — 学习频道创建、模式设置、主题管理、密钥保护和用户限制。