Ergo 2.19 配置参数详解

目标：逐段解读 Ergo 2.19.1 默认配置文件 default.yaml（共 1227 行）的全部核心参数域，说明每项的默认值、作用与改动影响，帮助管理员快速完成从开发测试到生产环境的配置迁移。所有行号、默认值均来自官方 tar.gz 中的 default.yaml 实测文件。

一、环境信息

• 软件版本：Ergo 2.19.1
• 配置文件路径：/opt/ergo/ircd.yaml（由 default.yaml 复制而来）
• 配置文件行数：1227 行
• 验证方式：修改后执行 systemctl reload ergo 即可热重载（少数字段如 datastore.path 等需重启）
• 测试域名：irc.quzuo-test.local

二、前置条件

• Ergo 已完成安装（预编译二进制或源码编译均可）；
• 已生成 ircd.yaml 并正确设置 network.name、server.name 与 opers 密码；
• 如需修改后热重载，请确保 systemd 单元中配置了 ExecReload=/bin/kill -HUP $MAINPID；
• 确认 datastore.path 所在目录可写（运行用户需有写权限）。

三、参数查看与修改方式

Ergo 没有运行时 get/set 命令，所有参数均在 ircd.yaml 中以 YAML 键值形式静态管理：

• 查看：直接阅读 ircd.yaml 或使用 grep 定位字段；
• 修改：编辑 ircd.yaml 后执行 systemctl reload ergo；
• 环境变量覆盖：当 allow-environment-overrides: true 时，可用 ERGO__段__键=值 形式注入（例如 ERGO__SERVER__MAX_SENDQ=128k），双下划线分隔嵌套层级；此方式无需改动文件，适合不便直接修改配置文件的自动化编排环境。

⚠️ 注意：每次修改前建议先备份当前生效的 ircd.yaml；热重载失败（配置格式错误）时，日志会指出具体行号，服务保持旧配置运行，不会中断现有连接。

四、参数总览

以下按域展开详解。

五、核心参数分类详解

5.1 network（第 26 行）

network:
    name: ErgoTest

• name：网络名称，显示在 005 NETWORK ISUPPORT 及 MOTD 中，客户端将其识别为所属网络。建议改为无空格和特殊字符的标识，如 QuzuoNet。

5.2 server（第 31 行）

server:
    name: ergo.test
    listeners:
        "127.0.0.1:6667":
        "[::1]:6667":
        ":6697":
            tls:
                cert: fullchain.pem
                key: privkey.pem
            min-tls-version: 1.2

• name：服务器主机名，显示在 WHOIS、错误消息和证书中。建议使用实际域名。
• listeners：监听地址与端口。
  • 默认仅回环监听明文 6667，全接口监听 TLS 6697；
  • 生产环境若使用 Let's Encrypt 等证书，把 fullchain.pem/privkey.pem 替换为真实证书路径即可；
  • min-tls-version 设为 1.2 或更高；
  • 若前端有负载均衡且发送 PROXY 协议头，设置 proxy: true。
• unix-bind-mode: 0777：Unix 域套接字监听时的权限；仅在使用 Unix socket 时有效。
• tor-listeners：Tor 专用监听配置，含 require-sasl、vhost、max-connections。
• sts（Strict Transport Security）：
  • enabled: false：默认不发送 STS 策略；若打算强制客户端长期使用 TLS，设为 true 并设置合理 duration（默认 1mo2d5m）；
  • port: 6697 需与 TLS 监听器端口一致；
  • 取消 STS 时保持 enabled: true 但将 duration 改为 0。
• websockets：allowed-origins 可限制 WebSocket 连接的来源域名，防止恶意网站劫持连接。
• casemapping: ascii：标识符（昵称/频道名/账号名）的大小写规则。可选值：
  • ascii：仅 ASCII 字符，默认；
  • precis：UTF-8，安全但需客户端兼容；
  • permissive：允许 emoji，安全性下降；
  • rfc1459 / rfc1459-strict：兼容旧 ircd。
  • ⚠️ 一旦上线，切勿轻易修改，会导致现有注册昵称/频道名冲突。
• enforce-utf8: true：丢弃非 UTF-8 消息（传统 IRC 允许非 UTF-8，但 websocket 客户端不支持）。
• lookup-hostnames: false：关闭反向 DNS 查询；默认启用 IP cloaking，此项保持 false 即可。
• check-ident: false：不使用 ident 协议获取用户名。
• coerce-ident: '~u'：强制将 USER 命令中的 ident 设为固定值 ~u。
• password：全局服务器密码（PASS 命令）。生产环境建议改用 require-sasl 构建私有网络，而非共享密码。
• motd: ergo.motd：MOTD 文件路径。支持 motd-formatting: true（使用 $c、$b 等 IRC 颜色码）。
• idle-timeouts：
  • registration: 60s：完成注册握手（含 SASL 协商）的最长时间；
  • ping: 1m30s：无数据时发送 PING 的间隔；
  • disconnect: 2m30s：未响应 PING 后断开的时间。
