Cronicle 0.9.131 配置参数详解

目标：面向已部署 Cronicle 的运维人员，逐项讲清配置文件 /opt/cronicle/conf/config.json 的参数含义、默认值与修改后的实际影响，并给出 Event（事件）、Job（作业）、Category（分类）三类核心对象的定义字段实操回显。全部参数默认值与运行行为均在 Ubuntu 22.04 服务器、Cronicle 0.9.131 实测环境逐项验证。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• Cronicle 版本：0.9.131（官方安装目录 /opt/cronicle，Node.js v24.18.1 运行时）
• 配置文件：/opt/cronicle/conf/config.json（服务启动时一次性加载）
• 初始化数据文件：/opt/cronicle/conf/setup.json（首启 setup 脚本使用，定义初始管理员与内置插件）
• 存储引擎：Filesystem（默认，数据落盘 /opt/cronicle/data）
• 验证手段：配置修改 + 服务重启后的行为对照、REST API 回显、通知链路（邮件/Webhook）实测送达
• 官方参考：Configuration.md（https://github.com/jhuckaby/Cronicle/blob/master/docs/Configuration.md），本篇以其为纲，实测补齐每个键的运行时影响

二、前置条件

• 已完成 Cronicle 部署并能登录 Web UI（部署过程见《Cronicle Docker Compose 部署指南》或官方 Setup.md）
• 拥有管理员账号（本篇实测使用 admin，演示口令 q1w2e3r4）
• 可执行 REST API 调用（curl + X-Session-ID 会话头；登录获取会话的实测命令见第三节）

三、参数查看与修改方式

3.1 查看当前生效配置

Cronicle 没有独立的「查看配置」命令行，配置的唯一权威来源是 /opt/cronicle/conf/config.json（启动时加载，运行中不回读）：

cat /opt/cronicle/conf/config.json | head -10

实测输出（首 10 行）：

