Ubuntu 22.04 安装 Riemann 0.3.12 指南

目标：在 Ubuntu 22.04.5 LTS 服务器上从零安装 Riemann 0.3.12 监控事件流处理系统，覆盖官方 deb 包安装与 standalone jar 免安装两种方案，完成 systemd 托管、JVM 堆内存限制（256–512MB）、监听端口配置与事件注入/查询端到端验证。全部命令与回显均已在真实 Ubuntu 22.04 服务器环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（Jammy，x86_64）
Java 运行时：OpenJDK 11.0.32.1（default-jre-headless 安装）
Riemann 版本：0.3.12（官方最新稳定版，2025-05-26 发布于 GitHub Releases，查询日期 2026-11-01）
软件包：riemann_0.3.12_all.deb（98858064 字节，md5 01d8c4ed1fe77465faaa7ca19355ee3e）
备用包：riemann-0.3.12-standalone.jar（112919449 字节，自带全部依赖的 fat jar）
配置文件：/etc/riemann/riemann.config（Clojure DSL）
JVM 参数文件：/etc/default/riemann
日志文件：/var/log/riemann/riemann.log
运行用户：riemann（uid/gid 999，deb 安装时自动创建）
监听端口：5555/TCP+UDP（事件摄入）、5556/TCP（WebSocket/HTTP 接口）、5557/TCP（SSE/HTTP 查询接口，需显式启用）

二、前置条件

Riemann 是 Clojure/JVM 程序，运行前必须有 Java 运行时。先确认系统基础工具与网络：

cat /etc/os-release | head -2

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"

java -version 2>&1 | head -1

bash: line 1: java: command not found

系统未带 Java，先安装 JRE 与下载工具：

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y default-jre-headless wget curl
java -version 2>&1

openjdk version "11.0.32.1" 2026-08-18
OpenJDK Runtime Environment (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu, mixed mode, sharing)

⚠️ 注意：Riemann deb 包的依赖字段写的是 Recommends: default-jre-headless (<= 1.7) | java7-runtime，这是历史遗留的过时约束（Java 7 时代），Ubuntu 22.04 没有满足 <= 1.7 的包，因此 dpkg -i 不会自动拉起 JRE，必须先手动安装（见第四章实测）。Riemann 0.3.12 在 OpenJDK 11 上实测运行正常。

三、版本选型说明

官方仓库 github.com/riemann/riemann（原 aphyr/riemann，访问旧地址会 301 跳转）的 releases.atom 实测（查询日期 2026-11-01）近三个版本：

版本	发布日期	说明
0.3.12	2025-05-26	当前最新稳定版，本文实测版本
0.3.11	2023-12-27	上一版
0.3.10	2023-10-30	更早版本

0.3.12 的发布资产包括：riemann_0.3.12_all.deb（Debian/Ubuntu 通用）、riemann-0.3.12-1.noarch-EL6/7/8/9.rpm（RHEL 系）、riemann-0.3.12-standalone.jar（免安装 fat jar）、riemann-0.3.12.tar.bz2（发行包）。

⚠️ 网络说明：官方文档历史上指向的 apt 仓库 http://apt.riemann.com/riemann.list 于 2026-11-01 实测不可达（curl 返回 http_code=000，连接即失败）。当前可用的官方下载渠道为 GitHub Releases 直连，实测下载速度正常（94MB 约 12 秒），无需代理与国内镜像降级。

四、方案 A：官方 deb 包安装（推荐）

4.1 下载软件包与校验

cd /root
wget https://github.com/riemann/riemann/releases/download/0.3.12/riemann_0.3.12_all.deb

 96400K .......... .......... .......... .......... .......... 99%  232M 0s
 96450K .......... .......... .......... .......... .......... 99%  136M 0s
 96500K .......... .......... .......... .......... .         100% 42.6M=4.7s

real	0m12.367s

ls -la riemann_0.3.12_all.deb
md5sum riemann_0.3.12_all.deb
curl -sL https://github.com/riemann/riemann/releases/download/0.3.12/riemann_0.3.12_all.deb.md5

-rw-r--r-- 1 root root 98858064 May 26  2025 riemann_0.3.12_all.deb
01d8c4ed1fe77465faaa7ca19355ee3e  riemann_0.3.12_all.deb
01d8c4ed1fe77465faaa7ca19355ee3e  riemann_0.3.12_all.deb

本地 md5 与官方 .md5 文件逐字一致，包体完整。

4.2 查看包元数据并安装

