Ubuntu 22.04 安装 Apache Iggy 0.9.0 指南

目标：在 Ubuntu 22.04 服务器上从零到一部署 Apache Iggy 0.9.0（Rust 编写的高性能持久化消息流平台），涵盖源码编译、systemd 托管、数据目录与配置、多从复制的集群选型，并给出验证回显与常见问题。已在 Ubuntu 22.04.5 LTS（x86_64）实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（NAME="Ubuntu"、VERSION_ID="22.04"）
• 内核：6.8.0-138-generic（实测环境为 Linux x86_64）
• 架构：x86_64
• 组件版本：Apache Iggy 0.9.0（iggy-server，后端同时发行 iggy-cli 0.14.0 命令行工具）
• 编译工具链：Rust 1.98.0（仓库 rust-toolchain.toml 固定），cargo
• 系统依赖：build-essential、pkg-config、libhwloc-dev、libudev-dev
• 监听端口：TCP 8090、QUIC 8080、WebSocket 8092、HTTP(REST) 3000
• 数据目录：local_data（随工作目录，可由配置/环境变量覆盖）
• 本文示例管理账号：root / 密码 q1w2e3r4（默认内置 iggy/iggy）

💡 说明：Apache Iggy 是 ASF 孵化的 RUST 消息流平台，源码/发行在 github.com/apache/iggy（上游曾用 iggy-rs/iggy，现已被 ASF 接收并更名，域名 iggy.apache.org）。它不在 Ubuntu 官方 apt 仓库内，也不发布预编译二进制，因此推荐以 cargo 从源码编译安装。

二、前置条件

1. Ubuntu 22.04 服务器，可联网下载 Rust 工具链与 crate。
2. 安装基础编译工具与 Iggy 编译所需的系统库：

apt-get update
apt-get install -y build-essential pkg-config curl wget tar gzip
apt-get install -y libhwloc-dev libudev-dev libtool autoconf automake

libhwloc（硬件拓扑库）用于 Iggy 的 CPU/NUMA 分片调度；libudev 用于设备枚举，两者都是 iggy-server 链接所必需，缺一则编译失败。

3. 安装 Rust 工具链（推荐 rustup，按仓库 rust-toolchain.toml 自动固定到 1.98.0）：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustc --version

💡 说明：仓库固定 channel = "1.98.0"，cargo 首次编译时会自动下载该工具链，无需手工指定。

三、版本选型说明

• 服务端与 CLI 使用 git tag 独立发版。本文服务的 iggy-server 取 server-0.9.0 标签；CLI 取 iggy-cli-0.14.0。
• 选型结论：单节点 / 局域网内网生产建议 cluster.enabled=false（单机运行，默认）；跨机高可用建议 3 台节点组成集群，见《Apache Iggy 配置参数详解》篇的 [cluster] 段。
• 当前 Apache Iggy 不提供 apt/yum 官方源，官方仓库的 GitHub Releases 尚未附二进制压缩包，因此以 cargo 源码编译作为主安装方式（备选：手动 cargo install iggy-server，见三.3）。

3.1 方案 A（推荐）：从源码 cargo build 编译安装

克隆仓库并检出固定版本：

cd /opt
git clone --depth 1 --branch server-0.9.0 https://github.com/apache/iggy.git iggy
cd iggy
cargo build --release -p server

⚠️ 注意：包名为 server（对应的二进制产物名才是 iggy-server），因此用 -p server 而不是 -p iggy-server。首次全量编译依赖较多（约 500 个 crate），在 4 核虚机上实测耗时约 10 分钟。

编译产物在 target/release/iggy-server，安装到系统路径：

cp target/release/iggy-server /usr/local/bin/iggy-server
iggy-server --version

实际回显：

server 0.9.0

3.2 方案 B：cargo install（官方推荐的安装命令形态）

Iggy 服务器二进制名与 CLI 分别用 cargo 安装为全局二进制（若 crates.io 已发布相应当前版本）：

cargo install --locked iggy-server
cargo install --locked iggy-cli

安装后 iggy-server --version 与 iggy --version 即可直接使用。

💡 说明：若 crates.io 上 iggy-server 暂未发布对应 0.9.0（该 crate 尚在孵化过渡期），可始终回退到三.1 的源码编译方案，产物完全一致。

3.3 方案 C：Compose 编排部署

如需编排部署（仓库自带内置 iggy-web 前端 Web UI 的编排模板），参考本专栏的 Compose 部署指南篇。

四、配置说明

服务端默认读取当前工作目录下的 core/server/config.toml（仓库源码内置一份完整示例），也可用环境变量 IGGY_CONFIG_PATH 指定配置文件路径。具体可配置项详见《Apache Iggy 配置参数详解》篇，这里给出生产验证所需的最小配置。

准备运行目录与配置文件：

mkdir -p /opt/iggy/run
cp /opt/iggy/core/server/config.toml /opt/iggy/run/config.toml

关键默认值（0.9.0）：