• relaymsg：RELAYMSG 命令（用于桥接其他协议），默认启用并允许频道操作员使用。
• ip-limits：IP 级连接限制（DoS 防护）。
  • count: true / max-concurrent-connections: 16：单 IP 最多 16 个并发连接；
  • throttle: true / window: 10m / max-connections-per-window: 32：每 10 分钟最多 32 次新连接；
  • cidr-len-ipv4: 32 / cidr-len-ipv6: 64：限制粒度；
  • exempted：白名单 IP 或 CIDR，如 "localhost"。
• ip-cloaking：IP 地址伪装。
  • enabled: true：默认启用，用户互相看到 pwbs2ui4377257x8.irc 形式的假主机名；
  • netname: "irc"：伪装域名后缀；
  • num-bits: 64：哈希输出位数，越大冲突越少但主机名越长。
• secure-nets：标记安全的内网 CIDR，来自这些地址的明文连接会被视为安全（获得 +Z 模式）。
• oper-throttle: 10s：两次 OPER 尝试之间的最小间隔（防暴力破解）。

5.3 accounts（第 412 行）

accounts:
    authentication-enabled: true
    registration:
        enabled: true
        bcrypt-cost: 4

• authentication-enabled：是否允许用户登录已有账号。
• registration.enabled：是否允许自助注册。构建私有服务器时设为 false，再用 NICKSERV SAREGISTER 由管理员手工创建。
• registration.bcrypt-cost：bcrypt 计算成本（最低 4）。增加此值可提升密码安全性，但会显著增加 CPU 负载，尤其在注册/登录高峰时。
• registration.verify-timeout: "32h"：注册后验证账号前的保留窗口（需配合邮件验证使用）。
• registration.email-verification：邮箱验证开关，默认关闭。
• login-throttling：登录频率限制（防密码爆破）。
  • duration: 1m / max-attempts: 3：每分钟内同一账号最多 3 次尝试。
• skip-server-password: false：若设为 true，SASL 认证成功后不要求 PASS 命令。
• login-via-pass-command: true：允许使用 PASS account:password 方式登录（兼容旧客户端）。
• advertise-scram: true：向客户端广告 SCRAM-SHA-256 SASL 方法。
• require-sasl：强制所有连接必须 SASL 认证。
  • enabled: false：默认关闭；打开时必须同时关闭 registration.enabled，否则任何人都能注册账号。
• nick-reservation：昵称保留策略。
  • enabled: true：开启昵称与账号绑定；
  • method: strict：未登录前不可使用保留昵称；
  • force-nick-equals-account: true：登录账号后强制使用账号名作为昵称；
  • guest-nickname-format: "Guest-*"：自动重命名模板。
• multiclient：多客户端/Bouncer 行为。
  • enabled: true：允许多设备附着到同一身份；
  • always-on: "opt-in"：用户可自愿设置为 always-on（断线后仍在线）。
• vhosts：HostServ 虚拟主机名，默认启用，max-length: 64。
• default-user-modes: +i：新用户默认加不可见模式。
• auth-script：外挂脚本认证（如对接 LDAP/Active Directory）。
• oauth2 / jwt-auth：外部令牌认证，默认关闭。

⚠️ 注意：bcrypt-cost 从 4 提升到 10 时，注册/登录延迟可能从数毫秒增加到数百毫秒。请根据你的并发量实测后决定，不要盲目调高。

5.4 channels（第 671 行）

channels:
    default-modes: +ntC
    max-channels-per-client: 100
    registration:
        enabled: true
        max-channels-per-account: 15

• default-modes：新频道默认模式。+n（禁止外部消息）、+t（仅操作员可改主题）、+C（禁止除 ACTION 外的 CTCP）。
• operator-only-creation: false：是否仅允许操作员创建频道。
• registration：频道注册。每个账号默认最多注册 15 个频道。
• list-delay: 0s：匿名连接多久后才允许使用 /LIST，防机器人刷频道列表。
• invite-expiration: 24h：INVITE 令牌有效期。
• auto-join：新用户自动加入的频道列表（谨慎使用）。

5.5 oper-classes（第 717 行）与 opers（第 756 行）

• oper-classes 定义两类权限模板：
  • chat-moderator：踢人、封禁 IP/CIDR、虚拟主机管理、SAMODE/SAJOIN、RELAYMSG 等；
  • server-admin：继承 chat-moderator，并额外拥有 rehash、accreg（管理账号）、chanreg（管理频道）、history（删除历史）、defcon（限制模式）、massmessage（全服广播）、metadata。
