Ubuntu 22.04 安装 Rudder 指南

目标：在 Ubuntu 22.04 LTS 上通过官方 APT 仓库完成 Rudder 根服务器（root server）与被管节点（agent）的完整部署，并跑通「安装 → 关联 → 清单上报 → Web 验收 → 策略收敛」全链路。文中全部命令与回显均于 2026-10-22 在两台 Ubuntu 22.04.5 LTS 真实服务器上逐条实测，Rudder 版本为 8.3.13（Ubuntu 22.04 平台当前可安装的最新版，选型依据见第三章）。

一、环境信息

本文所有操作在以下两台服务器上实测完成（2026-10-22，时区 Asia/Shanghai）：

角色	主机名	IP 地址	操作系统	安装软件	版本
根服务器	rudder-server	10.89.59.2	Ubuntu 22.04.5 LTS	rudder-server	8.3.13-ubuntu22.04
被管节点	rudder-agent	10.89.59.3	Ubuntu 22.04.5 LTS	rudder-agent	8.3.13-ubuntu22.04

版本实查日期：2026-10-22，来源 repository.rudder.io 官方 APT 仓库目录列表与 docs.rudder.io 8.3 参考手册
软件架构说明（组件构成、端口职责、选型对比）见《Rudder 9.1 介绍与选型指南》，本文聚焦安装落地
两台服务器已互相解析主机名（/etc/hosts 中登记对方 IP），节点接入依赖主机名解析，第二章有核对方法
回显约定：命令在服务器上以 root 执行，实测回显逐行照抄（节选处已标注）

二、前置条件

安装前逐项核对，任何一项不满足都会导致安装失败或节点无法接入。

2.1 硬件与系统要求

根服务器内存按官方口径（docs.rudder.io 8.3 参考手册「Root server sizing」页，2026-10-22 实查）：

管理节点数	根服务器最低内存
< 50 节点	3 GB
50 ~ 1000 节点	4 GB
> 1000 节点	4 GB + 每 500 节点追加 1 GB

本文环境为最小化部署（2 节点），根服务器物理内存 8 GB，Web 应用 JVM 堆限制调整为 512 MB（见第七章），运行平稳。被管节点无特殊内存要求。

2.2 网络与端口要求

节点须能访问根服务器的以下端口（实测 ss -ltn 核对，回显见 4.6 节）：

端口	用途	暴露范围
443/tcp	Web UI、节点报告与清单上报、策略 HTTPS 下载	全网
5309/tcp	CFEngine 协议策略分发（cf-serverd）	全网
80/tcp	HTTP 入口（自动跳转 HTTPS）	全网
5432/tcp	PostgreSQL 数据库	仅本机
389/tcp	OpenLDAP 目录服务	仅本机
8080/tcp	Jetty Web 应用	仅本机
3030/tcp	rudder-relayd 健康 API	仅本机

防火墙如开启，放行 443 与 5309 两个 tcp 端口即可。

2.3 系统准备

两台服务器统一执行：确认系统版本、时间同步、主机名解析。

cat /etc/os-release | head -2
hostname

实测回显（节点侧，服务器侧同理仅主机名不同）：

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

rudder-agent

在两台服务器 /etc/hosts 中互相登记（节点访问根服务器默认按主机名）：

echo "10.89.59.2 rudder-server" >> /etc/hosts      # 节点上执行
echo "10.89.59.3 rudder-agent" >> /etc/hosts       # 服务器上执行（可选，便于反查）

验证解析：

getent hosts rudder-server

实测回显（节点上执行）：

10.89.59.2    rudder-server

⚠️ 本章收尾验证：getent hosts rudder-server 必须在节点上解析成功，否则 5.3 节的 rudder agent policy-server 会因解析失败而无法关联。

三、版本选型说明

Ubuntu 22.04 用户安装 Rudder 前必须先弄清版本对应关系——Rudder 9.x 已不再为 Ubuntu 22.04 提供软件包，这一点官方仓库可以逐层实证。

3.1 版本实查结论（2026-10-22）

Rudder 最新稳定版：9.1.5（官方仓库 /apt/ 目录 latest/ 指向 9.1 系列，系列内最新补丁 9.1.5；9.2 系列仅有 9.2.0~rc1/rc2 预览包）
Ubuntu 22.04（jammy）可安装的最新版：8.3.13（8.3 LTS 系列最新补丁）

3.2 9.x 不支持 22.04 的仓库级证据

在 22.04 服务器上把软件源指向 9.1 系列后执行 apt-get update，实测报错：

