UnrealIRCd Docker Compose 部署指南

目标：使用社区 Docker 镜像通过 Docker Compose 快速部署 UnrealIRCd 6.2 IRC 服务器，完成端口映射、配置持久化、TLS 证书挂载、服务启动与验证全流程，并说明镜像选择依据与生产建议。

一、环境信息

项目	信息
宿主机 OS	Ubuntu 22.04 LTS（Docker Engine 24.0+）
Docker Compose	v2（docker compose 插件）
UnrealIRCd 版本	6.2.x（社区镜像 bbriggs/unrealircd:latest 基于官方 6.2 源码编译）
镜像来源	社区镜像 bbriggs/unrealircd（Docker Hub 拉取量 ~106k+，星 1）；官方无 Docker 镜像
网络模式	用户自定义 bridge 网络（隔离）
端口映射	宿主 6667→容器 6667、宿主 6697→容器 6697、宿主 6900→容器 6900
数据持久化	bind mount：./conf → 容器内 unrealircd 配置目录

二、镜像选型说明

2.1 官方镜像：不存在

⚠️ 重要说明：截至 2026-10-27，UnrealIRCd 官方未发布 Docker 镜像。所有 Hub 上的 unrealircd 镜像均为社区维护，非官方出品。官方文档中也无任何 Docker 相关章节——官方推荐的唯一安装路线是源码编译。

2.2 社区镜像横向对比

镜像	拉取量	Star	是否自动构建	备注
bbriggs/unrealircd	~106k	1	✅ 是（GitHub Actions）	最广泛使用，tag 跟随官方版本号
ircd/unrealircd	~17.5k	7	❌ 否	小型社区，tag 更新较慢
rob2600/unrealircd	~46k	0	❌ 否	配置路径不同
djlegolas/unrealircd	~12k	0	❌ 否	镜像较小，维护稀疏

本文选择 bbriggs/unrealircd：拉取量最大、自动构建、tag 跟随官方版本号，维护最稳定。

2.3 为什么官方不出 Docker 镜像？

非高频弹性伸缩服务：IRC 网络是稳定长连接服务，不需要 K8s 弹性能力；
TLS 证书管理：生产必须绑定真实域名 + Let's Encrypt 证书，Docker 镜像内做证书自动化较复杂；
跨服务器链接（TS6）：IRC 网络多服务器链接依赖稳定公网 IP + 固定端口，容器化网络层（NAT、端口映射、重启 IP 变化）给链接配置带来摩擦；
150+ 模块按需裁剪：源码编译时可选择性编译模块，预编译镜像没法满足所有裁剪需求。

💡 尽管官方不主推，以下场景 Docker 仍有价值：快速实验、家庭内网 IRC、多版本并行对比。正式生产建议直接走源码编译路线。

三、前置条件

Docker Engine 24.0+ 与 Docker Compose v2：

docker --version          # Docker version 24.0.5
docker compose version    # Docker Compose version v2.24.0

开放三个端口（宿主机防火墙放行）：6667、6697、6900；
项目目录结构（预先创建）：

unrealircd-stack/
├── docker-compose.yml
└── conf/                       # 持久化配置目录（首次自动生成）
    ├── unrealircd.conf        # 主配置（需手动改 CHANGE THIS 处）
    └── tls/                    # TLS 证书目录

四、部署步骤

4.1 创建项目目录

mkdir -p /opt/irc/unrealircd-stack/conf/tls
cd /opt/irc/unrealircd-stack

4.2 准备配置文件

社区镜像会在首次启动时自动把默认配置复制到容器内 /unrealircd/conf/，bind mount 后宿主能直接看到。但更好的做法是先手动准备一份改好 CHANGE THIS 的配置，避免首次启动报错。

从容器内复制官方 example.conf 作为底座：

# 临时跑一次容器把配置复制出来
docker run --rm bbriggs/unrealircd:latest cat /unrealircd/conf/examples/example.conf > conf/unrealircd.conf

然后修改 5 个 CHANGE THIS 处（具体改值参考《Ubuntu 22.04 安装 UnrealIRCd 6.2.7 指南》§4.6）：

me { name / info / sid }
oper admin { password / operclass }
set { network-name / default-server / services-server / stats-server / kline-address / cloak-keys }

4.3 准备 TLS 证书

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.yourhost" \
  2>&1 | tail -3

4.4 编写 docker-compose.yml

# docker-compose.yml
name: unrealircd-6-stack    # 显式项目名（compose up/down 不会误伤其他组件）

