Apache Iggy 配置参数详解

目标：系统讲解 Apache Iggy 0.9.0 服务端配置——core/server/config.toml 的完整参数段（监听、内存池、日志、加密、集群 VSR、分片、分区、消息总线）以及对应的 IGGY_ 环境变量覆盖方式，并给出生产配置模板。所有默认值均对照仓库 server-0.9.0 的 core/server/config.toml 实测核对。

一、环境信息

• 组件：Apache Iggy 0.9.0（iggy-server）
• 默认配置文件：仓库源码 core/server/config.toml（相对工作目录解析）
• 覆盖方式：环境变量 IGGY_<嵌套键>（下划线分隔），或 IGGY_CONFIG_PATH 指向自定义 TOML
• 数据目录：local_data（IGGY_PATH 覆盖）
• 监听端口：TCP 8090、QUIC 8080、WebSocket 8092、HTTP 3000

二、前置条件

• 具备 iggy-server 可执行文件（安装见《Ubuntu 22.04 安装 Apache Iggy 0.9.0 指南》篇）。
• 具备任意文本编辑器编辑 TOML。
• 了解 TOML 语法（[h2] 段、key = value）。

三、参数查看与修改方式

1. 默认配置来源：iggy-server 启动时从当前工作目录解析 core/server/config.toml。仓库源码自带完整示例（含每项注释）。

cd /opt/iggy
sed -n '1,80p' core/server/config.toml

实际首屏回显（示意）：

# Root directory for server data. Environment override: IGGY_PATH.
path = "local_data"

[consumer_group]
rebalancing_timeout = "30s"

[data_maintenance.messages]
cleaner_enabled = true
interval = "1 m"

[http]
enabled = true
address = "127.0.0.1:3000"
# 其余段落从略，完整示例见仓库源码 core/server/config.toml

2. 指定自定义配置：

IGGY_CONFIG_PATH=/etc/iggy/config.toml iggy-server

3. 环境变量覆盖：任何键都可用 IGGY_ 前缀 + 下划线嵌套覆盖，优先级高于配置文件。示例见 iggy-server --help：

IGGY_PATH=/data/iggy                          # 数据目录
IGGY_TCP_ADDRESS=127.0.0.1:8090               # TCP 监听
IGGY_HTTP_ADDRESS=0.0.0.0:3000                # HTTP 监听
IGGY_NODE_ADVERTISED_ADDRESS=localhost         # 客户端拨号地址
IGGY_LOGGING_LEVEL=debug                       # 日志级别
IGGY_ROOT_USERNAME=root                        # root 用户名
IGGY_ROOT_PASSWORD=q1w2e3r4                    # root 密码

4. 命令行参数：iggy-server -h 仅提供少量启动开关（--fresh 清空数据、--with-default-root-credentials、--replica-id N 选集群节点）；配置主体都在 TOML/环境变量。

四、参数总览（config.toml 全段）

五、核心参数分类详解

5.1 监听与传输段（[tcp] [http] [quic] [websocket]）

实测补充：IGGY_NODE_ADVERTISED_ADDRESS=localhost 在 Compose/通配绑定场景必须设置，默认监听本机 loopback 对外不可达。

5.2 内存池段（[memory_pool]）

内存池为消息缓冲复用，Iggy 是 Rust 服务无 JVM 堆，此段直接控制原生内存：

环境变量：IGGY_MEMORY_POOL_SIZE、IGGY_MEMORY_POOL_BUCKET_CAPACITY。生产按内存调整，例如低内存服务器可 IGGY_MEMORY_POOL_SIZE=512MiB。

5.3 日志段（[logging]）

环境变量：IGGY_LOGGING_LEVEL（如 debug）。诊断设 debug、生产默认 info。

5.4 加密段（[encryption]）

5.5 集群与 VSR 段（[cluster]，多节点高可用）

默认单机 enabled=false；为高可用将 enabled=true 并给出本节点 --replica-id：

示例（仓库 config.toml 内置）：

[cluster]
enabled = true
name = "iggy-cluster"

[[cluster.nodes]]
name = "iggy-node-1"
ip = "127.0.0.1"
replica_id = 0
ports = { tcp = 8090, quic = 8080, http = 3000, websocket = 8092, tcp_replica = 9090 }

[[cluster.nodes]]
name = "iggy-node-2"
ip = "127.0.0.1"
replica_id = 1
ports = { tcp = 8091, quic = 8081, http = 3001, websocket = 8093, tcp_replica = 9091 }

