一份实用的应用健康检查指南，涵盖了__CAPGO_KEEP_0__和 Electron 应用。该指南涵盖了运行时检查、更新、遥测、安全性、CI 脚本和回滚步骤。
周五下午，一份 JavaScript 应用程序更新发布。应用程序打开，认证看起来正常，崩溃计数器保持平稳。然后，某些设备上的检出开始失败，而 App Store 和 Play Console 控制台的仪表板则落后太多，无法支持有把握地回滚决定。 应用健康检查 作为一个仪表盘审查。健康的发布不仅仅是避免崩溃的发布。它必须快速启动，渲染重要屏幕，完成关键旅程，达到正确的后端版本，并为on-call工程师提供足够的遥测，以在延迟的存储数据赶上之前采取行动。
目录
- 周五下午发生的事件，启动了这个剧本
- 定义预测用户痛苦的健康标准
- 您可以在本周内连接的运行时检查
- 健康端点和CI检查，能够在用户之前捕捉问题
- 更新、更新器和存储和设备之间的盲点
- JavaScript 应用程序的安全性、权限和遥测卫生
- 当健康信号触发时，修复和回滚
周五下午发生的事件，启动了这个剧本
通常第一个报告听起来很模糊："某些用户的检出功能已损坏"。支持团队有几张截图，工程团队有最近的捆绑包，商店控制台显示没有明显的回归。团队比较日志，重现流程在一个设备上，并发现失败依赖于更新状态、后端响应形状和较旧的本机外壳。
这不是调试会话。这是一个发布系统故障。
大多数 KPI 的应用商店仪表板仍然落后约 24 小时，崩溃和 ANR 率的延迟可能达到 72 小时,根据商店遥测延迟参考。那些仪表板仍然有用来进行趋势分析，但它们太慢了，不能作为唯一的回滚触发器来处理现场事件。
实用规则： 商店控制台告诉你发生了什么事（延迟后）。你的更新器和运行时遥测必须告诉你当前发布正在做什么。
A mobile app健康检查的周期性检查为团队提供了三层证据:
- 运行时质量: 崩溃、ANR、启动行为、屏幕渲染、错误和资源压力。
- 用户结果: 登录完成、支付确认、其他用户认可的成功或失败的旅程。
- 发布交付: 采用率、失败的安装、被阻塞的设备、渠道行为和回滚状态。
每个层次都需要一个相应的运营杠杆。一个崩溃回归可能需要停止发布或回滚JavaScript包。一个失败的后端依赖需要服务修复，而不是应用回滚。一个破坏的更新路径需要渠道控制和设备级别的调查。
实践的回应应该从时间线开始，而不是责备的练习。记录发布的包、接收的渠道、第一个失败的旅程出现的时间以及受影响的版本。然后使用 移动团队的事件响应指南 来分配负责人、保存证据并决定最安全的行动是暂停渠道、回滚还是原生发布。
这个过程的目的很简单: 降低静默故障并缩短坏信号与安全动作之间的距离健康检查的其余部分应该围绕该结果进行设计。
定义预测用户痛苦的健康标准
周五发布可能会显示绿色的商店仪表板，而用户可能无法登录、完成结账或接收更新。定义“健康”在事件发生之前，在与发布、CI或回滚决策相关的术语中。设备侧事件必须覆盖平台报告可靠之前的24到72小时时间段。
第一层描述用户是否可以完成有意义的工作：
- 无故障的会话。 使用广泛引用的参考点，关于 99.93%的iOS和99.81%的Android，见于 应用健康框架参考。将这些值视为审查基准，而不是普遍保证。根据发布、操作系统、设备家族和推广小组将其分段。发布特定下降应该暂停扩张或触发捆绑回退。
- ANR行为。 A冻结的界面可能会阻止登录、结账或支付确认，而不产生崩溃。根据版本和流程分组，检查WebView工作、插件调用和native桥接操作可能阻塞主线程。修复可能位于code或CI中，而滚动部署的控制器是暂停。
- 启动和屏幕就绪。 测量到交互的时间，不仅仅是进程启动。一个快速打开的shell，但第一个有用屏幕是空白的仍然是不健康的。为CI设置回归阈值，并在失败时检查设备日志。
- 关键旅程成功。 登录、搜索、结账、支付、同步和注销需要明确的成功事件。HTTP响应不一定证明用户已经确认。一个下降应该在任何人选择回滚之前识别受影响的流程。
将发布门控从诊断信号中分离开来。
发布门控 通常包括无崩溃的会话、ANR、启动、身份验证和最高价值用户旅程。 诊断信号 包括内存压力、电池影响、存储增长、网络延迟、HTTP错误类别和WebView渲染。它们解释了失败并指导修复，但不应自动阻止每次部署。
以四个字段写每个标准：
| 健康检查 | 示例 |
|---|---|
| 信号 | 完成checkout |
| 分段 | 发布、平台、区域、设备家族 |
| 查看规则 | 与上一个稳定分组进行比较 |
| 操作 | 暂停发布、检查日志或回滚捆绑包 |
使用此 应用程序健康监控指南 作为一个起点，然后将每个信号分配给一个人或轮班，并记录可以改变结果的杠杆。保持原始信号可见。一个单独的分数可能会隐藏严重的支付失败在健康的背景活动之后。
一个健康的发布是稳定的、响应的、可观察的，并且能够完成用户所重视的任务。它还与一个on-call工程师可以采取的行动相连。
运行时检查你可以在本周内连接
在用户体验工作的地方进行仪表， 不仅仅是过程报告生命的地方。一个Capacitor应用程序可以捕获JavaScript异常、native崩溃、桥接失败、导航计时和旅程事件。一个Electron应用程序可以添加渲染进程失败、主进程错误、预载失败、窗口就绪和资源观察。
一个实际的应用程序健康检查测量 稳定性和性能一起，包括崩溃率、ANR率、启动时间、屏幕渲染时间、错误率和资源利用率。该 移动性能健康检查指南 也强调了根据发布版本和滚动分发进行分段。没有该分段，一个健康的旧版本可能会隐藏一个失败的新版本。
从改变决策的信号开始
捕获一个会话标识符、应用程序版本、native shell版本、平台、设备类别、地区和滚动频道与每个健康事件。避免将个人数据放入这些字段。上下文让on-call工程师在打开调试器之前回答“谁受影响？”
对于每个信号，定义目标和响应：
- 崩溃： 与平台benchmark上面的无崩溃会话进行比较。 一旦出现特定版本的下降，应暂停受影响的群体，直到工程师确定堆栈或插件边界。
- ANR： 按屏幕和操作分组。 在桥接调用期间反复出现的冻结通常需要与数据库迁移期间的冻结进行不同的缓解。
- 启动时间： 标记第一个可用交互式屏幕的点。 慢结果可能来自过大的Web资源、同步初始化、证书检查或在导航之前运行的插件。
- 屏幕渲染： 在checkout、登录、搜索等高价值屏幕周围发出开始和就绪事件。 缺少就绪事件通常会暴露一个静默失败，这些失败不会通过崩溃报告显示。
- 错误率： 记录标准化错误类别、状态家族和操作名称。 不要记录令牌、支付细节或完整的请求体。
- 资源利用率： 观察内存、存储、电池行为和网络故障作为证据。资源趋势最重要的是当它与失败的旅程或ANR相关联时。
下表故意保守。根据指南提供的基准值时，会包含其中。其他频段应从您的稳定基准值中选择，而不是作为普遍限值创造。
| 信号 | 单位 | 健康频段 | 为什么它很重要 |
|---|---|---|---|
| 无故障会话率 | 百分比 | 99.93%的iOS、99.81%的Android作为参考点 | 检测到意外终止的会话 |
| ANR率 | 事件或会话 | 无稳定分支的回归问题 | 识别冻结的接口 |
| 启动时间 | 毫秒或秒 | 稳定与上一个版本 | 显示应用是否迅速可用 |
| 屏幕渲染时间 | 毫秒或秒 | 关键屏幕稳定 | 揭示缓慢或不完整的旅程 |
| 错误率 | 每个操作的事件数 | 稳定性 | 将后端或客户端错误与用户工作关联起来 |
| 资源利用率 | 内存、存储、电池、网络测量 | 不出现未解释的发布特定下降 | 帮助解释冻结、退出和设备降级 |
用动作来仪器，而不是仅仅用警报
一个崩溃事件应该链接到一个发布和一个回滚路径。一个检出失败应该链接到失败的步骤和响应类。一个启动回归应该链接到消耗时间的初始化阶段。
对于Capacitor团队，保持仪器接近JavaScript和本机边界，然后在物理设备上验证它。对于Electron，收集单独的渲染器和主进程上下文，因为一个进程可以失败而另一个进程看起来健康。然后 Capacitor性能监控设置 可以帮助团队将这些信号与发布级别的调查联系起来。
健康端点和CI检查，能够在用户之前捕捉问题
A running process isn’t proof that the application is ready. Your backend can accept a TCP connection while its database pool is exhausted, its cache is unavailable, or a critical external service is timing out.
使用一个专门的、未经身份验证的就绪端点，例如 /healthz. 这个端点应该返回 200 当应用程序和关键依赖项健康时，503 当它们不健康时,遵循 健康端点实现指南. 这些建议还建议将检查时间限制在 500 ms内，检查数据库、缓存和关键外部服务，并为每个依赖项设置超时。
使响应有用且有界
返回一个小、稳定的响应形状。包括一个总体状态和可读的组件状态，但永远不要暴露凭据、堆栈跟踪、内部主机名或敏感配置。一个就绪检查应该在一个必需依赖项不可用时失败，而可选服务应该在应用程序仍然可以提供其核心功能时保持诊断。
验证的状态不仅仅是code:
- 确认响应是有效的 JSON 格式，包含预期的字段。
- 检查端点是否能正常访问预期的后端版本。
- 测试来自相关区域和网络路由的路径。
- 设置独立超时时间，以便一个慢速依赖项不能阻塞整个探测过程。
- 当基础设施需要区分进程失败和依赖项失败时，应将存活性和就绪性分开。
从用户的角度来看，200 响应的 JSON 格式错误或证书过期并不是一个健康的应用。
将检查放置在发布路径中。
在 CI 中，使用部署预览环境运行端点。然后，执行应用中使用的 API 操作，接着是对模拟器或设备农场的少量关键 UI 流程的测试。构建应该在环境无法满足生产所需的就绪性契约时失败。
一个 GitHub Actions 任务可以保持简单：
- 构建 Web 包和本机壳。
- 将其部署到隔离环境中。
- Poll
/healthzwith a timeout. - 验证状态和响应形状。
- 对登录和一个收入关键的旅程进行集成测试。
- 只有所有门控通过后才发布。
不要让端点执行写入或破坏性迁移。让它重复调用，低成本，安全。端点是一个发布门控，不是一个第二个应用。
更新、更新器和存储设备之间的盲点
一个发布可以从技术上是正确的，但仍然会在设备不接收它、安装它或报告其状态时失败。因此，更新器是应用健康的一部分，而不是交付细节。
考虑一个改变结帐验证的JavaScript包。商店安装的原生壳仍然可用，但更新通道将新的Web资产传递给设备的子集。一些设备成功安装。其他设备无法通过验证或因为其原生版本不兼容而被阻塞。商店仪表板不会立即显示这些状态之间的区别。
报告差距很重要。商店仪表板可能会滞后大约 24小时用于大多数KPI和72小时用于崩溃和ANR率 移动发布可见性参考近实时更新者遥测填充了间隔，显示哪些设备接收了一个捆绑包，哪些安装失败，哪些回滚，哪些从未检查过。
将频道视为安全边界
使用独立的beta、staging和生产频道，具有明确的兼容性规则。生产发布不应包含缺少必需插件或配置能力的本机外壳。通过频道、发布、平台和报告的应用程序版本跟踪采用和失败。
操作杠杆是具体的：
- 防护栏： 防止不兼容的捆绑包到达不受支持的外壳。
- 受众发布： 从控制的队列开始，然后在运行时和旅程信号保持健康时扩大。
- 差异性交付： 仅发送支持更新的更新者时更改的资产，减少更新中涉及的工作量和数据量。
- 回滚保护： 安装或启动验证失败时，恢复到已知的良好包。
- 版本比较： 比较新一代的崩溃、启动、WebView 和旅程健康状况与稳定控制组的健康状况。
Capgo 是 Electron 和 Capacitor 团队需要签名的 JavaScript、CSS、配置和资产更新、目标频道、设备日志、采用率和失败指标以及回滚控制的选项。 Capacitor 的实时更新概述 描述了更新器模型以及团队如何将交付状态与发布决策联系起来。
重要原则不是供应商。它是反馈循环。一次发布应该产生证据，而该证据应该控制下一代是否接收包。
JavaScript 应用程序的安全性、权限和遥测卫生
一个应用程序可能看起来稳定，但仍然携带不可接受的风险，通过权限、更新信任或遥测。对于 Capacitor 和 Electron 发布，审查插件和嵌入式 Web 内容作为攻击面的一部分。
从这些检查开始：
- 插件白名单： 移除未使用的插件，审查其本地功能，并验证联系人、文件、位置、摄像头、麦克风或外部意图的访问权限。
- 深度链接审查： 测试 URL 方案和 Android 意图。未受信任的链接不应打开特权流程或绕过身份验证。
- 捆绑验证： 在应用更新之前验证签名，拒绝不完整或意外的负载，并保留最后一次良好包装的恢复。
- 令牌存储： 将凭据保留在平台安全存储中，而不是 JavaScript 可访问的文件或未受限制的本地存储中。
- Electron 边界： 将特权 API 保留在主进程中，暴露窄 preload 接口，并防止任意远程内容到达本机 API。
遥测需要匹配的控制。记录事件名称、发布标识符、操作类别和失败类别。除非经过文档安全审查许可，否则排除令牌、支付信息、用户输入的完整文本、精确位置和原始响应体。
根据操作需求设置保留期，并根据角色限制访问。提供删除或抹除路径，其中适用隐私要求。健康事件应隔离发布回归，而不成为用户行为的第二个数据库。
存储仪表板不能立即提供整个图像。App Store 和 Play Console 遥测可能会留下 24-72 小时的报告间隙，因此将商店信号与更新器状态、发布标识符和设备侧失败事件配对。 Google Play Console 报告文档 解释了报告时应考虑的延迟结果的上下文。
在发布前确认每个新权限都有明确的目的，每个记录的字段都有负责人，更新器拒绝未经信任或不兼容的包。模糊的界限会阻止发布。当信号暴露了信任或隐私问题时，首先停止交付，然后修复导致问题的发布或配置。
信号触发后修复和回滚
只有当信号导致安全行动时，健康信号才有意义。写出决策树在事件发生前，团队还能清晰思考时。
- 发布或同群中出现崩溃或ANR回归: 暂停该频道，比较受影响的版本与稳定同群的版本，然后如果原生壳仍然兼容，回滚包。
- 健康端点返回503: 停止应用发布并修复失败的关键依赖项。重启服务可能有帮助，但不要用应用回滚来掩盖后端故障。
- 关键旅程失败而崩溃保持正常: 禁用受影响的功能或频道，检查响应形状和配置，然后发货修正的包。
- 更新安装或启动验证失败: 保持上一个捆绑包活动，标记发布不健康，并调查签名、兼容性或资产完整性。
- 原生权限或插件行为有问题： 可能需要更大的修复。准备一个商店发布，修复需要原生code、清单更改、特权或新权限声明。
The Capacitor实时更新回滚策略 应该是运行手册的一部分，而不是在危机期间发现的页面。自动保护适用于更新器可以可靠检测安装或启动失败的情况。即使用户可以完成启动，但在重要旅程中失败，也需要完整的事件。
商业压力明显。移动应用测试服务市场预计将达到 7.70亿美元（2025年） 并将达到 19.84亿美元（2031年），年增长率17.09%，而苹果应用商店拒绝率大约为 2024 年 24.9% 根据 市场和商店评估数据 . 这些数字并不能取代工程判断，但它们强调了将质量检查视为可选项的成本。
每次事故发生后，保存时间线，找出最早的可操作信号，记录哪个杠杆有效，并将缺失的检查转换为发布门控。成熟的应用程序健康检查不仅报告失败，还使下一次失败更容易检测、包含和逆转。
Capgo 为 Capacitor 和 Electron 团队提供了实时更新、目标频道、发布和失败遥测、设备日志和回滚保护，使运行时健康信号可以驱动发布决策。访问 Capgo 连接您的更新管道与应用程序健康检查和修复控制所描述的本手册。
