Apache Iggy Docker Compose 部署指南

目标：用 Docker Compose 一键编排 Apache Iggy 0.9.0（Rust 高性能持久化消息流平台）服务端，涵盖官网上游镜像构建、端口映射、数据卷持久化、环境变量与常用运维命令。已在系统内实测 Compose 编排与健康检查回显通过。

一、环境信息

系统：Ubuntu 22.04（含 Docker Engine 与 Docker Compose v2）
组件镜像：iggy-server（仓库 Dockerfile 构建，debian:trixie-slim 运行时）
组件版本：Apache Iggy 0.9.0（iggy-server）+ iggy-cli 0.14.0
监听端口映射：TCP 8090、QUIC 8080、HTTP(REST/Web UI) 3000、WebSocket 8092
数据卷：iggy-server:/local_data（具名卷持久化）
默认容器/服务名：iggy-server
示例管理账号：root / 密码 q1w2e3r4（镜像默认 iggy/iggy）

二、镜像选型说明

Apache Iggy 官方仓库 apache/iggy 自带两件编排资产：

Dockerfile：多阶段构建。构建阶段基于 rust:1.98-slim-trixie，编译 iggy（CLI）与 iggy-server（-p server）；同时用 npm --prefix web 构建内置 Web UI 静态资源（iggy-web feature）。运行阶段基于 debian:trixie-slim，仅安装 ca-certificates、liblzma5、libhwloc15 三个运行时库。
docker-compose.yml：单个 iggy-server 服务，映射 4 个端口，挂载 iggy-server:/local_data 具名卷。

Dockerfile 内置以下监听地址环境变量（全部绑定 0.0.0.0，以便容器外访问）：

ENV IGGY_HTTP_ADDRESS=0.0.0.0:3000
ENV IGGY_QUIC_ADDRESS=0.0.0.0:8080
ENV IGGY_TCP_ADDRESS=0.0.0.0:8090
ENV IGGY_WEBSOCKET_ADDRESS=0.0.0.0:8092

💡 说明：镜像将监听绑定 0.0.0.0，因此需要在 Compose 内声明客户端实际拨号地址 IGGY_NODE_ADVERTISED_ADDRESS（见下）。

三、前置条件

具备 Linux 真机的 Docker Engine（24.x+）与 Compose v2（docker compose 子命令）。
能访问 GitHub（拉取 apache/iggy 仓库源码以执行 build）。
宿主机保留端口 3000/8080/8090/8092 空闲。

四、部署步骤

克隆上游仓库（含 Dockerfile 与 docker-compose.yml）：

git clone --depth 1 --branch server-0.9.0 https://github.com/apache/iggy.git iggy
cd iggy

查看服务编排定义：

docker compose config

构建并启动：

docker compose up -d --build

查看容器状态：

docker compose ps

实际回显示例：

NAME          IMAGE         COMMAND         SERVICE       STATUS        PORTS
iggy-server   iggy-server   /iggy-server      iggy-server   Up 2 minutes 0.0.0.0:3000->3000/tcp, 0.0.0.0:8080->8080/tcp, 0.0.0.0:8090->8090/tcp, 0.0.0.0:8092->8092/tcp

健康检查（REST ping）：

curl -i http://127.0.0.1:3000/ping

实际回显：

HTTP/1.1 200 OK
content-type: text/plain; charset=utf-8
access-control-expose-headers: iggy-view
access-control-allow-origin: *
content-length: 4
date: Sun, 11 Oct 2026 10:54:38 GMT

pong

curl -s -X POST http://127.0.0.1:3000/users/login \
  -H "Content-Type: application/json" \
  -d '{"username":"root","password":"q1w2e3r4"}'

五、数据持久化说明

docker-compose.yml 使用一个具名卷 iggy-server:/local_data，对应镜像默认数据根目录 local_data（IGGY_PATH 未覆盖时）。其内部目录结构：

local_data/streams/<sid>/topics/<tid>/partitions/<pid>/：每个分区的 segment（*.log）、索引（*.index）、超级块（superblock.a）
local_data/metadata/journal.wal：元数据 VSR 日志
local_data/runtime/、local_data/state/、local_data/logs/：运行时、状态、日志

停止容器不删除数据；docker compose down 也不删除具名卷数据。彻底清理数据才需要 docker compose down -v。

💡 说明：如需把数据落到宿主机指定目录（便于备份），可将 volumes 的具名卷替换为 bind mount，例如 - /opt/data/iggy:/local_data。

六、常用环境变量表

镜像 Dockerfile 已预设 4 个监听地址；以下为平常用得到的 Iggy 运行时环境变量（IGGY_ 前缀，下划线分隔嵌套键）：

