返回资讯中心
外部精选
软件工程
#开发者实时流

Scalar 文档站上线基于标签的快速回滚恢复系统

来源标题:Implementing a tag-based restoration system for the Scalar docs sites

Scalar 为 ScalarDB、ScalarDL 文档站及文档落地页、归档页设计并实现了基于标签的恢复系统。维护者可在任意已知良好状态打上恢复标签,之后通过一次工作流触发即可将线上站点恢复到该状态,无需修改代码。此举旨在应对构建未完全成功却仍被部署、导致站点不可用的故障场景。

Hacker News 最新josh-scalar2026/11/20 · 今天15 分钟阅读

以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。

DevOps 文档 站点可靠性 事件响应计划 为 Scalar 文档站点实现基于标签的恢复系统 Josh Wong 阅读时长 7 分钟· 2026 年 10 月 26 日

文档站点的故障方式,有时并不会在 CI 检查通过时暴露出来。例如,页面中一个格式错误,比如缺少闭合标签,就可能导致站点构建失败。由于我们的文档站点依赖多个工具、组件和构建步骤协同工作,这类语法问题有时会让部署继续进行,尽管构建并未完全成功,最终导致站点对访问者不可用。一旦发生这种情况,每一分钟的停机都会侵蚀访问者的信任,而在压力下诊断根本原因只会延长故障时间。

为了解决这个问题,我们在 ScalarDB 和 ScalarDL 文档站点,以及 Scalar 文档落地站点和 Scalar 文档归档站点上,设计并实现了一套基于标签的恢复系统。该系统为维护者提供了一条快速、可靠的恢复路径:在任意已知良好的状态创建一个恢复标签,然后通过一次工作流调度即可将线上站点恢复到该标签——无需修改 main 分支,也不会丢失任何近期工作。

为什么我们需要恢复流程

在这套系统出现之前,文档站点发生故障时,我们唯一的选择要么是尽快修复问题,要么是回退若干提交(取决于问题是在为每个文档版本合并变更时何时引入的)。无论哪种方式,都可能花费几分钟到几个小时。由于即使构建已记录错误,部署工作流仍可能完成,故障往往是通过监控或访问者发现的,而不是由流水线本身发现。此外,也没有已知良好状态的清单,也没有自动记录自上一个稳定点以来发生了哪些变更。

新系统为每个 Scalar 文档站点仓库引入了两个 GitHub Actions 工作流:

这两个工作流共同为维护者提供了一个定义明确、可重复的流程,可以直接从 GitHub Actions UI 触发,有助于将我们的平均恢复时间(MTTR)保持在 15 分钟以内。该时间包括 Better Stack 检测到故障并发送 Slack 消息、维护者接手处理,以及恢复本身——根据构建情况大约需要 5–10 分钟。

两个工作流均通过 workflow_dispatch 手动触发,让维护者完全控制何时创建标签以及何时执行恢复。

create-tag.yml 工作流针对 main 分支运行,接受三个输入:

在创建标签之前,工作流会检查它是否在 main 分支上运行、标签名是否符合 YYYYMMDD 格式,以及标签是否已存在。如果任何检查失败,工作流会立即退出并给出描述性错误摘要。否则,它会创建一个附注标签,标签消息包含你的描述(如果你提供了的话)和创建时间戳,并将其推送到仓库。工作流摘要还会列出被标记的提交 SHA。

标签遵循简单的命名约定(YYYYMMDD),使得最近的恢复点可以按日期轻松识别。由于工作流会拒绝重复的标签名,我们每天只能创建一个与日期相关的标签。如果需要在同一天再次使用基于日期的标签,我们只需删除现有标签并以相同名称创建新标签。

restore-from-tag.yml 工作流接受一个输入:要从中恢复的 tag_name。然后它执行以下步骤:

该工作流不会以任何方式修改 main 分支。工作流完成后,恢复的状态会立即在 GitHub Pages 上线,但下一次推送到 main 分支将触发正常的 deploy.yml 工作流并将其覆盖。这种行为是有意为之的:任何问题都应在下一次推送之前先在 main 分支上解决,因此恢复仅用于弥合检测到问题与修复问题之间的间隙。

如果恢复后的站点仍无法正常工作,例如因为被标记的提交也存在构建问题,请使用上一个标签再次运行该工作流。

恢复工作流会生成一份变更跟踪报告,并将其包含在站点构建中。报告包含:

以下是报告外观的简化示例:

变更跟踪报告

恢复标签:20261030 工作流启动时的 main 分支 SHA:1234567890abcdef1234567890abcdef12345678

此恢复版文档站点中排除的内容(3 个文件)

以下文件在标签创建后被添加或修改。在问题修复并从 main 分支重新构建站点之前,它们的添加或更改会被暂时排除在站点之外:

  • docs/data-loader.mdx
  • docs/glossary.mdx
  • versioned_docs/version-3.18/data-loader.mdx

这份报告帮助你准确查看恢复后的站点缺少了什么。在 git 中没有任何内容被回退:所有更改都保留在 main 分支上,问题修复后的下一次部署时站点会重新包含它们。报告中的 git cherry-pick、git rebase 和 git merge 命令供你在需要将特定更改带入修复分支时使用。

典型的事件处理流程如下:

基于标签的恢复系统为 Scalar 文档站点维护者在出现问题时提供了一条快速、低风险的路径,回到已知良好的状态。通过结合附注 git 标签、自动化部署和变更跟踪报告,该系统确保事件能够被快速处理,并且团队始终清楚哪些更改暂时从线上站点中缺失。

要了解更多关于 Scalar 的信息,请查看我们在 Scalar 工程博客上的其他文章,以及 ScalarDB 和 ScalarDL 文档。

如果您正在考虑使用我们的产品,请联系我们。

正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。

打开原文
去社区讨论 →