Capgo 回滚管理指南

回滚管理对于修复导致 应用更新 崩溃或 Bug 的问题至关重要。通过 Capgo，您可以快速恢复到稳定版本，无需经过 App Store 审核。以下是具体操作方法： Capgo 简化回滚管理：

• 快速恢复：回滚平均仅需 114 毫秒。
• 自动更新：无需人工干预 - Capgo 可无缝处理更新与回滚。
• 安全流程：端到端加密确保更新安全。
• 轻松配置：安装 @capgo/capacitor-updater package 并在几分钟内完成应用配置。
• 更新通道：通过 staging、beta 和 production 环境控制更新。
• 手动与自动回滚: 根据需求选择手动干预或自动恢复。

快速设置步骤:

1. 安装 @capgo/capacitor-updater 并同步您的项目。
2. 配置 capacitor.config.json 进行更新。
3. 设置更新通道（staging、beta、production）。
4. 在生产环境部署前测试回滚功能。

Capgo 通过即时修复问题，确保您的应用保持稳定且用户体验良好。无论您倾向于手动控制还是自动触发，Capgo 都能为您的 Capacitor 应用提供可靠的安全保障。

设置 Capgo 回滚管理

要用 Capgo 高效管理回滚，你需要安装其核心包、配置应用设置并建立更新通道。这样能确保部署顺利，并为处理问题提供可靠的安全网。

安装并配置 Capgo

首先，将 @capgo/capacitor-updater 包添加到你的 Capacitor 项目。该包用于管理应用的更新和回滚。请在项目目录中运行以下命令：

npm install @capgo/capacitor-updater
npx cap sync

安装完成后，更新你的 capacitor.config.json 文件以启用更新功能。以下是示例配置：

{
  "plugins": {
    "CapacitorUpdater": {
      "autoUpdate": true,
      "updateUrl": "https://api.capgo.app/updates",
      "privateKey": "your-private-key-here",
      "version": "1.0.0",
      "directUpdate": false
    }
  }
}

• 在 autoUpdate 至 true 以实现自动更新。
• 保留 directUpdate 作为 false 以确保更新在部署前已通过验证。

接下来，将您的应用连接到 Capgo 的更新系统。请前往注册： capgo.app，然后使用 CLI 注册您的应用：

npx @capgo/cli app add your-app-id

此步骤将您的项目连接到 Capgo，从而实现版本追踪和用户分层，以便进行精准的回滚管理。

完成初始设置后，您可以配置更新通道来控制和监控部署。

设置更新通道

Update channels 用于管理更新的分发，支持进行彻底测试，并在需要时实现快速回滚。

要创建 channels，请使用 Capgo 的 CLI 工具。首先设置三个关键 channels 以实现高效的回滚管理：

npx @capgo/cli channel add staging
npx @capgo/cli channel add beta  
npx @capgo/cli channel add production

每个 channel 都有其特定的用途：

生产环境建议使用稳定的版本模式，例如 1.0.*；而 staging 环境可以使用更灵活的格式进行测试。

若要进一步优化回滚管理，请设置用户分层。这能让你在回滚时针对特定群体进行操作，在有效解决问题的同时，将对用户的影响降至最低。

通过定义基于错误率、性能指标或用户反馈等条件的触发器，实现回滚自动化。这些触发器能确保问题得到及时处理，无需人工干预。

在部署到生产环境之前，请先在 staging channel 测试回滚功能。这一步可以确保你的回滚系统在真实场景下运行符合预期。

最后，将你的更新 channel 与你的 CI/CD 流水线. 这种自动化简化了部署和回滚，在保持工作流高效的同时，也为不可预见的问题提供安全保障。

如何使用 Capgo 执行回滚

Capgo 的更新验证系统可确保应用稳定，其回滚功能在此基础上提供手动和自动恢复选项。了解如何有效使用这些方法，有助于在出现问题时快速恢复功能。

手动回滚步骤

手动回滚让您可以自主选择并应用稳定版本，从而在采取行动前充分评估当前情况。

首先，要禁用自动更新，请在您的 capacitor.config.json 文件中设置 autoUpdate 至 false。这会阻止 Capgo 自动管理更新，让您完全掌控整个流程。

禁用自动更新后，请使用 CapacitorUpdater.download() 方法获取所需版本，并使用 CapacitorUpdater.set() 来应用该版本。示例如下：

import { CapacitorUpdater } from '@capgo/capacitor-updater'

const version = await CapacitorUpdater.download({
  url: 'https://github.com/Cap-go/demo-app/releases/download/0.0.4/dist.zip',
})
await CapacitorUpdater.set(version); // Sets the new version and reloads the app

使用以下命令应用已下载的版本后 CapacitorUpdater.set()，应用会自动重新加载恢复后的 bundle。为了完成回滚流程，请务必调用 CapacitorUpdater.notifyAppReady() 以确认更新已稳定。

