为__CAPGO_KEEP_0__和Electron应用程序提供的实用应用程序健康检查指南。运行时检查、更新、遥测、安全性、CI脚本和回滚步骤。

周五下午，JavaScript 更新正常运行。应用程序打开，认证正常，崩溃计数器保持正常。然后，设备的一部分开始检验失败，而 App Store 和 Play Console 控制台的数据则落后太多，无法支持有信心的回滚决策。

在处理应用程序时，经常会遇到一些问题。 目录 周五下午的事件，这个战略指南的起点

定义预测用户痛苦的健康标准

• 将诊断信号与发布门槛分开
• 您可以在本周内连接的运行时检查
  • 从改变决策的信号开始
• 仅仅是警报而不是行动的仪器
  • The Friday Afternoon Incident That Starts This Playbook
  • Defining Health Criteria That Predict User Pain
• 健康检查点和CI检查
  • 让响应有用且有限
  • 将检查放入发布路径
• 更新、更新器和商店和设备之间的盲点
  • 将渠道视为安全边界
• JavaScript应用的安全性、权限和遥测卫生
• 当健康信号触发时的修复和回滚

周五下午发生的事件

第一份报告通常听起来很模糊：‘某些用户的检出失败了。’支持团队有几张截图，工程团队有最近的捆绑包，商店控制台显示没有明显的回归。团队比较日志，重现流程在一个设备上，并发现失败依赖于更新状态、后端响应形状和较旧的本机外壳。

这不是调试会话。这是一个发布系统的失败。

大多数KPI的应用商店仪表板 24小时内有大约根据商店的遥测延迟参考值。那些仪表盘仍然有用来进行趋势分析，但它们太慢了，不能作为直播事件中唯一的回滚触发器。

实践规则： 商店控制台告诉你发生了什么事，但这是在报告延迟之后。你的更新和运行时遥测必须告诉你当前发布正在做什么。

定期健康检查给团队提供了三层证据：

• 运行时质量： 崩溃、ANR、启动行为、屏幕渲染、错误和资源压力。
• 用户结果： 登录完成、支付确认、支付成功和其他用户认可为成功或失败的旅程。
• 发布交付： 采用率、失败的安装、阻塞设备、通道行为和回滚状态。

每个层次都需要一个相应的运营杠杆。一个崩溃回归可能需要停止发布或回滚JavaScript包。一个失败的后端依赖需要服务修复，而不是应用回滚。一个破坏的更新路径需要通道控制和设备级别的调查。

实践的回应应该从时间线开始，而不是责备。记录发布的包、接收的通道、第一个失败的旅程出现的时间以及受影响的版本。然后使用 移动团队的事件响应指南 为分配负责人、保存证据并决定是否暂停频道、回滚或发布原生版本

本过程的目的很简单： 减少静默故障并缩短坏信号和安全行动之间的距离. 其余健康检查应围绕该结果进行设计

定义预测用户痛苦的健康标准

周五发布可能会显示绿色的商店仪表板，而用户可能无法登录、完成结账或接收更新。 在事件发生之前，定义“健康”的标准，根据每个信号与发布、CI或回滚决策的联系。 由于设备侧事件必须覆盖平台报告可靠之前的24到72小时的盲点，存储的遥测数据也存在盲点

第一层描述用户是否可以完成有意义的工作：

1. 无故障的会话 使用广泛引用的参考点 99.93%的iOS和99.81%的Android, 文档在 应用健康框架参考. 将这些值视为审阅基准，不是普遍保证。按发布版本、操作系统、设备家族和推广小组段。发布特定降级应暂停扩展或触发捆绑回退。
2. ANR 行为。 一个冻结的界面可能会阻止登录、结帐或支付确认而不产生崩溃。按版本和流程分组，然后检查WebView工作、插件调用和本机桥操作可能阻塞主线程。修复可能位于code或CI中，而回滚的开关是暂停。
3. 启动和屏幕就绪。 测量到交互的时间，不仅仅是进程启动。一个快速打开的壳，但第一个有用屏幕空白仍然是不健康的。设置CI阈值来检测回归，并在失败时检查设备跟踪。
4. 关键旅程成功。 登录、搜索、结帐、支付、同步和注销需要明确的成功事件。一个HTTP响应并不证明用户已经到达确认。一个降级应该在任何人选择回滚之前识别受影响的流程。