• opers 中定义具体操作员账号：
  • class：引用上述模板；
  • password：bcrypt 哈希（由 ergo genpasswd 生成）；
  • hidden: true：隐藏 OPER 状态，普通用户看不到；
  • whois-line：在 WHOIS 中显示的身份说明；
  • certfp：可选，绑定 TLS 客户端证书指纹以自动 OPER。

5.6 logging（第 799 行）

logging:
    -
        method: stderr
        type: "* -userinput -useroutput"
        level: info

• method：stderr、stdout、file 或组合；
• type：过滤哪些日志类型进入此输出。* 表示全部，-userinput 表示排除用户输入。可选类型包括 server、accounts、channels、opers、services、internal、userinput、useroutput、connect-ip 等；
• level：debug < info < warn < error。

💡 说明：如不希望日志中出现用户 IP，可排除 connect-ip；如需要审计合规，可新增一个 file 输出项保留所有 userinput/useroutput。

5.7 debug（第 839 行）

debug:
    recover-from-errors: true

• recover-from-errors：在客户端触发 panic 时尝试恢复而非崩溃。对 DoS 更鲁棒，但可能引入状态不一致；偏好"崩溃-重启"策略的环境可设为 false。
• pprof-listener：可选 Go pprof HTTP 端点，建议绑定 localhost 或留空。

5.8 lock-file（第 858 行）

lock-file: "ircd.lock"

防止多个 Ergo 实例同时启动。如果因崩溃导致锁文件残留且确认无其他进程运行，可手动删除后重启。

5.9 datastore（第 861 行）

datastore:
    path: ircd.db
    autoupgrade: true
    mysql:
        enabled: false
        host: "localhost"
        port: 3306
    postgresql:
        enabled: false
        host: "localhost"
        port: 5432
    sqlite:
        enabled: false
        database-path: "ergo_history.db"

• path：BoltDB 文件相对工作目录的路径；
• autoupgrade：自动升级数据库 schema（升级前自动备份原数据库）；
• mysql/postgresql/sqlite：目前仅用于持久化历史消息，账号与频道注册仍存 BoltDB。配置主机、端口、用户名、密码、连接池大小等。

💡 说明：BoltDB 文件 ircd.db 必须定时备份；它包含所有账号与频道注册数据。如历史消息需跨重启保留，启用 MySQL/PostgreSQL/SQLite 后端即可。

5.10 languages（第 923 行）

languages:
    enabled: true
    default: en
    path: languages

控制多语言支持。languages/ 目录包含大量翻译文件（zh-CN、fr-FR、de-DE 等）。default: en 为默认语言，客户端可通过 draft/languages 能力协商。

5.11 limits（第 935 行）

limits:
    nicklen: 32
    identlen: 20
    realnamelen: 150
    channellen: 64
    awaylen: 390
    kicklen: 390
    topiclen: 390
    monitor-entries: 100
    whowas-entries: 100
    chan-list-modes: 100
    registration-messages: 1024
    multiline:
        max-bytes: 4096
        max-lines: 100

均为硬性上限。registration-messages: 1024 可防止注册握手阶段的 DoS 消息轰炸。multiline 限制多行消息（draft/multiline）的体积分片。

5.12 fakelag（第 976 行）

fakelag:
    enabled: true
    window: 1s
    burst-limit: 5
    messages-per-window: 2
    cooldown: 2s

• burst-limit: 5：允许一次性快速发送 5 条命令；
• messages-per-window: 2：超出突发量后，每秒最多 2 条命令；
• cooldown: 2s：停止发送命令 2 秒后恢复正常速率；
• command-budgets：为 CHATHISTORY、MARKREAD、MONITOR、WHO、WEBPUSH 设置更高的独立配额，避免历史回放或批量查询触发限流。

5.13 history（第 1064 行）

history:
    enabled: true
    channel-length: 2048
    client-length: 256
    autoresize-window: 3d
    autoreplay-on-join: 0
    chathistory-maxmessages: 1000
    znc-maxmessages: 2048
    restrictions:
        expire-time: 1w
        query-cutoff: none
        grace-period: 1h
    persistent:
        enabled: false

• channel-length: 2048：内存中保留的频道事件（消息、JOIN/PART）上限；
• client-length: 256：私聊消息内存上限；
• autoresize-window: 3d：若消息超过 3 天未读取，缓冲区允许覆盖旧数据而非持续扩容；
• expire-time: 1w：消息最长保留 1 周（持久化后端下也受此限制）；
• query-cutoff：历史查询权限，可选 none、registration-time（不能查注册前/登录前的消息）、join-time（不能查加入频道前的消息）；
• persistent.enabled：是否启用持久化后端（需同时配置 datastore.mysql/postgresql/sqlite）。