“如果不调用此方法，应用将被回滚到上一个成功版本（或内置 bundle）” [2]

如果跳过此确认步骤，Capgo 会认为回滚未成功，并可能再次回滚到最后已知可用版本。

对于需要更快响应的情况，自动回滚无需人工干预即可完成恢复。

自动回滚触发器

自动回滚非常适合需要持续监控的环境。它们通过检测问题并自动恢复到稳定版本来最大限度地减少停机时间。这些触发器基于健康检查和预定义的错误阈值。

设置健康检查以监控应用的核心功能，例如用户身份验证或数据加载。当这些检查检测到问题时，自动触发器可以立即回滚到稳定版本。

使用性能指标定义错误阈值，以确定何时需要进行回滚。下表列出了需要考虑的关键组件：

选择手动还是自动回滚，取决于你的应用环境和对风险的容忍度。

“回滚就是重新部署 code 的旧版本。它是 在大多数情况下是首选方案 因为在不到 5 分钟内即可消除对用户的负面影响，且不会妨碍你采取其他方案 [3]

在稳定性与安全性至关重要的生产环境中，手动回滚可以实现谨慎的评估与控制。相比之下，测试和预发布环境则能从自动化回滚的速度与效率中获益更多。结合这两种方法可以确保策略的平衡——通过自动化触发器处理即时故障，而将手动回滚保留给需要人工介入的复杂问题。

回滚管理最佳实践

有效的回滚策略通过结合渐进式部署与详细的回滚后分析，保护用户免受不稳定更新的影响。

分阶段发布与降低风险

分阶段发布是防止应用更新出现大规模问题的保障措施。与其一次性向所有用户推送变更，不如将更新增量式地发布给较小的用户群。首先从占用户总数 1–5% 的测试组开始。确保该群体涵盖了多种设备类型、操作系统和使用习惯。监控其表现 24–48 小时，以便及时发现任何早期故障迹象。

Feature flags 在这种情况下可以救命。它们允许你立即禁用特定功能，而无需进行完整的回滚 [4].

为推进发布阶段设定明确的标准。例如，你可以根据设备稳定运行的小时数或崩溃率阈值等指标来做决策。一个通用的经验法则是：在扩大发布范围之前，目标应至少达到 1,000 个设备小时的稳定运行。使用 Capgo 的 update channels 等工具可以简化这一流程，让你将更新分配给特定的用户组（如 beta 测试人员或早期采用者），从而实现对更新对象和时间的精准控制。

以下是分阶段发布的示例：

一旦发布趋于稳定，请将注意力转向回滚后的监控，以确保一切运行顺畅。

回滚后的监控与诊断

完成回滚后，必须进行彻底的监控，以确认回滚成功并防止未来再次出现问题。

设置实时告警，并跟踪崩溃率、应用启动时间、内存占用和网络性能等关键性能指标。这些指标对于评估稳定性及用户体验至关重要。对于生产环境，目标应是 99.9% 的基准稳定性，并确保在性能跌破此水平时能立即收到告警。

回滚后请至少持续监控 72 小时，以确认应用已恢复到稳定状态。密切关注直接影响用户的指标，例如应用启动速度或功能的响应速度。

使用具备清晰升级流程的错误追踪工具。汇总回滚事件（包括原因、受影响用户和解决时间）的自动化报告，可以帮助团队从每次事故中学习。详尽记录这些事件（包括触发条件、解决步骤和经验教训），对于优化流程和团队培训具有极高的价值。

采用渐进式监控方法也十分有效。在回滚后立即进行密集观察，随着稳定性的确认再逐步减少监控力度。这种方法能在彻底监管与资源高效利用之间取得平衡。

排查回滚问题

回滚有时会遇到影响用户体验的突发状况。掌握如何快速识别并修复这些问题，是确保系统平稳运行的关键。

修复校验和验证失败

校验和验证失败是回滚过程中可能遇到的较严重问题之一。这类失败表明更新文件在传输或存储过程中可能已损坏或被篡改。请按以下步骤处理：

• 仔细检查源文件和回滚 bundle 的完整性。
• 如有必要，请从版本控制系统中重新下载或重新生成 bundle。

Capgo 的端到端加密有助于保障传输过程中的文件安全，但本地存储仍可能出现问题。如果影响到多个用户，请清除其本地缓存以移除损坏的临时文件。你可以通过 Capgo 的 update channels 实现自动化，即推送一个微小的配置更新来强制重新下载。

此外，在验证下载时也要考虑网络相关问题。解决校验和问题后，请进一步排查潜在的版本冲突和网络挑战。

处理版本冲突与网络问题

当应用的各个部分未能正确同步时，就会发生版本冲突。如果出现这种情况，请立即回滚到上一个稳定版本以减少影响。利用 Capgo 的更新通道，你可以在大规模发布前，先针对特定用户群进行回滚测试。