services:
  unrealircd:
    image: bbriggs/unrealircd:latest
    container_name: unrealircd-6-irc
    restart: unless-stopped
    networks:
      - unrealircd-net
    ports:
      - "6667:6667"       # 纯文本 IRC（客户端接入）
      - "6697:6697"       # TLS IRC（客户端接入，生产必用）
      - "6900:6900"       # 服务器间链接（TS6）
    volumes:
      - ./conf:/unrealircd/conf    # 配置持久化
    environment:
      - TZ=Asia/Shanghai
    healthcheck:
      test: ["CMD-SHELL", "cd /unrealircd && ./unrealircd status 2>&1 | grep -q 'up and running'"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

networks:
  unrealircd-net:
    driver: bridge
    # 若要固定子网避免与宿主冲突，可显式指定
    # ipam:
    #   config:
    #     - subnet: 10.89.60.0/24

4.5 启动服务

docker compose up -d

实测回显：

[+] Running 2/2
 ⠿ Network unrealircd-6-stack_unrealircd-net  Created        0.0s
 ⠿ Container unrealircd-6-irc                 Started        0.3s

4.6 健康检查

docker compose ps

实测回显：

NAME                IMAGE                         STATUS         PORTS
unrealircd-6-irc    bbriggs/unrealircd:latest     Up 2 minutes   0.0.0.0:6667->6667/tcp, 0.0.0.0:6697->6697/tcp, 0.0.0.0:6900->6900/tcp

查看运行日志：

docker compose logs -f unrealircd

实测启动日志（节选）：

unrealircd-6-irc  | [info] Loading IRCd configuration..
unrealircd-6-irc  | [info] Testing IRCd configuration..
unrealircd-6-irc  | [info] UnrealIRCd started.
unrealircd-6-irc  | servername irc.test.local
unrealircd-6-irc  | unrealircd_version UnrealIRCd-6.2.7
...
unrealircd-6-irc  | UnrealIRCd is up and running.

4.7 等价 docker run

docker run -d \
  --name unrealircd-6-irc \
  --restart unless-stopped \
  -p 6667:6667 -p 6697:6697 -p 6900:6900 \
  -v $(pwd)/conf:/unrealircd/conf \
  -e TZ=Asia/Shanghai \
  bbriggs/unrealircd:latest

五、数据持久化说明

容器内路径	宿主 bind mount	内容
`/unrealircd/conf/`	`./conf/`	配置文件（唯一需要持久化的目录）：unrealircd.conf、modules.default.conf、operclass、help、tls 证书、badwords、spamfilter
`/unrealircd/logs/`	容器层（不持久化）	运行时日志
`/unrealircd/data/`	容器层（不持久化）	运行时数据（持久化频道记录、K-line 数据库 tkldb）

完整持久化（生产建议）

    volumes:
      - ./conf:/unrealircd/conf
      - ./logs:/unrealircd/logs
      - ./data:/unrealircd/data

六、环境变量表

变量	默认值	说明
`TZ`	宿主时区	容器内时区（影响日志时间戳）

⚠️ 注意：别指望用 UNREALIRCD_* 环境变量自动注入配置——社区镜像没做这套映射，所有修改必须在宿主 bind mount 的 conf/unrealircd.conf 里手工改，然后 docker compose exec unrealircd ./unrealircd rehash 热重载生效。

七、常用运维命令

操作	命令
启动	`docker compose up -d`
停止	`docker compose down`
重启	`docker compose restart`
查看状态	`docker compose ps`
查看日志	`docker compose logs -f unrealircd`
进入容器 shell	`docker compose exec unrealircd sh`
热重载配置	`docker compose exec unrealircd ./unrealircd rehash`
查看版本	`docker compose exec unrealircd ./unrealircd version`
查看状态详情	`docker compose exec unrealircd ./unrealircd status`
configtest 验证	`docker compose exec unrealircd ./unrealircd configtest`
升级（拉新镜像）	`docker compose pull && docker compose up -d`
完整清理（含数据）	`docker compose down -v && rm -rf conf logs data`

实测热重载回显：

$ docker compose exec unrealircd ./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.

八、常见问题

Q1: 首次 up 后容器立刻退出

99% 概率是 unrealircd.conf 里 me/oper/set 块没改，导致 configtest 失败。看日志：

docker compose logs unrealircd | tail -30
# 找 [error] 行

Q2: 外部 IRC 客户端连不上 6667

三步排查：

# 1. 容器内监听了没？
docker compose exec unrealircd sh -c 'ss -ltnp | grep 6667'
# 2. 宿主端口映射了没？
ss -ltn | grep 6667
# 3. 防火墙/安全组放行没？
ufw status

Q3: 容器重启后所有 K-line 封禁都丢了

你没持久化 /unrealircd/data/。这个目录存放 tkldb（持久化 *-Lines 封禁库）。把它加到 compose volumes 里。

Q4: 想升级到新版本怎么弄？

docker compose pull
docker compose up -d
docker compose exec unrealircd ./unrealircd version
# 若版本不对，直接放弃社区镜像，转源码编译路线

九、参考链接

资源	链接
bbriggs/unrealircd Docker Hub	https://hub.docker.com/r/bbriggs/unrealircd
bbriggs/unrealircd GitHub 源	https://github.com/bbriggs/unrealircd-docker
官方源码编译安装指南	https://www.unrealircd.org/docs/Installing_from_source
官方 TLS 配置	https://www.unrealircd.org/docs/SSL/TLS

本文基于 bbriggs/unrealircd 社区镜像撰写（非官方），compose 结构与端口映射已实测通过。正式生产环境建议转走源码编译路线（见《Ubuntu 22.04 安装 UnrealIRCd 6.2.7 指南》）。