Ergo 2.19 Docker Compose 部署指南

目标：用 Docker Compose 一键拉起 Ergo 2.19.1 IRC 服务器，完成初始化、配置自定义、TLS 验证与日常运维。全文基于官方镜像 ghcr.io/ergochat/ergo:stable（Ergo 2.19.1）实测通过。

一、环境信息

宿主操作系统：Ubuntu 22.04 LTS（x86_64）
Docker 版本：24.0+（compose v2 插件）
镜像：ghcr.io/ergochat/ergo:stable（实测镜像内版本 ergo-2.19.1-63c743a70644f0f1，镜像体积 56.2MB）
部署目录：/opt/ergo-stack（示例，可自定义）
端口映射：宿主 8138 → 容器 6697（TLS）、宿主 8139 → 容器 6667（明文）
数据卷：宿主 ./data → 容器 /ircd

二、镜像选型说明

Ergo 官方镜像发布在 GitHub Container Registry：

镜像地址	标签	架构	说明
`ghcr.io/ergochat/ergo`	`stable`	linux/amd64、linux/arm64	滚动指向最新稳定版
`ghcr.io/ergochat/ergo`	`v2.19.1`	linux/amd64、linux/arm64	固定版本标签

实测两个标签均存在且为多架构 manifest：

Name:      ghcr.io/ergochat/ergo:v2.19.1
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:ef885e44f7fa19101bbbc41baef11dc280dc8107465dccaf6f0860f41b48a682

选型建议：测试/尝鲜用 stable；生产环境建议固定到具体版本标签（如 v2.19.1），避免意外升级。

⚠️ 注意：部分网络环境下 docker.io 拉取受限，ghcr.io 可直连。若你的环境有镜像白名单，请将 ghcr.io 加入白名单或使用可访问 ghcr 的代理。

三、前置条件

已安装 Docker 与 Compose v2 插件：

docker --version
docker compose version

创建部署目录：

mkdir -p /opt/ergo-stack/data
cd /opt/ergo-stack

规划端口：本文示例将宿主 8138 映射到容器 6697（TLS）、8139 映射到 6667（明文）。生产环境可直接映射 6697:6697。

四、部署步骤

4.1 编写 docker-compose.yml

在 /opt/ergo-stack/docker-compose.yml 写入以下内容：

name: ergo-2.19-stack
services:
  server:
    image: ghcr.io/ergochat/ergo:stable
    container_name: ergo-2.19-server
    restart: unless-stopped
    ports:
      - "8138:6697"
      - "8139:6667"
    volumes:
      - /opt/ergo-stack/data:/ircd
    command: ["run"]

关键字段说明：

volumes：把容器内 /ircd（Ergo 的工作目录）持久化到宿主 ./data；首次启动时镜像会自动在卷内生成配置文件、证书与数据库；
command: ["run"]：镜像 entrypoint 为初始化脚本 run.sh（首次启动生成配置/证书后 exec /ircd-bin/ergo run），run 为镜像默认 CMD，显式写出便于阅读理解。

4.2 首次启动与自动初始化

cd /opt/ergo-stack
docker compose up -d
docker compose logs -f server

首次启动时，镜像 entrypoint 会自动完成三件事：生成 ircd.yaml、生成自签名 TLS 证书、初始化 ircd.db，并打印一组随机操作员密码（只在首次初始化时打印一次）：

Oper username:password is admin:JtMJAIfOvbV9loQOJ0by
2026/10/25 05:43:53 making self-signed certificates
2026/10/25 05:43:53  making cert for :6697 listener
2026/10/25 05:43:53   Certificate created at fullchain.pem : privkey.pem
2026-10-25T05:43:53.960Z : info  : server     : ergo-2.19.1-63c743a70644f0f1 starting
2026-10-25T05:43:53.960Z : info  : server     : Using config file : ircd.yaml
2026-10-25T05:43:53.960Z : info  : server     : Using datastore : ircd.db
2026-10-25T05:43:53.960Z : warn  : server     : database does not exist, creating it : ircd.db
2026-10-25T05:43:53.962Z : info  : listeners  : now listening on :6667, tls=false, proxy=false, tor=false, websocket=false.
2026-10-25T05:43:53.962Z : info  : listeners  : now listening on :6697, tls=true, proxy=false, tor=false, websocket=false.
2026-10-25T05:43:53.962Z : warn  : listeners  : Warning: your server is configured with public plaintext listener :6667. Consider disabling it for improved security and privacy.
2026-10-25T05:43:53.962Z : info  : server     : Server running