详细的日志对于诊断这些冲突至关重要。通过查找 API 版本不匹配或数据库 Schema 问题等错误，可以精准定位问题是源于后端变更、客户端更新，还是两者兼有。

另一方面，网络问题可能会完全阻碍回滚尝试。连接超时、SSL 证书错误或代理配置错误是常见的诱因。要解决这些问题：

• 确保所有更新端点、证书和版本标识符均为最新状态。
• 在用户遇到问题的相同环境下测试你的网络连接。

在企业环境中，代理和防火墙规则可能会干扰更新。请与企业客户协作，将 Capgo 的更新端点加入白名单，并确认 安全策略 没有拦截回滚流程。

定期测试版本不匹配、Bundle 损坏、网络故障和 API 超时等场景，可确保您的 Rollback 机制能够应对真实世界的挑战。这种主动预防的方法能为您在生产环境遇到问题时提供信心。

总结

拥有一套可靠的回滚策略，对保持你的应用 Capacitor 应用稳定性至关重要，而 Capgo 提供了让这一过程无缝衔接的工具。它结合了高效的回滚 更新管理 与强大的安全措施，确保你的应用始终可靠且受到保护。

Capgo 的核心亮点在于其 一键回滚功能，如果出现问题，你可以快速回滚到之前的版本。这能最大限度地减少停机时间，并把对用户的干扰降到最低。此外，该平台在确保符合 Apple 和 Google 要求的同时，还利用 端到端加密 来保障你在生产环境中的应用安全。

“对于想提高效率的开发者来说，Capgo 是必备工具。修复 Bug 不用过审，这一点非常宝贵。” —— Bessie Cooper [1]

这些功能简化了工作流，并在出现挑战时提供即时解决方案。通过 CI/CD 和 semantic-release 自动化，Capgo 简化了回滚流程。无论是面临校验和验证错误、版本不匹配还是网络波动，Capgo 的基础设施和监控工具都能帮助你在问题影响用户之前将其解决。

对于管理生产环境中 Capacitor 应用的团队，Capgo 提供了有效回滚策略所需的安全性、可靠性和简洁性。已有超过 2,000 款应用信任该平台，选择它意味着你正在选择一种既能提升开发效率又能提高用户满意度的解决方案。 [1].

当问题发生时，Capgo 确保你能够立即解决它们。

常见问题

::: faq

Capgo 如何在回滚期间保证应用更新的安全？

Capgo 采用 端到端加密 来保障从创建到交付每个阶段的应用更新安全。这确保了更新始终受到保护，并通过严格的访问控制将权限仅限于授权用户。

为了保证更新的完整性，Capgo 使用 加密检查 例如哈希值和数字签名。这些工具可以确认更新未被篡改。如果发生任何问题，平台的自动化回滚功能可以让你快速、安全地恢复到之前的版本。这些功能共同确保了你的应用更新既安全又可靠。 :::

::: 常见问题

使用 Capgo 的自动化回滚相比手动回滚有哪些优势？

使用 Capgo 的自动化回滚比手动回滚更快速、更可靠且更不容易出错。当更新后出现问题时，这些回滚可以迅速将您的应用恢复到稳定版本，从而减少停机时间并确保用户体验的无缝衔接。

自动化的核心优势在于消除了人为错误。通过遵循预定义的最佳实践，它能确保每次操作的一致性。这不仅节省了宝贵的时间，还为应用管理提供了一种更稳定、更高效的方式。对于使用 Capacitor 应用的开发者来说，自动化回滚提供了一种无压力且可靠的更新处理方案。 :::

::: 常见问题

在将更新发布到生产环境之前，我该如何测试 Capgo 的回滚功能？

为了有效测试 Capgo 的回滚功能，首先需要搭建一个 staging 环境。这允许您在更新正式上线前，在受控环境中进行测试。您可以邀请 beta 测试人员 以便尽早发现潜在问题，并确保您拥有 实时监控 来追踪性能并快速检测错误。同时，定义明确的 回滚触发条件也至关重要，例如达到特定的错误率或收到特定的用户反馈，这样您就能准确知道何时需要回滚更新。

在发布任何更新之前，请彻底测试回滚流程。确保它可以无缝返回到之前的稳定版本，而不会引发额外问题。模拟故障场景是验证回滚机制是否按预期工作的另一种好方法。最后，充分利用 Capgo 的 分析工具 来密切关注更新性能和用户参与度。这些洞察可以指导您做出明智的决策，判断何时可能需要进行回滚。 :::

继续阅读 Capgo 的回滚管理指南：

如果你正在使用 Capgo 回滚管理指南 规划回滚与版本控制，并将其与 回滚 有关 Rollbacks 的实现细节， 版本定向 有关 Version Targeting 的实现细节， 更新行为 有关 Update Behavior 的实现细节， bundle 有关 bundle 的实现细节，以及 Capgo Live Updates 用于 Capgo Live Updates 中的产品工作流。