E: Failed to fetch http://repository.rudder.io/apt/9.1/dists/jammy/main/binary-amd64/Packages  404  Not Found [IP: 212.129.48.80 80]
E: Some index files failed to download. They have been ignored, or old ones used instead.

进一步实查官方仓库目录（2026-10-22）：

/apt/9.1/dists/ 下不存在 jammy 索引目录，仅提供 debian12、debian13、noble（24.04）等代号
/apt/pool/ 下 9.x 系列仅有 debian12/13、ubuntu24.04/26.04 构建，无 ubuntu22.04 目录
8.3 系列则保留完整 jammy 支持：/apt/8.3/dists/jammy/ 索引正常，pool 中存在 rudder-server_8.3.13-ubuntu22.04_amd64.deb

3.3 选型结论

服务器系统	推荐版本	说明
Ubuntu 24.04 / 26.04	9.1 系列（当前 9.1.5）	最新稳定版，安装方法同理，软件源写 `9.1`
Ubuntu 22.04	8.3 LTS（当前 8.3.13）	唯一可选系列，官方持续维护（8.3.13 为 LTS 补丁版）

因此本文在 Ubuntu 22.04 上安装 8.3.13。若计划长期使用 22.04，需接受与 9.x 的大版本功能差异；若必须使用 9.x，应将系统升级至 24.04 后参考《Rudder 9.1 介绍与选型指南》第五章的 24.04 安装流程。

四、方案：官方 APT 仓库安装 Root Server

4.1 方案说明

Rudder 官方为 Debian/Ubuntu 提供 APT 仓库（repository.rudder.io/apt/<系列>/<代号>），rudder-server 元包会自动拉齐全部服务端组件（Java/Scala Web 应用、PostgreSQL、OpenLDAP、Apache、rudder-relayd、CFEngine 服务端）。这是唯一经过官方完整测试、也是本文唯一实测的安装方式。

Rudder 未提供离线 deb 包合集与源码编译安装路径：断网环境可自行从 pool 目录下载 deb 依赖手工安装（本文未实测，不展开）；编译源码仅适用于参与开发。以下均针对在线仓库方案。

4.2 配置官方软件源

第一步，导入官方签名密钥（GPG 环节实测无输出即为成功）：

apt-get install -y gnupg wget
wget --quiet -O /etc/apt/keyrings/rudder_apt_key.gpg "https://repository.rudder.io/apt/rudder_apt_key.gpg"

校验密钥指纹（应与官方公布的 7C16 9817 7904 212D D58C B4D1 9322 C330 474A 19E8 一致）：

gpg --show-keys --with-fingerprint --with-colons /etc/apt/keyrings/rudder_apt_key.gpg | grep "^fpr"

实测回显（主指纹与子钥指纹各一行）：

fpr:::::::::7C1698177904212DD58CB4D19322C330474A19E8:
fpr:::::::::56E9547DBA3CFEA4D8D8FC8403B5A39F047ECE4A:

第二步，写入 8.3 系列软件源（Ubuntu 22.04 代号为 jammy）：

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/rudder_apt_key.gpg] http://repository.rudder.io/apt/8.3/ $(lsb_release -cs) main" > /etc/apt/sources.list.d/rudder.list
apt-get update

实测回显（节选，仓库索引命中即成功）：

Hit:5 http://repository.rudder.io/apt/8.3 jammy InRelease
Reading package lists...

确认候选版本为 8.3.13：

apt-cache policy rudder-server | head -6

实测回显：

rudder-server:
  Installed: (none)
  Candidate: 8.3.13-ubuntu22.04
  Version table:
     8.3.13-ubuntu22.04 500
        500 http://repository.rudder.io/apt/8.3 jammy/main amd64 Packages

⚠️ 本章收尾验证：apt-cache policy rudder-server 的 Candidate 必须显示 8.3.13-ubuntu22.04。若显示 404 类报错，回看软件源行是否把系列写错（9.1 在 jammy 上必然 404，见第三章）。

4.3 安装 rudder-server

apt-get install -y rudder-server

实测回显（安装日志尾部节选）：

Setting up openjdk-17-jre-headless:amd64 (17.0.20.1+1-1~22.04) ...
update-alternatives: using /usr/lib/jvm/java-17-openjdk-amd64/bin/java to provide /usr/bin/java (java) in auto mode
Setting up rudder-server (8.3.13-ubuntu22.04) ...
INFO Repository index updated
INFO Not updating licenses as no configured credentials were found
INFO All plugins were upgraded successfully
INFO All postinstall scripts ran successfully

