Kestra 2.0.6 配置参数详解

目标：逐项说明 Kestra 2.0.6 的配置体系、关键参数默认值与实测行为。已在 Ubuntu 22.04 实测通过。

本文档所有参数行为均来自 Ubuntu 22.04 实机实测（Kestra 2.0.6，2026-10-17）：逐项修改配置并重启验证。文中 jar 内默认值均通过解包官方发布件原样摘录。

一、环境信息

操作系统：Ubuntu 22.04（31GiB 内存实测机）
Kestra 版本：2.0.6（OSS，commitId b59444f）
Java 版本：OpenJDK 25.0.4.1（启动日志 Java version 25.0.4.1+1-1-22.04.4-Ubuntu）
端口：8080（主端口 micronaut.server.port 默认值）、8081（管理端口 endpoints.all.port 默认值，单二进制形态默认未监听）
数据目录：/opt/kestra/data（内嵌 H2 database.mv.db、plugins、storage）
配置路径：/opt/kestra/confs/application.yaml（单机安装标准配置文件）
部署形态：单二进制安装 + systemd 为主，覆盖 Compose（KESTRA_CONFIGURATION）形态差异

二、配置体系与加载顺序

2.1 四层配置来源

Kestra 2.0.6 的配置生效优先级（高 → 低）：

命令行 --config 指定的 YAML（单二进制安装用，如 --config /opt/kestra/confs/application.yaml）；
环境变量 KESTRA_CONFIGURATION（内联 YAML，Compose 部署用）；
JVM 系统属性与环境变量（如 JAVA_OPTS 只管 JVM 参数，不经 Kestra 配置解析）；
jar 内置默认配置 application.yml（打包在发布件内，所有未显式配置项的兜底值）。

2.2 查看内置默认值

发布件是自执行 jar，可直接解包读取默认配置：

cd /tmp && unzip -o -q /opt/kestra/kestra-2.0.6 "application.yml" -d /tmp/jarconf
wc -l /tmp/jarconf/application.yml

回显：

299 /tmp/jarconf/application.yml

这份 299 行的默认配置是本文"默认值"的原始出处。查看运行时合并后的最终配置可用 GET /api/v1/configs（仅返回关键聚合信息，见 7.3）。

2.3 单机安装的标准配置文件

cat /opt/kestra/confs/application.yaml

回显（本文实测环境的基础配置）：

kestra:
  server:
    basic-auth:
      username: admin@example.com
      password: q1w2E3r4
  anonymous-usage-report:
    enabled: false
  storage:
    type: local
    local:
      base-path: /opt/kestra/data/storage

修改后 systemctl restart kestra 生效。

三、服务与端口

3.1 主端口：micronaut.server.port

默认 8080（Micronaut 框架默认值）。改为 8082 实测：

micronaut:
  server:
    port: 8082

重启后验证：

ss -tln | grep 808

回显：

LISTEN 0    4096    *:8082    *:*

8082 监听、原 8080 不再监听，API 与 Web UI 一并迁移。注意：Flow 里通过 http://localhost:8080 调用自身 API 的任务（如 http.Request）需同步改端口。

3.2 管理端口：endpoints.all.port

jar 内默认值（原样摘录）：

endpoints:
  all:
    port: 8081

实测行为存在运行形态差异：

单二进制 server local / systemd server local --config ... 运行时，8081 实际未监听（ss -tln | grep 8081 无输出），/health、/metrics、/prometheus 走 8080 也返回 404，仅 /ping 可用（返回 200）；
官方镜像（Compose）运行时，8081 生效且未认证（详见《Kestra 2.0.6 Docker Compose 部署指南》5.3，/health 返回 200 与版本 JSON）。

3.3 访问日志：access-logger

jar 内默认值（原样摘录）：

micronaut:
  server:
    netty:
      access-logger:
        enabled: true
        logger-name: io.kestra.webserver.access
        log-format: "%{yyyy-MM-dd'T'HH:mm:ss.SSS'Z'}t | %r | status: %s | ip: %a | length: %b | duration: %D"
        exclusions:
          - /ui/.+
          - /health
          - /health/.+
          - /metrics
          - /metrics/.+
          - /prometheus(\?.*)?

四、认证配置

4.1 basic-auth

kestra:
  server:
    basic-auth:
      username: admin@example.com   # 必须是邮箱格式
      password: q1w2E3r4            # 至少 8 位 + 大写字母 + 数字

