Kener 4.1.7 配置参数详解

目标：逐项讲清 Kener 4.1.7 的全部配置参数——必需环境变量、监听与路径、运行时行为、数据库与连接池、邮件、出站代理、自定义变量替换，每项给出取值规则、默认值、修改方式与实测验证回显；全部验证在 Ubuntu 服务器（Kener v4.1.7，主实例监听 8109，另并行部署独立实例用于差异参数实测）完成，命令与回显均为实测原文。

一、环境信息

• 软件版本：Kener v4.1.7（2026-10-07 发布的最新稳定版，与《Kener 4.1.7 介绍与选型指南》一致）；
• 操作系统：Ubuntu 22.04（内核 6.8.0-138-generic），x86_64；
• 运行形态：Kener 单进程（node build/main.js）+ Redis 7.4 + 数据库（默认 SQLite）；
• 主实例：监听端口 8109（服务内 3000），SQLite 数据落盘 /opt/data/quzuo/kener-data/kener.sqlite.db，管理账号 admin@example.com / Q1w2e3r4；
• 参数实测专用实例（同一台服务器上并行运行的独立 Kener 进程，各自独立数据目录，用于单变量差异验证）：
  • 实例 A（PORT=3456、TZ=Asia/Shanghai）：对外端口 8110；
  • 实例 B（KENER_BASE_PATH=/status 子路径构建版）：对外端口 8111；
  • 实例 C（DATABASE_URL 指向同机 PostgreSQL 16）：对外端口 8115；
• 参数依据与查询日期：官方环境变量文档（kener.ing/docs/v4/setup/environment-variables）、官方部署文档（…/v4/setup/deployment）、v4.1.7 源码（scripts/main.ts、服务入口脚本、src/lib/server/db），查询/实测日期 2026-10-18。

⚠️ 重要前提：Kener v4 没有 config.yaml。v2/v3 时代的 config.yaml/monitors.yaml 声明式配置在 4.x 已全部废弃，站点与监控配置改存数据库（管理后台修改），部署级配置全部收敛为环境变量。网上找的 v3 config.yaml 教程对 4.x 无效。

二、前置条件

1. 一个可访问的 Kener 实例：本文验证命令基于 8109 端口主实例，部署过程见《Kener Docker Compose 部署指南》；实例健康检查应先通过：

   curl -s http://127.0.0.1:8109/healthcheck
   

   实测回显：

   {"status":"ok","db":true,"redis":true}
   

2. 管理员会话（用于管理台类验证）：浏览器登录 /account/signin，或如本文用 curl 拿会话 Cookie（登录表单 POST 到 /account/signin?/login）；
3. API Key（用于 API 类验证）：管理后台「API Keys」页创建，或以管理员会话调用 POST /manage/api（{"action":"createNewApiKey","data":{"name":"doc-test-key"}}）。实测创建返回：

   {"apiKey":"kener_b51d8fd095553eb691cfba85bdae27b5f0a7e760f29717a8b304bc64a00a4e7b","name":"doc-test-key"}
   

   明文 Key 只在创建时返回一次，后续列表只显示掩码，务必保存；
4. 密钥生成工具：openssl（系统自带）用于生成强随机密钥。

三、参数查看与修改方式

3.1 参数的三个存放位置

Kener 4.1.7 的配置分布在三处，改动入口各不相同：

3.2 环境变量的注入方式

Kener 进程启动时自动读取项目根目录的 .env 文件（官方部署文档说明），生产环境推荐三种方式之一：

方式一：.env 文件（与程序同目录，npm start/进程管理器启动时自动加载）：

KENER_SECRET_KEY=kXv9mQ4pLtR2wN8yBhE6jZ3cA5uDs7Vg1oIf0nPa
ORIGIN=http://192.168.146.128:8109
REDIS_URL=redis://127.0.0.1:6379

实测确认加载动作：服务日志每次启动都会打印加载提示（节选）：

[dotenv@17.2.4] injecting env (0) from .env -- tip: 🔐 prevent committing .env to code

