Ubuntu 22.04 安装 Ergo 2.19 指南

目标：在 Ubuntu 22.04 LTS 服务器上完成 Ergo 2.19.1 的从零安装、基础配置、systemd 托管与功能验证。全文命令与回显均来自真实环境实测，默认安装路径为 /opt/ergo。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64）
软件版本：Ergo 2.19.1（2026-08-04 发布）
安装路径：/opt/ergo
运行用户：ergo（系统专用用户，非 root）
监听端口：6667（明文，默认仅回环）、6697（TLS，全接口）
数据文件：/opt/ergo/ircd.db（BoltDB 内嵌数据库）
配置文件：/opt/ergo/ircd.yaml
测试域名：irc.quzuo-test.local（请替换为实际域名）

二、前置条件

开始前请确认系统满足以下条件：

已取得 root 或 sudo 权限；
系统时间准确（TLS 证书依赖时间）：
```
timedatectl status
```
如使用域名访问，请提前配置 DNS A/AAAA 记录指向本机；仅内网测试可在客户端 hosts 中绑定；
防火墙放行 6697（如需公开明文服务再额外放行 6667）：
```
ufw allow 6697/tcp
```

⚠️ 注意：本文所有操作均在真实 Ubuntu 22.04 服务器视角书写。若你在本地虚拟机或云主机上操作，请确保该环境具备 systemd（多数云镜像默认支持）。

三、版本选型说明

Ergo 官方同时提供预编译二进制包与源码两种获取方式：

方案	获取方式	优点	缺点	适用场景
A. 官方预编译二进制	GitHub Releases 下载 tar.gz	无需编译环境，10 分钟完成；官方签名校验	需能访问 GitHub（或镜像代理）	绝大多数生产部署
B. Go 源码编译	`go install` 或克隆 stable 分支构建	可自定义 build tags、交叉编译	需要 Go 1.24+ 工具链；编译耗时	需要定制功能或平台无预编译包

本文默认推荐方案 A，方案 B 作为备用。两种方案最终都会得到同一个 ergo 二进制文件。

💡 技术拓展：Ergo 的构建标签（build tags）控制着可选功能是否编入二进制：i18n（非 ASCII 昵称/频道名）、mysql、postgresql、sqlite（历史持久化后端）。官方预编译包默认已包含全部标签；源码编译时可通过 ERGO_BUILD_TAGS 裁剪。

四、在线安装方案（A：官方预编译二进制）

4.1 方案说明

从 Ergo GitHub Releases 下载对应平台的 tar.gz，校验 SHA-256 后解压到 /opt/ergo。这是官方推荐的生产部署方式。

4.2 下载与校验

# 安装基础工具
apt update
apt install -y wget ca-certificates

# 下载 Ergo 2.19.1 linux-x86_64 包
# 注意：GitHub 直连受限时，可经 ghproxy.net 镜像代理下载
wget https://ghproxy.net/https://github.com/ergochat/ergo/releases/download/v2.19.1/ergo-2.19.1-linux-x86_64.tar.gz

# 下载官方校验文件
wget https://gh-proxy.com/https://github.com/ergochat/ergo/releases/download/v2.19.1/ergo-2.19.1-checksums.txt

# 校验完整性
sha256sum -c ergo-2.19.1-checksums.txt 2>&1 | grep linux-x86_64

实测回显：

ergo-2.19.1-linux-x86_64.tar.gz: OK

⚠️ 注意：若 ghproxy.net 不可用，可替换为其他 GitHub 镜像代理；下载后务必执行 sha256sum -c 校验，防止中间人篡改。

4.3 解压与安装

# 解压
tar -xzf ergo-2.19.1-linux-x86_64.tar.gz

# 移动到安装目录
mv ergo-2.19.1-linux-x86_64 /opt/ergo
cd /opt/ergo

# 查看文件构成
ls -l

实测回显：

total 18836
-rw-r--r-- 1 root root    54196 Oct 25 05:38 default.yaml
drwxr-xr-x 2 root root     4096 Oct 25 05:38 docs
-rwxr-xr-x 1 root root 19083426 Oct 25 05:38 ergo
-rw-r--r-- 1 root root     1773 Oct 25 05:38 ergo.motd
drwxr-xr-x 2 root root    12288 Oct 25 05:38 languages
-rw-r--r-- 1 root root    52355 Oct 25 05:38 traditional.yaml

4.4 验证二进制可用性

./ergo --version

实测回显：

ergo-2.19.1

./ergo --help

实测回显（节选）：