⚠️ 注意：集群模式下每个启用的传输在 ports 须显式声明端口；节点用 iggy-server --replica-id <N> 选定自身配置。ip 是副本级地址（字面 IP），客户端拨号地址用 advertised_address。

[cluster.auth] / [cluster.tls]：副本间认证（PSK+BLAKE3）与 TLS（enabled、shared_secret、证书）；[cluster.coordinator] 控制分片 0 的协调者放置。

5.6 分片段（[sharding]）

5.7 元数据共识段（[metadata]，分片 0 的 VSR 副本）

5.8 分区段（[partition]，每分区共识与存储）

💡 说明：partition 是逐分区的共识管线，调大 prepare_queue_depth 会按分区数倍增钉住内存，生产须克制。

5.9 消息总线段（[message_bus]）

六、Topic 级选项（iggy options topic，创建时可配）

以下选项不在 config.toml，而是创建 topic 时通过 CLI --set key=value 或 HTTP options 字段设置；服务端 options 子命令输出如下（0.9.0 实测）：

CLI 查看方式：

iggy options topic

实际回最后一次（节选关键行，表格完整列见 iggy options topic 全量输出）。

七、生产配置模板

适用场景：16 GB 内存、NVMe SSD、单机（cluster.enabled=false）、OLTP 消息流（低延迟读写混合），端口对外 0.0.0.0。

/etc/iggy/config.toml：

path = "/var/lib/iggy"

[tcp]
address = "0.0.0.0:8090"

[http]
address = "0.0.0.0:3000"
web_ui = true
cors = { allowed_origins = ["*"], allowed_methods = ["GET", "POST", "PUT", "DELETE"] }

[http.jwt]
encoding_secret = "a3Zlcm5hdGVkLWlnZ3ktJTQyLXNlY3JldC0yMDI2LS1zZWNyZXQtZW5jb2RlLTE="
decoding_secret = "a3Zlcm5hdGVkLWlnZ3ktJTQyLXNlY3JldC0yMDI2LS1zZWNyZXQtZGVjb2RlLTE="

[quic]
enabled = false

[websocket]
enabled = false

[memory_pool]
enabled = true
size = "2 GiB"
bucket_capacity = 4096

[logging]
level = "info"
max_file_size = "500 MB"
max_total_size = "4 GB"
retention = "7 days"

[partition]
prepare_queue_depth = 32
dedup_clients_max = 4096

[message_bus]
max_batch = 256
max_message_size = "64 MiB"

💡 说明：内存 16 GB 场景把内存池压到 2 GiB，其余留给消息缓冲与系统；NVMe 场景可保持 max_batch=256 以增大 writev 批量；QUIC/WebSocket 按需关闭以少开端口。JWT 的 encoding_secret/decoding_secret 用于重启后令牌仍有效（否则每次重启重生成随机密钥）。

内存/磁盘选型对照：

八、常见问题

Q1：配置变更后如何生效？

配置文件/环境变量在启动时读取，需重启 iggy-server（systemd：systemctl restart iggy）。

Q2：改了 cluster.name 后无法启动？

cluster.name 经哈希写入首个启动数据的集群 ID；改后会因恢复的 ID 与配置不符而拒绝启动。需用空数据目录启动（改名即换新目录）。

Q3：为什么 IGGY_HTTP_ADDRESS=0.0.0.0:3000 后客户端仍连不上？

通配绑定需同时声明客户端拨号地址 IGGY_NODE_ADVERTISED_ADDRESS=<主机名或IP>（node.advertised_address），否则集群元数据/重定向拿不到可路由地址。

Q4：JWT 重启后失效？

未配 http.jwt.encoding_secret/decoding_secret 时每次启动随机生成，旧 token 失效。生产务必配置固定密钥。

Q5：如何提高写入吞吐？

调大 message_bus.max_batch（≤512）、memory_pool.size，并把存储放 NVMe；Iggy 无 JVM 堆，核心是内存池与磁盘 IO 并行度（[sharding] CPU 分配）。

九、参考链接

• 官方配置文档：https://iggy.apache.org/docs
• 仓库配置示例：https://github.com/apache/iggy/blob/server-0.9.0/core/server/config.toml
• 快速上手：https://iggy.apache.org/docs/introduction/getting-started/