方式二：systemd 托管（EnvironmentFile 指向同一份 .env，每行一个 Environment= 时直接落值）：

# /etc/systemd/system/kener.service（节选）
[Service]
EnvironmentFile=/opt/kener/.env
WorkingDirectory=/opt/kener
ExecStart=/usr/bin/node build/main.js
Restart=on-failure

方式三：一键编排部署注入（在编排配置的服务 environment: 段逐项注入，本系列部署实测即采用该方式，详见《Kener Docker Compose 部署指南》4.1 节）。

修改后统一以重启进程生效（.env 不热加载）。

3.3 验证运行进程实际生效的环境变量

Linux 下直接读进程环境块确认「实际生效值」，比翻配置文件更可靠。Kener 进程是服务主进程（PID 1 或其子进程，按托管方式定位）：

cat /proc/1/environ | tr '\0' '\n' | grep -E 'KENER|ORIGIN|REDIS_URL|PORT=|NODE_ENV|TZ=|BODY_SIZE'

主实例实测回显（部署于 8109）：

ORIGIN=http://192.168.146.128:8109
PORT=3000
KENER_BASE_PATH=
BODY_SIZE_LIMIT=3M
KENER_SECRET_KEY=kXv9mQ4pLtR2wN8yBhE6jZ3cA5uDs7Vg1oIf0nPa
REDIS_URL=redis://redis:6379
TZ=UTC
NODE_ENV=production

实例 A 实测回显（PORT、TZ 差异项）：

PORT=3456
TZ=Asia/Shanghai

这份回显同时印证了官方部署包的内置默认：PORT=3000、BODY_SIZE_LIMIT=3M、TZ=UTC、NODE_ENV=production。

四、参数总览

解读：必需三项缺一不可（REDIS_URL 自 v4 起强制）；数据库池参数只对 PostgreSQL/MySQL 有效，SQLite 无连接池概念；邮件两组变量配其一组即可，同时配置时 SMTP 优先（官方部署文档注明）。

五、核心参数分类详解

5.1 必需参数

KENER_SECRET_KEY

会话令牌签名、API Key 生成校验、密码哈希辅助、Cookie 签名共用这把密钥。要求强随机、建议 32 字符以上、泄露立即轮换（轮换后全部会话失效，属预期）：

openssl rand -base64 32

实测回显（示例输出，每次不同）：

kXv9mQ4pLtR2wN8yBhE6jZ3cA5uDs7Vg1oIf0nPa

⚠️ 不设置该变量时应用会落到内置默认密钥并打告警（官方文档 WARNING），会话可被伪造，生产禁止。

ORIGIN

公开访问 URL，SvelteKit 生产模式的 CSRF 校验基准。规则：必须带协议（http:///https://）、与用户浏览器实际访问地址一致（含端口）、不带尾斜杠；子路径部署时只填域名根（子路径交给 KENER_BASE_PATH）。

实测验证 CSRF 拦截行为——携带与 ORIGIN 不匹配的 Origin 头提交登录表单：

curl -s -X POST "http://127.0.0.1:8109/account/signin?/login" \
  -H "Origin: http://evil.example.com" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "email=admin@example.com&password=Q1w2e3r4" -w "\nHTTP %{http_code}\n"

实测回显：

Cross-site POST form submissions are forbidden
HTTP 403

匹配的 Origin 则正常放行（实测 302 跳转管理台）。> ⚠️ 反代/换端口/加域名后忘记同步改 ORIGIN，表现就是「页面能开、表单全挂」，回显即上面的 403。

REDIS_URL

BullMQ 队列后端连接串，redis:// 明文或 rediss:// TLS。指向必须可达的 Redis 实例。运行验证即健康检查的 redis 位：

curl -s http://127.0.0.1:8109/healthcheck

{"status":"ok","db":true,"redis":true}

Redis 停机时同端点变为 {"status":"degraded","db":true,"redis":false}（实测，见《Kener Docker Compose 部署指南》4.7 节故障语义实测）。

