Ergo 2.19 常用 CLI 命令与工具详解

详解 Ergo 2.19.1 单二进制 CLI 的全部子命令：initdb/upgradedb/importdb/genpasswd/mkcerts/defaultconfig/gentoken/run --smoke 与 --help/--version，每条命令给出真实参数、实测回显、使用场景与常见错误处理。

ErgoErgoIRC2026/10/25

Ergo 2.19 常用 CLI 命令与工具详解

目标：掌握 Ergo 2.19.1 命令行工具的全部子命令与真实用法。Ergo 采用单二进制设计，所有管理操作均通过 ergo <子命令> 完成，无独立的管理 CLI。全文命令与回显均来自 /opt/ergo 目录下的实测。

一、环境信息

  • 软件版本：Ergo 2.19.1
  • 安装路径：/opt/ergo
  • 配置文件：/opt/ergo/ircd.yaml
  • 数据库文件：/opt/ergo/ircd.db
  • 证书文件：/opt/ergo/fullchain.pem / /opt/ergo/privkey.pem
  • 运行用户：ergo

二、工具概览

Ergo 只有一个可执行文件 ergo，支持以下子命令：

子命令作用
initdb初始化 BoltDB 数据库文件
upgradedb升级数据库 schema 到当前版本
importdb从 JSON 导出文件导入数据库
genpasswd生成 bcrypt 密码哈希（用于配置 opers/password）
mkcerts生成自签名 TLS 证书
defaultconfig输出当前版本的默认配置到 stdout
gentoken生成高强度随机令牌（用于 API bearer token 等）
run启动 IRC 服务器主进程
run --smoke冒烟测试：启动并验证监听后立即退出
--help / -h显示帮助
--version显示版本

三、前置条件

  • 已进入 Ergo 安装目录：cd /opt/ergo；
  • 当前用户对 ircd.yaml、ircd.db、证书文件有读写权限；
  • 若使用 systemd 托管，注意 run --smoke 与正在运行的服务存在锁冲突（详见常见问题 Q1）。

四、各工具详解

4.1 ergo --version

显示当前二进制版本。

./ergo --version

实测回显：

ergo-2.19.1

4.2 ergo --help

显示全部子命令与全局参数。

./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
Options:
	--conf <filename>  Configuration file to use [default: ircd.yaml].
	--quiet            Don't show startup/shutdown lines.
	-h --help          Show this screen.
	--version          Show version.

全局参数说明：

  • --conf <filename>：指定配置文件路径，默认当前目录下的 ircd.yaml；
  • --quiet：抑制启动/关闭横幅，适合脚本化调用。

4.3 ergo initdb

初始化数据库文件 ircd.db，存放账号、频道注册等持久化数据。仅在首次安装时执行一次。

./ergo initdb

正常执行时无输出（--quiet 模式下完全静默）。若数据库已存在，会报错：

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

⚠️ 注意：不要试图通过反复执行 initdb 来"重置"数据库；如需重建，先备份现有 ircd.db，再删除它后执行 initdb。

4.4 ergo upgradedb

在升级 Ergo 二进制版本后，将数据库 schema 升级到当前版本。datastore.autoupgrade: true（默认）时通常会自动完成，此命令作为兜底。

./ergo upgradedb

实测回显：

2026/10/25 05:55:02 database upgraded:  ircd.db

若数据库已是最新，执行同样会输出升级完成（内部检测到 schema 一致即视为成功）。

4.5 ergo importdb

从 JSON 文件导入数据库内容。用于跨版本迁移或从备份恢复。

./ergo importdb /path/to/backup.json

要求目标数据库为空。若 ircd.db 已存在，会报错：

2026/10/25 05:59:56 Error while importing db:Datastore already exists (delete it manually to continue): ircd.db

💡 说明：导出功能需通过运行时管理命令或 API 完成（如 NICKSERV EXPORT 需 oper 权限），importdb 只负责导入。

4.6 ergo genpasswd

生成 bcrypt 密码哈希，用于写入 ircd.yaml 的 opers.<name>.password 或 server.password。

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

实测回显：

$2a$04$wAWgmjBva8j3nNFGZEsmD.lfoLd2wf6OYFDPHmkSS1Wkux1o0v5X2

说明：

  • 命令从 stdin 读取两行密码并确认一致；
  • 输出可直接粘贴到 YAML 配置中；
  • 每次执行因随机盐不同，哈希值会变化，但对应明文均为 q1w2e3r4。

4.7 ergo mkcerts

生成自签名 TLS 证书（fullchain.pem 与 privkey.pem），供 6697 TLS 监听器使用。

./ergo mkcerts

首次执行会生成证书；再次执行会提示已存在并复用：

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 fullchain.pem -noout -subject -dates

实测回显：

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

⚠️ 注意：自签名证书有效期一年，客户端会提示不受信任。生产环境建议替换为受信 CA 证书，替换后执行 systemctl reload ergo 热加载。

4.8 ergo defaultconfig

将当前二进制的完整默认配置输出到 stdout，可用于比对版本差异或重新生成配置模板。

./ergo defaultconfig

输出即 default.yaml 的全部 1227 行内容，以下为输出节选（实测首尾）：

