gocron 0.14.1 配置参数详解

目标：把 gocron 0.14.1 的唯一配置文件 config.yaml 从头到尾讲透——参数查看与修改方式、热重载边界、九大配置段逐项解释、生产可用模板。全部参数取自 v0.14.1 服务首次启动自动生成的默认配置（实测全文照录），热重载行为有实测日志佐证，实测环境 Ubuntu 22.04（x86_64），查询/实测日期 2026-10-30。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• gocron 版本：v0.14.1（构建时间 2026-10-23，gocron -version 实测输出 gocron v0.14.1 (built 2026-10-23T07:25:25Z, source https://github.com/flohoss/gocron)）
• 配置文件路径：/opt/gocron/config/config.yaml（按《gocron Docker Compose 部署指南》部署后的标准位置）
• 运行库：/opt/gocron/config/db.sqlite（标准 SQLite 3 格式，文件头实测为 SQLite format 3）
• 服务监听：默认 0.0.0.0:8156
• 版本特性基线：v0.13.3 新增 server.app_url；v0.14.0 起登录为独立 /login 页面并内置 OIDC（来源：官方 releases 发布说明，查询日期 2026-10-30）

二、前置条件

1. gocron 服务已部署并可访问（部署过程见《gocron Docker Compose 部署指南》第十一节之前的任一形态均可）。
2. 已拿到配置文件：首次启动后 /opt/gocron/config/config.yaml 会自动生成一份带完整注释的默认配置（约 200 行，含 5 个示例任务），本文所有参数均以这份实测文件为蓝本。
3. 理解热重载边界（下节详述）：大多数参数改完即生效，server 段例外需要重启服务。

三、参数查看与修改方式

gocron 的全部行为配置只有一个来源：YAML 配置文件。没有环境变量覆盖机制，没有数据库配置表，改配置就是改文件。

查看当前配置：

cat /opt/gocron/config/config.yaml

修改与生效流程：直接编辑保存 → 观察服务日志确认热重载 → 不生效的段落重启服务。实测一次完整流程（把时区从 UTC 改为 Asia/Shanghai）：

# 编辑 time_zone: 'UTC' 为 time_zone: 'Asia/Shanghai' 后，观察服务日志

实测回显（服务自动检测到文件变化并重载）：

time=2026-10-30T01:11:10.206Z level=INFO msg="Configuration reloaded" jobs=5 schedules=4 auth_enabled=false

日志里的 jobs=5 schedules=4 auth_enabled=false 是重载摘要：识别到 5 个任务、生成 4 条调度计划（第 5 个任务 disable_cron: true 不生成计划）、认证未启用。这条日志是确认任何配置修改生效的标准验证手段。

热重载边界总表（实测归纳）：

💡 技术拓展：服务配置的加载策略常见三种——启动时一次性读取（改完必须重启，如 Nginx 早期形态）、信号触发重载（如 nginx -s reload）、文件监听自动重载（如本文 gocron 与大多数「配置即代码」新工具）。gocron 采用第三种：配置文件保存即触发重载，jobs=5 schedules=4 这类摘要日志就是重载回执，比信号式少一步命令，也避免了「忘了 reload」的经典事故。

四、参数总览

默认配置共 9 个配置段、约 40 个参数，全景如下（★=高频必知，☆=按需）：

五、核心参数分类详解

5.1 顶层全局参数（time_zone / log_level / delete_runs_after_days）

# All schedules run in this time zone, applied on config reload
time_zone: 'UTC'

# One of: debug | info | warn | error
log_level: 'info'

# Delete runs from the db after x days, disable with 0
delete_runs_after_days: 7

逐项说明：

• time_zone：所有 cron 表达式的解释时区。默认 UTC，国内服务器建议 Asia/Shanghai——否则 0 3 * * 0 这类「周日 03:00」会按 UTC 解释，与直觉差 8 小时。热重载生效（实测改后日志出现 Configuration reloaded）。注意它与部署时的 TZ 环境变量是两回事：TZ 只影响日志时间戳显示，调度解释只认这里（实测设 TZ=Asia/Shanghai 后日志仍打 UTC 点 time=2026-10-30T01:09:05.267Z）。
• log_level：四档。排障临时调 debug，稳定运行 info 即可；warn/error 会吞掉重载回执日志，不建议。热重载生效。
• delete_runs_after_days：运行历史（每次触发在 SQLite 里的一条记录）保留天数，默认 7 天，0 为永不清理。这是 SQLite 文件体积的第一控制项——分钟级高频任务一年能积累数十万条记录，生产建议保留 30 天以内。

5.2 db 段（SQLite 数据库位置）

# SQLite database directory (defaults to the folder of this config file),
# absolute path or relative to the config file
db:
  location: '.'
  name: 'db.sqlite'

• db.location：数据库目录，. 即配置文件所在目录（部署形态下就是挂载出来的 /opt/gocron/config/）；支持绝对路径。不建议改动——配置与运行库同目录让「备份一个目录」成为完整的备份动作。
• db.name：库文件名，默认 db.sqlite。改名后注意旧文件不会自动迁移，需手动搬移。

验证库文件的标准格式（实测）：

head -c 16 /opt/gocron/config/db.sqlite

SQLite format 3␀

5.3 software 段（执行环境自动装配）

# Software to bake into the image (requires an image rebuild to take effect):
# apprise, borgbackup, docker, git, podman, rdiff-backup, restic, rsync,
# rclone, logrotate, sqlite3, kopia
# See internal/software/software.go for installation details and versions.
software:
  - name: 'git'

清单里的每一项会在服务启动时自动装配进执行环境，任务命令可以直接调用。可选工具共 12 项：apprise（通知推送）、borgbackup、docker、git、podman、rdiff-backup、restic、rsync、rclone、logrotate、sqlite3、kopia——清一色是备份/同步/通知场景的工具链，暗示了项目的定位。

实测装配行为（首启日志，git 装配约 6 秒）：

time=2026-10-30T01:09:05.267Z level=INFO msg="Installing software" name=git
time=2026-10-30T01:09:10.988Z level=INFO msg=Done

• 加工具：往清单里加一行 - name: 'restic' 后重启服务即可（该清单标注 requires an image rebuild，部署形态下对应重启服务重新装配）。
• 离线服务器：清空清单可跳过装配（避免访问软件源超时），宿主已有的命令不受影响。
• 装配失败不阻断启动：日志报错后服务照常起，只是对应任务执行时找不到命令。

5.4 terminal 段（命令白名单）

terminal:
  allow_all_commands: false
  allowed_commands:
    cat:
      args:
        - /config/config.yaml
    docker:
      args:
        - ps
        - version
    export:
      allow_all_args: true

• allow_all_commands：true 时面板终端可执行任意命令且白名单失效，等价于把服务器 shell 暴露给所有能打开面板的人，启用前提是认证已收紧（见 5.6）。
• allowed_commands：白名单字典。args 列表限定「只能带这些参数执行」；allow_all_args: true 表示该命令不检查参数。示例含义：cat 只能读固定路径、docker 只能跟 ps 或 version、export 任意参数放行。
• 安全原则：白名单按「最小可用」配置，cat 示例里限定单个文件路径的写法值得照抄。

5.5 server 段（网络与限流，修改需重启）

server:
  address: '0.0.0.0'
  port: 8156
  # app_url: 'https://gocron.example.com'
  trusted_proxies: []
  cors:
    allow_origins: ['*']
  rate_limit:
    enabled: false
    rate: 20
    burst: 40

• address / port：监听地址与端口。0.0.0.0 保证跨机可达；以分发件形态部署时端口改动需与《gocron Docker Compose 部署指南》中端口映射的右侧联动。
• app_url：对外访问源（协议+域名）。反代或 HTTPS 场景必配——OIDC 登录回调用它拼绝对地址（v0.13.3 引入，解决反代后回调地址错误的问题）。
• trusted_proxies：IP/CIDR 列表，声明哪些代理有权设置 X-Forwarded-For。留空时永远取直连 IP——反代部署不配它，日志与限速会把代理 IP 当客户端 IP。
• cors.allow_origins：跨域白名单，默认 *；前端与 API 同源部署（不走独立域名前端）时可收紧为具体来源。
• rate_limit：每 IP 限速，rate 每秒请求数、burst 突发容量（0 表示按 rate 推导）。公网暴露时建议 enabled: true 并调低。
• 本段任何修改都需要重启服务（官方注释原文：Changing this section requires a restart; only jobs, schedules, log_level, time_zone and auth are applied on config reload）——这是全文件唯一的热重载例外段。

5.6 auth.oidc 段（单点登录，热重载生效）

# auth:
#   oidc:
#     enabled: true
#     issuer_url: 'https://id.example.com'
#     client_id: ''
#     client_secret: ''
#     session_ttl: '24h'
#     cookie_secure: false

默认整段注释（即未启用认证，实测重载摘要 auth_enabled=false，UI 与 API 均无需登录）。逐项说明：

• enabled：打开后 UI 出现独立 /login 登录页（v0.14.0 起）与「Sign in with OIDC」按钮，API 也要求会话。
• issuer_url：身份提供方的 issuer 地址，必须与令牌 iss 声明完全一致、不带尾部斜杠；端点自动从 <issuer_url>/.well-known/openid-configuration 发现。
• client_id / client_secret：在身份提供方（官方注释推荐 Pocket-ID）注册客户端所得。回调地址固定填 <对外访问地址>/api/auth/callback。
• session_ttl：会话有效期，如 24h。
• cookie_secure：服务走 HTTPS 时设 true（会话 Cookie 仅经加密通道传输）。
• 该段热重载生效：启用/关闭认证不用重启，实测日志摘要的 auth_enabled 字段随之变化。

生产暴露的最小安全组合：auth.oidc.enabled: true + server.app_url + server.trusted_proxies + cookie_secure: true + 反代 HTTPS。

5.7 healthcheck 段（三阶段回调）

# healthcheck:
#   authorization: '...'
#   type: 'POST'
#   start:
#     url: https://status.example.com
#     params:
#       success: true
#     body: '{"foo": "bar"}'
#   end:
#     url: https://status.example.com
#     params:
#       success: true
#     body: '{"foo": "bar"}'
#   failure:
#     url: https://status.example.com
#     params:
#       success: false
#       error: 'Backup failed'
#     body: '{"foo": "bar"}'

任务执行三阶段的外部 HTTP 回调：start（开始）、end（成功结束）、failure（失败），每阶段可独立配置 url + 查询参数 + JSON 体；type 支持 HEAD | GET | POST；authorization 作为授权头随请求发送。典型用法：把 end 指向 Uptime Kuma 心跳地址、failure 指向告警 Webhook，gocron 自身无需内建通知能力。failure 示例体里的 error: 'Backup failed' 展示了失败信息透传的写法。

5.8 job_defaults 段（任务默认值）

job_defaults:
  cron: '0 3 * * 0'
  # timeout: '30s'
  # retries: 2
  envs:
    - key: SLEEP_TIME
      value: '5'
  pre_commands:
    - echo "Starting backup..."
  post_commands:
    - echo "Backup finished!"

这里定义的值自动应用到全部任务（任务里可单独覆盖）：

• cron：默认调度计划 0 3 * * 0（每周日 03:00，按时区解释）；
• timeout：单命令超时（注释态默认不限），如 30s、5m；
• retries：失败重试次数（注释态默认 0 次不重试）；
• envs：注入所有任务的环境变量；
• pre_commands / post_commands：任务执行前后各插入的命令（示例用 echo 打标记，生产常用于开始通知与结束清理）。

💡 技术拓展：任务超时（timeout）与重试（retries）的组合策略是调度系统设计的经典取舍——

策略	特点	适用
超时 + 不重试	失败即告警，人工介入	幂等性差的命令（如发通知）
超时 + 固定次数重试	抖动自愈，代价是失败延迟暴露	网络类命令（rclone/restic 同步）
不设超时 + 重试	长任务友好，卡死风险自担	大体量备份、确定能自结束的作业

gocron 支持前两种组合（job_defaults 全局兜底 + 任务级覆盖），备份同步类任务建议全局 timeout: '30m' + retries: 2，通知类任务覆盖为不重试。

5.9 jobs 段（任务定义本体）

jobs:
  - name: 'Example Scheduled Happy Path'
    cron: '0 5 * * 0'
    disable_fail_fast: false
    commands:
      - echo "start"
      - date
      - echo "done"

  - name: 'Example Continue On Failure'
    cron: '15 5 * * 0'
    disable_fail_fast: true
    commands:
      - echo "before fail"
      - false
      - echo "continues"

  - name: 'Example Env Expansion'
    cron: '30 5 * * 0'
    envs:
      - key: TEST_VALUE
        value: 'default-value'
    commands:
      - echo "value=${TEST_VALUE}"

  - name: 'Example Timeout And Retries'
    cron: '45 5 * * 0'
    timeout: '30s'
    retries: 2
    commands:
      - echo "timeout and retries configured"

  - name: 'Example Manual Long Running'
    disable_cron: true
    commands:
      - sleep 5
      - echo "manual done"

字段逐项说明：

• name：任务名，面板显示与 slug 化后用于 API（Example Scheduled Happy Path 的 slug 为 example-scheduled-happy-path，实测 GET /api/jobs 回显可验证）；
• cron：五段式表达式；disable_cron: true 时省略（该任务仅手动触发，如 Example Manual Long Running）；
• commands：按序执行的命令列表，shell 语义，可多行复杂脚本；
• disable_fail_fast：默认 false（首败即停），true 时某条命令失败后继续执行后续命令（官方用 false 命令演示——它必然失败，但 echo "continues" 仍会执行）；
• timeout / retries：任务级覆盖 job_defaults；
• envs：任务级环境变量，命令中 ${VAR} 展开（Example Env Expansion 演示）；
• disabled：API 回显中出现的布尔字段，停用任务用。

实测验证任务真实触发（把 Example Scheduled Happy Path 的 cron 改为 * * * * * 保存，热重载后等一分钟）：

time=2026-10-30T01:11:10.206Z level=INFO msg="Configuration reloaded" jobs=5 schedules=4 auth_enabled=false

curl -s http://localhost:8156/api/jobs | python3 -c "
import json,sys
d=json.load(sys.stdin)
j=[x for x in d if x['name']=='Example Scheduled Happy Path'][0]
print('cron:',j['cron']); print('runs:',len(j.get('runs') or []))
for x in (j.get('runs') or [])[:2]: print(' ',x)
"

实测回显（01:12:00 准时触发，命令序列 0 秒跑完）：

cron: * * * * *
runs: 1
  {'id': 1, 'job_name': '', 'status_id': 3, 'start_time_unix': 1793322720048, 'start_time': '2026-10-30 01:12:00', 'end_time': '2026-10-30 01:12:00', 'duration': '0s', 'logs': None}

运行记录字段解读：status_id（运行状态码，成功运行实测为 3）、start_time/end_time/duration（起止与耗时）、logs（输出日志，瞬时完成的命令可为 None）。连续三分钟观测到 01:12、01:13、01:14 三条记录，调度精度为分钟级准时触发。

六、生产配置模板

以下模板面向「2 核 4G 内存、SSD 磁盘的单机备份调度服务器」场景：承载 10–30 个分钟/小时级任务（数据库备份、文件同步、日志清理、证书续期），运行历史保留 30 天，启用 OIDC 认证并置于反向代理之后，执行环境带 restic/rclone/git。可直接替换后使用：

time_zone: 'Asia/Shanghai'

log_level: 'info'

delete_runs_after_days: 30

db:
  location: '.'
  name: 'db.sqlite'

software:
  - name: 'git'
  - name: 'restic'
  - name: 'rclone'
  - name: 'sqlite3'

terminal:
  allow_all_commands: false
  allowed_commands:
    cat:
      args:
        - /opt/gocron/config/config.yaml

server:
  address: '0.0.0.0'
  port: 8156
  app_url: 'https://gocron.example.com'
  trusted_proxies:
    - 10.0.0.0/8
  cors:
    allow_origins: ['*']
  rate_limit:
    enabled: true
    rate: 20
    burst: 40

auth:
  oidc:
    enabled: true
    issuer_url: 'https://id.example.com'
    client_id: 'gocron'
    client_secret: '${GOCRON_OIDC_CLIENT_SECRET}'
    session_ttl: '24h'
    cookie_secure: true

healthcheck:
  type: 'POST'
  end:
    url: 'https://monitor.example.com/ping/gocron'
    params:
      success: true
  failure:
    url: 'https://monitor.example.com/alert/gocron'
    params:
      success: false
    body: '{"error": "job failed"}'

job_defaults:
  timeout: '30m'
  retries: 2
  post_commands:
    - echo "job finished"

jobs:
  - name: 'Nightly DB Backup'
    cron: '0 2 * * *'
    commands:
      - /usr/local/bin/backup-db.sh

模板要点解说：

• 内存/磁盘依据：gocron 进程本身几十 MB 内存量级，4G 内存的余量全部留给任务命令（restic 大库快照、rclone 大目录扫描）；SQLite 运行库在 30 天保留 + 分钟级任务下约为几十 MB，SSD 足以承载。
• ${GOCRON_OIDC_CLIENT_SECRET}：真实密钥禁止明文落盘，注入方式为编辑服务定义（如 Compose 的 environment: 列表注入 GOCRON_OIDC_CLIENT_SECRET 环境变量，取值向身份提供方管理员索取）或系统级环境变量后重启服务；除此之外的演示值均可直接用。
• delete_runs_after_days: 30：比默认 7 天长（满足月度回溯），比永不清理安全。
• rate_limit.enabled: true：公网可达时的基本姿态；纯内网可关闭。
• healthcheck 只配 end/failure 两阶段：开始回调信息量低，省掉可减少监控端噪音。

七、常见问题

Q1：改了配置怎么确认生效了？

看服务日志有没有 Configuration reloaded 摘要行（第三节有实测回显）。server 段是唯一例外——它不触发热重载，需要重启服务；如果改了 server 段却只看到旧配置行为，先重启再排查。

Q2：时区到底有几个？TZ、time_zone 怎么分？

两个互不覆盖：TZ（环境变量）只影响日志时间戳显示；time_zone（配置项）决定 cron 表达式的解释时区，全部调度计划跟着它走。实测环境 TZ=Asia/Shanghai 时日志仍打 UTC 点，而 time_zone 改为 Asia/Shanghai 后调度按北京时间重排。国内生产两个都设成 Asia/Shanghai 最不容易混。

Q3：任务多了 SQLite 会成为瓶颈吗？

调度触发本身不走复杂查询，瓶颈出现在运行历史写入与面板查询。delete_runs_after_days 控制总量：7 天保留 + 每分钟 1 个任务 ≈ 1 万条记录量级，SQLite 毫无压力；秒级高频任务建议改用外部监控汇聚，别把面板当数据库用。

Q4：software 清单加了工具但任务里找不到命令？

装配发生在启动阶段——加清单项后必须重启服务（该段注释明确 requires an image rebuild）。装配失败的常见原因是执行环境访问软件源超时，日志里会有对应报错行；离线环境跳过装配，改用宿主已装命令。

Q5：OIDC 配好后登录跳转报地址错误？

回调地址 = app_url + /api/auth/callback。三处必须对齐：server.app_url 填浏览器实际访问的对外地址（反代后是 https 域名而非 8156）、身份提供方注册的回调 URL 与之一致、issuer_url 与令牌 iss 完全匹配且无尾部斜杠。这是 v0.13.3 引入 app_url 要解决的核心场景。

Q6：示例任务可以删吗？

可以，jobs: 列表整段替换为自己的任务即可；全删留空列表（jobs: []）也合法，任务面板为空但服务正常。删除后热重载摘要 jobs=N 计数变化即确认生效。

八、参考链接

• 项目仓库：https://github.com/flohoss/gocron
• 发布说明（版本特性溯源）：https://github.com/flohoss/gocron/releases.atom（查询日期 2026-10-30）
• 系列文档：《gocron 0.14.1 介绍与选型指南》（定位与选型）、《gocron Docker Compose 部署指南》（部署与持久化）、《gocron 0.14.1 CLI 命令与运维实操详解》（命令与 API 实操）