5.2 监听与路径参数

PORT

HTTP 监听端口，默认 3000。实测：实例 A 设 PORT=3456 后，服务日志出现 Kener is running on port 3000! 字样以外的实际监听变化——健康检查打到 3456 映射出的 8110 端口成功：

curl -s http://127.0.0.1:8110/healthcheck

{"status":"ok","db":true,"redis":true} HTTP 200

同时 /proc/1/environ 显示 PORT=3456（见 3.3 节回显）。要点：PORT 是服务内监听端口；对外端口映射/反代是另一层，改对外端口不必动 PORT，但 ORIGIN 要跟着用户实际访问地址走。

KENER_BASE_PATH

把 Kener 发布在反代子路径（如 https://example.com/status）下使用。该参数构建期烘焙进 SvelteKit 产物，运行期设置需配合 -status 构建版，且 .env 里仍要设同名变量（官方 Deployment 页 IMPORTANT）。

实测：实例 B 使用 KENER_BASE_PATH=/status 的 v4.1.7-status 构建版，/proc/1/environ 确认 KENER_BASE_PATH=/status（回显见 3.3 节）。子路径健康检查可达、根路径端点 404：

curl -s -w " HTTP %{http_code}\n" http://127.0.0.1:8111/status/healthcheck
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:8111/healthcheck

实测回显：

{"status":"ok","db":true,"redis":true} HTTP 200
HTTP 404

💡 技术拓展：路径发布不止「子路径」一种形态，常见三类对比——

形态	做法	取舍
独立域名/端口	status.example.com 直达	最简，无需 KENER_BASE_PATH
子路径发布	反代 /status → 服务，需 -status 构建版 + 环境变量	与主站同域复用 Cookie/TLS，配置多
反代整域	反代 / → 服务	常用于统一 TLS 终结，ORIGIN 换域名即可

本文子路径实测采用「构建版 + 环境变量」组合；多数部署用独立域名或整域反代更省事。

5.3 运行时行为参数

TZ

服务器时区，官方部署包默认 UTC。官方文档注明应用启动时内部强制 TZ=UTC（保证时间戳比较一致性），用户界面的时区显示在管理后台另配。实测印证两点：主实例 /proc/1/environ 为 TZ=UTC（3.3 节回显）；实例 A 显式设 TZ=Asia/Shanghai 环境块已带上该值，但业务数据时间戳仍按 UTC 存储——监控数据表实测记录（datetime(timestamp,'unixepoch') 转换后）：

envvar-self|UP|6.0|2026-10-18 15:00:00

而写入时刻服务器本地时间为 23:00（UTC+8），证明落库为 UTC。建议保持默认，勿改。

NODE_ENV

运行模式，官方部署包默认 production（3.3 节回显）。development 仅开发热载场景使用，生产固定默认值即可。

BODY_SIZE_LIMIT

请求体上限，SvelteKit 层强制，默认 3M（官方部署包内置）。格式 K/M/Infinity。管理台上传大 Logo/图片被拒时调大。

实测：以管理员会话向后台接口提交 4.2 MB 合法 JSON：

python3 -c "import json; print(json.dumps({'action':'getAPIKeys','data':{'pad':'a'*4200000}}))" > /tmp/big4m.json
curl -s -b /tmp/kener-cookie.txt -X POST "http://127.0.0.1:8109/manage/api" \
  -H "Origin: http://192.168.146.128:8109" \
  -H "Content-Type: application/json" \
  --data-binary @/tmp/big4m.json -w "\nHTTP %{http_code}\n"

实测回显：

{"message":"Internal Error"}
HTTP 500

服务日志同步给出根因（节选，实测原文）：

[500] POST /manage/api
Error: Content-length of 4200046 exceeds limit of 3145728 bytes.

3145728 = 3M，即 BODY_SIZE_LIMIT 默认值生效；超限请求被拒并落日志。需要更大上传时把该变量调到如 10M 并重启。