ergo.
Usage:
	ergo initdb [--conf <filename>] [--quiet]
	ergo upgradedb [--conf <filename>] [--quiet]
	ergo importdb <database.json> [--conf <filename>] [--quiet]
	ergo genpasswd [--conf <filename>] [--quiet]
	ergo mkcerts [--conf <filename>] [--quiet]
	ergo defaultconfig
	ergo gentoken
	ergo run [--conf <filename>] [--quiet] [--smoke]
	ergo -h | --help
	ergo --version

五、源码编译方案（B：Go 源码编译）

5.1 方案说明

当预编译包没有覆盖目标平台，或需要自定义 build tags 时，可从源码编译。Ergo 官方建议构建 stable 分支（对应最新稳定 tag）。

5.2 安装 Go 工具链

# Ubuntu 22.04 仓库中的 Go 版本较旧，建议安装官方 Go 1.24+
wget https://go.dev/dl/go1.24.7.linux-amd64.tar.gz
rm -rf /usr/local/go
tar -C /usr/local -xzf go1.24.7.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> /etc/profile
source /etc/profile
go version

实测回显：

go version go1.24.7 linux/amd64

5.3 编译安装

# 方式一：直接 go install stable 分支（最简）
go install github.com/ergochat/ergo@stable

# 编译产物默认在 ~/go/bin/ergo
ls -l ~/go/bin/ergo

# 移动到安装目录
mkdir -p /opt/ergo
mv ~/go/bin/ergo /opt/ergo/

如需启用 MySQL 历史持久化等可选功能，可指定 build tags：

git clone --branch stable https://github.com/ergochat/ergo.git
cd ergo
ERGO_BUILD_TAGS="i18n mysql postgresql sqlite" make build
cp ergo /opt/ergo/

5.4 准备配置文件与语言包

源码编译不会自动生成 default.yaml 和 languages/，需要从官方仓库或预编译包中提取：

# 从预编译包中复制配置模板与语言文件（假设已下载 tar.gz）
tar -xzf ergo-2.19.1-linux-x86_64.tar.gz
cp ergo-2.19.1-linux-x86_64/default.yaml /opt/ergo/
cp ergo-2.19.1-linux-x86_64/traditional.yaml /opt/ergo/
cp ergo-2.19.1-linux-x86_64/ergo.motd /opt/ergo/
cp -r ergo-2.19.1-linux-x86_64/languages /opt/ergo/
cp -r ergo-2.19.1-linux-x86_64/docs /opt/ergo/

六、方案对比与选择建议

维度	方案 A：预编译二进制	方案 B：源码编译
安装耗时	约 5–10 分钟	约 15–30 分钟（含 Go 安装）
磁盘占用	约 20 MB	需额外下载 Go 工具链与源码，约 500 MB+
依赖	无外部依赖	需要 Go 1.24+ 环境
定制能力	不可裁剪 build tags	可自由组合 i18n/mysql/postgresql/sqlite
升级便利性	替换二进制即可	需重新编译
推荐度	★★★★★ 生产首选	★★★☆☆ 定制/无预编译平台时使用

选择建议：除非需要自定义 build tags 或目标平台无官方包，否则一律使用方案 A。

七、配置说明

无论采用哪种方案，安装完成后都需要进行以下基础配置。

7.1 复制并编辑主配置

cd /opt/ergo
cp default.yaml ircd.yaml

编辑 ircd.yaml，重点修改以下三处：

# 1. 网络名称（第 28 行附近）
network:
    name: QuzuoNet        # 改为你自己的网络名，如 MyNet

# 2. 服务器主机名（第 33 行附近）
server:
    name: irc.quzuo-test.local   # 改为实际域名或主机名

# 3. 操作员密码（第 781 行附近）
opers:
    admin:
        password: "$2a$04$wAWgmjBva8j3nNFGZEsmD.lfoLd2wf6OYFDPHmkSS1Wkux1o0v5X2"

7.2 生成操作员密码哈希

不要直接写入明文密码，先用 ergo genpasswd 生成 bcrypt 哈希：

cd /opt/ergo
printf "q1w2e3r4\nq1w2e3r4\n" | ./ergo genpasswd --quiet

实测回显：

$2a$04$wAWgmjBva8j3nNFGZEsmD.lfoLd2wf6OYFDPHmkSS1Wkux1o0v5X2

将输出的哈希字符串填入 ircd.yaml 的 opers.admin.password 字段。

💡 说明：genpasswd 每次输出不同（随机盐），只要对应明文是 q1w2e3r4 即可。生产环境请使用强口令。

7.3 生成自签名 TLS 证书

cd /opt/ergo
./ergo mkcerts

首次执行会生成 fullchain.pem 与 privkey.pem。再次执行时会提示已存在：