{
        "base_app_url": "http://localhost:3012",
        "email_from": "admin@localhost",
        "smtp_hostname": "localhost",
        "smtp_port": 25,
        "max_emails_per_day": 0,
        "secret_key": "7beb03e516cb0197571cb272a34bd778",

        "log_dir": "logs",
        "log_filename": "[component].log",

3.2 修改方式一：编辑 config.json + 重启（推荐）

直接编辑配置文件后重启服务生效。本篇实测以此方式修改 universal_web_hook（空 → 告警接收端地址）与 smtp_hostname/smtp_port（指向内网邮件中继），重启后两条通知链路均实测送达（邮件原文与 Webhook 报文回显见第五节 5.1/5.8 与《Cronicle 日常运维手册》），证明该方式生效可靠：

# 修改 universal_web_hook 后重启服务
/opt/cronicle/bin/control.sh restart

⚠️ 注意：config.json 是 JSON 格式，编辑后建议先做语法校验（python3 -m json.tool /opt/cronicle/conf/config.json > /dev/null && echo valid）再重启，JSON 语法错误会导致服务起不来。

3.3 修改方式二：CRONICLE_ 环境变量覆盖

Cronicle 支持 CRONICLE_ 前缀环境变量覆盖配置键：顶层键直接接后缀（CRONICLE_base_app_url），嵌套键用双下划线（CRONICLE_WebServer__http_port）。环境变量优先于 config.json。

实测证据：配置文件中 base_app_url 保持默认值 http://localhost:3012 未动，仅以环境变量注入 CRONICLE_base_app_url=http://192.168.1.62:8115 启动后，作业完成邮件正文中的链接为 Job Details: http://192.168.1.62:8115/#JobDetails?id=jmveuhffw01——运行时取的是环境变量值。

3.4 不支持通过 REST API 改配置

实测以会话身份调用配置更新接口：

curl -s -X POST "http://127.0.0.1:3012/api/app/update_config/v1" \
  -H "X-Session-ID: $SID" -H 'Content-Type: application/json' -d '{}'

实测输出：

{"code":1,"description":"Unsupported API: app/api_update_config"}

/api/app/* 命名空间不提供配置写入接口，配置以「文件 + 环境变量」两种方式为准。

3.5 登录获取会话（后续实测共用）

本篇所有 API 实测都基于会话头 X-Session-ID，获取方式：

SID=$(curl -s -X POST http://127.0.0.1:3012/api/user/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['session_id'])")

实测返回（节选）：{"code":0,"username":"admin",...,"session_id":"862420851506a27b..."}，code:0 即登录成功。

四、参数总览

config.json 按「顶层键 + 四个嵌套对象（client / Storage / WebServer / User）」组织，高频参数速查（默认值均为 0.9.131 发行包内 config.json 实测值）：

解读：这张表里改动频率最高的三组是「通知链路」（5.1，装完必配）、「作业资源限制」（5.3，按负载调）与「存储引擎」（5.4，上多主集群必换）；其余多数场景保持默认即可。

五、核心参数分类详解

5.1 全局与通知链路（base_app_url / SMTP / 邮件）

这一组决定「Cronicle 如何对外表达自己」。实测默认值：

{
    "base_app_url": "http://localhost:3012",
    "email_from": "admin@localhost",
    "smtp_hostname": "localhost",
    "smtp_port": 25,
    "max_emails_per_day": 0
}

逐项说明：

• base_app_url：所有通知（邮件正文、Webhook 消息）里的 job_details_url / edit_event_url 都以它为基底。默认 localhost:3012 只适合本机访问；生产必须改为对外可达地址。实测改为 http://192.168.1.62:8115 后，作业邮件正文的详情链接随之变为 http://192.168.1.62:8115/#JobDetails?id=jmveuhffw01。
• smtp_hostname / smtp_port / email_from：邮件通知三件套。Cronicle 用 nodemailer 直连 SMTP，无本地 sendmail 时直接给 SMTP 服务器地址即可。实测将 smtp_hostname 指向内网邮件中继、smtp_port 改为中继端口后重启，触发一次成功作业，中继侧完整收到邮件，邮件头实测如下（节选）：

From: admin@localhost
To: ops@quzuo.net
Subject: =?UTF-8?Q?=E2=9C=85_Cronicle_Job_Completed_Success?=...（解码为 ✅ Cronicle Job Completed Successfully: 测试-Shell回显）
Date: Mon, 19 Oct 2026 05:59:50 +0000

• max_emails_per_day：每日邮件发送上限，0 表示不限。通知风暴场景（如每分钟失败的作业配了失败邮件）建议设置上限兜底。
• 邮件是否发送由事件级的 notify_success / notify_fail 字段控制（收件人邮箱），不配置收件人则不发。

5.2 调度与队列（maintenance / Queue / 超时组）

• maintenance（默认 04:00）：每日维护窗口，主节点在此时刻执行过期数据清理等例行维护。可改到业务低谷（如 03:00）。
• queue_dir（默认 queue）：相对 /opt/cronicle 的队列暂存目录。事件启用排队（queue_max > 0）时，排队中的作业数据经此目录中转。
• job_data_expire_days（默认 180）：作业历史（含日志、性能数据）保留天数，与 maintenance 配合每日清理。历史量大时调小此值是最直接的磁盘水位手段。
• list_row_max（默认 10000）：单个列表（如历史记录）的最大行数上限，防止列表无限膨胀。
• scheduler_startup_grace（默认 10 秒）：主节点启动后的调度宽限期——主节点切换/重启后宽限期内的调度点不补跑，避免重启期间的重复触发。
• master_ping_freq / master_ping_timeout（默认 5 / 60 秒）：节点对主节点的心跳参数，60 秒收不到心跳才判定失联并触发转移。网络抖动频繁的环境可适当调大 master_ping_timeout 防误切。
• dead_job_timeout（默认 120 秒）：作业进程无响应多久后判定僵死并标记失败。
• child_kill_timeout（默认 10 秒）：作业被终止（超时/手动中止）时，向子进程发信号后等待其退出的时限，超时强杀。实测超时作业行为：timeout: 10 的事件运行到 10 秒被 SIGTERM，日志记录 Caught SIGTERM, killing child: 49 与 # Error: Job Aborted: Exceeded maximum run time (10 seconds)，elapsed 实测 20.5 秒（含宽限与清理）。
• max_jobs（默认 0 不限）：全局同时运行作业数上限；共享服务器上建议按 CPU 核数设定（如 4C 设 8）防资源挤兑。

5.3 作业资源限制（job_memory_max 组）

{
    "job_memory_max": 1073741824,
    "job_memory_sustain": 0,
    "job_cpu_max": 0,
    "job_cpu_sustain": 0,
    "job_log_max_size": 0,
    "job_env": {}
}

逐项说明：

• job_memory_max（默认 1 GiB）：单作业默认内存上限（字节），判定基于进程实际 RSS，0 为不限。此值是全局默认，事件与分类均可各自覆盖（memory_limit 字段）。
• job_memory_sustain（默认 0）：内存持续超限秒数才触发终止，0 表示瞬时超限立即杀。对内存毛刺型负载（如 JVM 启动）设 30~60 秒可减少误杀。
• job_cpu_max / job_cpu_sustain（默认 0 不限）：CPU 百分比上限与持续秒数，同理。
• job_log_max_size（默认 0 不限）：单作业日志上限；高频大输出作业建议设为如 10485760（10 MB）防日志膨胀。
• job_env（默认 {}）：注入所有作业进程的环境变量，如 {"TZ": "Asia/Shanghai"}。敏感值不建议走此键（配置文件明文）。

5.4 存储引擎（Storage 组）

"Storage": {
    "engine": "Filesystem",
    "list_page_size": 50,
    "concurrency": 4,
    "log_event_types": { "get": 1, "put": 1, "head": 1, "delete": 1, "expire_set": 1 },
    "transactions": true,
    "trans_auto_recover": true,
    "Filesystem": {
        "base_dir": "data",
        "key_namespaces": 1
    }
}

逐项说明：

• Storage.engine：Filesystem（默认）/ Couchbase / S3 三选一。单机与「单主+worker」用 Filesystem 足够；多主故障转移集群必须换成共享存储（NFS 上的 Filesystem、Couchbase 或 S3）。
• Filesystem.base_dir（默认 data）：相对 /opt/cronicle 的数据目录，持久化备份即备份它。
• Storage.transactions / trans_auto_recover（默认 true/true）：写事务与自动恢复，保证 JSON 存储崩溃一致性，保持默认。
• list_page_size（默认 50）：列表接口分页大小。
• concurrency（默认 4）：存储并发线程数。
• log_event_types：存储操作审计日志开关，排障时可临时全开。

5.5 Web 服务（WebServer 组）

"WebServer": {
    "http_port": 3012,
    "https": false,
    "https_port": 3013,
    "https_cert_file": "conf/ssl.crt",
    "https_key_file": "conf/ssl.key",
    "https_force": false,
    "http_max_upload_size": 104857600,
    "http_gzip_text": true,
    "http_timeout": 30
}

逐项说明：

• http_port（默认 3012）：UI 与 API 端口，前置反向代理或改端口都在这里。
• https / https_port（默认 false / 3013）：HTTPS 开关与端口；证书路径默认 conf/ssl.crt、conf/ssl.key（安装包内置自签证书，生产替换为自己的）。https_force: true 时 HTTP 访问强制跳转 HTTPS。实测映射 3013 端口但 https: false 时该端口无服务监听，属预期行为。
• https_header_detect：反向代理场景识别 HTTPS 的请求头（X-Forwarded-Proto 等），走代理终结 TLS 时保持默认即可。
• http_max_upload_size（默认 100 MB）：上传上限（插件脚本上传等场景）。
• http_response_headers 默认带 Access-Control-Allow-Origin: *：内网可接受，公网暴露时建议收紧。
• HTML 页面默认带 X-Frame-Options: DENY、nosniff 等安全响应头（配置键 http_uri_response_headers 定义），保持默认。

5.6 用户与会话（User 组）

"User": {
    "session_expire_days": 30,
    "max_failed_logins_per_hour": 5,
    "max_forgot_passwords_per_hour": 3,
    "free_accounts": false,
    "sort_global_users": true,
    "use_bcrypt": true,
    "default_privileges": {
        "admin": 0,
        "create_events": 1,
        "edit_events": 1,
        "delete_events": 1,
        "run_events": 0,
        "abort_events": 0,
        "state_update": 0
    }
}

逐项说明：

• session_expire_days（默认 30）：会话有效期，安全要求高的环境缩短到 1~7。
• max_failed_logins_per_hour（默认 5）：单账号每小时登录失败上限，超过锁定，防爆破第一道闸。
• free_accounts（默认 false）：是否允许自助注册，内网管理系统保持 false。
• use_bcrypt（默认 true）：密码哈希算法（官方 README 术语表同样注明密码以 bcrypt 加盐哈希存储）。
• default_privileges：新建非管理员用户的默认权限位。默认给「增删改事件」但不给「运行/中止/调度开关」，按团队角色调整。

5.7 分类与插件全局配置（client 组）

"client": {
    "name": "Cronicle",
    "debug": 1,
    "default_password_type": "password",
    "privilege_list": [
        { "id": "admin", "title": "Administrator" },
        { "id": "create_events", "title": "Create Events" },
        { "id": "edit_events", "title": "Edit Events" },
        { "id": "delete_events", "title": "Delete Events" },
        { "id": "run_events", "title": "Run Events" },
        { "id": "abort_events", "title": "Abort Events" },
        { "id": "state_update", "title": "Toggle Scheduler" }
    ],
    "new_event_template": {
        "enabled": 1,
        "params": {},
        "timing": { "minutes": [0] },
        "max_children": 1,
        "timeout": 3600,
        "catch_up": 0,
        "queue_max": 1000
    }
}

逐项说明：

• privilege_list：权限模型定义（权限位 ID 与显示名）。自定义角色就在这里扩展，User.default_privileges 与用户对象里的 privileges 都引用这些 ID。
• new_event_template：新建事件的默认值模板——新事件默认启用（enabled 1）、默认每小时 0 分触发（timing.minutes [0]）、默认超时 3600 秒、默认并发上限 1、默认排队上限 1000。模板里的 max_children 是事件/分类对象的必填键：实测调用 create_category 不带 max_children 时直接被拒：

{"code":"api","description":"Missing parameter: max_children"}

补齐后创建成功（{"code":0,"id":"cmveua39a01"}）——分类对象继承该必填约束。

5.8 Webhook 消息模板（web_hook_text_templates）

"web_hook_text_templates": {
    "job_start": "Job started on [hostname]: [event_title] [job_details_url]",
    "job_complete": "Job completed successfully on [hostname]: [event_title] [job_details_url]",
    "job_failure": "Job failed on [hostname]: [event_title]: Error [code]: [description] [job_details_url]",
    "job_launch_failure": "Failed to launch scheduled event: [event_title]: [description] [edit_event_url]"
}

说明：四种消息的文本模板，[hostname]、[event_title]、[job_details_url]、[code]、[description] 为占位符，可自由改写（如加中文前缀方便群里辨识）。Webhook POST 的 JSON 里 message/text 字段即模板渲染结果。实测一次超时失败作业的 Webhook 报文：完结报文 action 为 job_complete（作业完结事件统一用该 action），而 message 按 code≠0 选择了 job_failure 模板渲染为 Job failed on cronicle-server: 测试-超时被杀: Error 1: Job Aborted: Exceeded maximum run time (10 seconds) http://.../#JobDetails?id=jmveucxa401。

六、生产配置模板

适用场景：4 核 8 GB 内存 / 100 GB 磁盘的单主节点，承载 3~10 台 worker 的运维作业调度（备份、巡检、日志清理等 shell 类作业为主，分钟级频率）。以下为在默认配置基础上需要显式设置或确认的键（其余保持默认）：

{
    "base_app_url": "https://cronicle.example.internal:3012",
    "email_from": "cronicle@example.internal",
    "smtp_hostname": "smtp.example.internal",
    "smtp_port": 25,
    "max_emails_per_day": 500,
    "secret_key": "<openssl rand -hex 16 生成，全集群一致>",
    "debug_level": 3,
    "maintenance": "03:00",
    "list_row_max": 10000,
    "job_data_expire_days": 60,
    "dead_job_timeout": 300,
    "universal_web_hook": "http://alert.example.internal:19999/cronicle-hook",
    "max_jobs": 8,
    "job_memory_max": 2147483648,
    "job_memory_sustain": 30,
    "job_log_max_size": 10485760,
    "Storage": { "engine": "Filesystem", "Filesystem": { "base_dir": "data" } },
    "WebServer": { "http_port": 3012, "https": true, "https_port": 3013 }
}

模板要点（为什么这么改）：

• job_data_expire_days 180→60：运维作业历史 60 天足够复盘，直接压缩磁盘水位（默认 180 天对高频作业是主要磁盘消耗源）
• debug_level 5→3：默认 5 的日志偏啰嗦，生产 3 足够定位问题且显著减少日志量
• max_jobs 8：4 核机器的并发作业兜底
• job_memory_max 2 GiB + sustain 30 秒：给备份类作业留余量同时防内存毛刺误杀
• max_emails_per_day 500：通知风暴保险丝
• https: true：管理界面走 TLS（证书放 conf/ 下替换内置自签证书）
• secret_key：多节点集群的灵魂——openssl rand -hex 16 生成并同步到所有节点
• 磁盘水位关联：数据主体在 data/（作业历史+日志），配合 maintenance 每日清理与 job_data_expire_days 控制增长；巡检水位命令见《Cronicle 日常运维手册》

七、Event / Job / Category 定义字段实操

三份实测回显逐字照抄（通过 REST API 实测获取），字段即权威定义。

7.1 Event（事件）定义字段

创建事件（timing 省略即为按需手动触发）后用 get_schedule 查回的完整对象：

{
    "title": "测试-Shell回显",
    "enabled": 1,
    "category": "general",
    "plugin": "shellplug",
    "target": "cronicle-server",
    "params": {
        "script": "#!/bin/sh\necho hello-cronicle-test; date; hostname"
    },
    "timeout": 60,
    "id": "emveu1c8y01",
    "modified": 1792388962,
    "created": 1792388840,
    "max_children": 0,
    "timezone": "Asia/Shanghai",
    "username": "admin"
}

字段解读：plugin 为插件 ID（shellplug = Shell Script 内置插件）；target 可以是服务器组 ID 或单机主机名（此处为主节点主机名）；params 结构由插件决定（shellplug 的脚本参数是 script）；timing 缺省表示纯手动/API 触发；timeout 秒为超时上限；max_children 单机并发上限（0 不限）；timezone 独立于服务器时区；username 记录创建者。完整可选字段还包括 timing（hours/minutes/days/months/years 数组组合）、retries/retry_delay（重试）、catch_up（补跑）、multiplex（多路并发）、queue_max（排队上限）、notify_success/notify_fail（邮件收件人）、web_hook（事件级 Webhook，优先于全局）、memory_limit/cpu_limit（事件级资源覆盖）、detached（脱离模式）。

7.2 Job（作业）定义字段

一次失败作业（超时被杀）经 get_job_status 返回的完整 job 对象：

{
    "category": "general",
    "plugin": "shellplug",
    "target": "cronicle-server",
    "params": {
        "script": "#!/bin/sh\necho start-long-sleep; sleep 30; echo should-never-print",
        "annotate": 0,
        "json": 0
    },
    "timeout": 10,
    "timezone": "Asia/Shanghai",
    "source": "Manual (admin)",
    "id": "jmveua9mf03",
    "time_start": 1792389256.353,
    "hostname": "cronicle-server",
    "event": "emveua39j02",
    "now": 1792389256,
    "event_title": "测试-超时被杀",
    "plugin_title": "Shell Script",
    "category_title": "General",
    "nice_target": "cronicle-server",
    "command": "bin/shell-plugin.js",
    "log_file": "/opt/cronicle/logs/jobs/jmveua9mf03.log",
    "pid": 42,
    "code": "SIGTERM",
    "description": "Script exited with code: SIGTERM",
    "complete": 1,
    "time_end": 1792389276.887,
    "elapsed": 20.509999990463257,
    "type": "cronicle_job"
}

字段解读：id 是作业 ID（job 与 event 的 id 前缀不同：jm/em）；event 回指事件 ID；source 记录触发来源（Manual (admin) 手动 / API Key 名称 / Scheduler）；time_start/time_end/elapsed 构成耗时三元组；code 成功为 0，失败为错误码或信号名（SIGTERM）；description 为失败原因；log_file 指向作业日志路径（logs/jobs/<job_id>.log，完结后归档入存储，通过 get_job_log API 取回）；pid 为子进程 PID。

7.3 Category（分类）定义字段

实测创建分类 max_children 为必填（见 5.7），成功后 get_categories 返回：

{
    "code": 0,
    "rows": [
        {
            "title": "运维巡检",
            "description": "日常巡检与备份类作业",
            "color": "4C6EF5",
            "max_children": 0,
            "id": "cmveua39a01",
            "modified": 1792389248,
            "created": 1792389248,
            "username": "admin"
        },
        {
            "id": "general",
            "title": "General",
            "enabled": 1,
            "username": "admin",
            "modified": 1792388708,
            "created": 1792388708,
            "description": "For events that don't fit anywhere else.",
            "max_children": 0
        }
    ],
    "list": { "page_size": 50, "first_page": 0, "last_page": 0, "length": 2, "type": "list" }
}

字段解读：color 为 UI 高亮色（十六进制 RGB）；max_children 为该分类下事件的默认并发上限；general 为首启自带分类；事件通过 category 字段引用分类 ID。

八、常见问题

Q1：改了 config.json 不生效？ 配置在启动时一次性加载，改完必须重启服务（/opt/cronicle/bin/control.sh restart）。另外确认没有同名键的 CRONICLE_ 环境变量在覆盖它（环境变量优先，实测见 3.3）。

Q2：通知邮件/Webhook 发不出来？ 三步排查：① 事件上是否配置了收件人（notify_success/notify_fail）或全局 universal_web_hook，两者都不配则不通知；② SMTP 三件套（smtp_hostname/smtp_port/email_from）是否指向可达的中继（实测把 smtp_hostname 从默认 localhost 改为内网中继后才收到邮件）；③ 看 Error.log 是否有投递错误记录。Webhook 侧先用 curl 直接 POST 接收端验证接收端可用，再验证 Cronicle 发送（完整排障路径见《Cronicle 日常运维手册》）。

Q3：作业历史/日志把磁盘吃满了？ job_data_expire_days（默认 180）调小 + 确认 maintenance 时刻服务在运行（清理只在维护窗口执行）；单个作业输出过大时配 job_log_max_size。磁盘水位巡检命令与阈值建议见《Cronicle 日常运维手册》。

Q4：多节点集群各节点配置不一致会怎样？ 官方 Ops Notes 明确要求所有节点使用完全相同的 config.json（尤其 secret_key），且时钟必须同步、主机名必须唯一可解析。节点间配置漂移会导致通信认证失败或调度异常。

Q5：create_event / create_category 报 Missing parameter？ 对象必填键与 client.new_event_template 强相关：事件必填 title/enabled/category/plugin/target，分类必填 title 与 max_children（实测报错 {"code":"api","description":"Missing parameter: max_children"}）。照第七节字段表补齐即可。

九、参考链接

1. 官方配置文档 Configuration.md：https://github.com/jhuckaby/Cronicle/blob/master/docs/Configuration.md
2. 安装与组网文档 Setup.md：https://github.com/jhuckaby/Cronicle/blob/master/docs/Setup.md
3. REST API 文档 APIReference.md：https://github.com/jhuckaby/Cronicle/blob/master/docs/APIReference.md
4. 插件文档 Plugins.md：https://github.com/jhuckaby/Cronicle/blob/master/docs/Plugins.md
5. 官方示例配置 sample_conf/config.json：https://github.com/jhuckaby/Cronicle/blob/master/sample_conf/config.json
6. 本专栏配套文档：《Cronicle Docker Compose 部署指南》《Cronicle 日常运维手册》