Kener v4.0.0 升级实战指南:架构、API 契约与数据模型迁移全解读
Kener v4.0.0 升级实战指南:架构、API 契约与数据模型迁移全解读
Kener v4.0.0 是该项目的一次里程碑式大版本发布,核心变化集中在**运行时架构(引入 Redis)、API 契约(v3 资源式路由全面替换为 /api/v4/*)、以及数据模型(Pages、递归维护、订阅系统重构)**三个层面。本文以官方 v4.0.0 Changelog 为骨架,结合仓库迁移脚本、API 参考文件与调度器源码,逐条拆解 Breaking Changes、迁移注意事项与升级检查清单,帮助 v3 用户在升级前做足功课,也让新用户快速理解 v4 的能力边界。
版本总览:为什么 v4.0.0 是一次"重构级"发布
v4.0.0 不是一次增量小版本,而是对底层的一次系统性重写。官方 Changelog 的定位是:architecture, API, and data-model changes(架构、API、数据模型三重变革),并带来四大新平台能力:
- Pages:单实例发布多个状态页/子路径,按页控制监控可见性;
- Recurring Maintenance:基于 RRULE 的重复性维护窗口编排;
- Customizable Templates:内置邮件模板可从后台直接定制;
- Improved Subscriptions:订阅系统整体重构,与 v4 事件生命周期对齐。
同时,v4 对现有 v3 部署引入了多项迁移要求。如果你正从 v3 升级,建议先完整阅读本指南再动手。
Breaking Changes:升级前必须知道的四项变更
1. Redis 成为核心运行时依赖
v4 中 Redis 从"可选缓存"升级为核心运行时依赖,用于支撑队列/后台工作流,包括:
- 告警(alerts)触发与分发;
- 调度任务(schedulers)执行;
- 邮件 fan-out(email fan-out);
- 文档索引更新(docs indexing updates);
- 以及其他异步操作。
仓库中的调度器实现印证了这一点:例如 maintenanceScheduler.ts 直接依赖 bullmq 的 Queue/Worker,并通过 queues/q.ts 连接 Redis 实现每小时定时生成维护事件。
升级动作:确保在环境中配置 REDIS_URL。连接格式与示例(详见 redis-setup.md/docs/content/v4/setup/redis-setup.md)):
REDIS_URL=redis://localhost:6379
REDIS_URL=redis://:password@localhost:6379
REDIS_URL=rediss://default:password@your-endpoint:6379 # TLS 场景
验证连通性:redis-cli -u $REDIS_URL ping,预期返回 PONG。要求 Redis 6.0+(推荐 7.0+);若报 NOAUTH Authentication required,需在 URL 中包含密码;报 READONLY 则说明连到了只读副本,应指向主实例。
2. Heartbeat 端点路径变更
Heartbeat 监控的推送端点从 v3 迁到 v4:
- v3:
/api/heartbeat/{tag}:{secret} - v4:
/ext/heartbeat/{tag}:{secret}
仓库中实际的路由实现位于 src/routes/(ext)/ext/heartbeat/[tag]/[secret]/+server.ts,同时导出 GET 与 POST 两种方法,两者共用同一 handler,最终调用 RegisterHeartbeat(tag, secret) 完成状态登记。
补充说明:虽然本文档记录的迁移路径是
{tag}:{secret}冒号形式,但根据 heartbeat.md/docs/content/v4/monitors/heartbeat.md) 的说明,较新的路径分隔形式/ext/heartbeat/{tag}/{secret}同样受支持,且旧冒号形式会被自动重写,因此存量 cron 任务可以无缝切换。升级时必须更新旧集成中的路径。
3. 订阅系统整体重构
v4 重新设计了订阅的模型与存储。以下 v3 表被废弃:
subscription_triggerssubscriptionssubscribers
同时 invitations 表也随 v4 的用户流程重设计而废弃。新的订阅体系由 migrations/20260128120000_redesign_subscription_system.ts 建立,包含三张核心表:
| 表 | 职责 |
|---|---|
subscriber_users |
订阅者身份(邮箱唯一、PENDING/ACTIVE 状态、验证码与过期时间) |
subscriber_methods |
订阅渠道(如邮件地址),含 method_type/method_value,支持唯一约束与级联删除 |
user_subscriptions_v2 |
订阅关系(用户 × 渠道 × 事件类型),带 event_type 维度与状态字段 |
升级动作:v3 的订阅数据不会自动迁移,需要升级后在 v4 后台重新配置订阅设置,存量订阅者需重新订阅。
4. API 契约变更(v3 → v4)
对比 static/api-references/v3.json 与 static/api-references/v4.json,官方统计为:
- 36 个端点/方法新增
- 16 个端点/方法移除
变化方向非常清晰:
- 新增
/api/v4/*资源命名空间,为以下资源提供"一等公民"级别的 REST 支持:incidents+ incident comments(事件评论)maintenances+ maintenance events(维护及其事件)monitors+ monitoring data edits(监控及数据编辑)pages(状态页)siteconfig keys(站点配置项)
- 旧 v3 路由(如
/api/incident/*、/api/monitor*、/api/status)被 v4 资源式路由取代。
实际从 v4.json 中可看到完整的 v4 资源面:/api/v4/incidents、/api/v4/incidents/{incident_id}/comments、/api/v4/maintenances/{maintenance_id}/events、/api/v4/monitors/{monitor_tag}/data、/api/v4/pages/{page_path}、/api/v4/site/{config_key} 等均已就位。
升级动作:审计所有集成脚本中已移除的 v3 API 路由,并基于 static/api-references/v4.json 重新生成或重新导入 API 客户端。
数据模型与迁移要点
Pages:页面模型与子路径支持
v4 引入页面级状态视图与监控映射,新增两张表:
pages:页面元数据(page_path、page_title、page_header、page_subheader、page_logo、page_settings_json)pages_monitors:页面与监控的多对多关联(复合主键page_id + monitor_tag,含monitor_settings_json用于控制排序与可见性)
建表逻辑见 migrations/20260107120000_add_pages_tables.ts。由此,你可以在单实例上发布多个状态页/子路径,并按页控制监控可见性。页面管理入口为 Manage → Pages,操作细节见 pages.md/docs/content/v4/pages.md):创建页面需填写 Path(URL 段)、Title、Header;默认首页(/)不可改路径、不可删除;页面支持独立的历史天数(桌面/移动端)与四种布局风格(default-list、default-grid、compact-list、compact-grid)。
分类与监控排序迁移到 Pages
v3 中基于站点的分类/排序逻辑,在 v4 中统一通过 Pages 管理:
- 将监控加入某个页面后,该页面按添加顺序展示这些监控;
- 页面上监控的顺序 = 用户看到的顺序。
因此迁移后若不在页面中显式分配监控,监控将不会出现在任何状态页上(详见下文"已知迁移问题")。
RRULE 递归维护调度
v4 新增基于 RRULE 的递归维护能力,配套三张表:
maintenances:维护主记录(title、description、start_date_time、rrule、duration_seconds、status、is_global)maintenance_monitors:维护影响的监控及每监控的monitor_impact(默认MAINTENANCE)maintenances_events:由 RRULE 展开生成的具体事件实例(start_date_time/end_date_time/status)
建表结构见 migrations/20260109120000_add_maintenances_tables.ts。事件生成的底层实现位于 maintenanceScheduler.ts:它使用 rrule 库的 rrulestr 解析 RRULE,每小时(every: 3600000)扫描未来 7 天窗口,为每次出现生成 maintenances_events 记录(COUNT=1 的一次性维护在创建时直接处理)。RRULE 语法与大量实用模式(每日/每周/每月/季度、序数 BYDAY、时区与校验)可参考 rrule-patterns.md/docs/content/v4/maintenances/rrule-patterns.md)。
维护对监控的影响与状态覆盖
维护现在支持按监控粒度的 impact/status 行为——例如在事件进行期间将监控状态覆盖为 MAINTENANCE,从而在计划工作中改善事件沟通。类型定义(db.ts 与 maintenanceController.ts)显示 monitor_impact 取值包括 UP | DOWN | DEGRADED | MAINTENANCE,并可通过控制器更新 maintenance_monitors 中的 impact。
监控数据增强
v4 的监控数据携带更丰富的运维上下文,包括:
monitoring_data.error_message:错误消息字段,支持排查失败原因;- 配套的数据查看/更新工作流(
/api/v4/monitors/{monitor_tag}/data与/data/{timestamp}的 GET/PATCH)。
字段由 migrations/20260202090915_add_new_columns_data_monitors.ts 添加(同时新增 monitors.external_url),类型层面对应 db.ts 中 MonitoringData.error_message 的声明。
新能力详解
订阅体验与管理员工作流
- 订阅 UX 全面重设计;
- 更完善的 incidents/maintenances 偏好流;
- 管理员可直接在后台(Dashboard)添加/管理订阅者;
- 订阅通知与 v4 的 incident/maintenance 生命周期事件对齐。
公开订阅流程(详见 subscriptions.md/docs/content/v4/subscriptions.md)):用户在状态页点击 Subscribe → 输入邮箱(若开启验证码需先过验证)→ 收到 6 位 OTP → 验证后获得订阅会话 token → 按需切换 incident/maintenance 偏好。触发时机上,incident 订阅邮件在告警创建/恢复时入队;maintenance 订阅邮件在事件状态跃迁(READY → ONGOING → COMPLETED)时入队。发送采用按收件人逐个入队的 privacy-safe fan-out 方式。
可定制的邮件模板
内置邮件模板可在 Manage → Templates 管理并定制(含订阅相关模板)。仓库中的模板表由 migrations/20260128145145_add_general_email_templates.ts 建立(template_subject / template_html_body / template_text_body)。目前内置五类模板(详见 email-templates.md/docs/content/v4/guides/email-templates.md)):
| 模板 ID | 用途 |
|---|---|
invite_user |
团队成员邀请邮件 |
verify_email |
邮箱验证链接邮件 |
forgot_password |
密码重置链接邮件 |
subscription_account_code |
订阅账户验证 OTP |
subscription_update |
订阅者的 incident/maintenance 更新邮件 |
模板渲染使用 Mustache 变量:站点级变量({{site_name}}、{{site_url}}、{{logo}}、{{favicon}}、{{tagline}}),以及按模板区分的 {{invitation_link}}、{{verification_link}}、{{reset_link}}、{{email_code}}、{{title}}、{{update_subject}}、{{update_text}}、{{cta_text}}、{{cta_url}}、{{update_id}}、{{event_type}} 等。注意:定制需 admin 或 editor 角色;seed 只补缺失模板,不会覆盖已有定制。
站点级公告横幅
v4 支持站点级公告横幅,具备更丰富的控制能力:消息、类型、关闭行为、可选 CTA。数据结构定义在 src/lib/types/site.ts 的 SiteAnnouncement:
interface SiteAnnouncement {
title: string;
message: string;
type: "INFO" | "WARNING" | "ERROR";
reshowAfterInHours: number | null; // 关闭后多少小时重新显示
cancellable: boolean; // 是否允许用户关闭
ctaURL: string | null;
ctaText: string | null;
}
配置入口为 Manage → Customizations(对应 customizations/+page.svelte/manage/app/customizations/+page.svelte)),前端渲染与"关闭后 N 小时重新出现"逻辑在 SiteBanner.svelte。
Embed 与事件可见性改进
- 实时事件(live events)的 embed 体验得到扩展;
- 进行中的 incident/maintenance 事件有更好的呈现(event surfacing);
- 状态沟通的分享/嵌入工作流得到改进。
可用性计算更灵活
v4 的 uptime 行为更具可配置性,包括公式级灵活性与维护感知行为。从源码看,监控级设置 MonitorSettings(db.ts)支持自定义 uptime_formula_numerator 与 uptime_formula_denominator;默认种子值(seedMonitorData.ts)为:
uptime_formula_numerator = "up + maintenance"
uptime_formula_denominator = "up + maintenance + down + degraded"
即默认把 maintenance 计入"可用"分子,运维人员可按需调整公式维度。
渲染与 Dashboard UX 升级
v4 包含更广的前端/运行时改进:监控与运维视图采用更多客户端驱动的数据交互,响应性与控制力都有提升(这部分属于渐进式 UI 重构,与 v4 API 的数据编辑能力相辅相成)。
已知迁移问题(v3 → v4)
升级前请逐条核对以下社区反馈的高频问题。
上传文件与自定义字体返回 404
v3 从 /uploads/ 目录提供静态文件(图片、字体);v4 将图片存入数据库并从 /assets/images/[id] 提供。升级后任何引用 /uploads/... 的 URL 都会 404,受影响范围:
- Custom CSS 中引用的自定义字体文件(
.woff2、.woff、.ttf); - v3 后台上传过的图片。
修复:通过 v4 后台 Manage → Site 重新上传站点图片(logo、favicon 等);自定义字体改为外部托管(CDN 或自托管 URL),并更新 Custom CSS 中 @font-face 的 src URL。
订阅者与订阅数据不迁移
订阅系统在 v4 中全面重建(新表 subscriber_users、subscriber_methods、user_subscriptions_v2)。v3 的 subscribers、subscriptions、subscription_triggers 数据不会自动迁移。
修复:升级后在 v4 后台重新配置订阅设置,存量订阅者需重新订阅。
监控超时字段类型错误
v3 迁移过来的监控可能把 timeout 存成字符串(如 "30000")而非数字,导致运行时错误:
"msecs" argument must be of type number. Received type string ('30000')
修复:在 v4 后台打开受影响的监控,核对超时值并保存;重新保存即可转为正确的数字类型。
监控不在状态页显示
v4 引入 Pages/docs/content/v4/pages.md) 模型后,监控必须显式分配到页面才会出现在状态页上。迁移后已有监控在分配之前不可见。
修复:进入 Manage → Pages,创建或编辑页面并分配监控。
站点图片(logo、favicon)需重新上传
v3 上传的站点品牌图片以指向 /uploads/ 的文件路径存储,v4 期望它们是数据库存储的图片。
修复:进入 Manage → Site 重新上传 logo 与 favicon。
升级检查清单:从 v3 到 v4
在将 v4 推向生产环境前,逐项确认:
- 配置 Redis(
REDIS_URL)。 - 更新所有 heartbeat 调用方到
/ext/heartbeat/{tag}:{secret}(或/ext/heartbeat/{tag}/{secret})。 - 通过 Manage → Site 重新上传站点图片(logo、favicon)——v3 的
/uploads/路径已失效。 - 通过 Manage → Pages 分配监控到页面——未分配前监控不可见。
- 打开并重新保存任何使用自定义 timeout 的监控,修复字符串转数字的类型问题。
- 重新配置订阅——v3 订阅数据不会迁移到 v4 新体系。
- 若曾通过
/uploads/使用自定义字体,改为外部托管并更新 Custom CSS 的@font-faceURL。 - 审计集成/脚本中已移除的 v3 API 路由。
- 从
static/api-references/v4.json重新生成或重新导入 API 客户端。 - 在生产环境验证自定义域名 +
ORIGIN以及认证表单行为。
延伸阅读
- Heartbeat Monitor/docs/content/v4/monitors/heartbeat.md):push 型监控的端点、secret 规则与状态逻辑
- User Subscriptions/docs/content/v4/subscriptions.md):订阅流程、管理员后台操作与通知触发时机
- Pages/docs/content/v4/pages.md):页面 CRUD、监控分配、显示设置与 SEO 覆盖层级
- RRULE Patterns/docs/content/v4/maintenances/rrule-patterns.md):递归维护的完整 RRULE 语法与示例
- Email Templates/docs/content/v4/guides/email-templates.md):内置模板、变量表与最佳实践
- Redis Setup/docs/content/v4/setup/redis-setup.md):连接格式、服务规格与故障排查