2026/10/25 05:59:56 making self-signed certificates
2026/10/25 05:59:56  making cert for :6697 listener
2026/10/25 05:59:56 Preexisting TLS cert and/or key files: fullchain.pem privkey.pem

查看证书信息：

openssl x509 -in /opt/ergo/fullchain.pem -noout -subject -dates

实测回显：

subject=O = Ergo
notBefore=Oct 25 05:39:19 2026 GMT
notAfter=Oct 25 05:39:19 2027 GMT

⚠️ 注意：自签名证书有效期一年，客户端会提示不受信任。生产环境建议替换为 Let's Encrypt 等受信证书，只需把 fullchain.pem/privkey.pem 替换为真实证书路径即可。

7.4 初始化数据库

cd /opt/ergo
./ergo initdb

正常无输出（--quiet 模式下）。重复执行会报错，说明数据库已存在：

2026/10/25 05:55:02 Error while initializing db:Datastore already exists (delete it manually to continue): ircd.db

7.5 创建专用运行用户

useradd -r -s /usr/sbin/nologin -d /opt/ergo ergo
chown -R ergo:ergo /opt/ergo

八、systemd 托管

8.1 创建服务单元

创建 /etc/systemd/system/ergo.service：

[Unit]
Description=Ergo IRC server
After=network.target

[Service]
Type=simple
User=ergo
Group=ergo
WorkingDirectory=/opt/ergo
ExecStart=/opt/ergo/ergo run --conf /opt/ergo/ircd.yaml
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

8.2 启动并设置开机自启

systemctl daemon-reload
systemctl enable ergo
systemctl start ergo

8.3 验证服务状态

systemctl status ergo --no-pager

实测回显：