dpkg -I riemann_0.3.12_all.deb | sed -n '9,16p'

 Package: riemann
 Version: 0.3.12
 Section: java
 Priority: optional
 Architecture: all
 Recommends: default-jre-headless (<= 1.7) | java7-runtime
 Maintainer: aphyr@aphyr.com
 Description: A network event stream processor. Intended for analytics, metrics, and alerting; and to glue various monitoring systems together.

dpkg -i /root/riemann_0.3.12_all.deb

Selecting previously unselected package riemann.
(Reading database ... 8229 files and directories currently installed.)
Preparing to unpack /root/riemann_0.3.12_all.deb ...
Unpacking riemann (0.3.12) ...
Setting up riemann (0.3.12) ...
invoke-rc.d: policy-rc.d denied execution of start.

⚠️ 说明：invoke-rc.d: policy-rc.d denied execution of start 表示 postinst 尝试拉起服务但被系统策略阻止（精简/无服务管理环境常见）；在完整 systemd 服务器上此处会自动启动服务。无论哪种情况，都按下文手动 systemctl enable --now 控制，结果一致。

4.3 安装落盘文件确认

dpkg -L riemann | grep -vE '\.jar$'

/.
/etc
/etc/default
/etc/default/riemann
/etc/init.d
/etc/init.d/riemann
/etc/riemann
/etc/riemann/riemann.config
/usr
/usr/bin
/usr/bin/riemann
/usr/share
/usr/share/riemann
/var
/var/log
/var/log/riemann

ls /usr/share/riemann/; id riemann

riemann.jar
uid=999(riemann) gid=999(riemann) groups=999(riemann)

deb 包以 all 架构分发（本质是 jar + 启动脚本），核心程序为 /usr/share/riemann/riemann.jar，启动器 /usr/bin/riemann，托管脚本 /etc/init.d/riemann（SysV 风格，systemd 通过 sysv-generator 自动生成同名 service 单元），运行用户 riemann 已自动创建。

五、方案 B：standalone jar 免安装运行

适合不便装包、或需要多版本并存的场景。jar 自带全部依赖，仅需 JRE：

wget https://github.com/riemann/riemann/releases/download/0.3.12/riemann-0.3.12-standalone.jar -O /root/riemann-standalone.jar
ls -la /root/riemann-standalone.jar

real	0m6.581s
-rw-r--r-- 1 root root 112919449 May 26  2025 /root/riemann-standalone.jar

用方案 A 的配置文件（仅把端口 555x 改为 565x 避免与已在跑的服务冲突）前台启动：

sed 's/5555/5655/g; s/5556/5656/g; s/5557/5657/g' /etc/riemann/riemann.config > /tmp/riemann-alt.config
java -Xms256m -Xmx512m -jar /root/riemann-standalone.jar start /tmp/riemann-alt.config

INFO [2026-11-01 09:52:18,827] clojure-agent-send-off-pool-2 - riemann.transport.websockets - Websockets server 0.0.0.0 5656 online
INFO [2026-11-01 09:52:18,864] clojure-agent-send-off-pool-1 - riemann.transport.tcp - TCP server 0.0.0.0 5655 online
INFO [2026-11-01 09:52:18,873] clojure-agent-send-off-pool-6 - riemann.transport.udp - UDP server 0.0.0.0 5655 16384 -1 online
INFO [2026-11-01 09:52:18,875] clojure-agent-send-off-pool-0 - riemann.transport.sse - SSE server 0.0.0.0 5657 online
INFO [2026-11-01 09:52:18,875] main - riemann.core - Hyperspace core online

ss -ltn | grep 565

LISTEN 0      50                 *:5656             *:*
LISTEN 0      50                 *:5657             *:*
LISTEN 0      50                 *:5655             *:*

四个服务全部 online，Hyperspace core online 是 Riemann 内核就绪的标志日志。Ctrl-C（或 pkill -f standalone）即停止，无残留。

六、方案对比与选择建议

维度	方案 A：官方 deb	方案 B：standalone jar
版本	0.3.12	0.3.12
是否需联网	安装时需（下载 94MB）	运行期不需要（下载一次后离线可用）
安装方式	`dpkg -i`	解压即用，无安装动作
systemd 来源	deb 自带 `/etc/init.d/riemann`，sysv-generator 生成单元	需自行编写 service 单元
运行用户	自动创建 `riemann`(999)	当前用户（建议自行降权）
配置/日志路径	`/etc/riemann`、`/var/log/riemann`	自选路径
升级/回滚	`dpkg -i` 覆盖安装	替换 jar 文件即可
优缺点	托管完整、路径规范	灵活、多版本并存，但托管需自建