# This is the default config file for Ergo.
# It contains recommended defaults for all settings, including some behaviors
# that differ from conventional ircd+services setups. See traditional.yaml
# for a config with more "mainstream" behavior.
...

使用场景：

  • 升级版本后比对配置差异：diff ircd.yaml <(./ergo defaultconfig)；
  • 配置损坏时快速重建。

4.9 ergo gentoken

生成高强度随机令牌，用于 HTTP API 的 bearer-tokens、extjwt 等需要共享密钥的字段。

./ergo gentoken

实测回显：

6wyjfMxeBj8T95u1JDnqXZ6rbf59m7GsZJk6DTg9kcA

输出为 43 字符的 URL-safe 随机串，可直接复制到 api.bearer-tokens 列表。

4.10 ergo run

启动 IRC 服务器主进程。

./ergo run

正常启动后日志输出到 stderr（或配置指定的文件），进程保持前台运行。生产环境应通过 systemd 托管：

systemctl start ergo
systemctl status ergo

实测 systemd 状态回显：

● 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
   Main PID: 942 (ergo)
     Memory: 8.2M
     CGroup: /system.slice/ergo.service
             └─942 /opt/ergo/ergo run --conf /opt/ergo/ircd.yaml

4.11 ergo run --smoke

冒烟测试模式：启动进程、加载配置、监听端口，然后立即正常退出。用于 CI/CD 或部署后快速验证配置与端口可用性。

systemctl stop ergo
./ergo run --smoke
echo "EXIT=$?"
systemctl start ergo

实测回显：

2026-10-25T06:01:38.777Z : info  : server     : ergo-2.19.1 starting
2026-10-25T06:01:38.777Z : info  : server     : Using config file : ircd.yaml
2026-10-25T06:01:38.777Z : info  : server     : Using datastore : ircd.db
2026-10-25T06:01:38.777Z : info  : server     : Proxied IPs will be accepted from : localhost
2026-10-25T06:01:38.778Z : info  : listeners  : now listening on [::1]:6667, tls=false, proxy=false, tor=false, websocket=false.
2026-10-25T06:01:38.778Z : info  : listeners  : now listening on :6697, tls=true, proxy=false, tor=false, websocket=false.
2026-10-25T06:01:38.778Z : info  : listeners  : now listening on 127.0.0.1:6667, tls=false, proxy=false, tor=false, websocket=false.
2026-10-25T06:01:38.778Z : info  : server     : Server running
EXIT=0

⚠️ 注意：若服务已在运行，--smoke 会因无法获取 ircd.lock 而报错退出，这是正常保护机制，不是配置错误。

五、注意事项

  1. 锁文件互斥：ircd.lock 防止多实例同时启动。run、run --smoke、initdb、importdb 在执行前都会尝试获取锁；若报错 failed to acquire flock，先检查是否有其他 ergo 进程。
  2. 工作目录敏感：--conf、datastore.path、lock-file 等相对路径均相对于启动时的工作目录解析。建议始终在 /opt/ergo 下执行命令，或在 systemd 单元中显式设置 WorkingDirectory=/opt/ergo。
  3. 权限最小化：不要用 root 直接运行 ergo run。应创建专用用户 ergo，并确保证书私钥（privkey.pem）权限为 600。
  4. 配置热重载：修改 ircd.yaml 后执行 systemctl reload ergo（内部发送 SIGHUP）。日志出现 Rehash completed successfully 即生效；若配置格式错误，服务保持旧配置运行。
  5. 密码与令牌不要硬编码到命令行历史：genpasswd 建议通过管道或交互方式输入，避免明文密码残留在 shell history 中。

六、常见问题

Q1：执行 ergo run --smoke 报错 failed to acquire flock on ircd.lock？

A：说明已有 Ergo 进程在运行（通常是 systemd 托管的服务）。正确做法是先停止服务，执行冒烟测试后再恢复：

systemctl stop ergo
./ergo run --smoke
systemctl start ergo

Q2：initdb 或 importdb 报错 Datastore already exists？

A：这两个命令都要求目标数据库为空。如需重建，先备份 ircd.db 再删除，然后重新执行。

Q3：genpasswd 生成的哈希每次都不一样，是否影响登录？

A：不影响。bcrypt 哈希包含随机盐，每次输出不同，但验证时会对明文重新计算比对。只要哈希值正确写入 opers.admin.password，即可用对应明文登录。

Q4：mkcerts 生成的证书过期了怎么办？

A：直接重新执行 ./ergo mkcerts 会复用已有文件。要强制重新生成，需先删除 fullchain.pem 和 privkey.pem，再执行 mkcerts，然后 systemctl reload ergo。

Q5：如何确认当前运行的是哪个配置文件？

A：查看启动日志中的 Using config file : /path/to/ircd.yaml，或执行 ps -ef | grep ergo 查看 --conf 参数。

Q6：defaultconfig 输出的配置可以直接覆盖 ircd.yaml 吗？

A：不建议直接覆盖，因为默认配置中 network.name=ErgoTest、server.name=ergo.test、opers 密码为占位哈希。应复制后按实际环境修改关键字段再使用。

七、参考链接