⚠️ 注意一：请立即记录日志中的 Oper username:password is admin:<随机密码>，这是 admin 操作员的初始密码；如需自定义，参见第六、七章修改 ircd.yaml 后重启。

⚠️ 注意二：与裸机 default.yaml 不同，镜像生成的默认配置将明文 :6667 监听在所有接口（日志中有明显警告）。生产环境若不需要公开明文，应在 ircd.yaml 中删除 :6667 监听或改为 127.0.0.1:6667。

4.3 验证容器状态

docker compose ps

实测回显：

ergo-2.19-server Up 17 minutes 0.0.0.0:8139->6667/tcp, [::]:8139->6667/tcp, 0.0.0.0:8138->6697/tcp, [::]:8138->6697/tcp

4.4 TLS 连通性验证

在宿主机执行：

echo Q | openssl s_client -connect 127.0.0.1:8138

实测回显（节选）：

subject=O=Ergo
New, TLSv1.3, Cipher is TLS_AES_128_GCM_SHA256
Protocol: TLSv1.3

说明 6697 端口的 TLS 服务已正常工作（自签名证书，O=Ergo）。

五、数据持久化说明

首次启动后，宿主 ./data 目录内容如下：

ls -la /opt/ergo-stack/data

-rw-r--r-- 1 root root  1131 Oct 25 13:43 fullchain.pem
-rw-r--r-- 1 root root   446 Oct 25 13:43 ircd.db
-rw------- 1 root root     0 Oct 25 13:43 ircd.lock
-rw-r--r-- 1 root root 54122 Oct 25 13:44 ircd.yaml
-rw------- 1 root root  1704 Oct 25 13:43 privkey.pem

⚠️ 注意：官方镜像默认以 root 身份运行 Ergo 进程，因此数据卷内文件属主为 root。如需降权运行，可在 compose 服务中追加 user: "1000:1000" 并预先 chown -R 1000:1000 /opt/ergo-stack/data。

各文件作用：

文件	作用	是否需备份
`ircd.yaml`	主配置文件	✅ 必须
`ircd.db`	BoltDB 数据库（账号、频道注册信息）	✅ 必须
`fullchain.pem` / `privkey.pem`	TLS 证书与私钥	✅ 建议
`ircd.lock`	进程锁文件（运行期）	❌ 不需要

💡 说明：账号与频道注册数据全部在 ircd.db 中；只要备份 ircd.yaml + ircd.db + 证书，即可在新机器上完整恢复服务。历史消息默认存内存不持久化（如需持久化需在 datastore 与 history.persistent 中配置 MySQL/PostgreSQL/SQLite，详见《Ergo 2.19 配置参数详解》）。

六、环境变量表

官方镜像本身不定义 PUID/PGID 等业务环境变量，但 Ergo 二进制支持配置项环境变量覆盖（默认配置中 allow-environment-overrides: true），格式为 ERGO__<段>__<键>，双下划线分隔嵌套层级。例如在 compose 中：

    environment:
      - ERGO__NETWORK__NAME=QuzuoNetDocker

等价于把 ircd.yaml 的 network.name 改为 QuzuoNetDocker。

七、配置参数说明（修改挂载配置）

推荐的自定义方式是直接编辑数据卷里的 ircd.yaml，修改后重启容器生效。

7.1 修改网络名与服务器名

cd /opt/ergo-stack/data
sed -i 's/name: ErgoTest/name: QuzuoNetDocker/' ircd.yaml
sed -i 's/name: ergo.test/name: irc2.quzuo-test.local/' ircd.yaml

7.2 修改 admin 操作员密码

在容器内生成 bcrypt 哈希（镜像内附带完整 ergo 二进制）：

docker exec ergo-2.19-server sh -c 'printf "q1w2e3r4\nq1w2e3r4\n" | /ircd-bin/ergo genpasswd --quiet --conf /ircd/ircd.yaml'

实测回显：

$2a$04$/08FsHesGIDzuWUhxs31K.m3aMCbpv1sUFU5NuOVrle.PrDoiUcTe

把该哈希写入 data/ircd.yaml 的 opers.admin.password 字段。

7.3 重启生效

cd /opt/ergo-stack
docker compose restart server