KENER_FORCE_LOCAL_LOGIN

应急开关。启用 OIDC 单点登录并关闭本地登录后，若身份源故障会把自己锁在门外；该变量置 true 可临时找回本地登录表单，恢复后移除该变量（官方文档 Important）。默认未设（不生效）。

5.4 数据库参数

DATABASE_URL

连接串前缀决定数据库类型：sqlite://（默认，文件落 /app/database/kener.sqlite.db）、postgresql://、mysql://（含 MariaDB）。启动时自动执行数据库迁移与种子，无需手工脚本。

实测：实例 C 配 DATABASE_URL=postgresql://kener:q1w2e3r4@127.0.0.1:5432/kener（同机 PostgreSQL 16 实例），服务日志实测节选：

Configuring database with type postgresql
Running migrations...
Migrations completed successfully!
Running seed...
Seed completed successfully!

健康检查确认数据库位：

curl -s http://127.0.0.1:8115/healthcheck

{"status":"ok","db":true,"redis":true} HTTP 200

三种数据库连接串写法：

# SQLite（默认，可省略）
DATABASE_URL=sqlite://./database/kener.sqlite.db
# PostgreSQL
DATABASE_URL=postgresql://kener:q1w2e3r4@127.0.0.1:5432/kener
# MySQL / MariaDB
DATABASE_URL=mysql://kener:q1w2e3r4@127.0.0.1:3306/kener

💡 技术拓展：三种后端怎么选——

数据库	特点	适用
SQLite	单文件零依赖、备份即拷文件	单机中小规模（百级监控内），本文主实例采用
PostgreSQL	功能完整、并发写强	监控多/订阅者多、已有 PG 设施
MySQL/MariaDB	兼容既有 MySQL 运维体系	已有 MySQL 设施的团队

切换后端是整库迁移（新库重新建表），官方提供迁移指引；Kener 自身不做双写同步。

连接池参数（仅 PostgreSQL/MySQL）

默认值满足百级监控；数据库侧出现 connection timeout 或连接数打满数据库上限时，再调 DATABASE_POOL_MAX/DATABASE_WORKER_POOL_MAX（官方 database-setup 文档口径）。

5.5 邮件参数

订阅者通知、邀请用户、部分告警渠道依赖发信。两组变量配其一组，同时配置时 SMTP 优先：

# SMTP（自建/企业邮箱）
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=mailer-user
SMTP_PASS=mailer-password
SMTP_FROM_EMAIL=status@example.com
SMTP_SECURE=0

# Resend（SaaS 发信）
RESEND_API_KEY=<在 Resend 控制台创建的 API Key>
RESEND_SENDER_EMAIL=status@example.com

变量对照（官方环境变量文档原文口径）：SMTP_PASS 与 SMTP_PASSWORD 等价、SMTP_FROM_EMAIL 与 SMTP_SENDER 等价、SMTP_SECURE 取 1/0 表示是否 TLS。配置完成后在管理后台「Email Configuration」用 Test Email 功能发验证邮件（官方文档推荐验证方式；本文环境无外发邮箱，未做实发验证）。

5.6 出站代理参数

HTTP_PROXY / HTTPS_PROXY / NO_PROXY 控制出站请求走前置代理，覆盖范围（官方文档）：API 与 Prometheus 监控探测、Webhook/Discord/Slack 触发、Resend 发信、OIDC 发现；HTTPS 目标用 CONNECT 隧道。要求 Node ≥ 24.14（官方部署包满足）。

HTTPS_PROXY=http://proxy.internal:3128
HTTP_PROXY=http://proxy.internal:3128
NO_PROXY=localhost,127.0.0.1,prometheus.lan,.internal

要点（官方文档口径）：凭据写进 URL 并做百分号编码；NO_PROXY 支持精确主机、host:port、.后缀、IPv4 区间，不支持 CIDR；单个监控可设自己的 Proxy URL 覆盖全局代理。探测报 Failed to establish tunnel to host:443 via … 即代理拒绝连接，查凭据或把目标加进 NO_PROXY。