● ergo.service - Ergo IRC server
     Loaded: loaded (/etc/systemd/system/ergo.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-25 05:51:23 UTC; 3min 38s ago
    Process: 958 ExecReload=/bin/kill -HUP $MAINPID (code=exited, status=0/SUCCESS)
   Main PID: 942 (ergo)
      Tasks: 12 (limit: 3612)
     Memory: 8.2M
        CPU: 65ms
     CGroup: /system.slice/ergo.service
             └─942 /opt/ergo/ergo run --conf /opt/ergo/ircd.yaml

九、验证回显

9.1 监听端口验证

ss -lntp | grep -E "6667|6697"

实测回显：

LISTEN 0      4096       127.0.0.1:6667       0.0.0.0:*    users:(("ergo",pid=942,fd=9))
LISTEN 0      4096               *:6697             *:*    users:(("ergo",pid=942,fd=8))
LISTEN 0      4096           [::1]:6667          [::]:*    users:(("ergo",pid=942,fd=7))

默认配置下，明文 6667 仅监听回环，TLS 6697 监听所有接口。

9.2 查看启动日志

journalctl -u ergo --no-pager -n 20

实测回显（节选）：

Oct 25 05:51:23 irc.quzuo-test.local ergo[942]: 2026-10-25T05:51:23.591Z : info  : server     : ergo-2.19.1 starting
Oct 25 05:51:23 irc.quzuo-test.local ergo[942]: 2026-10-25T05:51:23.591Z : info  : server     : Using config file : /opt/ergo/ircd.yaml
Oct 25 05:51:23 irc.quzuo-test.local ergo[942]: 2026-10-25T05:51:23.592Z : info  : listeners  : now listening on 127.0.0.1:6667, tls=false, proxy=false, tor=false, websocket=false.
Oct 25 05:51:23 irc.quzuo-test.local ergo[942]: 2026-10-25T05:51:23.592Z : info  : listeners  : now listening on :6697, tls=true, proxy=false, tor=false, websocket=false.
Oct 25 05:51:23 irc.quzuo-test.local ergo[942]: 2026-10-25T05:51:23.592Z : info  : server     : Server running

9.3 IRC 客户端连接验证

使用任意 IRC 客户端（如 HexChat、Irssi、WeeChat）连接 irc.quzuo-test.local:6697（TLS），接受自签名证书。以下用 openssl s_client 模拟握手：

openssl s_client -connect 127.0.0.1:6697 -servername irc.quzuo-test.local

连接成功后发送：

NICK guest01
USER guest01 0 * :guest01

服务器会返回 001–005 注册欢迎消息：

:irc.quzuo-test.local 001 guest8233 :Welcome to the QuzuoNet IRC Network guest8233
:irc.quzuo-test.local 002 guest8233 :Your host is irc.quzuo-test.local, running version ergo-2.19.1
:irc.quzuo-test.local 005 guest8233 AWAYLEN=390 BOT=B CASEMAPPING=ascii CHANLIMIT=#:100 CHANMODES=Ibe,k,fl,CEMRUimnstu CHANNELLEN=64 CHANTYPES=# CHATHISTORY=1000 ELIST=U EXCEPTS EXTBAN=,m FORWARD=f INVEX :are supported by this server

9.4 账号注册与 SASL 登录

连接后向 NickServ 注册账号：

PRIVMSG NickServ :REGISTER q1w2e3r4

实测回显：

:NickServ!NickServ@localhost NOTICE bob2131 :Account created
:NickServ!NickServ@localhost NOTICE bob2131 :You're now logged in as bob2131

账号注册后，昵称会被保留。未登录时直接使用该昵称会被拒绝：

:irc.quzuo-test.local 433 * alice :Nickname is reserved by a different account

之后连接需通过 SASL PLAIN 认证。以账号 alice、密码 q1w2e3r4 为例，base64 编码为 YWxpY2UAYWxpY2UAcTF3MmUzcjQ=：

CAP REQ :sasl
AUTHENTICATE PLAIN
AUTHENTICATE YWxpY2UAYWxpY2UAcTF3MmUzcjQ=

实测回显：

:irc.quzuo-test.local 900 * * alice :You are now logged in as alice
:irc.quzuo-test.local 903 * :Authentication successful

9.5 注册频道与获取操作员权限

登录后创建并注册频道：

JOIN #general
PRIVMSG ChanServ :REGISTER #general

实测回显：

:ChanServ!ChanServ@localhost NOTICE alice :Channel #general successfully registered
:ChanServ!ChanServ@localhost MODE #general +q alice

使用配置文件中设置的 admin 密码获取 IRC 操作员权限：

OPER admin q1w2e3r4

实测回显：

:irc.quzuo-test.local 381 alice :You are now an IRC operator
:irc.quzuo-test.local MODE alice +o

执行 WHOIS alice 可看到操作员标识、安全连接标识与登录账号：

:irc.quzuo-test.local 311 alice alice ~u qiy953an8yvpe.irc * alice
:irc.quzuo-test.local 313 alice alice :is the server administrator
:irc.quzuo-test.local 671 alice alice :is using a secure connection
:irc.quzuo-test.local 330 alice alice alice :is logged in as

十、常见问题

Q1：启动时报错 failed to acquire flock on ircd.lock

A：说明已有另一个 Ergo 进程在运行。检查方式：

systemctl status ergo
pgrep -a ergo

若确认无其他实例但锁文件残留，可停止服务后删除 /opt/ergo/ircd.lock 再启动。

Q2：客户端提示证书不受信任

A：默认生成的是自签名证书。生产环境应替换为受信 CA 证书，或在客户端手动添加信任。替换证书后执行 systemctl reload ergo 即可热加载。

Q3：明文 6667 无法从外网连接

A：这是默认安全策略。default.yaml 中明文仅监听 127.0.0.1 与 [::1]。如需公开明文服务，编辑 ircd.yaml，将 server.listeners 中的 "127.0.0.1:6667" 与 "[::1]:6667" 注释掉，改为 ":6667":，然后 systemctl reload ergo。

Q4：如何修改网络名后不停机生效？

A：编辑 ircd.yaml 后执行 systemctl reload ergo，日志会出现 Rehash completed successfully。绝大多数配置（网络名、监听、账号策略、历史限制）支持热重载。

Q5：密码输错多次后无法 OPER

A：Ergo 默认对 OPER 有 10 秒节流（server.oper-throttle），连续失败需等待后重试。这是防暴力破解的正常行为。

Q6：下载速度慢或 GitHub 无法访问

A：可使用镜像代理下载，例如：

wget https://ghproxy.net/https://github.com/ergochat/ergo/releases/download/v2.19.1/ergo-2.19.1-linux-x86_64.tar.gz
wget https://gh-proxy.com/https://github.com/ergochat/ergo/releases/download/v2.19.1/ergo-2.19.1-checksums.txt

下载后务必执行 sha256sum -c 校验。

十一、卸载与清理

如需完全移除 Ergo，按以下步骤执行：

# 1. 停止并禁用服务
systemctl stop ergo
systemctl disable ergo

# 2. 删除 systemd 单元
rm -f /etc/systemd/system/ergo.service
systemctl daemon-reload

# 3. 删除程序与数据
rm -rf /opt/ergo

# 4. 删除运行用户（可选）
userdel ergo

# 5. 关闭防火墙端口（如之前放行过）
ufw delete allow 6697/tcp

十二、参考链接

Ergo 官方网站：https://ergo.chat/
Ergo GitHub Releases：https://github.com/ergochat/ergo/releases
Ergo 官方手册：https://ergo.chat/manual.html
Ergo 构建指南：https://github.com/ergochat/ergo/blob/stable/docs/BUILD.md