Kill Bill 0.24.22 配置参数详解

目标：讲清 Kill Bill 0.24.22 的配置体系与逐参数用法——三种配置来源（内置默认值 / 环境变量覆盖 / 属性文件）、官方发行包的参数映射规则、从启动日志提取的 227 条实测默认值全景，以及连接池、发票、支付、队列、安全、HTTP 服务六大核心域的逐参数详解与生产模板，全部默认值取自 Kill Bill 0.24.22 实测环境启动日志逐行照抄。

一、环境信息

• 操作系统：Ubuntu 22.04.4 LTS（内核 6.8.0-138-generic）
• Kill Bill：0.24.22（官方发行包，Compose 编排部署，部署过程见 《Kill Bill 0.24.22 Docker Compose 部署指南》）
• 数据库：killbill/mariadb 0.24（MariaDB 10.x 线）
• 配置取证方式：启动日志参数赋值行 227 条全量提取、进程环境变量实测读取、属性文件与认证配置文件实测查看（2026-10-23）
• JVM：OpenJDK 11（镜像内置），堆实测调优为 -Xms256m -Xmx512m（见部署篇第七节）

二、前置条件

本文逐参数讲解以一份已运行的 Kill Bill 0.24.22 为基础，需要：

1. 服务已部署并可访问 API（Swagger 描述文件 http://<IP>:8146/swagger 返回 200）；
2. 能在服务器上读取 Kill Bill 进程的日志文件与环境变量（本文演示账号 admin，口令 q1w2e3r4；日志文件位于发行包日志目录 logs/killbill.out，systemd 托管形态下等价命令为 journalctl -u killbill，两种方式回显一致）；
3. 了解 Kill Bill 属性命名规律：所有配置项以 org.killbill. 为前缀，按域组织（dao. 连接池、invoice. 发票、payment. 支付、notificationq. 队列等）。

三、参数查看与修改方式

3.1 三层配置来源与生效优先级

Kill Bill 0.24.22 实测确认的配置装载顺序（后者覆盖前者）：

1. 内置默认值：编译在核心代码内，启动日志以 Assigning default value [...] 打印；
2. 外部属性源：环境变量或属性文件，启动日志以 Assigning value [...] 打印（区别于 default 字样）；
3. 运行时 API/租户级配置：部分配置（目录、逾期规则、插件配置）存于数据库按租户生效，走 REST API 管理。

判断某参数当前实际值的最可靠手段：grep 启动日志的赋值行。以连接池为例：

grep 'org.killbill.dao.maxActive' logs/killbill.out

实测回显：