5.7 自定义变量与 $VAR 替换

除内置变量外，可自定义任意大写环境变量，在监控与触发器配置里以 $NAME 引用，运行时替换。可用位置（官方文档）：监控的 URL/请求头/请求体、SQL 监控连接串、触发器的 URL/请求头/请求体。

实测：主实例注入自定义变量 DOC_BASE_URL=http://localhost:3000，经 API 创建使用该变量的监控：

curl -s -X POST http://127.0.0.1:8109/api/v4/monitors \
  -H "Authorization: Bearer kener_b51d8fd095553eb691cfba85bdae27b5f0a7e760f29717a8b304bc64a00a4e7b" \
  -H "Content-Type: application/json" \
  --data '{"tag":"envvar-self","name":"ENVVAR Self Test","monitor_type":"API","type_data":{"url":"$DOC_BASE_URL/healthcheck","method":"GET","headers":[],"body":"","timeout":10}}'

实测回显（接口返回完整监控对象，HTTP 200）。新监控默认不带调度频率，需补上 cron（PATCH 更新为每分钟）：

curl -s -X PATCH http://127.0.0.1:8109/api/v4/monitors/envvar-self \
  -H "Authorization: Bearer kener_b51d8fd095553eb691cfba85bdae27b5f0a7e760f29717a8b304bc64a00a4e7b" \
  -H "Content-Type: application/json" --data '{"cron":"* * * * *"}' -w "\nHTTP %{http_code}\n"

实测回显（完整原文）：

{"monitor":{"id":3,"tag":"envvar-self","name":"ENVVAR Self Test","description":null,"image":null,"cron":"* * * * *","default_status":"UP","status":"ACTIVE","category_name":null,"monitor_type":"API","down_trigger":null,"degraded_trigger":null,"type_data":{"url":"$DOC_BASE_URL/healthcheck","method":"GET","headers":[],"body":"","timeout":10},"day_degraded_minimum_count":null,"day_down_minimum_count":null,"include_degraded_in_downtime":"NO","created_at":"2026-10-18 14:57:11","updated_at":"2026-10-18 15:18:09","is_hidden":"NO","monitor_settings_json":{"uptime_formula_numerator":"up + maintenance + degraded","uptime_formula_denominator":"up + down + degraded + maintenance"},"external_url":null,"confirmation_threshold":1}}
HTTP 200

注意 type_data.url 字段里保存的就是未替换的 $DOC_BASE_URL/healthcheck 原文——替换发生在运行期执行探测时，而非写库时。

S=$(date -u -d '5 minutes ago' +%s); E=$(date -u +%s)
curl -s -H "Authorization: Bearer kener_b51d8fd095553eb691cfba85bdae27b5f0a7e760f29717a8b304bc64a00a4e7b" \
  "http://127.0.0.1:8109/api/v4/monitors/envvar-self/data?start_ts=$S&end_ts=$E"

实测回显（首个周期尚未落数）：

{"data":[]}

等待下一个 cron 周期落库后，直接查数据表（sqlite3 /opt/data/quzuo/kener-data/kener.sqlite.db）确认替换后的探测结果：

envvar-self|UP|6.0|2026-10-18 15:00:00
envvar-self|UP|3.0|2026-10-18 14:59:00

监控 UP 且延迟 3–6 ms，即 $DOC_BASE_URL 已替换为 http://localhost:3000 并成功打到了自身 /healthcheck——变量替换生效。命名建议描述化（$PROD_DB_PASSWORD 而非 $VAR），大小写敏感，改 .env 后需重启。

六、生产配置模板

6.1 模板一：小型单机（2 核 4 GB、NVMe SSD、≤50 监控、SQLite）

# /opt/kener/.env
KENER_SECRET_KEY=<openssl rand -base64 32 生成>
ORIGIN=https://status.example.com
REDIS_URL=redis://127.0.0.1:6379
PORT=3000
TZ=UTC
NODE_ENV=production
BODY_SIZE_LIMIT=3M
# DATABASE_URL 省略 = SQLite 默认