实测行为：

配置后所有业务 API 返回 401/200 分界（-u 携带凭证后 200）；
Web UI 登录页使用同一组凭证；
密码规则为登录期校验：改成全小写弱密码 q1w2e3r4 重启后服务照常 active，但认证返回 401（详见 FAQ 9.1）。

4.2 免认证路径：open-urls

jar 内默认值（原样摘录）：

kestra:
  server:
    basic-auth:
      open-urls:
        - "/ping"
        - "/api/v1/executions/webhook/"
        - "/api/v1/main/executions/webhook/"
        - "/api/v1/*/executions/webhook/"

这解释了实测现象：未带凭证时 /ping 返回 200（健康检查放行），而其他 API 一律 401。Webhook 触发路径默认放行——生产环境如不使用 Webhook，可自行收紧该列表。

4.3 内部任务凭证联动：tasks.sdk.authentication

jar 内默认值（原样摘录）：

kestra:
  tasks:
    sdk:
      authentication:
        username: ${kestra.server.basic-auth.username:}
        password: ${kestra.server.basic-auth.password:}

Flow 内 SDK/HTTP 任务调用本机 API 时默认复用 basic-auth 凭证，无需在任务里重复传参。

五、数据层：数据源、存储与队列

5.1 数据源（datasources）

单二进制安装不写 datasources 时默认使用内嵌 H2，数据文件实测位于 /opt/kestra/data/database.mv.db（H2 单进程独占，双实例启动会报 Database may be already in use，见《Kestra 2.0.6 Ubuntu 22.04 安装指南》8.1）。Compose 部署使用 PostgreSQL（实测配置）：

datasources:
  postgres:
    url: jdbc:postgresql://postgres:5432/kestra
    driverClassName: org.postgresql.Driver
    username: kestra
    password: k3str4

💡 技术拓展：元数据存储后端对比—— 内嵌 H2：零依赖、开箱即用，实测单机安装默认即是；但单进程独占、不支持集群，仅适合测试/单机自用； PostgreSQL：官方 Compose 模板默认选型，实测 repository 与 queue 都跑在 PG 上；支持生产部署与多实例，备份恢复手段成熟（pg_dump）； MySQL：官方同样提供 MySQL 驱动支持（配置结构同上，url: jdbc:mysql://...），本文未实测，选型前以官方文档 https://kestra.io/docs/configuration 为准。队列实现（kestra.queue.type）与 repository 通常同源：实测单机默认 JDBC 队列跑在 H2 上、Compose 用 postgres 队列；更大规模可引入 Kafka（详见官方文档）。

5.2 任务产物存储：kestra.storage

实测配置（单机）：

kestra:
  storage:
    type: local
    local:
      base-path: /opt/kestra/data/storage

Compose 部署实测把 base-path 指到 /app/storage 并挂载 named volume，任务产物落卷。默认不配置时产物同样落在数据目录下的 storage 路径。

💡 技术拓展：storage 后端对比——local（实测默认，产物存本地目录，简单可靠但单机）；对象存储后端（S3/MinIO/GCS/Azure Blob 等）由官方插件提供，type 换成对应插件类型并补充访问凭证即可，适合多实例共享产物场景（本文未实测，见官方文档 Storage 一节）。

5.3 队列微调：kestra.queue 与 jdbc.queues

jar 内默认值（原样摘录）：

kestra:
  queue:
    message-protection:
      enabled: true
      limit: 1048576        # 1MB，超限消息报错防护

  jdbc:
    queues:
      min-poll-interval: 25ms
      max-poll-interval: 500ms
      poll-switch-interval: 60s

JDBC 队列以轮询实现，默认 25ms～500ms 动态间隔；消息超过 1MB 会被 message-protection 拦截（大 payload 应走 storage 而不是队列）。

5.4 内部控制通道：kestra.controller.port

jar 内默认值：

kestra:
  controller:
    port: 50051

Worker 与服务端内部通信端口，单机模式无需关心；集群部署时需保证该端口在服务间可达。

六、调度与运行时行为

6.1 tutorial-flows：内置示例 Flow

jar 内默认值（原样摘录）：

kestra:
  tutorial-flows:
    # Automatically loads all tutorial flows at startup.
    enabled: true

默认加载官方入门示例 Flow（tutorial 命名空间下 getting-started 系列）。实测日志中可见其调度记录：

