Rudder 9.1.5 配置参数详解
Rudder 9.1.5 服务端与代理端配置参数详解:配置文件地图、JVM 内存、数据库连接池、报告清理、relayd、用户与网段等核心参数的实测修改方法与生产配置模板。
Rudder 9.1.5 配置参数详解
目标:系统梳理 Rudder 9.1.5 服务端与被管节点的配置参数——覆盖配置文件分布、参数查看与修改方式、核心参数逐项详解(含「改值 → 验证 → 还原」完整实测)、按规模给出的生产配置模板。文中全部文件内容、命令与回显均于 2026-10-22 在两台 Ubuntu 24.04.5 LTS 真实服务器(Rudder 9.1.5)上逐条实测取得,回显逐字照抄。
一、环境信息
本文所有操作在以下两台服务器上实测完成(2026-10-22,时区 Asia/Shanghai):
| 角色 | 主机名 | IP 地址 | 操作系统 | 软件 | 版本 |
|---|---|---|---|---|---|
| 根服务器 | rudder-server | 10.89.61.2 | Ubuntu 24.04.5 LTS | rudder-server | 9.1.5-ubuntu24.04 |
| 被管节点 | rudder-agent | 10.89.61.3 | Ubuntu 24.04.5 LTS | rudder-agent | 9.1.5-ubuntu24.04 |
- 版本核对(节点上执行):
rudder agent version
实测回显:
Rudder agent 9.1.5
- 服务端组件架构、端口职责与安装流程见《Rudder 9.1 介绍与选型指南》;Ubuntu 22.04 平台的安装与版本选型见《Ubuntu 22.04 安装 Rudder 指南》,本文不重复安装步骤
- 回显约定:命令以 root 执行,实测回显逐行照抄;涉及口令、哈希处已做脱敏标注
二、前置条件
逐项核对后再动手改参数,避免把「配置问题」误判为「软件故障」:
- 服务健康:改参数前后都应确认服务正常,作为基线:
rudder server health
实测回显:
OK
- 文件备份习惯:本文每处修改前都用
cp 原文件 原文件.bak备份,改完验证后还原。Rudder 的配置文件多数不受包管理器接管,但升级时会合并部分模板,手工备份是唯一稳妥手段。 - 明确「谁读这个文件」:Rudder 配置分三类消费者——Java Web 应用(读
rudder-web.properties、rudder-users.xml)、Rust 组件 rudder-relayd(读relayd/main.conf)、系统服务与脚本(读/etc/default/rudder-jetty等)。改错文件不会报错,只会「不生效」,第三章的文件地图务必先看。 - 重启窗口:
rudder-jetty重启会导致 Web UI 与 API 中断 30~60 秒(本文实测约 40 秒恢复),生产环境请安排变更窗口;agent 端参数均即时生效,无需重启服务。
三、参数查看与修改方式
3.1 配置文件地图
服务端(root server)实测目录列表:
ls /opt/rudder/etc/
实测回显:
agent-capabilities
hooks.d
htpasswd-webdav
htpasswd-webdav-initial
instance-id
logback.xml
openldap
plugins
policy_server.dat
postgresql
relayd
reportsInfo.xml
rudder-apache-relay-common.conf
rudder-apache-relay-nossl.conf
rudder-apache-relay-ssl.conf
rudder-apache-relay-ssl.conf.j2
rudder-apache-webapp-common.conf
rudder-apache-webapp-nossl.conf
rudder-apache-webapp-ssl.conf
rudder-apache-webapp-ssl.conf.j2
rudder-jetty-base
rudder-jetty.conf
rudder-networks-24.conf
rudder-networks-policy-server-24.conf
rudder-passwords.conf
rudder-pkg
rudder-users.xml
rudder-web.properties
rudder-web.properties.d
rudder.conf
ssl
uuid.hive
按「谁消费」归类的核心文件地图(全部路径实测存在):
| 文件 | 格式 | 消费者 | 生效方式 | 管什么 |
|---|---|---|---|---|
/opt/rudder/etc/rudder-web.properties | Java properties | Web 应用(Jetty) | systemctl restart rudder-jetty | 数据库、清理任务、清单、认证、目录路径等主配置 |
/opt/rudder/etc/rudder-users.xml | XML | Web 应用 | 保存即生效(登录时读取) | Web 登录账号与权限角色 |
/opt/rudder/etc/relayd/main.conf | TOML 0.5 | rudder-relayd | systemctl restart rudder-relayd | 报告/清单接收落盘、数据库直写、上游转发 |
/opt/rudder/etc/relayd/logging.conf | TOML 0.5 | rudder-relayd | systemctl restart rudder-relayd | relayd 日志级别与过滤 |
/etc/default/rudder-jetty | 环境变量 | Jetty 启动脚本 | systemctl restart rudder-jetty | JVM 堆内存、GC、JVM 额外参数 |
/opt/rudder/etc/rudder-jetty.conf | Shell 变量 | Jetty 启动脚本 | 随上者生效 | JVM 参数默认值与拼装逻辑(一般不改) |
/opt/rudder/etc/rudder-networks-24.conf | Apache 指令 | Apache httpd | systemctl reload apache2 | Web UI 与上报接口的来源 IP 白名单 |
/opt/rudder/etc/rudder-passwords.conf | Key=value | 安装脚本 + 各组件 | 下次 agent 运行时分发 | LDAP/WebDAV/PostgreSQL 等组件口令 |
/opt/rudder/etc/policy_server.dat | 纯文本 | 服务端自管 | — | 服务端自身的上级指向(默认 127.0.0.1) |
被管节点(agent)侧只有少量本地配置:
| 文件/命令 | 说明 |
|---|---|
/var/rudder/cfengine-community/policy_server.dat | 策略服务器地址(纯文本,一行) |
rudder agent policy-server <host> | 修改上述文件的标准命令(5.8 节实测) |
rudder agent set-force-audit / unset-force-audit | 节点级审计模式开关(5.9 节实测) |
⚠️ 实测踩坑:relayd 的配置目录名是
/opt/rudder/etc/relayd/,不是rudder-relayd。按服务名猜测路径会失败:
cat /opt/rudder/etc/rudder-relayd/main.conf
实测回显:
cat: /opt/rudder/etc/rudder-relayd/main.conf: No such file or directory
3.2 修改与生效方式
通用流程四步:备份 → 改值 → 重启对应服务 → 验证 → 还原(或保留)。不同配置的重启对象:
# 改 rudder-web.properties / rudder-users.xml 相关 JVM 侧后
systemctl restart rudder-jetty
# 改 relayd/*.conf 后
systemctl restart rudder-relayd
# 改 rudder-networks-24.conf 后
systemctl reload apache2
两个辅助验证手段:
# 确认 JVM 进程参数(验证内存修改是否生效,5.1 节实测)
ps -ef | grep java | grep -v grep | grep -oE "\-Xms[0-9]+m -Xmx[0-9]+m"
# 确认 Web 应用已恢复(HTTP 302 跳登录页即正常)
curl -sk -o /dev/null -w "%{http_code}\n" https://localhost/rudder/secure/index.html
实测回显(服务正常时):
-Xms512m -Xmx512m
302
💡
rudder-web.properties支持.d目录扩展:实测存在/opt/rudder/etc/rudder-web.properties.d/,升级不覆盖的自定义参数可放这里,避免直接改主文件在版本升级时被冲掉。
四、参数总览
下表汇总 9.1.5 上最常动的参数(值为本文环境的实测默认值/当前值):
4.1 Web 应用主配置(rudder-web.properties)
| 参数 | 实测值 | 说明 |
|---|---|---|
rudder.jdbc.url | jdbc:postgresql://localhost:5432/rudder | PostgreSQL 连接串 |
rudder.jdbc.username | rudder | 数据库账号 |
rudder.jdbc.maxPoolSize | 25 | JDBC 连接池上限 |
rudder.jdbc.batch.max.size | 500 | 报告批量入库单批上限 |
rudder.postgresql.local | true | 数据库与服务端同机 |
ldap.host / ldap.port | localhost / 389 | OpenLDAP 目录地址 |
ldap.maxPoolSize | 2 | LDAP 连接池上限 |
rudder.batch.reportscleaner.delete.TTL | 4 | 明细报告保留天数 |
rudder.batch.reportscleaner.archive.TTL | 0 | 归档报告保留天数(0=不归档清理) |
rudder.batch.reportscleaner.deleteLogReport.TTL | 2x | 日志类报告保留倍率 |
rudder.batch.reportscleaner.compliancelevels.delete.TTL | 8 | 合规度快照保留天数 |
rudder.batch.reportscleaner.frequency | daily | 清理任务频率 |
rudder.batch.databasecleaner.runtime.day | sunday | 深度清理执行日 |
inventories.root.directory | /var/rudder/inventories | 清单接收目录 |
inventory.parse.parallelization | 2 | 清单解析并行度 |
inventories.watcher.max.age.before.deletion | 2 days | 待处理清单文件最长保留 |
rudder.batch.purge.inventories.delete.TTL | 7 | 历史清单保留天数 |
rudder.batch.dyngroup.updateInterval | 5 | 动态组刷新间隔(分钟) |
rudder.batch.techniqueLibrary.updateInterval | 5 | 技术库刷新间隔(分钟) |
rudder.policy.distribution.port.cfengine | 5309 | 策略分发(cf-serverd)端口 |
rudder.policy.distribution.port.https | 443 | 策略 HTTPS 下载端口 |
rudder.server.upload.maxSize | 8MiB | 单次上传大小上限 |
rudder.dir.gitRoot | /var/rudder/configuration-repository | 技术库 Git 仓库根 |
rudder.auth.provider | file | 认证来源(file=本地用户文件) |
rudder.auth.userRestToken | enabled | 允许用户使用 API Token |
rudder.auth.idle-timeout | 30 minutes | Web 会话空闲超时 |
rudder.users.cleanup.account.disableAfterLastLogin | 180 days | 账号闲置自动禁用阈值 |
rudder.users.cleanup.account.deleteAfterLastLogin | never | 账号闲置自动删除(默认关闭) |
rudder.git.gc | 0 42 3 * * ? | 技术库 Git 仓库 gc 计划(cron) |
4.2 rudder-relayd(relayd/main.conf)
| 参数 | 实测值 | 说明 |
|---|---|---|
node_id | "root" | 本 relay 标识 |
listen | "127.0.0.1:3030" | 健康/管理 API 监听地址 |
peer_authentication | "cert_pinning" | 节点证书校验策略(证书绑定) |
https_port | 443 | 上游(本机 Web 应用)端口 |
[processing.reporting] directory | "/var/rudder/reports" | 报告落盘目录 |
[processing.reporting] output | "database" | 报告去向:直接写数据库 |
[processing.inventory] directory | "/var/rudder/inventories" | 清单落盘目录 |
[processing.inventory] output | "disabled" | 清单去向:root server 上本地落盘关闭 |
[output.database] max_pool_size | 10 | relayd 自己的数据库连接池 |
[remote_run] use_sudo | true | 允许通过 API 触发节点远程运行 |
4.3 JVM 与系统层
| 参数 | 实测值 | 位置 | 说明 |
|---|---|---|---|
JAVA_XMX | 512(默认 1024) | /etc/default/rudder-jetty | JVM 堆上限(MB),同时决定 -Xms |
JAVA_MAXPERMSIZE | 256 | 同上 | 永久代/元空间相关参数 |
JAVA_GC | G1GC + StringDedup + AlwaysPreTouch | 同上 | 垃圾收集器组 |
JAVA_GC_LOG_FILE | /var/log/rudder/webapp/jvm/jvm-gc.log | 同上 | GC 日志路径(默认轮转 5×50M) |
| Apache 白名单 | Require ip <网段> | /opt/rudder/etc/rudder-networks-24.conf | 上报与 UI 的来源网段 |
4.4 节点侧
| 参数/文件 | 实测值 | 说明 |
|---|---|---|
/var/rudder/cfengine-community/policy_server.dat | rudder-server | 策略服务器主机名 |
Run interval | 5 min(rudder agent info 实测) | 收敛周期,服务端统一下发 |
Forced audit mode | no(默认) | 节点级强制审计开关 |
五、核心参数分类详解
每小节按「文件原貌 → 修改实测 → 验证 → 还原」组织,回显均为 2026-10-22 真实执行结果。
5.1 Web 应用 JVM 内存(JAVA_XMX)
JVM 内存是 Rudder 最常调的参数:官方口径(docs.rudder.io 9.1 sizing 页)根服务器 <50 节点最低 3 GB 内存、50~1000 节点 4 GB、每 500 节点追加 1 GB、启用 CVE 插件再 +2 GB;演示级算例 2600 节点给 JVM 分 4 GB。内存紧张的实验/小规模环境需要把默认堆下调。
内存有两层配置:/opt/rudder/etc/rudder-jetty.conf 定义默认值与拼装逻辑(实测关键行):
JAVA_XMX=${JAVA_XMX:=1024}
以及拼装段(实测内容):
-Xms${JAVA_XMX}m -Xmx${JAVA_XMX}m
即 -Xms 与 -Xmx 绑定同一个 JAVA_XMX。该脚本还内置 Java 版本门槛(低于 17 直接拒绝启动,实测提示原文):
Rudder requires Java 17 or later. Your version of Java (detected as ${JAVA}) is ${JAVA_MAJOR_VERSION}.
运维只改 /etc/default/rudder-jetty,实测该文件头部:
JAVA_XMX=512
JAVA_MAXPERMSIZE=256
修改实测(512 → 384 → 还原 512,含两次重启验证):
sed -i "s/^JAVA_XMX=512/JAVA_XMX=384/" /etc/default/rudder-jetty
grep "^JAVA_XMX" /etc/default/rudder-jetty
systemctl restart rudder-jetty
ps -ef | grep java | grep -v grep | grep -oE "\-Xms[0-9]+m -Xmx[0-9]+m" | head -1
实测回显:
JAVA_XMX=384
-Xms384m -Xmx384m
还原为 512 并再次重启:
JAVA_XMX=512
-Xms512m -Xmx512m
重启后等 Web 应用就绪(登录页 302 即恢复,实测 webapp_code=302),再执行登录回归确认功能正常:
curl -sk -o /dev/null -w "admin_login=%{http_code} %{redirect_url}\n" -d "username=admin&password=q1w2e3r4" https://localhost/rudder/j_spring_security_check
实测回显:
admin_login=302 https://localhost/rudder/secure/index.html
经验值:2~4 GB 内存的小规模服务器给 JAVA_XMX=512 起步观察;rudder server health 与 GC 日志(/var/log/rudder/webapp/jvm/jvm-gc.log)无异常后再承载更多节点。
⚠️ 本章收尾验证:
ps -ef必须看到-Xms512m -Xmx512m与/etc/default/rudder-jetty里的值一致,才算改对位置。只改文件不重启rudder-jetty是最常见的「改了不生效」。
5.2 数据库与目录连接池(rudder-web.properties)
实测有效行(脱敏口令):
rudder.jdbc.driver=org.postgresql.Driver
rudder.jdbc.url=jdbc:postgresql://localhost:5432/rudder
rudder.postgresql.local=true
rudder.jdbc.username=rudder
rudder.jdbc.password=<已脱敏>
rudder.jdbc.maxPoolSize=25
rudder.jdbc.batch.max.size=500
ldap.host=localhost
ldap.port=389
ldap.authdn=cn=manager,cn=rudder-configuration
ldap.maxPoolSize=2
ldap.authpw=<已脱敏>
调整要点:
rudder.jdbc.maxPoolSize(默认 25):节点数上千、报告高峰期入库排队时上调(如 50)。每连接约占 PostgreSQLmax_connections一席,需与数据库侧配额一起评估。rudder.jdbc.batch.max.size(默认 500):单批写库的报告条数,报告积压时适度上调,过大反而增加单事务压力。ldap.maxPoolSize(默认 2):UI 查询节点树走的目录连接,卡顿时小幅上调即可,不必大。- 外置数据库场景改
rudder.postgresql.local=false并把rudder.jdbc.url指向远程库(本文未实测外置库,仅标注参数入口)。
修改后必须 systemctl restart rudder-jetty 生效(见 3.2 节)。
5.3 报告与清单生命周期
合规报告是 Rudder 的主要磁盘消费者。实测默认链路:报告由 relayd 直写 PostgreSQL([processing.reporting] output = "database"),Web 侧按 TTL 清理:
rudder.batch.reportscleaner.archive.TTL=0
rudder.batch.reportscleaner.delete.TTL=4
rudder.batch.reportscleaner.deleteLogReport.TTL=2x
rudder.batch.reportscleaner.compliancelevels.delete.TTL=8
rudder.batch.reportscleaner.frequency=daily
rudder.batch.databasecleaner.runtime.minute=0
rudder.batch.databasecleaner.runtime.hour=0
rudder.batch.databasecleaner.runtime.day=sunday
delete.TTL=4:明细报告保留 4 天;compliancelevels.delete.TTL=8:聚合合规快照保留 8 天——合规报表曲线的长度由这两个参数决定,审计留存要求长的环境要调大。deleteLogReport.TTL=2x:日志类(非保障型)报告按 2 倍 TTL 处理。- 清理默认每日执行,深度清理安排在周日 00:00。
清单(inventory)侧实测默认:
inventories.root.directory=/var/rudder/inventories
inventories.watcher.period.garbage.old=5 minutes
inventories.watcher.max.age.before.deletion=2 days
inventories.reject.maxAgeBeforeNow=2 days
inventories.reject.maxAgeAfterNow=12 hours
inventory.parse.parallelization=2
rudder.batch.purge.inventories.delete.TTL=7
inventories.reject.maxAgeBeforeNow/AfterNow:清单时间戳超出窗口会被拒收(节点时钟漂移导致清单被拒时先查这两个值)。- relayd 侧还有一份落盘清理(实测 main.conf):
[processing.reporting.cleanup]
frequency = "10min"
retention = "1day"
即 /var/rudder/reports、/var/rudder/inventories 目录里的中转文件最多留 1 天,正常情况下目录应当是空的——若 reports/incoming 持续堆积,说明数据库直写链路故障,先看 relayd 日志再谈调参。
5.4 rudder-relayd 行为(main.conf)
完整实测文件(脱敏口令):
[general]
nodes_list_file = "/var/rudder/lib/relay/nodeslist.json"
nodes_certs_file = "/var/rudder/lib/ssl/allnodescerts.pem"
node_id = "root"
listen = "127.0.0.1:3030"
peer_authentication = "cert_pinning"
https_port = 443
[processing.inventory]
directory = "/var/rudder/inventories"
output = "disabled"
[processing.inventory.catchup]
frequency = 10
limit = 50
[processing.reporting]
directory = "/var/rudder/reports"
output = "database"
skip_event_types = []
[processing.reporting.catchup]
frequency = 10
limit = 0
[output.database]
url = "postgresql://rudder@localhost:5432/rudder"
password = "<已脱敏>"
max_pool_size = 10
[output.upstream]
host = "127.0.0.1"
user = "rudder"
password = "<已脱敏>"
[remote_run]
command = "/opt/rudder/bin/rudder"
use_sudo = true
[shared_files]
path = "/var/rudder/shared-files/"
[shared_folder]
path = "/var/rudder/configuration-repository/shared-files/"
关键参数解读:
peer_authentication = "cert_pinning":按预置证书指纹逐一校验节点,是默认也是最严策略。排障时可临时改_https_skip_certificate_verification = true(官方提供的调试开关)定位证书问题,验证完必须还原。listen = "127.0.0.1:3030":relayd 自身 API 只绑回环,供健康检查与平台内部调用(rudder server health实测返回OK即经过该链路)。- 中转 relay 的改法:
output可选database(直写库)、upstream(向上一级 relay 转发)、disabled;本文环境为 root server 实测值(reporting=database、inventory=disabled),中转 relay 按upstream部署,属于官方多级架构文档范畴,本文不展开。 - 改完生效:
systemctl restart rudder-relayd(Web 平台另提供了热重载入口,实测 properties 中登记的命令为rudder relay reload -p)。
5.5 relayd 日志级别(logging.conf)
排障利器。实测文件(默认 level 处于注释态,即 info):
[general]
#level = "info"
#filter = ""
打开 debug 并重启的完整实测:
cp /opt/rudder/etc/relayd/logging.conf /tmp/logging.conf.bak
sed -i 's|^#level = "info"|level = "debug"|' /opt/rudder/etc/relayd/logging.conf
grep "^level" /opt/rudder/etc/relayd/logging.conf
systemctl restart rudder-relayd
journalctl -u rudder-relayd --no-pager -n 12 | tail -12
实测回显:
level = "debug"
Oct 22 10:35:49 rudder-server rudder-relayd[32371]: DEBUG rudder_relayd: Creating HTTP client for upstream
Oct 22 10:35:49 rudder-server rudder-relayd[32371]: DEBUG rudder_relayd::http_client: Creating HTTP client with pinned certificates
Oct 22 10:35:49 rudder-server rudder-relayd[32371]: DEBUG rudder_relayd: Setup configuration reload signal handler
Oct 22 10:35:49 rudder-server rudder-relayd[32371]: INFO reporting:watcher{path="/var/rudder/reports/incoming" cfg=CatchupConfig { frequency: 10s, limit: 0 }}: rudder_relayd::input::watch: Starting file watcher on "/var/rudder/reports/incoming"
Oct 22 10:35:49 rudder-server rudder-relayd[32371]: INFO rudder_relayd: Skipping inventory as it is disabled
Oct 22 10:35:49 rudder-server rudder-relayd[32371]: INFO api: rudder_relayd::api: Starting API on 127.0.0.1:3030
Oct 22 10:35:49 rudder-server rudder-relayd[32371]: DEBUG rudder_relayd::processing::shared_files: starting shared-files cleanup in "/var/rudder/shared-files/"
Oct 22 10:35:49 rudder-server rudder-relayd[32371]: DEBUG rudder_relayd: Setup shutdown signal handler
Oct 22 10:35:49 rudder-server rudder-relayd[32371]: DEBUG rudder_relayd::processing::shared_files: cleaning shared-files in "/var/rudder/shared-files/"
Oct 22 10:35:49 rudder-server rudder-relayd[32371]: DEBUG rudder_relayd::input::watch: listing "/var/rudder/reports/incoming"
Oct 22 10:35:49 rudder-server rudder-relayd[32371]: DEBUG rudder_relayd::input::watch: cleaning "/var/rudder/reports/incoming"
Oct 22 10:35:49 rudder-server rudder-relayd[32371]: DEBUG rudder_relayd::input::watch: cleaning "/var/rudder/reports/failed"
filter 支持按组件定向提级(如只对 database 组件开 trace),比全局 debug 更可控。排障结束还原 logging.conf 并重启(实测还原后服务 active)。
5.6 用户账号(rudder-users.xml 与 create-user)
账号文件实测结构(模板行 + 已建账号,哈希脱敏):
<user name="NAME" password="REPLACE_BY_HASH" permissions="ROLE" tenants="*" />
<user name="admin" password="$argon2id$...(哈希略)" permissions="administrator"/>
- 口令为 argon2id 哈希,不要手写哈希——用官方命令创建:
rudder server create-user -u opsuser -p "Ops#2026x"
实测回显:
User 'opsuser' added, restarting the Rudder server
命令自动重启 Web 应用,新账号即刻可登录。
- 删除账号:直接编辑文件删除对应
<user .../>行即可,保存即生效。实测删除 opsuser 后:
grep -c opsuser /opt/rudder/etc/rudder-users.xml
curl -sk -o /dev/null -w "%{http_code} -> %{redirect_url}\n" -d "username=opsuser&password=Ops#2026x" https://localhost/rudder/j_spring_security_check
实测回显:
0
302 -> https://localhost/rudder/index.html?login_error=true
即文件里已无该用户,登录立即失败——无需重启任何服务。
- 重复创建同名账号会报
User 'admin' already exists, aborting.(实测见《Ubuntu 22.04 安装 Rudder 指南》FAQ Q2),重建先删行再执行命令。 permissions角色体系(administrator/administrator_readonly/user/...)由平台 RBAC 文档定义,改角色同样直接编辑该行。- 长期治理参数在
rudder-web.properties:rudder.users.cleanup.account.disableAfterLastLogin=180 days(闲置 180 天自动禁用)、deleteAfterLastLogin=never(默认不自动删)。
5.7 访问控制网段(rudder-networks-24.conf)
Apache 层的来源 IP 白名单,实测内容:
Require ip 127.0.0.0/8
Require ip ::1
Require ip 127.0.0.1
Require ip 10.89.61.2
Require ip 127.0.0.1
Require ip 10.89.61.2/24
解读:
- 节点接入时平台自动登记了网段条目(实测
10.89.61.2/24覆盖同网段全部 agent),正常情况下无需手工维护。 - 跨网段接入新节点被拒(HTTP 403)时,在此文件追加对应网段后
systemctl reload apache2;Web UI 的「Allowed Networks」设置与该文件同步。 - 该文件同时管控 Web UI 与节点上报入口(都在 443 上),收紧公网暴露面时也改这里。
5.8 策略服务器指向(policy_server.dat)
节点指向哪个策略服务器由一个纯文本文件决定。实测内容:
cat /var/rudder/cfengine-community/policy_server.dat
实测回显:
rudder-server
查看与修改的标准命令(不带参数=查看;带参数=设置并自动处理证书信任):
rudder agent policy-server
rudder agent policy-server rudder-server
实测回显(两次调用):
rudder-server
(第二条无输出,退出码 0,文件内容保持 rudder-server。)
改错会怎样——把文件手工改成不可解析的主机名实测:
echo rudder-wrong > /var/rudder/cfengine-community/policy_server.dat
rudder agent update
实测回显(完整):
error: Unable to resolve policy server host: rudder-wrong
error: Unable to resolve policy server host: rudder-wrong
error: No suitable server found for '/var/rudder/cfengine-community/inputs/rudder-promises-generated.tmp'
error: Promise belongs to bundle 'update_action' in file '/var/rudder/cfengine-community/inputs/common/1.0/update.cf' near line 187
error: Errors encountered when actuating files promise '/var/rudder/cfengine-community/inputs/rudder-promises-generated.tmp'
R: ******************************************************************************
* rudder-agent could not get an updated configuration from the policy server. *
* This can be caused by: *
* * an agent key that has been changed *
* * if this node is not accepted or deleted node on the Rudder root server *
* * if this node has changed policy server without sending a new inventory *
* Any existing configuration policy will continue to be applied without change. *
*********************************************************************************
error: Rudder agent policies could not be updated.
命令退出码 2。两个要点:
- 框提示语已说明:已有策略继续生效,节点不会失联失控,只是拿不到新策略——这也是排障时「节点还在收敛但策略不更新」的常见根因。
- 修复即还原文件内容(或用标准命令
rudder agent policy-server rudder-server),实测还原后rudder agent update退出码 0,策略恢复拉取。
服务端自身也有同名文件 /opt/rudder/etc/policy_server.dat,实测内容为 127.0.0.1(根服务器的上级是自己,不要改它)。
5.9 节点审计模式开关(force-audit)
「只审计不修改」是合规场景的常用姿态。节点级开关实测:
rudder agent set-force-audit
实测回显:
ok: Rudder agent is now enforced in audit mode.
立即生效,rudder agent info 实测新增行(节选):
Report mode: full-compliance
Forced audit mode: since 2026-10-22 10:33:45+0000
关闭:
rudder agent unset-force-audit
实测回显:
ok: Rudder agent is not enforced in audit mode anymore.
验证:
rudder agent info | grep -i audit
实测回显:
Forced audit mode: no
要点:该开关优先于服务端下发的模式设置(锁死为审计),适合「敏感机临时冻结写操作」;全网统一审计优先用 Web UI 的节点模式设置(默认模式),节点开关用于例外管理。开关后下一次 rudder agent run 起所有组件只报告不修复。
5.10 其他高频参数速查
- 上传大小:
rudder.server.upload.maxSize=8MiB(实测默认)——通过 API/插件上传大文件报 413 时上调。 - 会话与 API:
rudder.auth.idle-timeout=30 minutes(空闲登出)、rudder.auth.userRestToken=enabled(用户 API Token 开关)。 - 动态组/技术库刷新:
rudder.batch.dyngroup.updateInterval=5、rudder.batch.techniqueLibrary.updateInterval=5(均为分钟,实测默认 5)。 - 技术库 Git 维护:
rudder.git.gc=0 42 3 * * ?(每日 03:42 gc),仓库过大时关注。 - 口令集中管理:
/opt/rudder/etc/rudder-passwords.conf定义 LDAP/WebDAV/PostgreSQL 口令(实测文件注释原文说明「可在该文件手工定义新口令,下次 agent 运行时 Rudder 会把它们设置到正确位置;重置口令会重启组件」)。改库口令的正确入口是这里,而不是直接改rudder-web.properties里的密文。
六、生产配置模板
以下三套模板均来自本文实测参数位,按规模选择后替换即可。共同前提:系统时间同步(NTP)、/var/rudder 与数据库所在分区预留足够空间(经验:百节点规模报告与清单合计 10 GB 级起,按节点数线性增长)。
6.1 实验室 / 演示环境(≤10 节点,4 GB 内存)
| 参数 | 值 | 依据 |
|---|---|---|
JAVA_XMX(/etc/default/rudder-jetty) | 512 | 本文实测值:512 下 Web 应用正常登录、health OK |
rudder.jdbc.maxPoolSize | 保持 25 | 小规模无并发压力 |
| 报告 TTL | 保持默认(4/8 天) | 无留存要求 |
relayd logging.conf | 保持注释(info) | 排障时才开 debug |
6.2 小型生产(≤50 节点,8 GB 内存,本文环境同规模段)
| 参数 | 建议值 | 说明 |
|---|---|---|
JAVA_XMX | 1024(默认)~ 2048 | 官方 sizing:<50 节点服务器内存 3 GB 起,堆给 1~2 GB |
rudder.jdbc.maxPoolSize | 25(默认) | 50 节点内默认池足够 |
rudder.batch.reportscleaner.delete.TTL | 按审计要求(如 30) | 合规留存要求高的场景调大 |
rudder.batch.reportscleaner.compliancelevels.delete.TTL | 随 delete.TTL 同步放大(如 60) | 保证报表曲线长度一致 |
| 磁盘 | /var/rudder 独立分区 ≥ 20 GB | 报告中转 + 清单 + 技术库 |
JAVA_GC_LOG_ROTATE | 保持默认 5×50M | GC 日志最多占 250 MB |
6.3 中型生产(50~1000 节点,16 GB 内存)
| 参数 | 建议值 | 说明 |
|---|---|---|
JAVA_XMX | 4096 | 对齐官方「2600 节点给 JVM 4 GB」算例量级 |
rudder.jdbc.maxPoolSize | 50 | 高峰入库并发上升 |
inventory.parse.parallelization | CPU 核数(如 4) | 清单高峰解析提速 |
rudder.jdbc.batch.max.size | 1000 | 报告批量写入加大 |
relayd [output.database] max_pool_size | 20 | relayd 直写并发加大 |
| 磁盘 | /var/rudder ≥ 100 GB,PostgreSQL 分区独立 | 报告体量按 1000 节点预估 |
| 会话安全 | rudder.users.cleanup.account.disableAfterLastLogin=180 days(默认保留) | 合规基线 |
⚠️ 任何规模变更后:
rudder server health返回OK+ps -ef核对 JVM 参数 + 观察一轮 5 分钟收敛周期无积压,三项通过才算变更完成。
七、常见问题
Q1:改了 /etc/default/rudder-jetty 但 ps -ef 里 -Xmx 还是旧值。
没重启或重启错服务。生效链路是:启动脚本读 /etc/default/rudder-jetty → 覆盖 /opt/rudder/etc/rudder-jetty.conf 的默认值 → 拼出 -Xms/-Xmx。必须 systemctl restart rudder-jetty(本文 5.1 节两次重启验证均生效)。
Q2:rudder agent update 报 Unable to resolve policy server host。
policy_server.dat 内容被改错或主机名不可解析(本文 5.8 节完整复现与修复实录)。还原正确主机名或执行 rudder agent policy-server <主机名> 即恢复;期间节点继续按旧策略运行,不会中断。
Q3:节点报告/清单突然不再上报,但 Web UI 能开。
按顺序排查:① 节点 IP 是否在 Apache 白名单内(5.7 节,跨网段接入最常见);② relayd 是否正常 systemctl is-active rudder-relayd;③ 按第 5.5 节开 debug 看 relayd 是否报证书校验失败(cert_pinning 策略下节点证书重装会触发)。本文实测 debug 日志可用于快速定位(回显见 5.5 节)。
Q4:登录后立刻被踢回,URL 带 ?login_error=true。
三种实测可能:① 口令错;② 用户行已从 rudder-users.xml 删除(本文 5.6 节实测:删行即时生效);③ 账号被闲置自动禁用(disableAfterLastLogin,默认 180 天)。判别技巧:登录 302 的 redirect_url 指向 /rudder/secure/index.html 才是成功,指向 index.html?login_error=true 都是失败——本文实测两种失败路径回显一致。
Q5:找不到 relayd 的配置文件。
路径是 /opt/rudder/etc/relayd/(main.conf + logging.conf),不是按服务名猜的 rudder-relayd 目录——本文 3.1 节有报错实录。同类目录还有 /opt/rudder/etc/postgresql/、/opt/rudder/etc/openldap/。
Q6:Web UI 报告曲线只有最近几天。
不是故障,是清理 TTL(5.3 节实测默认:明细 4 天、合规快照 8 天)。需要更长留存按 6.2/6.3 节调大两个 TTL 参数。
Q7:想改数据库口令,直接改 rudder-web.properties 里的密文行行不行。
不行。实测该文件里存的是密文(rudder.jdbc.password 为哈希值)。正确入口是 /opt/rudder/etc/rudder-passwords.conf(5.10 节):写新明文口令后由 Rudder 在 agent 运行时统一分发到各组件(Web、relayd、WebDAV、LDAP),避免多处不一致。
八、参考链接
- 官方参考手册(9.1):https://docs.rudder.io/reference/9.1/
- relayd 配置说明:https://docs.rudder.io/reference/9.1/administration/relayd.html
- 服务端 administration(含 server 命令、用户管理):https://docs.rudder.io/reference/9.1/administration/server.html
- 性能与 JVM 内存官方口径:https://docs.rudder.io/reference/current/administration/performance.html
- 本系列:《Rudder 9.1 介绍与选型指南》(架构、端口与选型对比)、《Ubuntu 22.04 安装 Rudder 指南》(安装与节点接入全链路)、《Rudder 9.1.5 常用 CLI 命令详解》(命令行工具全集)