企业官网建设流程全解析

在对接 Proton Drive 云盘时，"文件下载后校验失败"、"某些节点解密报错"这类疑难问题往往难以复现。Proton Drive SDK（开源仓库sdk）内置了一个开箱即用的诊断工具sdkDiagnostic：它能遍历你的 My Files 文件夹或 Photos 时间线，逐个节点校验元数据签名、内容完整性（SHA1）、缩略图，并把过程中出现的日志、指标、HTTP 异常全部以结构化事件流输出，帮你像"体检报告"一样快速定位问题。

一、sdkDiagnostic 是什么？为什么新手用得上 🩺

sdkDiagnostic是 Proton Drive SDK 提供的云端数据体检工具，源码位于 client/js/src/diagnostic/ 目录。它和普通的 API 调用不同：

• 全量真实访问：它强制使用空缓存（NullCache），保证每个节点都从服务器重新拉取一次，避免缓存"掩盖"问题；
• 三探头监听：SDK 内部所有 HTTP 请求、错误日志、性能指标都会被"探针"截获并转成诊断事件；
• 结果可流式消费：检查结果以 AsyncGenerator 形式逐条产出，边体检边出结果，适合大文件量的账号。

简单说：当你怀疑云盘里的某个文件"数据不对"或 SDK 集成"行为异常"时，跑一次诊断就能拿到完整证据链。

二、诊断工具的三大探针机制

打开 diagnostic/index.ts 可以看到initDiagnostic工厂函数，它构造了三个关键组件：

这套组合拳的意义在于：诊断期间 SDK 的每一个异常动作都无处遁形，你不需要自己去猜问题出在哪一层。

三、快速上手：四步跑完一次完整诊断

1️⃣ 引入诊断模块

诊断工具通过子路径导出，源码入口见 diagnostic/index.ts：

import { initDiagnostic } from '@protontech/drive-sdk/diagnostic';

2️⃣ 初始化诊断实例

传入和你创建ProtonDriveClient相同的依赖（认证、HTTP 客户端等）即可：

const diagnostic = initDiagnostic(sdkDependencies);

官方 CLI 模块中的真实用法可以参考 cli/src/init.ts，它正是用同一份sdkDependencies初始化出sdkDiagnostic实例的。

3️⃣ 选择诊断入口

Diagnostic接口（定义见 diagnostic.ts）提供五个方法：

• verifyMyFiles()—— 体检整个 My Files 根目录（最常用）
• verifyNodeTree(node)—— 只体检指定文件夹/文件子树
• verifyPhotosTimeline()—— 体检 Photos 时间线（实现见 sdkDiagnosticPhotos.ts）
• getNodeTreeStructure(node)/getPhotosTimelineStructure()—— 只输出树结构快照，不做深度校验

4️⃣ 消费结果事件流

for await (const result of diagnostic.verifyMyFiles({ verifyContent: true })) { console.log(result.type, result); }

onProgress回调还会每 500ms 上报一次进度（loadedNodes/checkedNodes），方便你在终端或界面上显示体检进度条。

四、读懂体检报告：17 种诊断结果速查表

所有结果都定义在 interface.ts 中，按类型（type字段）可快速分流处理：

其中内容完整性校验是核心能力：诊断工具会把文件流式下载到内存中边读边算 SHA1（实现见 integrityVerificationStream.ts），再与服务端声明值比对，任何 1 字节差异都会被捕获。

五、三类典型疑难场景排查思路 🔍

场景 1：用户反馈"文件下载后打不开"

运行verifyMyFiles({ verifyContent: true })，重点盯两类事件：

• 出现content_integrity_error→ 内容真的坏了，附上claimedSha1与computedSha1提工单最有说服力；
• 只出现content_download_error→ 多为网络波动或服务端 5xx，重跑即可区分。

场景 2：个别文件在客户端"变灰/降级"

degraded_node事件会带上safeNodeDetails（节点 UID、作者、各字段错误列表），直接把这份信息交给开发者定位是哪个字段（密钥、名称还是内容）解密失败。

场景 3：自动化回归验证

通过expectedStructure（ExpectedTreeNode）声明"预期的目录树"：每个节点可指定name、expectedSha1、expectedSizeInBytes、expectedAuthors，工具会自动比对并输出expected_structure_missing_node/expected_structure_unexpected_node/expected_structure_integrity_error，非常适合 CI 中做数据一致性回归。

六、诊断选项调优：平衡速度与成本

DiagnosticOptions支持三个开关（sdkDiagnosticBase.ts）：

• verifyContent: 'peakOnly'🚀 —— 每个文件只读前 1KB（见 verifyContentPeak），快速验证"文件能不能下"，适合大账号首轮筛查；
• verifyContent: true—— 完整下载并校验 SHA1，最严格但流量最大；
• verifyThumbnails: true—— 额外验证缩略图服务是否正常。

建议策略：先'peakOnly'全量扫一遍定位可疑文件，再对可疑子树用verifyNodeTree(node, { verifyContent: true })做深度校验。

七、常见问题 FAQ 💬

Q：诊断会把我的文件内容上传到别处吗？A：不会。SHA1 是在本地边下载边计算（integrityVerificationStream.ts），诊断工具只做读取与校验，不修改任何云端数据。

Q：为什么诊断比正常操作"慢"？A：这是设计使然——它刻意清空实体缓存、强制逐节点真实访问（见 index.ts 注释），目的就是排除缓存干扰、复现真实问题。

Q：诊断和 C# / Swift 等其他语言 SDK 有关系吗？A：sdkDiagnostic属于 JS/TypeScript SDK（包名@protontech/drive-sdk）。其他语言 SDK 的遥测能力可参考 client/cs/ 与 incubating/client/swift/ 对应目录，但诊断工具目前以 JS 版为准。

八、小结

Proton Drive SDK 诊断工具把"猜问题"变成了"看证据"：一次遍历，签名、内容、缩略图、日志、HTTP 五类证据全部落袋。下次遇到云盘 SDK 疑难杂症，不妨先跑一轮verifyMyFiles，让数据自己开口说话。

📎 核心源码导航：诊断入口 diagnostic/index.ts ｜ 结果类型定义 diagnostic/interface.ts ｜ 校验主逻辑 sdkDiagnosticBase.ts