00:02:16.576 INFO  scheduler-scheduling-loop_3 i.kestra.scheduler.TriggerScheduler Starting trigger scheduling for [3, 15] vNodes

不想被示例干扰时置为 false 并重启即可。

6.2 重试默认值：kestra.retries

jar 内默认值（原样摘录）：

kestra:
  retries:
    attempts: 5
    multiplier: 2.0
    delay: 1s
    maxDelay: ""

未显式声明重试策略的任务类默认按"5 次、1 秒起步、倍率 2"执行。

6.3 优雅停机：terminationGracePeriod

jar 内默认值（原样摘录）：

kestra:
  server:
    terminationGracePeriod: 5m
    workerTaskRestartStrategy: AFTER_TERMINATION_GRACE_PERIOD

Kestra 收到停机信号后最长等待 5 分钟让任务收尾，之后才真正退出——这就是官方 Compose 模板把 stop_grace_period 设为 6 分钟（比 5m 略长）的原因。systemd 部署时本文把 TimeoutStopSec 设为 150 秒（3 分钟内必退，实测停机 8～12 秒完成）。

6.4 存活探测：kestra.server.liveness

jar 内默认值（原样摘录，节选）：

kestra:
  server:
    liveness:
      enabled: true
      interval: 10s
      timeout: 1m
      initialDelay: 1m
      heartbeatInterval: 3s

实测日志中的 WARN service-liveness 告警即来自该机制（探测超时的服务实例会被标记）。

6.5 使用报告：anonymous-usage-report

jar 内默认值（原样摘录）：

kestra:
  anonymous-usage-report:
    enabled: true
    uri: https://api.kestra.io/v1/reports/server-events
    initial-delay: 5m
    fixed-delay: 1h

  ui-anonymous-usage-report:
    enabled: true

内网/合规环境建议关闭（本文全部实例均设 enabled: false）。关闭后 GET /api/v1/configs 实测返回 isAnonymousUsageEnabled: false（回显见《Kestra 2.0.6 Docker Compose 部署指南》4.2）。

七、插件与可观测性

7.1 插件仓库与目录

jar 内默认值（原样摘录）：

kestra:
  plugins:
    repositories:
      central:
        url: https://repo.maven.apache.org/maven2/

脚本类插件首次使用时从 Maven Central 下载到 /opt/kestra/data/plugins（实测首次执行 deps_demo 时自动完成下载）。网络受限环境可提前离线放置插件 jar 到该目录。

7.2 管理端点开关：endpoints.metrics / prometheus

jar 内默认值（原样摘录）：

endpoints:
  metrics:
    enabled: true
    sensitive: false
  prometheus:
    enabled: true
    sensitive: false

注：官方注释说明 Micronaut 自带 /metrics 非敏感，/prometheus 需单独对齐配置，方便抓取器统一。如前述 2.2，单二进制形态下这些端点实际未暴露，该配置主要作用于镜像部署形态。

7.3 运行时信息验证：GET /api/v1/configs

curl -s -u admin@example.com:q1w2E3r4 http://localhost:8080/api/v1/configs

回显（单行 JSON，已折行展示）：