将发布门槛与诊断信号分开

发布门槛 通常包括无崩溃的会话、ANR、启动、身份验证和最高价值用户旅程。 诊断信号 包括内存压力、电池影响、存储增长、网络延迟、HTTP错误类别和WebView渲染。它们解释了失败并指导修复，但不应自动阻止每次部署。

写每个标准四个字段:

使用这个 应用健康监控指南 作为起点，分配每个信号给一个人或轮班，并记录可以改变结果的杠杆。保持原始信号可见。一个单独的分数可能会隐藏严重的支付失败背后的健康背景活动。

健康的发布是稳定的、响应的、可观察的，并且能够完成用户所重视的任务。它还与一个on-call工程师可以采取的行动相连。

运行时检查你可以在本周内连接

在用户体验工作的地方， Instrument 应用，而不是仅仅在进程报告生命的地方。一个Capacitor应用可以捕获JavaScript异常、native崩溃、桥接失败、导航时间和旅程事件。一个Electron应用可以添加渲染进程失败、主进程错误、预载失败、窗口就绪和资源观察。

一个实际的应用健康检查 衡量稳定性和性能,包括崩溃率、ANR率、启动时间、屏幕渲染时间、错误率和资源利用率。 移动性能健康检查指南 也强调根据发布版本和发布分组进行分段。没有这个分段，一个健康的旧版本可能会隐藏一个失败的新版本。

开始从变化决策的信号

捕获每个健康事件时的会话标识符、应用版本、原生 shell 版本、平台、设备类别、地区和发布频道。避免将个人数据放入这些字段中。上下文让负责人在打开调试器之前回答“谁受影响？”

为每个信号定义目标和响应:

• 崩溃: 与平台benchmark进行比较。一个特定版本的崩溃率下降应该暂停受影响的群体，直到工程师确定栈或插件边界。
• ANR: 根据屏幕和操作分组。重复的冻结在桥接调用期间指向不同的缓解措施，而数据库迁移期间的冻结则指向不同的缓解措施。
• 启动时间: 标记第一个可用交互屏幕的点。一个慢的结果可能来自过大的Web资产、同步初始化、证书检查或在导航之前运行的插件。
• 屏幕渲染: 在checkout、登录、搜索等高价值屏幕周围发出开始和就绪事件。缺失的就绪事件通常会揭示一个静默失败，这种失败不会通过崩溃报告显示出来。
• 错误率: 记录标准化错误类别、状态家族和操作名称。不要记录令牌、支付细节或完整的请求体。
• 资源利用率： 监控内存、存储、电池行为和网络故障作为证据。资源趋势最重要的是它与失败的旅程或ANR相关联。

下表故意保守。根据提供的基准，表中包括了它。其他频段应该从自己的稳定基准中选择，而不是作为普遍限度创造。

仅仅是警报而不是动作

一个崩溃事件应该链接到一个发布和一个回滚路径。一个检出失败应该链接到失败的步骤和响应类别。一个启动回归应该链接到初始化阶段消耗的时间。

对于Capacitor团队，保持仪表板接近JavaScript和本机边界，然后在物理设备上验证它。对于Electron，收集单独的渲染器和主进程上下文，因为一个进程可以失败而另一个进程看起来健康。 Capacitor性能监控设置 可以帮助团队将这些信号与发布级别的调查联系起来。

健康端点和CI检查：在用户之前捕捉问题

一个正在运行的进程并不能证明应用程序已经准备好。您的后端可以接受一个TCP连接，而数据库池已经耗尽，缓存不可用，或者一个关键外部服务正在超时。