生产服务器选方案 A（托管与降权开箱即用）；离线环境、蓝绿切换或多版本验证选方案 B。本文后续章节均基于方案 A。

七、systemd 托管与 JVM 内存限制

7.1 启动与开机自启

systemctl enable riemann
systemctl start riemann
systemctl status riemann --no-pager | head -12

riemann.service is not a native service, redirecting to systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable riemann
● riemann.service - LSB: Riemann server
     Loaded: loaded (/etc/init.d/riemann; generated)
     Active: active (running) since Sun 2026-11-01 09:42:07 UTC; 2s ago
       Docs: man:systemd-sysv-generator(8)
    Process: 4194 ExecStart=/etc/init.d/riemann start (code=exited, status=0/SUCCESS)
      Tasks: 39 (limit: 2266)
     Memory: 345.4M
        CPU: 4.767s
     CGroup: /system.slice/.../riemann.service
             └─4201 java -cp /usr/share/riemann/riemann.jar: riemann.bin start /etc/riemann/riemann.config

💡 技术拓展：deb 提供的是 SysV init 脚本而非原生 systemd unit，systemd 的 systemd-sysv-generator 会为其自动生成 riemann.service（Loaded: ... generated 即此含义）。常见 JVM 服务托管形态对比——

形态特点适用
SysV 脚本 + sysv-generator（本文所用）兼容老包，无原生 unit 精细控制（如资源限制需 override）发行版打包的老 Java 服务
原生 systemd unit ExecStart/MemoryMax/Environment 直接可控自建部署
容器化部署编排灵活，堆限经环境变量注入云原生场景

本文按 deb 自带的 SysV 托管形态实测；如需原生 unit 覆盖，用 systemctl edit riemann 加 override 即可。

形态	特点	适用
SysV 脚本 + sysv-generator（本文所用）	兼容老包，无原生 unit 精细控制（如资源限制需 override）	发行版打包的老 Java 服务
原生 systemd unit	`ExecStart`/`MemoryMax`/`Environment` 直接可控	自建部署
容器化部署	编排灵活，堆限经环境变量注入	云原生场景

注意 status 中 Memory: 345.4M——默认启动没有任何堆限制，JVM 按物理内存自动取默认 -Xmx，必须显式限制。

7.2 设置 JVM 堆限（256–512MB 硬性要求）

启动器 /usr/bin/riemann 第 4–6 行会 source /etc/default/riemann，并把其中 EXTRA_JAVA_OPTS 原样传给 java（脚本末行 exec java $EXTRA_JAVA_OPTS $OPTS -cp "$JAR" riemann.bin "$COMMAND" "$CONFIG"）。因此堆限的修改位置就是 /etc/default/riemann 的 EXTRA_JAVA_OPTS：

vi /etc/default/riemann

# Optionally add classes to the classpath for additional functionality
# EXTRA_CLASSPATH=

# Optional JAVA_OPTS
EXTRA_JAVA_OPTS="-Xms256m -Xmx512m"
...

重启服务并验证生效：

systemctl restart riemann
jps -v | grep -v Jps

4553 bin -Xms256m -Xmx512m

ps -ef | grep [j]ava

riemann     4553       1 36 09:43 ?        00:00:04 java -Xms256m -Xmx512m -cp /usr/share/riemann/riemann.jar: riemann.bin start /etc/riemann/riemann.config

jps -v 与 ps -ef 双通道均确认 -Xms256m -Xmx512m 已生效，进程 RSS 稳定在数百 MB 以内，不会挤占同机其他服务内存。

7.3 启动脚本的 Java 版本解析缺陷（实测报错）

每次调用 riemann 命令都会看到一行 bash 报错：