{"uuid":"3Pb9ubDo834p4aFBI66mY4","version":"2.0.6","edition":"OSS","commitId":"b59444f","chartDefaultDuration":"PT24H","flowTemplate":"","commitDate":"2026-10-13T13:52:17Z","isCustomDashboardsEnabled":false,"isAnonymousUsageEnabled":false,"isUiAnonymousUsageEnabled":true,"url":"http://localhost:8080...

可核对的配置映射：isAnonymousUsageEnabled ↔ kestra.anonymous-usage-report.enabled、chartDefaultDuration ↔ kestra.ui.charts.default-duration（默认 PT24H）。

八、JVM 内存配置（JAVA_OPTS）

8.1 默认堆行为

不配置 JAVA_OPTS 时，Kestra 启动脚本带 -XX:MaxRAMPercentage=50.0，即 JVM 堆上限 = 可用内存的 50%。实测（31GiB 机器）：

01:10:31.026 INFO  main         i.k.c.c.s.AbstractServerCommand Machine information: 12 available cpu(s), 16032MB max memory, Java version 25.0.4.1+1-1-22.04.4-Ubuntu

8.2 三种部署形态下的设置位置（全部实测生效）

形态	设置位置	实测验证
手工前台/后台运行	命令前缀 `JAVA_OPTS="-Xms256m -Xmx512m"`	`ps -ef` 可见参数；日志 512MB max memory
systemd 托管	unit 文件 `Environment="JAVA_OPTS=-Xms256m -Xmx512m"`（引号必加）	同上
Compose	服务环境变量 `JAVA_OPTS: -Xms256m -Xmx512m`	`docker top` 可见参数；日志 512MB

以 systemd 为例（完整单元见《Kestra 2.0.6 Ubuntu 22.04 安装指南》7.1）：

[Service]
Environment="JAVA_OPTS=-Xms256m -Xmx512m"

验证（ps 与日志交叉核对）：

kestra      1821       1  9 01:13 ?        00:00:38 java -XX:MaxRAMPercentage=50.0 -Xms256m -Xmx512m --add-opens java.base/java.nio=ALL-UNNAMED ...
Oct 17 01:13:41 0e4bc4c3ce89 kestra[1821]: 01:13:41.078 INFO  main         i.k.c.c.s.AbstractServerCommand Machine information: 12 available cpu(s), 512MB max memory, Java version 25.0.4.1+1-1-22.04.4-Ubuntu

⚠️ 排障实录：systemd Environment=JAVA_OPTS=-Xms256m -Xmx512m 不加引号时，空格被当作变量分隔符，-Xmx512m 会被静默丢弃（ps -ef 只剩 -Xms256m、日志回到 16032MB）且无任何告警。

九、常见问题（FAQ）

9.1 服务正常但登录/认证 401

密码改为弱密码（如 q1w2e3r4）后服务照常启动，但认证期被拒。实测强密码 q1w2E3r4 通过、弱密码 401。检查 basic-auth.password 是否满足"至少 8 位 + 大写字母 + 数字"。

9.2 配置改了没生效

确认三点：改的是运行中实例实际加载的文件（systemd 形态看 unit ExecStart 的 --config 路径；Compose 形态改的是 KESTRA_CONFIGURATION 内联段而不是宿主机某个 application.yaml）；改完执行了重启；YAML 缩进正确（用 cat 回读核对）。

9.3 管理口 8081 连不上

单二进制形态默认不监听 8081（实测 ss -tln 无该端口），健康检查用 /ping（主端口，默认免认证）；需要 /health、/metrics、/prometheus 时使用官方镜像部署形态或参考官方文档启用管理端点。

9.4 数据目录迁移

datasources 为默认 H2 时，元数据在 base-path 指定的数据目录（本文 /opt/kestra/data，含 database.mv.db、plugins、storage）。整体迁移 = 停机 → 拷贝整个数据目录 → 启动。实测 2.0.5 数据目录被 2.0.6 直接接管并自动迁移（见《Kestra 2.0.6 进阶实战与运维》）。

Kestra 2.0.6 配置参数详解

Kestra 2.0.6 配置参数详解

一、环境信息

二、配置体系与加载顺序

2.1 四层配置来源

2.2 查看内置默认值

2.3 单机安装的标准配置文件

三、服务与端口

3.1 主端口：micronaut.server.port

3.2 管理端口：endpoints.all.port

3.3 访问日志：access-logger

四、认证配置

4.1 basic-auth

4.2 免认证路径：open-urls

4.3 内部任务凭证联动：tasks.sdk.authentication

五、数据层：数据源、存储与队列

5.1 数据源（datasources）

5.2 任务产物存储：kestra.storage

5.3 队列微调：kestra.queue 与 jdbc.queues

5.4 内部控制通道：kestra.controller.port

六、调度与运行时行为

6.1 tutorial-flows：内置示例 Flow

6.2 重试默认值：kestra.retries

6.3 优雅停机：terminationGracePeriod

6.4 存活探测：kestra.server.liveness

6.5 使用报告：anonymous-usage-report

七、插件与可观测性

7.1 插件仓库与目录

7.2 管理端点开关：endpoints.metrics / prometheus

7.3 运行时信息验证：GET /api/v1/configs

八、JVM 内存配置（JAVA_OPTS）

8.1 默认堆行为

8.2 三种部署形态下的设置位置（全部实测生效）

九、常见问题（FAQ）

9.1 服务正常但登录/认证 401

9.2 配置改了没生效

9.3 管理口 8081 连不上

9.4 数据目录迁移

十、参考链接