使用一个专门的、未经身份验证的就绪端点，如 /healthz端点应返回 200，当应用程序和关键依赖项健康时，503否则，遵循 健康端点实现指南。该指南还建议将检查时间限制在 500毫秒，检查数据库、缓存和关键外部服务，并为每个依赖项设置超时。

使响应有用且有界

返回一个小型、稳定的响应形状。包括一个整体状态和可读的组件状态，但绝不暴露凭据、堆栈跟踪、内部主机名或敏感配置。一个就绪检查应该在一个必需的依赖不可用时明确失败，而可选服务应该在应用程序仍然可以提供核心功能时保持诊断状态。

验证状态code的更多内容：

• 确认响应是有效的 JSON 格式，具有预期的字段。
• 检查端点是否达到预期的后端版本。
• 测试从相关区域和网络路由中访问的路径。
• 设置独立超时，以便一个慢速依赖项不能阻塞整个探测。
• 在基础设施需要区分进程失败和依赖项失败时，保持就绪和存活状态分开。

一个 200 响应，包含错误的 JSON 或过期证书，不是从用户的角度来看健康的应用程序。

将检查放置在发布路径中

在 CI 中将端点运行在部署的预览环境中。然后，执行应用程序使用的API操作，接着是对一个模拟器或设备农场的少量关键 UI 流程的测试。构建应该在环境无法满足生产所需的相同就绪契约时失败。

一个GitHub Actions 任务可以保持简单：

• 构建 Web 包和原生 shell。
• 部署到隔离环境。
• 轮询 /healthz 带超时。
• 验证状态和响应形状。
• 运行登录和收入关键路径的集成测试。
• 只有所有门槛通关后才发布。

不要让端点执行写入或破坏性迁移。让它重复调用，低成本，安全。端点是发布门槛，不是第二个应用程序。

更新、更新器和存储设备之间的盲点

即使发布技术上是正确的，也可能在设备未接收、安装或报告状态时失败。因此，更新器是应用健康的一部分，而不是交付细节。

考虑一个改变结算验证的 JavaScript 包。商店安装的原生 shell 可用，但更新通道将新 Web 资产分发给设备的子集。一些设备安装成功。其他设备无法通过验证或被阻塞，因为它们的原生版本不兼容。商店仪表板不会立即显示这些状态之间的差异。

报告差距很重要。商店仪表板可能会滞后大约 24 小时内大部分 KPI 指标更新，故障和 ANR 率更新时间最长 72 小时, 如 移动发布可见性参考 . 近实时更新器遥测填补了时间间隔，显示哪些设备接收了一个捆绑包，哪些安装失败，哪些回滚，哪些从未检查过。

将通道视为安全边界

使用独立的 beta、staging 和生产通道，并且使用明确的兼容性规则。生产发布不应包含缺少必需插件或配置能力的原生 shell。通过通道、发布、平台和报告的应用程序版本跟踪采用和失败。

操作的杠杆是具体的：

• 防护栏： 防止不兼容的捆绑包到达不受支持的 shell。
• 受众发布： 首先使用受控的团体，然后在运行时和旅程信号保持健康时扩大。
• 差异性发布: 只发送支持的更新器的更改资源，减少更新过程中的工作量和数据量。
• 回滚保护： 安装或启动验证失败时，恢复到已知的良好包。
• 版本比较: 比较新一代的崩溃、启动、WebView和旅程健康状况与稳定控制组的健康状况。

Capgo 是 Electron 和 Capacitor 团队需要签名的 JavaScript、CSS、配置和资源更新、目标频道、设备日志、采用率和失败指标以及回滚控制的选项。 Capacitor 的实时更新概述 描述了更新器模型以及团队如何将交付状态与发布决策联系起来。

关键原则不是供应商。它是反馈循环。一次发布应该产生证据，而证据应该控制下一代是否接收包。

JavaScript 应用程序的安全性、权限和遥测卫生