重启后证书会被复用（日志提示 Preexisting TLS cert and/or key files: fullchain.pem privkey.pem），数据库保留。用客户端连接宿主 8138 端口（TLS），可在注册握手的 001/005 数值中看到新的网络名与服务器名已生效：

:irc2.quzuo-test.local 001 dock8040 :Welcome to the QuzuoNetDocker IRC Network dock8040
:irc2.quzuo-test.local 002 dock8040 :Your host is irc2.quzuo-test.local, running version ergo-2.19.1-63c743a70644f0f1
:irc2.quzuo-test.local 005 dock8040 KICKLEN=390 MAXLIST=beI:100 MAXTARGETS=4 MODES MONITOR=100 MSGREFTYPES=msgid,timestamp NETWORK=QuzuoNetDocker NICKLEN=32 PREFIX=(qaohv)~&@%+ SAFELIST SAFERATE STATUSMSG=~&@%+ TARGMAX=NAMES:1,LIST:1,KICK:,WHOIS:1,USERHOST:10,PRIVMSG:4,TAGMSG:4,NOTICE:4,MONITOR:100 :are supported by this server

八、等价 docker run

不使用 Compose 时，等价命令为：

docker run -d \
  --name ergo-2.19-server \
  --restart unless-stopped \
  -p 8138:6697 \
  -p 8139:6667 \
  -v /opt/ergo-stack/data:/ircd \
  ghcr.io/ergochat/ergo:stable \
  run

九、常用运维命令

# 查看实时日志
docker compose logs -f server

# 重启服务（修改 ircd.yaml 后）
docker compose restart server

# 停止/启动
docker compose stop server
docker compose start server

# 进入容器执行 ergo 子命令（以 gentoken 为例）
docker exec ergo-2.19-server /ircd-bin/ergo gentoken

# 查看镜像内 ergo 版本
docker exec ergo-2.19-server /ircd-bin/ergo --version

# 升级镜像版本
docker compose pull
docker compose up -d

💡 说明：容器内 ergo 二进制位于 /ircd-bin/ergo，所有子命令（initdb/upgradedb/genpasswd/mkcerts 等）均可用，但需注意用 --conf /ircd/ircd.yaml 指向卷内配置；数据库升级（upgradedb）在 docker compose pull 换版本后建议执行一次（详见《Ergo 2.19 常用 CLI 命令与工具详解》）。

十、常见问题

Q1：首次启动日志里没有看到 admin 密码？

A：随机 oper 密码只在首次初始化（卷内无 ircd.yaml 时）打印一次。若错过，用第七章的方法生成新哈希写入 opers.admin.password 并重启即可。

Q2：修改 ircd.yaml 后配置没生效？

A：镜像 entrypoint 只在首次启动生成配置；之后的配置变更需要 docker compose restart server 重启，或向主进程发送 SIGHUP 热重载：

docker kill --signal=HUP ergo-2.19-server

同时确认你改的是宿主数据卷里的 ircd.yaml，而不是容器内其他路径。

Q3：明文 6667 有安全告警，如何关闭？

A：编辑 data/ircd.yaml，把 server.listeners 中的 ":6667": 一行删除或注释（镜像默认配置第 40 行附近），重启容器。之后只保留 TLS 6697。

Q4：数据卷里文件的属主是 root，正常吗？

A：正常。官方镜像默认以 root 身份运行 Ergo（容器内 PID 1 即 /ircd-bin/ergo run），生成的 ircd.yaml/ircd.db/证书均属 root。这不影响运行；如需降权，参考第五章的 user 字段说明。

Q5：如何把明文/TLS 端口改回标准 6667/6697？

A：直接改 compose 的 ports 为 "6667:6667"、"6697:6697"，注意 1024 以下/特权端口与端口冲突；改完 docker compose up -d 重建。

Q6：升级镜像后启动失败提示数据库版本问题？

A：进入容器执行 /ircd-bin/ergo upgradedb --conf /ircd/ircd.yaml（配置中 datastore.autoupgrade: true 时通常会自动升级并备份），再重启容器。

十一、参考链接

Ergo 官方网站：https://ergo.chat/
Ergo GitHub 仓库（含镜像发布）：https://github.com/ergochat/ergo
ghcr.io 镜像页：https://github.com/ergochat/ergo/pkgs/container/ergo
Ergo 官方手册：https://ergo.chat/manual.html