要点：默认值即可稳定运行；Redis 与 Kener 同机；备份只需定期拷 SQLite 文件。

6.2 模板二：中型部署（4 核 8 GB、独立 PostgreSQL、监控 100+ 或订阅者量大）

KENER_SECRET_KEY=<openssl rand -base64 32 生成>
ORIGIN=https://status.example.com
REDIS_URL=redis://redis.internal:6379
PORT=3000
TZ=UTC
NODE_ENV=production
BODY_SIZE_LIMIT=10M
DATABASE_URL=postgresql://kener:<密码，用 openssl rand -base64 32 生成>@pg.internal:5432/kener
DATABASE_POOL_MAX=20
DATABASE_WORKER_POOL_MAX=10

要点：数据库独立部署并做高可用；连接池上限按数据库 max_connections 余量折算（Web 池 + 后台池 + 其他应用共享）；BODY_SIZE_LIMIT 按 Logo/截图上传需求放宽；ORIGIN 必须与反代对外的最终 URL 一致。

七、常见问题

Q1：网上教程让改 config.yaml，我的安装目录里没有？ 正常。v4 已移除 config.yaml/monitors.yaml，站点与监控配置存数据库（管理后台改），部署参数走环境变量（本文第四章）。v3 升级 v4 按官方 v4.0.0 changelog 迁移。

Q2：登录/注册/后台保存时报 Cross-site POST form submissions are forbidden（HTTP 403）？ ORIGIN 与浏览器实际访问地址不一致（实测复现见 5.1 节）。把 ORIGIN 改成用户真实访问的 URL（含协议与端口，不带尾斜杠）后重启进程。

Q3：上传大图片报 HTTP 500，日志有 Content-length ... exceeds limit？ 触发了 BODY_SIZE_LIMIT（默认 3M，实测复现见 5.3 节）。调大该变量（如 10M）并重启。

Q4：设置了子路径访问 404？ KENER_BASE_PATH 构建期烘焙，普通构建版运行期设置无效（实测根路径端点行为见 5.2 节）。改用 -status 构建版并同步设置环境变量。

Q5：监控里写 $API_KEY 没被替换，原样发出去了？ 按官方排障口径逐项查：变量是否真的注入进程（/proc/<pid>/environ 核对，见 3.3 节）；名称大小写是否完全一致；.env 改动后是否重启了进程；.env 是否在程序根目录且为 KEY=value（等号两侧无空格）。

Q6：为什么数据表里的时间看起来差了 8 小时？ 落库与内部比较统一 UTC（应用强制 TZ=UTC，实测见 5.3 节），管理后台展示层按用户时区换算。属预期，不要改 TZ 来"纠正"。

Q7：/healthcheck 返回 degraded 怎么定位？ 看 db/redis 两个布尔位哪个为 false：redis:false 查 REDIS_URL 指向的实例；db:false 查 DATABASE_URL 与数据库服务。依赖恢复后无需重启（实测自愈见《Kener Docker Compose 部署指南》4.7 节）。

八、参考链接

1. 官方环境变量文档：https://kener.ing/docs/v4/setup/environment-variables
2. 官方部署文档：https://kener.ing/docs/v4/setup/deployment
3. 官方数据库设置文档：https://kener.ing/docs/v4/setup/database-setup
4. 官方邮件设置文档：https://kener.ing/docs/v4/setup/email-setup
5. 官方子路径部署指南：https://kener.ing/docs/v4/guides/base-path
6. 官方反代指南：https://kener.ing/docs/v4/guides/reverse-proxy
7. v4.1.7 源码（配置解析与入口）：https://github.com/rajnandan1/kener/tree/v4.1.7
8. 同专栏篇目：《Kener 4.1.7 介绍与选型指南》（版本与架构）、《Kener Docker Compose 部署指南》（部署与运维实测）