Assigning default value [100] for [org.killbill.dao.maxActive] on [org.killbill.commons.jdbi.guice.DaoConfig#getMaxActive()]

default value 字样说明当前生效的是内置默认 100，未被外部覆盖。

3.2 属性文件方式（官方 Tomcat 发行形态）

裸装 Tomcat 的官方部署路径（来源：官方 Getting Started 文档 Tomcat 章节，docs.killbill.io/latest/getting_started.html，查询日期 2026-10-23）：把属性追加到 $TOMCAT_HOME/conf/catalina.properties 文件末尾，例如数据源三件套：

org.killbill.dao.url=jdbc:mysql://127.0.0.1:3306/killbill
org.killbill.dao.user=killbill
org.killbill.dao.password=killbill

修改后重启 Tomcat 进程生效。官方发行包内也保留了这个文件的占位形态——发行包内 /var/lib/killbill/killbill.properties 实测内容仅一行注释：

# Placeholder

即官方发行形态默认不依赖属性文件，全部走环境变量（见 3.3），属性文件仅在自行挂载覆盖时使用（挂载方法见部署篇第八节）。

3.3 环境变量方式（Compose/发行包形态，实测重点）

官方发行包支持两类环境变量前缀，实测规则如下：

① 专用变量（镜像启动脚本直接消费）：

数据源映射的生效证据（启动日志实测，口令自动脱敏为星号）：

Assigning value [********] for [org.killbill.dao.password] on [org.killbill.commons.jdbi.guice.DaoConfig#getPassword()]
Assigning value [jdbc:mysql://db:3306/killbill] on [org.killbill.commons.jdbi.guice.DaoConfig#getJdbcUrl()]

② 通用映射变量：任意 org.killbill.* 属性都可用 KB_ 前缀 + 点号转下划线的环境变量覆盖，规则为 org.killbill.jaxrs.threads.pool.nb → KB_org_killbill_jaxrs_threads_pool_nb。

覆盖生效实测（两例，改环境变量重启后日志对照）：

# 服务进程环境变量实测读取（进程 PID 以 pgrep 实取）
cat /proc/$(pgrep -f 'catalina.sh run' | head -1)/environ | tr '\0' '\n' | grep KB_org

实测回显：

KB_org_killbill_server_updateCheck_skip=true
KB_org_killbill_jaxrs_threads_pool_nb=23

重启后启动日志对照回显：

Assigning value [23] for [org.killbill.jaxrs.threads.pool.nb] on [org.killbill.billing.util.config.definition.JaxrsConfig#getJaxrsThreadNb()]
Assigning value [true] for [org.killbill.server.updateCheck.skip] on [org.killbill.billing.server.config.UpdateCheckConfig#shouldSkipUpdateCheck()]

对照内置默认值日志（未设置时）：

Assigning default value [10] for [org.killbill.jaxrs.threads.pool.nb] on [org.killbill.billing.util.config.definition.JaxrsConfig#getJaxrsThreadNb()]
Assigning default value [false] for [org.killbill.server.updateCheck.skip] on [org.killbill.billing.server.config.UpdateCheckConfig#shouldSkipUpdateCheck()]

Assigning value（非 default）+ 数值变为 23/true，映射规则实测生效。Compose 形态下修改环境变量后需 --force-recreate 重建服务（见部署篇）。

3.4 安全认证文件 shiro.ini

管理员凭据由发行包启动脚本从模板渲染生成：模板 /var/lib/killbill/config/shiro.ini.template 实测内容：

[users]
admin = $KB_ADMIN_PASSWORD, root
[roles]
root = *:*

启动后渲染为实际口令（实测，KB_ADMIN_PASSWORD=q1w2e3r4 时）：

[users]
admin = q1w2e3r4, root
[roles]
root = *:*

需要更细的角色权限（如只读运维账号）时挂载自定义 shiro.ini 并同步 org.killbill.security.shiroResourcePath 指向之。口令哈希迭代次数由 org.killbill.security.shiroNbHashIterations 控制（实测默认 200000，见参数总览）。

3.5 运行时级配置（数据库/租户层）

以下配置不走属性体系，运行时按租户存于数据库、经 REST API 管理：定价目录（Catalog XML/JSON 版本化上传）、逾期规则（Overdue XML）、发票模板、插件级配置（经 POST /1.0/kb/tenants/uploadPluginConfig）。属性文件只解决平台级参数，业务级配置见本专栏 API 篇。

四、参数总览

以下参数表全部取自 Kill Bill 0.24.22 实测启动日志（227 条赋值行中按域归纳的核心集，值为实测内置默认值）。查看服务器上实际生效值的统一方法：grep '<参数名>' logs/killbill.out。

4.1 数据源与连接池（org.killbill.dao.*）

另有两组同构连接池：org.killbill.billing.main.ro.dao.*（主库只读副本，默认 minIdle=1/maxActive=100）与 org.killbill.billing.osgi.dao.*（插件数据源，默认同），供有读写分离与插件独立数据源的部署使用。

4.2 发票域（org.killbill.invoice.*）

4.3 支付域（org.killbill.payment.*）

4.4 队列与事件总线（notificationq / persistent.bus）

💡 说明：${instanceName} 是实例名占位，多节点部署时按实例取值（单节点即默认实例名），实际属性键如 org.killbill.notificationq.main.queue.capacity；实例名本身由 org.killbill.server.instanceName 控制。队列运行模式另有 org.killbill.notificationq.main.queue.mode（实测发行包注入为 POLLING，轮询数据库队列）。

4.5 安全与 HTTP 服务（security / jaxrs / server）

五、核心参数分类详解

5.1 连接池调参要点

默认 maxActive=100 对小内存实例偏大：连接池对象本身吃内存，且数据库端连接数是全服务共享资源。4GiB 内存、单实例场景建议 20–30；配合 leakDetectionThreshold=60s 观察日志中是否有泄漏告警。修改示例（Compose 环境变量形态）：

    environment:
      - KB_org_killbill_dao_maxActive=25

重建服务后验证（grep 日志，应见 Assigning value [25] 而非 default 100）：

grep 'org.killbill.dao.maxActive' logs/killbill.out

transactionIsolationLevel 默认 TRANSACTION_READ_COMMITTED（读已提交），是账务系统的正确起点——更严格的 REPEATABLE READ 会增加锁冲突，无明确诉求不要上调。

5.2 发票安全边界三件套

maxNumberOfMonthsInFuture=36、maxInvoiceLimit=P200Y、maxDailyNumberOfItemsSafetyBound=15 三个参数构成发票系统的「天文数字账单」防线：目录配置错误（如把月费配成日费）或用量异常放大时，发票引擎会在安全边界内拒绝出账并把账户挂起（parkAccountsOnAllExceptions=true），等待人工处理而非无限出账。零售/小额高频场景可调高 maxDailyNumberOfItemsSafetyBound，企业大额合同场景重点检查 maxNumberOfMonthsInFuture 是否覆盖合同期。

5.3 支付重试节奏

两组重试计划需分清：org.killbill.payment.retry.days=8,8,8 是支付状态机对失败发票的自动重扣节奏（首次失败后第 8/16/24 天再扣，配合逾期状态机在重扣期间推进账户状态）；org.killbill.payment.janitor.* 系列是 Janitor 清账任务对 PENDING/UNKNOWN（网关侧状态不明）交易的对账轮询计划。改重试节奏只动前者；Janitor 计划用于网关回调丢失场景的兜底，保持默认即可。

5.4 队列与线程规模

通知队列（notificationq）与事件总线（persistent.bus）默认按中小规模实例配置（派发线程 10/30、队列容量 100/30000、轮询间隔 3 秒）。事件量大的部署（海量订阅变更 Webhook）优先扩 nbThreads 与 queue.capacity；注意轮询模式（POLLING）下事件延迟下限即 sleep=3000 毫秒，对实时性敏感的通知改用插件直推而非调小轮询。

5.5 对外服务与更新检查

org.killbill.server.baseUrl 默认 http://localhost:8080，凡涉及回调地址的通知场景必须改为对外可达地址（如 https://kb.example.com）。updateCheck.skip 默认 false，即每次启动会请求官方更新清单（实测日志可见该请求配置），离线/内网部署建议设为 true（本文已实测验证），消除无关外联。

六、生产配置模板

适用场景：4GiB 内存、NVMe SSD、单实例、月万级订阅的中小规模 SaaS 计费（Compose 环境变量形态，逐项含义见上表）：

    environment:
      - KILLBILL_DAO_URL=jdbc:mysql://db:3306/killbill
      - KILLBILL_DAO_USER=root
      - KILLBILL_DAO_PASSWORD=killbill
      - KB_ADMIN_PASSWORD=q1w2e3r4
      - TOMCAT_JAVA_XMS=256m
      - TOMCAT_JAVA_XMX=512m
      - KB_org_killbill_server_baseUrl=https://kb.example.com
      - KB_org_killbill_server_updateCheck_skip=true
      - KB_org_killbill_dao_maxActive=25
      - KB_org_killbill_dao_leakDetectionThreshold=60s
      - KB_org_killbill_jaxrs_threads_pool_nb=20
      - KB_org_killbill_payment_plugin_threads_nb=8
      - KB_org_killbill_security_shiroNbHashIterations=200000

💡 说明：堆内存 256–512MB 为起步值（官方镜像默认 512m/2G，小内存服务器须下调，修改位置与 jps -v 验证方法见部署篇第七节）；maxActive=25 与 512MB 堆匹配；连接池如报耗尽再按监控逐级上调。每项改后均以「grep 日志赋值行」方式验证生效，方法见 3.1 节。

七、常见问题

Q1：改了参数为什么没生效？ 三点排查：外部属性源是否真正注入（cat /proc/<PID>/environ 实测环境变量）；属性键名是否拼写正确（通用映射规则 KB_ + 点转下划线，一个都不能错）；服务是否真正重建（Compose 下普通 up -d 对「环境变量有变化」会自动重建，但对挂载文件变更不会，需 --force-recreate）。最终以启动日志赋值行为准（Assigning value 出现且值正确才算生效）。

Q2：日志里 default value 和 value 有什么区别？ Assigning default value [X] 表示该参数当前用内置默认值 X（外部未覆盖）；Assigning value [Y] 表示有外部属性源注入值 Y。逐行对照即可判断每个参数的生效来源。

Q3：口令在日志里会泄漏吗？ 不会明文。实测日志中 org.killbill.dao.password 显示为 ********；但 Compose 编排文件与进程环境变量（/proc/<PID>/environ）中是明文，注意文件权限与服务器访问控制。

Q4：哪些配置不在 properties 体系里？ 定价目录、逾期规则、发票模板、插件配置属租户级运行时配置，存数据库、经 REST API 管理（属性文件里只有 org.killbill.overdue.uri、KILLBILL_CATALOG_URI 这类「初始文件指向」）；多租户部署时各租户配置相互独立。

Q5：如何确认某个参数存在？ 在启动日志 227 条赋值行里 grep 参数关键词即可确认存在性与默认值；日志没有出现的属性名（拼错或该版本不存在）不会有赋值行——这也是甄别「网上流传参数是否适用于 0.24.22」的实测手段。

八、参考链接

1. 官方 Getting Started（Tomcat 章节的 catalina.properties 属性追加方式来源）：https://docs.killbill.io/latest/getting_started.html
2. 官方配置文档（System Properties 目录）：https://killbill.io/docs/
3. 本平台同组件文档：《Kill Bill 0.24.22 介绍与选型指南》、《Kill Bill 0.24.22 Docker Compose 部署指南》