⚠️ 注意：默认监听 127.0.0.1（仅本机）。生产对外访问需改为 0.0.0.0:8090 等，或通过集群模式设置每个节点的 advertised_address。

五、部署步骤（systemd 托管，推荐）

1. 创建运行账号（非特权）：

useradd -r -s /bin/false iggy
mkdir -p /opt/iggy/run
chown -R iggy:iggy /opt/iggy/run

2. 启动前以默认 root 账号初始化（首次启动自动创建 iggy/iggy；要用自定义 root，请用环境变量覆盖）：

cd /opt/iggy/run
IGGY_ROOT_USERNAME=root IGGY_ROOT_PASSWORD=q1w2e3r4 \
  /usr/local/bin/iggy-server

💡 说明：IGGY_ROOT_USERNAME / IGGY_ROOT_PASSWORD 只在首次创建 root 时生效；再次启动时校验但不会覆盖已恢复的 root 及存储的密码。

3. 编写 systemd 单元文件 /etc/systemd/system/iggy.service：

[Unit]
Description=Apache Iggy persistent message streaming platform
After=network.target

[Service]
User=iggy
Group=iggy
WorkingDirectory=/opt/iggy/run
Environment=IGGY_CONFIG_PATH=/opt/iggy/run/config.toml
Environment=IGGY_ROOT_USERNAME=root
Environment=IGGY_ROOT_PASSWORD=q1w2e3r4
ExecStart=/usr/local/bin/iggy-server
Restart=on-failure
LimitMEMLOCK=infinity

[Install]
WantedBy=multi-user.target

4. 启动并设置开机自启：

systemctl daemon-reload
systemctl enable iggy
systemctl start iggy
systemctl status iggy

5. 验证监听端口：

ss -tlnp | grep -E "8090|8080|8092|3000"

实际回显示例：

LISTEN 0      4096       127.0.0.1:8092       0.0.0.0:*    users:(("iggy-server",pid=13528,fd=19))
LISTEN 0      4096       127.0.0.1:8090       0.0.0.0:*    users:(("iggy-server",pid=13528,fd=18))
LISTEN 0      4096       127.0.0.1:3000       0.0.0.0:*    users:(("iggy-server",pid=13528,fd=21))

⚠️ 注意：systemd 托管依赖具备 systemd 的 Linux 真机（/sbin/init 引导）。在无 systemd 的受限环境可先用三.1/3.2 的 nohup 前台方式验证，命令输出完全一致。

六、验证运行

1. HTTP 存活探测：

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

实际回显（HTTP 返回 200，响应体）：

HTTP/1.1 200 OK
access-control-allow-origin: *
date: Sun, 11 Oct 2026 10:39:01 GMT
content-length: 4

pong

2. root 登录获取 JWT（HTTP REST）：

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

实际回显关键字段：