5.14 metadata / webpush / api（第 1175、1194、1213 行）

• metadata：允许用户和频道设置键值元数据（如用户签名、频道链接）。operator-only-modification: false 时普通用户可自行修改。
• webpush：移动端推送通知（实验性）。⚠️ 不要在 Tor/I2P 隐藏服务中启用。
• api：HTTP JSON API，默认关闭，监听 127.0.0.1:8089。启用后需配置 bearer-tokens（用 ergo gentoken 生成强口令）。

六、生产配置模板

以下是一份适合中小型社区/团队内网的精简 ircd.yaml 模板，基于 default.yaml 裁剪，标注了建议修改项。使用时请替换示例值。

network:
    name: MyNet               # 必填：你的网络名

server:
    name: irc.example.com     # 必填：服务器域名
    listeners:
        "127.0.0.1:6667":    # 明文仅本机
        "[::1]:6667":
        ":6697":
            tls:
                cert: fullchain.pem
                key: privkey.pem
            min-tls-version: 1.2
    sts:
        enabled: true
        duration: 2mo
        port: 6697
    lookup-hostnames: false
    ip-cloaking:
        enabled: true
        netname: "irc"
        num-bits: 64

accounts:
    authentication-enabled: true
    registration:
        enabled: true
        bcrypt-cost: 10            # 安全场景可适当提升
    login-throttling:
        enabled: true
        duration: 1m
        max-attempts: 3
    nick-reservation:
        enabled: true
        method: strict
        force-nick-equals-account: true
    multiclient:
        enabled: true
        always-on: opt-in
    default-user-modes: +i

channels:
    default-modes: +ntC
    max-channels-per-client: 100
    registration:
        enabled: true
        max-channels-per-account: 10

oper-classes:
    "chat-moderator":
        title: Chat Moderator
        capabilities:
            - "kill"
            - "ban"
            - "relaymsg"
            - "samode"
            - "sajoin"
            - "snomasks"
            - "vhosts"
    "server-admin":
        title: Server Admin
        extends: "chat-moderator"
        capabilities:
            - "rehash"
            - "accreg"
            - "chanreg"
            - "history"
            - "massmessage"

opers:
    admin:
        class: "server-admin"
        hidden: true
        whois-line: is the server administrator
        password: "$2a$04$<genpasswd输出的哈希>"

logging:
    -
        method: stderr
        type: "* -userinput -useroutput"
        level: info

datastore:
    path: ircd.db
    autoupgrade: true

history:
    enabled: true
    channel-length: 2048
    client-length: 256
    expire-time: 1w
    restrictions:
        query-cutoff: none
    persistent:
        enabled: false

limits:
    nicklen: 32
    channellen: 64
    topiclen: 390
    registration-messages: 1024

fakelag:
    enabled: true
    burst-limit: 5
    messages-per-window: 2
    cooldown: 2s

💡 说明：若部署环境需要私有服务器（仅限注册账号访问），在上述模板中将 accounts.registration.enabled 设为 false，并将 accounts.require-sasl.enabled 设为 true，同时关闭公开注册。

七、常见问题

Q1：修改 server.name 后，客户端看到的网络名没变？

A：server.name 是服务器标识；network.name 才是 005 NETWORK 数值里的网络名。两者请分别检查。

Q2：配置了 require-sasl: true，但新用户仍能注册账号？

A：require-sasl 只控制"是否必须认证才能连接"，不控制"是否允许注册"。要建私有服务器，必须同时将 accounts.registration.enabled 设为 false。

Q3：datastore.autoupgrade: true 安全吗？

A：官方设计为自动备份原数据库后执行升级，若失败则回滚。建议升级前仍手动备份 ircd.db。

Q4：如何限制频道数量，防止一个账号注册过多频道？

A：调整 channels.registration.max-channels-per-account，默认 15。设为 0 可禁止频道注册（仅操作员可用 NICKSERV SAREGISTER 或 CS TRANSFER）。

Q5：日志里出现大量 userinput/useroutput，如何过滤？

A：在 logging.type 中加入 -userinput -useroutput。如需审计保留，可另开一个 file 日志项专门记录它们。

Q6：修改 casemapping 后服务起不来或出现重复昵称？

A：casemapping 一旦上线就不应修改，因为已注册的账号名和频道名基于旧的映射规则存储。如需变更，需重建 ircd.db（即丢失注册数据）。

八、参考链接

• Ergo 官方手册：https://ergo.chat/manual.html
• Ergo default.yaml 完整注释：https://github.com/ergochat/ergo/blob/stable/default.yaml
• IRCv3 规范与能力列表：https://ircv3.net/