安装完成。安装过程自动完成：Jetty 运行环境（OpenJDK 17）部署、PostgreSQL 与 OpenLDAP 初始化、Apache 站点配置、CFEngine 服务端密钥生成。

4.4 初始化配置：创建首个管理员账号

Rudder 的 Web 登录账号存于 /opt/rudder/etc/rudder-users.xml（argon2id 哈希），首个账号用官方命令创建：

rudder server create-user -u admin -p q1w2e3r4

实测回显：

User 'admin' added, restarting the Rudder server

命令会自动重启 Web 应用使账号生效。等待约 20 秒后即可登录。若重复执行同名创建会报错（处理办法见第八章 FAQ 8.2）。

4.5 systemd 托管

rudder-server 是伞形服务（umbrella service），拉起全部服务端单元：

systemctl is-active rudder-server rudder-jetty rudder-slapd rudder-relayd rudder-cf-serverd apache2 postgresql

实测回显（7 个单元全部 active）：

active
active
active
active
active
active
active

查看伞形服务详情：

systemctl status rudder-server --no-pager | head -8

实测回显：

● rudder-server.service - Rudder server umbrella service
     Loaded: loaded (/lib/systemd/system/rudder-server.service; enabled; vendor preset: enabled)
     Active: active (exited) since Thu 2026-10-22 09:39:26 UTC; 44min ago
       Docs: https://docs.rudder.io
   Main PID: 21632 (code=exited, status=0/SUCCESS)
        CPU: 1ms

Oct 22 09:39:26 rudder-server systemd[1]: Starting Rudder server umbrella service...

服务已设为开机自启（enabled），服务器重启后无需手工干预。

4.6 安装验证

逐一核对监听端口与服务健康度：

ss -ltn | grep -E ":(443|80|5432|389|5309|3030|8080) "
rudder server health

实测回显：

LISTEN 0      511               0.0.0.0:443        0.0.0.0:*
LISTEN 0      511               0.0.0.0:80         0.0.0.0:*
LISTEN 0      128             127.0.0.1:3030       0.0.0.0:*
LISTEN 0      2048            127.0.0.1:389        0.0.0.0:*
LISTEN 0      244             127.0.0.1:5432       0.0.0.0:*
LISTEN 0      128                     *:5309             *:*
LISTEN 0      50     [::ffff:127.0.0.1]:8080             *:*

OK

curl -sk -d "username=admin&password=q1w2e3r4" -o /dev/null -w "%{http_code} %{redirect_url}\n" https://localhost/rudder/j_spring_security_check

实测回显：

302 https://localhost/rudder/secure/index.html

⚠️ 本章收尾验证：7 个服务单元 active、rudder server health 返回 OK、登录 302 跳转 /rudder/secure/index.html，三项全部满足才算服务器就绪。

五、方案：官方 APT 仓库安装 Agent 并关联节点

5.1 方案说明

被管节点只需安装 rudder-agent（内含 CFEngine 代理、清单采集、报告上报组件），指向根服务器后由管理员在 Web UI 审批接入。节点安装与服务器共用同一软件源（key 与源配置方法与 4.2 节完全一致，仅不需要 gnupg 之外的额外依赖）。

5.2 安装 rudder-agent

节点上先完成 4.2 节的密钥导入与软件源配置（内容相同，不再重复），然后：

apt-get install -y rudder-agent

实测回显（安装日志尾部节选）：

Setting up rudder-agent (8.3.13-ubuntu22.04) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

确认代理版本：

rudder agent version

实测回显：

Rudder agent 8.3.13

5.3 关联根服务器

rudder agent policy-server rudder-server

命令静默完成（无输出即成功）。核对当前指向：

rudder agent policy-server

实测回显：

rudder-server

拉取初始策略（首次会自动信任服务器密钥）：

rudder agent update

实测回显（节选）：

R: Initial policies have been successfully downloaded from the policy server
ok: Rudder agent policies were updated.

5.4 上报清单与 Web 验收

发送节点清单：

rudder agent inventory

实测回显（节选）：

E| compliant     Inventory                 Inventory                                    The inventory has been successfully sent

清单入库约需半分钟。在 Web UI（https://10.89.59.2/rudder/）依次进入 Node management → Pending nodes，勾选新节点并点击 Accept 完成验收。也可以用根服务器本地 curl 调用内部接口完成同样动作（本文实测采用此方式，回显更直观）：

# 在根服务器上执行：登录会话
curl -sk -c /tmp/ck -d "username=admin&password=q1w2e3r4" -o /dev/null \
  https://localhost/rudder/j_spring_security_check