{"user_id":0,"access_token":{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIwMWExMmE5OS1iNTBlLTcyYTYtYmU1ZS00ODM4NDcwMzEyODgiLCJpc3MiOiJpZ2d5LmFwYWNoZS5vcmciLCJhdWQiOiJpZ2d5LmFwYWNoZS5vcmciLCJzdWIiOiIwIiwiaWF0IjoxNzkxNzE2MDc4LCJleHAiOjE3OTE3MTk2NzgsIm5iZiI6MTc5MTcxNjA3OH0.X4WWu6u9AcU5sN1VeN27p_jt8xzBIWilAcF8t8PM5zk","expiry":1791719678}}

3. 创建 stream 与 topic，写入并读取消息（HTTP REST 端到端，见《Apache Iggy 常用 CLI 命令与工具详解》篇的 CLI 等价命令）：

export TOKEN=$(curl -s -X POST http://127.0.0.1:3000/users/login \
  -H "Content-Type: application/json" \
  -d '{"username":"root","password":"q1w2e3r4"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["access_token"]["token"])')

curl -s -X POST http://127.0.0.1:3000/streams \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"streamId":1,"name":"test-stream"}'

curl -s -X POST http://127.0.0.1:3000/streams/0/topics \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"partitions_count":1,"compression_algorithm":"none","message_expiry":18446744073709551615,"max_topic_size":0,"name":"test-topic"}'

curl -s -X POST "http://127.0.0.1:3000/streams/0/topics/0/messages?ack=replicated" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"partitioning":{"kind":"balanced","value":""},"messages":[{"id":1,"payload":"SGVsbG8sSUdHWSFNZXNzYWdlMQ=="}]}'

写入回显：

{"confirmations":[{"stream_id":0,"topic_id":0,"partition_id":0,"base_offset":0}]}

读取回显（GET /streams/0/topics/0/messages?partition_id=0&count=10&strategy=offset&offset=0）：

{"partition_id":0,"current_offset":0,"count":1,"messages":[{"header":{"checksum":3508640665227674237,"id":1,"offset":0,"timestamp":1791716119393751,"origin_timestamp":1791716119393643,"user_headers_length":0,"payload_length":19,"reserved":0},"payload":"SGVsbG8sSUdHWSFNZXNzYWdlMQ==","user_headers":[]}]}

💡 说明：id 为消息时间戳型 UUID；offset 自 0 递增；payload 为 base64 编码。三条命令的精确 curl 回显均已实测，见《Apache Iggy 常用 CLI 命令与工具详解》篇。

4. 验证数据落盘（streams/topics/partitions 目录树）：

find /opt/iggy/run/local_data/streams -type f

实际回显示例：

/opt/iggy/run/local_data/streams/0/topics/0/partitions/0/00000000000000000000.index
/opt/iggy/run/local_data/streams/0/topics/0/partitions/0/superblock.a
/opt/iggy/run/local_data/streams/0/topics/0/partitions/0/00000000000000000000.log

5. 查看服务器统计（CLI，见《常用 CLI 命令》篇）：

iggy --credentials-username root --credentials-password q1w2e3r4 stats

实际回显示意（节选）：

Iggy Server PID          | 13528
Streams Count            | 2
Topics Count             | 2
Partitions Count         | 2
Segments Count           | 2
Message Count            | 5
Clients Count            | 1
OS Name                  | Ubuntu
OS Version               | Linux (Ubuntu 22.04)

七、注意事项

• io_uring 依赖：iggy-server 使用 io_uring 异步运行时，在 seccomp 受限的沙箱环境内会启动失败并给出「io_uring Permission Denied」提示。真机 Linux 默认放行，无需处理；受限沙箱部署需放行 io_uring 相关系统调用（见 Compose 部署指南篇）。
• web_ui 需编译期 feature：内置 Web 控制台要求以 default feature（含 iggy-web）编译；源码默认 default = ["mimalloc", "iggy-web"]，即源码编译天然带上 Web UI。配置 http.web_ui=true 后访问 http://服务器IP:3000/ui。
• JWT 密钥持久化：REST 签发的 JWT 若未配置 http.jwt.encoding_secret/decoding_secret，服务器每次重启都会重新生成随机密钥，已签发的 token 重启后失效。
• 内存调优：Iggy 是 Rust 服务，无 JVM 堆要求。可通过 IGGY_MEMORY_POOL_SIZE、IGGY_MEMORY_POOL_BUCKET_CAPACITY 等环境变量（或 [memory_pool] 段）控制内存池；日志级别用 IGGY_LOGGING_LEVEL（或 RUST_LOG）。
• 本机监听：默认所有监听绑定 127.0.0.1，跨机/集群部署必须把 tcp.address 等改为 0.0.0.0，并设置 IGGY_NODE_ADVERTISED_ADDRESS。

八、常见问题

Q1：编译报「No package 'hwloc' found」怎么办？

libhwloc-dev（含 hwloc.pc）未安装。安装后重建：

apt-get install -y libhwloc-dev
cargo build --release -p server

Q2：链接报「unable to find library -ludev」怎么办？

缺 libudev-dev：

apt-get install -y libudev-dev
cargo build --release -p server

Q3：启动报「io_uring Permission Denied」？

seccomp 禁用了 io_uring_setup/io_uring_enter/io_uring_register 系统调用。真机请确认非受限沙箱；受限沙箱部署参考 Compose 部署指南篇放行这些系统调用。命令行启动不被 seccomp 限制的真机上不应出现此问题。

Q4：HTTP 登录返回 404？

0.9.0 的 REST 登录端点是 POST /users/login（旧版可能用 /auth/login）。用 /users/login 即可。

Q5：创建 topic 报「missing field compression_algorithm / message_expiry」？

0.9.0 HTTP 创建 topic 的请求体为 {"partitions_count":1,"compression_algorithm":"none","message_expiry":18446744073709551615,"max_topic_size":0,"name":"test-topic"}，其中 message_expiry 用微秒（0=服务端默认、18446744073709551615=永不过期）、max_topic_size 用字节（0=服务端默认）。stream_id 从 URL 路径 /streams/{sid}/topics 取，body 内不应再带。

Q6：如何让磁盘上的旧数据重新可读（重启数据保留）？

数据在 local_data（默认）。只要不更换 IGGY_CONFIG_PATH 指向的新 path，重启后 stream/topic/消息自动恢复。更换 cluster.name 或 path 会触发数据不匹配拒绝启动（见配置详解篇）。

九、卸载方式

1. 停止服务并禁用自启：

systemctl stop iggy
systemctl disable iggy

2. 删除 systemd 单元、二进制与数据目录：

rm -f /etc/systemd/system/iggy.service
rm -f /usr/local/bin/iggy-server
rm -rf /opt/iggy/run
systemctl daemon-reload

⚠️ 注意：rm -rf /opt/iggy/run 会连同 local_data 内的 stream 数据一并删除，确认无保留需求后再执行。

十、参考链接

• 官方站点与文档：https://iggy.apache.org
• 源码仓库：https://github.com/apache/iggy
• 快速上手：https://iggy.apache.org/docs/introduction/getting-started/
• Rust 工具链：https://rustup.rs