环境变量	默认值	说明
`IGGY_TCP_ADDRESS`	`127.0.0.1:8090`	TCP 监听（镜像置为 `0.0.0.0:8090`）
`IGGY_HTTP_ADDRESS`	`127.0.0.1:3000`	HTTP/REST 监听（镜像置为 `0.0.0.0:3000`）
`IGGY_QUIC_ADDRESS`	`127.0.0.1:8080`	QUIC 监听（镜像置为 `0.0.0.0:8080`）
`IGGY_WEBSOCKET_ADDRESS`	`127.0.0.1:8092`	WebSocket 监听（镜像置为 `0.0.0.0:8092`）
`IGGY_NODE_ADVERTISED_ADDRESS`	派生自绑定地址	客户端拨号地址，绑定通配地址时必填
`IGGY_PATH`	`local_data`	数据目录
`IGGY_ROOT_USERNAME`	`iggy`	root 用户名（首次创建生效；Compose 建议设 `root`）
`IGGY_ROOT_PASSWORD`	`iggy`	root 密码（首次创建生效）
`IGGY_CONFIG_PATH`	`core/server/config.toml`	指向自定义 TOML 配置
`IGGY_LOGGING_LEVEL`	`info`	日志级别（trace/debug/info/warn/error/off）
`IGGY_MEMORY_POOL_SIZE`	`4 GiB`	内存池大小
`IGGY_MEMORY_POOL_BUCKET_CAPACITY`	`8192`	内存池每桶缓冲数
`IGGY_HTTP_WEB_UI`	`false`	是否开启内置 Web 控制台 `/ui`

💡 说明：任何 config.toml 配置项都能用 IGGY_ 前缀 + 下划线嵌套键覆盖，例如 IGGY_HTTP_WEB_UI=true 对应 [http] web_ui = true。

七、常用配置参数说明（command）

docker-compose.yml 中使用 command 或 entrypoint 可传入 iggy-server 的命令行参数。常用：

services:
  iggy-server:
    command: ["/iggy-server", "--with-default-root-credentials"]

常用 iggy-server 命令行参数：

参数	说明
`--fresh` / `-f`	启动前删除数据目录（会清空全部数据，仅用于开发测试）
`--with-default-root-credentials`	用默认 `iggy`/`iggy` root 凭据（开发用，不安全）
`--replica-id <N>`	集群模式下声明本节点对应 `cluster.nodes[*].replica_id`
`-V` / `--version`	打印版本

八、配置文件持久化（conf 挂载）

若不想用环境变量，可挂载自定义 config.toml 到容器并指定 IGGY_CONFIG_PATH：

services:
  iggy-server:
    volumes:
      - iggy-server:/local_data
      - ./iggy-config.toml:/etc/iggy/config.toml:ro
    environment:
      - IGGY_CONFIG_PATH=/etc/iggy/config.toml

本地 iggy-config.toml 示例：

path = "/local_data"

[tcp]
address = "0.0.0.0:8090"

[http]
address = "0.0.0.0:3000"
web_ui = true

九、等价 docker run 运行方式

不使用 Compose，可用单条 docker run 等价启动：

docker run -d --name iggy-server \
  --security-opt seccomp=unconfined \
  -e IGGY_NODE_ADVERTISED_ADDRESS=localhost \
  -e IGGY_ROOT_USERNAME=root -e IGGY_ROOT_PASSWORD=q1w2e3r4 \
  -p 3000:3000 -p 8080:8080 -p 8090:8090 -p 8092:8092 \
  -v iggy-server-data:/local_data \
  iggy-server:latest

⚠️ 注意：--security-opt seccomp=unconfined 是必需的——iggy-server 使用 io_uring（io_uring_setup/io_uring_enter/io_uring_register 系统调用），默认容器的 seccomp 会拦截导致启动失败。

十、常用运维命令

docker compose logs -f iggy-server     # 跟踪日志
docker compose restart iggy-server     # 重启服务（数据保留）
docker compose down                    # 停止并移除容器（保留具名卷数据）
docker compose down -v                 # 停止并删除数据卷（谨慎）
docker compose pull                    # 拉取/更新镜像
docker exec -it iggy-server sh         # 进入容器
docker exec iggy-server /iggy-server --version          # 查看服务端版本

容器内 CLI 验证（镜像同时打进 iggy CLI）：

docker exec -it iggy-server /iggy --version

实际回显：

iggy-cli 0.14.0

十一、常见问题（FAQ）

Q1：启动报「io_uring Permission Denied」？

默认容器的 seccomp 拦截了 io_uring 系统调用。在 Compose 服务定义里加 security_opt: - seccomp:unconfined（上游 docker-compose.yml 已内置），或用 docker run --security-opt seccomp=unconfined。

Q2：容器外 curl 端口不通？

镜像把监听绑定 0.0.0.0，但客户端实际拨号地址必须声明。设置 IGGY_NODE_ADVERTISED_ADDRESS=localhost（或宿主机 IP）。同时确认端口已 -p 映射。

Q3：REST 登录 404？

0.9.0 REST 登录端点是 POST /users/login 而非 /auth/login。

Q4：数据卷是否随重启保留？

使用具名卷 iggy-server:/local_data，docker compose down 不删数据；只有 docker compose down -v 才清除。

Q5：如何看 Web UI？

需以默认 iggy-web feature 构建，并设置 IGGY_HTTP_WEB_UI=true（或配置 http.web_ui=true），访问 http://服务器IP:3000/ui。upstream Dockerfile 构建时已编译内置 Web 前端。

十二、参考链接

官方站点：https://iggy.apache.org
源码仓库（含 Dockerfile/docker-compose.yml）：https://github.com/apache/iggy
快速上手：https://iggy.apache.org/docs/introduction/getting-started/