/usr/bin/riemann: line 11: [[: 11.032: syntax error: invalid arithmetic operator (error token is ".032")

定位：脚本第 11 行用 sed 从 java -version 提取版本号做 [[ "$JAVA_VERSION" -le 18 ]] 比较，其正则对 11.0.32.1 这类四段版本串提取出 11.032（把主次版本拼在一起），bash 算术比较直接报错。影响：if 两个分支都不执行——既不注入 CMS/GC 优化参数也不注入 --add-modules，服务照常启动（实测 active），属无害噪音；若追求干净，把第 11 行改为只取主版本号：

JAVA_VERSION=$(java -version 2>&1 | awk -F\" '/version/ {print $2}' | cut -d. -f1)

改后 riemann -v 不再报错（见第九章实测）。

八、配置说明与热加载

8.1 默认配置只监听 127.0.0.1

deb 自带的 /etc/riemann/riemann.config 关键行：

(logging/init {:file "/var/log/riemann/riemann.log"})

(let [host "127.0.0.1"]
  (tcp-server {:host host})
  (udp-server {:host host})
  (ws-server  {:host host}))

(periodically-expire 5)

(let [index (index)]
  (streams
    (default :ttl 60
      index
      (expired
        (fn [event] (info "expired" event))))))

⚠️ 注意：默认只绑 127.0.0.1，远程 agent 无法投递事件；且默认未启用 SSE/HTTP 查询接口。生产需改为监听所有网卡并加 sse-server。

8.2 生产监听配置

; -*- mode: clojure; -*-
; vim: filetype=clojure

(logging/init {:file "/var/log/riemann/riemann.log"})

; Listen on all interfaces: TCP/UDP 5555, websockets 5556, SSE/HTTP 5557
(let [host "0.0.0.0"]
  (tcp-server {:host host :port 5555})
  (udp-server {:host host :port 5555})
  (ws-server  {:host host :port 5556})
  (sse-server {:host host :port 5557}))

; Expire old events from the index every 5 seconds.
(periodically-expire 5)

(let [index (index)]
  ; Inbound events will be passed to these streams:
  (streams
    (default :ttl 60
      ; Index all events immediately.
      index

      ; Log expired events.
      (expired
        (fn [event] (info "expired" event))))))

逐项说明：tcp-server/udp-server 默认端口 5555（TLS 模式默认 5554），负责 protobuf/JSON 事件摄入；ws-server 默认 5556，提供 WebSocket 与 HTTP POST /events、GET /index（仅 WS 升级请求）；sse-server 默认 5558，本文显式改为 5557，提供纯 HTTP GET /index?query=... 查询与 SSE 事件流；periodically-expire 5 每 5 秒清理索引中过期事件；default :ttl 60 给未带 ttl 的事件补 60 秒存活期；expired 流把过期事件写日志。配置详解见《Riemann 0.3.12 配置参数详解》。

8.3 SIGHUP 热加载

改完配置无需重启，Riemann 支持 SIGHUP 全量重载（init 脚本的 reload 动作即发 SIGHUP）：

systemctl reload riemann
sleep 4
tail -6 /var/log/riemann/riemann.log

INFO [2026-11-01 09:47:54,471] clojure-agent-send-off-pool-5 - riemann.transport.udp - UDP server 127.0.0.1 5555 16384 -1 shut down
INFO [2026-11-01 09:47:54,473] clojure-agent-send-off-pool-12 - riemann.transport.websockets - Websockets server 0.0.0.0 5556 online
INFO [2026-11-01 09:47:54,474] clojure-agent-send-off-pool-8 - riemann.transport.tcp - TCP server 0.0.0.0 5555 online
INFO [2026-11-01 09:47:54,475] clojure-agent-send-off-pool-10 - riemann.transport.udp - UDP server 0.0.0.0 5555 16384 -1 online
INFO [2026-11-01 09:47:54,476] clojure-agent-send-off-pool-7 - riemann.transport.sse - SSE server 0.0.0.0 5557 online
INFO [2026-11-01 09:47:54,477] SIGHUP handler - riemann.core - Hyperspace core online

ss -ltn | grep -E '555[5-7]'; ss -lun | grep 5555

LISTEN 0      50                 *:5556             *:*
LISTEN 0      50                 *:5557             *:*
LISTEN 0      50                 *:5555             *:*
UNCONN 0      0                  *:5555             *:*

旧服务 shut down、新服务 online、SIGHUP handler - Hyperspace core online，全接口监听就绪，进程 PID 不变、索引不丢。

九、安装验证

9.1 版本与配置自检

riemann -v

/usr/bin/riemann: line 11: [[: 11.032: syntax error: invalid arithmetic operator (error token is ".032")
WARNING: abs already refers to: #'clojure.core/abs in namespace: clojure.math.numeric-tower, being replaced by: #'clojure.math.numeric-tower/abs
0.3.12

输出版本号 0.3.12（首行为 7.3 节所述脚本缺陷噪音，abs WARNING 为 Clojure 库加载噪音，均无害）。

riemann test /etc/riemann/riemann.config

INFO [2026-11-01 09:51:22,267] main - riemann.bin - Loading /etc/riemann/riemann.config

Testing clojure.core

Ran 0 tests containing 0 assertions.
0 failures, 0 errors.

test 子命令加载配置并执行 riemann.test 注册的用例（默认配置无用例故为 0），可用来上线前验证配置文件语法。

9.2 端到端事件注入与查询

通过 5556 的 HTTP 接口注入一条事件（注意：每行一个 JSON 对象，不是 JSON 数组，见第十章 Q3）：

echo '{"host":"web-01","service":"cpu","state":"ok","metric":42.0,"ttl":600}' | \
  curl -s -X POST --data-binary @- http://127.0.0.1:5556/events

{}

{} 为摄入成功回执。通过 5557 的 SSE 查询接口检索索引（查询语法见第十章 Q4）：

curl -s -N -m 2 "http://127.0.0.1:5557/index?query=service%20%3D%20%22cpu%22"

data: {"host":"web-01","service":"cpu","state":"ok","metric":42.0,"ttl":600,"time":"2026-11-01T09:53:33.486Z"}

事件已被索引并可查询，安装完成。更多 CLI 用法见《Riemann 0.3.12 常用 CLI 命令与工具详解》。

十、常见问题（FAQ）

10.1 官方 apt 仓库不可达

Q1： 按官方文档配置 http://apt.riemann.com/riemann.list 后 apt update 报错？ A： 2026-11-01 实测该仓库已不可达（curl http://apt.riemann.com/riemann.list 返回 http_code=000，连接即失败），不要再用。直接下载 GitHub Releases 的 riemann_0.3.12_all.deb 安装（第四章），国内网络下载慢时可临时 wget -x http://<代理地址>:7897 <URL> 走代理。

10.2 dpkg 安装后没有自动装 JRE

Q2： dpkg -i 成功但 java 不存在，服务起不来？ A： deb 的依赖声明停留在 Java 7 时代（Recommends: default-jre-headless (<= 1.7)），22.04 无包满足，dpkg 静默跳过。手动 apt-get install -y default-jre-headless 即可（第二章）。

10.3 POST /events 返回 LazySeq 类型转换错误

Q3： 用 JSON 数组 [{...},{...}] POST 到 5556 返回：

{"error":"class clojure.lang.LazySeq cannot be cast to class clojure.lang.Associative (clojure.lang.LazySeq and clojure.lang.Associative are in unnamed module of loader 'app')"}

A： POST /events 的请求体是换行分隔的单个 JSON 对象（NDJSON），不是数组。每条事件一行：echo '{"host":"web-01","service":"cpu"}' | curl -X POST --data-binary @- http://127.0.0.1:5556/events。

10.4 查询接口返回语法错误

Q4： GET /index?query=service="cpu" 返回 extraneous input '"cpu"' expecting {<EOF>, 'and', 'or'}？ A： Riemann 查询 DSL 里 = 两侧必须有空格（无空格时 service= 会被词法整体吞成字段名），且字符串值必须用双引号。正确写法 service = "cpu"（URL 编码为 service%20%3D%20%22cpu%22）。service = cpu（不带引号）会被解析成两个字段比较，恒不匹配，注意区分。

10.5 远程 agent 连不上 5555

Q5： 防火墙已放行但 statsd/agent 报连接失败？ A：默认配置只绑 127.0.0.1（第八章 8.1），改为 0.0.0.0 后 systemctl reload riemann 热加载，用 ss -ltn | grep 5555 确认变为 *:5555。

10.6 每次执行 riemann 命令报 line 11 算术错误

Q6： /usr/bin/riemann: line 11: [[: 11.032: syntax error？ A：官方脚本对四段 Java 版本号解析缺陷（7.3 节），无害噪音；按 7.3 给出的 awk 写法修复第 11 行即可消除。

十一、卸载与清理

systemctl stop riemann
systemctl is-active riemann

inactive

systemctl disable riemann
apt-get purge -y riemann

Executing: /lib/systemd/systemd-sysv-install disable riemann
(Reading database ... 8731 files and directories currently installed.)
Purging configuration files for riemann (0.3.12) ...
dpkg: warning: while removing riemann, directory '/var/log/riemann' not empty so not removed

ls /etc/riemann 2>&1; rm -rf /var/log/riemann; ls /var/log/riemann 2>&1

ls: cannot access '/etc/riemann': No such file or directory
ls: cannot access '/var/log/riemann': No such file or directory

purge 会移除程序与 /etc/riemann 配置目录，但日志目录因非空保留，最后 rm -rf /var/log/riemann 清净。运行用户 riemann 如需一并删除：userdel riemann; groupdel riemann。

十二、参考链接

Riemann 官方仓库：https://github.com/riemann/riemann
Riemann 0.3.12 Releases：https://github.com/riemann/riemann/releases/tag/0.3.12
Riemann 官方文档：https://riemann.io/
同专栏文档：《Riemann 介绍与选型指南》《Riemann 0.3.12 配置参数详解》《Riemann 0.3.12 常用 CLI 命令与工具详解》