一个应用程序可能看起来稳定，但仍然携带不可接受的风险，通过权限、更新信任或遥测。对于 Electron 和 Capacitor 发布，审查插件和嵌入式 Web 内容作为攻击面的一部分。

开始使用这些检查:

• 插件白名单: 移除未使用的插件，检查其本地功能，验证联系人、文件、位置、摄像头、麦克风或外部意图的访问权限。
• 深度链接检查: 测试 URL 方案和 Android 意图。未经信任的链接不应打开特权流或绕过身份验证。
• 包裹验证: 在应用更新之前验证签名，拒绝不完整或意外的负载，并保留最后一次已知良好的包裹以便恢复。
• 令牌存储: 将凭据存储在平台安全存储中，而不是 JavaScript 可访问的文件或未受限制的本地存储中。
• Electron 边界: 将特权 API 保留在主进程中，暴露窄的预载接口，并防止任意远程内容到达本机 API。

遥测需要匹配的控制。记录事件名称、发布标识符、操作类别和失败类别。除非经过文档安全审查许可，否则排除令牌、支付信息、完整用户输入文本、精确位置和原始响应体。

根据业务需求设置保留期限，并根据角色限制访问。提供删除或抹除路径，适用于隐私要求的场景。健康事件应该隔离发布回归，而不成为用户行为的第二个数据库。

存储仪表板不能立即提供完整的图像。App Store 和 Play Console 的 telemetry 可能会导致 24–72 小时的报告延迟，因此请将存储信号与更新状态、发布标识符和设备侧故障事件配对。 Google Play Console 报告文档 解释延迟结果时，团队应该考虑报告上下文。

在发布前确认每个新权限都有明确的目的，每个记录的字段都有负责人，更新器拒绝不受信任或不兼容的包。模糊的界限是发布阻塞。 当信号暴露了信任或隐私问题时，首先停止交付，然后修复导致它的发布或配置。

健康信号的修复和回滚

只有当它导致安全行动时，健康信号才有意义。 写决策树在事件发生前，团队还能清晰思考。

• 发布或分组中的崩溃或 ANR 回归： 暂停该渠道，比较受影响的版本与稳定分组，若原生壳仍然兼容，则回滚包。
• 健康端点返回 503： 停止应用发布并修复失败的关键依赖项。 重启服务可能有帮助，但不要用应用回滚来掩盖后端故障。
• 关键旅程失败时，应用程序崩溃保持正常状态： 禁用受影响的功能或频道，检查响应形状和配置，然后发布修正的包。
• 更新安装或启动验证失败： 保持上一个包处于活动状态，标记发布为不健康，调查签名、兼容性或资产完整性。
• 本机权限或插件行为不正确： 可能需要一个存储版本的发布。修复需要本机code、清单更改、特权或新权限声明时，仅使用实时JavaScript更新可能不足。

The Capacitor live update 回滚策略 应包含在运行手册中，而不是在危机期间发现的页面。自动保护适用于更新器可以可靠检测安装或启动失败的情况。然而，当用户可以完成启动，但在关键旅程中失败时，仍需要完整的事件。

商业压力明显。移动应用程序测试服务市场预计将达到 7.70亿美元 并预计到达 $19.84亿美元到2031年，17.09%的CAGR,苹果应用商店拒绝率报告为大约 24.9%在2024年,根据 市场和商店评论数据.这些数字并不能取代工程判断，但它们强调了将质量检查视为可选项的成本。

每次事故后，保存时间线，确定最早的可操作信号，记录哪个杠杆有效，转变为缺失的检查为发布门户。成熟的应用程序健康检查不仅报告失败。它使下一次失败更容易检测、包含和逆转。

Capgo给了Capacitor和Electron团队签署的实时更新、目标频道、回滚和失败遥测、设备日志和回滚保护，使运行时健康信号可以驱动发布决策。访问 Capgo 连接您的更新管道与应用程序健康检查和修复控制所描述的本手册。