# 查看待审列表
curl -sk -b /tmp/ck -H "X-Requested-With: XMLHttpRequest" -H "X-CSRF-Token: x" \
  https://localhost/rudder/secure/api/nodes/pending

实测回显（节选）：

{"action":"listPendingNodes","result":"success","data":{"nodes":[
  {"id":"e17d2d6b-257b-44e8-8d76-aa618660d658","hostname":"rudder-agent","status":"pending", ...

执行验收：

curl -sk -b /tmp/ck -H "X-Requested-With: XMLHttpRequest" -H "X-CSRF-Token: x" \
  -d "status=accepted" \
  "https://localhost/rudder/secure/api/nodes/pending/e17d2d6b-257b-44e8-8d76-aa618660d658"

实测回显：

{"action":"changePendingNodeStatus","result":"success","data":{"nodes":[
  {"id":"e17d2d6b-257b-44e8-8d76-aa618660d658","status":"accepted","hostname":"rudder-agent",
   "osName":"Ubuntu","osVersion":"22.04.5 LTS (Jammy Jellyfish)","machineType":"Virtual"}]}}

5.5 systemd 托管

节点服务由 rudder-agent 伞形服务托管（cf-execd 每 5 分钟执行一轮策略，cf-serverd 接收服务端远程触发）：

systemctl is-active rudder-agent rudder-cf-execd rudder-cf-serverd

实测回显：

active
active
active

若服务单元处于非运行状态，用代理自带的启停命令恢复：

rudder agent start

实测回显：

rudder-cf-execd: enabled
ok: start service rudder-agent succeeded

5.6 收敛验证

验收后约 1 分钟内，服务端完成策略生成。节点上手动触发一轮完整收敛：

rudder agent update
rudder agent run -i

实测回显（稳定后的汇总段）：

## Summary #####################################################################
8 components verified in 4 directives
   => 8 components in Enforce mode
      -> 6 compliant
      -> 2 not-applicable
Execution time: 0.45s
################################################################################
Reports sent.

compliant 表示符合预期、not-applicable 表示不适用本机的检查项，errors 必须为 0。随后每 5 分钟代理自动收敛一次（rudder agent info 的 Run interval 可核对）。验收后首分钟内出现个别 error 属正常现象，原因与处理见第八章 FAQ 8.3。

⚠️ 本章收尾验证：rudder agent run -i 汇总中 errors 为 0，且 Web UI Nodes → All 中节点显示绿色合规状态，链路即闭环。

六、配置说明

以下为安装后建议立即检查的三处全局配置，均实测验证。

6.1 JVM 堆内存（JAVA_XMX）

Web 应用（Jetty）默认堆为 1024 MB，内存紧张的服务器应下调。堆大小由两个文件联动控制：

grep -n "^JAVA_XMX" /etc/default/rudder-jetty
grep -n "JAVA_XMX" /opt/rudder/etc/rudder-jetty.conf

实测回显：

44:JAVA_XMX=${JAVA_XMX:=1024}
64:-Xms${JAVA_XMX}m -Xmx${JAVA_XMX}m

修改方法：在 /etc/default/rudder-jetty 中设置 JAVA_XMX=512（该文件为管理员覆盖入口，rudder-jetty.conf 第 44 行的 :=1024 仅为缺省值），然后重启服务：

sed -i 's/^JAVA_XMX=.*/JAVA_XMX=512/' /etc/default/rudder-jetty
systemctl restart rudder-jetty

验证生效（进程参数中出现 -Xms512m -Xmx512m）：

ps -ef | grep -E "Xms.*Xmx" | grep -v grep | grep -o "\-Xms[0-9]*m -Xmx[0-9]*m"

实测回显：

-Xms512m -Xmx512m

JVM 堆建议控制在 256–512 MB 区间起步，随节点规模增长再上调（官方口径见第一章表格）。

6.2 允许接入的网络（Allowed Networks）

服务端默认仅放行本机回环网段，接入节点时安装程序会自动把节点所在网段写入 /opt/rudder/etc/rudder-networks-24.conf。本文环境安装节点后实测文件内容：

Require ip 127.0.0.0/8
Require ip ::1
Require ip 127.0.0.1
Require ip 10.89.59.2
Require ip 127.0.0.1
Require ip 10.89.59.2/24

跨网段部署时手动在文件末尾追加 Require ip <节点网段> 后重启 apache2，否则节点清单上报会被 Web 层拒绝。

6.3 防火墙端口

仅放行 443/tcp（Web 与上报）与 5309/tcp（策略分发）：

ufw allow 443/tcp && ufw allow 5309/tcp

七、常见问题（FAQ）

Q1：apt-get update 报 repository.rudder.io/apt/9.1/dists/jammy/... 404 Not Found。

这是版本选型错误，不是网络故障：9.x 系列已停止为 Ubuntu 22.04 提供索引与构建（证据见第三章 3.2 节）。把软件源系列号改为 8.3 后重新 apt-get update 即可恢复（实测验证）。

Q2：rudder server create-user -u admin -p ... 报 User 'admin' already exists, aborting.

账号已存在时不允许覆盖。实测回显：

User 'admin' already exists, aborting.

若确需重建（如忘记密码），先删除 /opt/rudder/etc/rudder-users.xml 中该用户的 <user name="admin" .../> 行，再重新执行 create-user，实测可成功创建并恢复登录（见 4.4 节回显）。

Q3：节点验收后 rudder agent run 汇总出现 E| error Common Update Cannot update configuration policy，但同一次运行里又有 Configuration policy updated 的成功信息。

这是验收瞬间的正常过渡态：服务端策略生成、cf-serverd 访问授权重载与代理端的类持久化存在约 1–5 分钟的时间窗，窗口期内「先失败后成功」的双份报告会让汇总出现 1 个 error。实测处理：等待一个收敛周期（5 分钟）后重跑，错误消失：

## Summary #####################################################################
8 components verified in 4 directives
   => 8 components in Enforce mode
      -> 6 compliant
      -> 2 not-applicable
Execution time: 0.45s
################################################################################
Reports sent.

若超过 10 分钟仍持续报错，在节点上执行 rudder agent check 做全量自检（输出末行 FINISH: Rudder agent check ran properly 即无异常），再核对 6.2 节的网段放行配置。

Q4：rudder agent update 提示 Rudder node waiting to be accepted。

节点尚未在 Web UI 验收（或验收后服务端策略尚未生成完毕）。确认 5.4 节验收步骤完成后，等待约 1 分钟重新 rudder agent update，实测回显变为 ok: Rudder agent policies were updated.。

Q5：节点服务未运行（systemctl is-active rudder-agent 非 active）。

用代理自带命令拉起并验证：rudder agent start，实测回显 ok: start service rudder-agent succeeded（见 5.5 节）。仍失败时用 rudder agent check 输出定位具体单元。

八、卸载与清理

8.1 卸载被管节点

apt-get purge -y rudder-agent

实测回显（尾部节选）：

dpkg: warning: while removing rudder-agent, directory '/var/rudder' not empty so not removed
dpkg: warning: while removing rudder-agent, directory '/var/log/rudder/install' not empty so not removed
dpkg: warning: while removing rudder-agent, directory '/opt/rudder' not empty so not removed

purge 不会删除残留数据的目录（代理身份密钥、历史报告），确认不再回装时可手工清理：

rm -rf /var/rudder /opt/rudder /var/log/rudder

8.2 卸载根服务器

apt-get purge -y rudder-server

实测回显（尾部节选）：

dpkg: warning: while removing rudder-server, directory '/var/rudder/configuration-repository' not empty so not removed
dpkg: warning: while removing rudder-server, directory '/var/log/rudder/webapp/jvm' not empty so not removed
dpkg: warning: while removing rudder-server, directory '/var/log/rudder/ldap' not empty so not removed
dpkg: warning: while removing rudder-server, directory '/opt/rudder/etc/rudder-jetty-base' not empty so not removed

同样按需清理残留目录：

rm -rf /var/rudder /opt/rudder /var/log/rudder

⚠️ 根服务器卸载会连带删除 PostgreSQL 数据目录与 OpenLDAP 中的节点清单，卸载前如需保留合规报告与策略配置，先做数据备份（常用运维命令见《Rudder 9.1.5 常用 CLI 命令详解》）。

九、参考链接

Rudder 官方 8.3 安装手册（Debian/Ubuntu server）：https://docs.rudder.io/reference/8.3/installation/server/debian.html
Rudder 官方 8.3 安装手册（agent）：https://docs.rudder.io/reference/8.3/installation/agent/debian.html
官方 APT 仓库索引：https://repository.rudder.io/apt/
官方签名密钥：https://repository.rudder.io/apt/rudder_apt_key.gpg
Rudder 8.3 参考手册（容量要求）：https://docs.rudder.io/reference/8.3/
本专栏系列：《Rudder 9.1 介绍与选型指南》、《Rudder 9.1.5 配置参数详解》、《Rudder 9.1.5 常用 CLI 命令详解》