Kener v4.0.0 升级实战指南:架构、API 契约与数据模型迁移全解读

原创2026-10-12 12:25:281,938 阅读
文章标签:可观测性后端前端运维

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_triggers
  • subscriptions
  • subscribers

同时 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(状态页)
    • site config 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 推向生产环境前,逐项确认:

  1. 配置 Redis(REDIS_URL)。
  2. 更新所有 heartbeat 调用方到 /ext/heartbeat/{tag}:{secret}(或 /ext/heartbeat/{tag}/{secret})。
  3. 通过 Manage → Site 重新上传站点图片(logo、favicon)——v3 的 /uploads/ 路径已失效。
  4. 通过 Manage → Pages 分配监控到页面——未分配前监控不可见。
  5. 打开并重新保存任何使用自定义 timeout 的监控,修复字符串转数字的类型问题。
  6. 重新配置订阅——v3 订阅数据不会迁移到 v4 新体系。
  7. 若曾通过 /uploads/ 使用自定义字体,改为外部托管并更新 Custom CSS 的 @font-face URL。
  8. 审计集成/脚本中已移除的 v3 API 路由。
  9. 从 static/api-references/v4.json 重新生成或重新导入 API 客户端。
  10. 在生产环境验证自定义域名 + 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):连接格式、服务规格与故障排查
登录后查看全文
kener