企业官网建设流程全解析

HarmonyOS 应用实战 58：诊断导出别变成日志泄露，用脱敏报告替代原始 hilog

用户反馈“答案抽错了”“导入后题库少了两条”时，开发最容易说一句：把日志导出来看看。这个动作在团队内部很顺，但放到面向用户的应用里就不一样了。hilog里可能出现题库名称、问题正文、答案片段、文件路径、异常堆栈和调试开关，一旦原样打包给用户复制，诊断入口就会从排障工具变成隐私出口。

更稳的做法不是禁止诊断，而是把诊断导出做成一份业务白名单报告：只告诉开发者故障发生在哪个阶段、触发了哪个事件码、候选数量是多少、关联的是哪个安全标识；不导出正文、不导出原始日志、不导出 Preferences 全量内容。

本文解决四个问题：

1. 区分开发日志、运行账本和用户可发送报告。
2. 设计只包含安全字段的诊断事件模型。
3. 把脱敏和报告组装收在导出边界，而不是散在页面里。
4. 用敏感样本反向验证报告里没有用户正文。

先把故障链拆开：诊断不等于日志打包

在“答案之书”这类本地应用里，用户数据通常都在设备侧：题库、历史、收藏、备份文件都可能含有私人内容。故障排查需要线索，但线索不等于原文。真正要定位的问题通常只有这几个：是不是当前题库为空、抽取候选是否被过滤没了、导入是否被 schema 拦住、写入 Preferences 是否失败。

危险链路： 页面打印 questionText -> 开发为了省事导出 hilog -> 用户反馈附件含私人问题和答案 -> 故障排清楚了，但隐私边界已经失守 安全链路： 业务层记录 safeEvent -> 导出服务按白名单组装报告 -> 用户预览后复制 -> 开发只拿 stage、code、count、safeId 排查

这一步先确定责任边界。hilog适合开发阶段定位现场，运行账本适合沉淀可解释事件，用户导出的报告只能读安全账本。三者混在一起，后面再靠正则删除敏感字段，很难保证不漏。

事件模型只允许安全字段进入账本

诊断模型应该从类型层就限制输入。不要先定义一个大对象，再提醒调用方“不要传敏感字段”。更可靠的做法是让SafeDiagnosticEvent根本没有questionText、answerText、deckName这类字段。

typeDiagnosticStage='startup'|'draw'|'favorite'|'import'|'backup'|'diagnostics';typeDiagnosticCode=|'OK'|'EMPTY_DECK'|'INVALID_ROUTE'|'SCHEMA_MISMATCH'|'STORE_WRITE_FAILED'|'REPORT_REDACTED';interfaceSafeDiagnosticEvent{eventId:string;occurredAt:number;stage:DiagnosticStage;code:DiagnosticCode;deckRef?:string;itemCount?:number;appVersion:string;note?:string;}

这段代码的关键不是字段多少，而是字段性质。deckRef不是题库名，它应该来自系统生成的稳定 id 片段；itemCount只表达数量；note只写固定短语，不能拼接用户输入。这样模型本身就能挡住大部分误用。

写 hilog 时也要按公开字段组织

HarmonyOS 的hilog支持用格式占位标记公开或隐私参数。即使日志系统可以隐藏隐私参数，业务侧仍然不要把正文传进去后再指望日志显示层兜底。比较稳的策略是：日志只打事件码和计数，正文完全不进入日志调用。

importhilogfrom'@ohos.hilog';constDOMAIN=0x0001;constTAG='AnswerBook';classAnswerBookLog{staticdrawFinished(code:DiagnosticCode,candidateCount:number):void{hilog.info(DOMAIN,TAG,'drawFinished code=%{public}s count=%{public}d',code,candidateCount);}staticdrawRejected(code:DiagnosticCode):void{hilog.warn(DOMAIN,TAG,'drawRejected code=%{public}s',code);}}

这段日志能帮助判断抽取链路是否执行、候选数量是否异常，但它不关心“用户问了什么”。如果某次问题必须复现，也应该由用户手动描述，而不是应用自动把正文带出设备。

脱敏器不要处理正文，要处理系统生成的标识

很多团队会说“那我把问题正文 hash 一下再导出”。这听起来安全，实际不够稳：短文本、常见问题、固定答案都有被字典猜测的可能。诊断报告需要的是关联同一条业务对象，不需要还原内容，所以更推荐只处理系统生成的 id。

classSafeReference{staticfromStableId(id:string|undefined):string{if(!id||id.length<8){return'unknown';}return`${id.substring(0,4)}-${id.substring(id.length-4)}-${id.length}`;}staticrejectUserText(label:string,value:string|undefined):void{if(value&&value.trim().length>0){thrownewError(`${label}must not enter diagnostics report`);}}}

这里的设计意图是反直觉的：不要“安全地导出正文”，而是从流程上不接收正文。fromStableId只接受系统 id，rejectUserText用在测试或调试构造里，帮助团队尽早发现有人把正文传到了诊断边界。

运行账本由 Service 写入，页面只触发业务动作

页面层最容易拿到完整展示数据，因此也最容易误把展示字段写进诊断报告。更清晰的 owner 是DiagnosticsLedgerService：它提供几个窄入口，每个入口只接收必要参数。

classDiagnosticsLedgerService{privatereadonlyrepository:DiagnosticsRepository;constructor(repository:DiagnosticsRepository){this.repository=repository;}asyncrecordDrawResult(deckId:string,candidateCount:number,ok:boolean):Promise<void>{constevent:SafeDiagnosticEvent={eventId:`draw-${Date.now()}`,occurredAt:Date.now(),stage:'draw',code:ok?'OK':'EMPTY_DECK',deckRef:SafeReference.fromStableId(deckId),itemCount:candidateCount,appVersion:AppBuildInfo.versionName};awaitthis.repository.append(event);}asyncrecordImportBlocked(deckId:string,importedCount:number):Promise<void>{awaitthis.repository.append({eventId:`import-${Date.now()}`,occurredAt:Date.now(),stage:'import',code:'SCHEMA_MISMATCH',deckRef:SafeReference.fromStableId(deckId),itemCount:importedCount,appVersion:AppBuildInfo.versionName});}}

这段代码把“什么时候记一笔账”和“报告长什么样”分开了。抽取服务、导入服务只写安全事件；导出服务只读安全事件；页面没有机会把题目正文拼进报告字符串。

导出服务重新组装报告，而不是复制系统日志

用户报告应该是一份可读文本或 JSON，而不是hilog文件。报告头写清版本和时间，事件列表只保留白名单字段。为了便于客服沟通，可以给每个事件加一句固定解释，但解释也必须来自 code 映射表，不能拼接用户输入。

constCODE_MESSAGE:Record<DiagnosticCode,string>={OK:'流程完成',EMPTY_DECK:'当前题库没有可抽取条目',INVALID_ROUTE:'入口参数无效',SCHEMA_MISMATCH:'导入文件版本不兼容',STORE_WRITE_FAILED:'本地写入失败',REPORT_REDACTED:'报告已按白名单脱敏'};classDiagnosticsReportService{constructor(privatereadonlyrepository:DiagnosticsRepository){}asyncbuildReport():Promise<string>{constevents=awaitthis.repository.loadRecent(30);constlines:string[]=[`app=${AppBuildInfo.versionName}`,`createdAt=${Date.now()}`,'privacy=only safe diagnostic fields are exported',''];events.forEach((event:SafeDiagnosticEvent,index:number)=>{lines.push([`#${index+1}`,`stage=${event.stage}`,`code=${event.code}`,`message=${CODE_MESSAGE[event.code]}`,`deck=${event.deckRef??'-'}`,`count=${event.itemCount??0}`,`at=${event.occurredAt}`].join(' '));});returnlines.join('\n');}}

报告看起来没有原始日志“丰富”，但它更适合用户发送。开发者能看到阶段、错误码、计数和版本，足够决定下一步是查导入 schema、题库加载、路由参数还是本地写入。

设置页要让用户先预览，再复制

诊断导出不适合做成一个静默复制按钮。用户应该先看到将要发送的内容，确认里面没有私人问题和答案，再点复制。页面只负责展示报告和触发复制动作，真正的报告内容仍然由 Service 生成。

@Componentstruct DiagnosticsExportPanel{@StateprivatereportText:string='';@StateprivateloadError:string='';privatereportService:DiagnosticsReportService=newDiagnosticsReportService(newDiagnosticsRepository());aboutToAppear():void{this.reportService.buildReport().then((text:string)=>{this.reportText=text;}).catch(()=>{this.loadError='诊断报告生成失败，请稍后重试';});}build(){Column({space:12}){Text('诊断报告').fontSize(18).fontWeight(FontWeight.Medium)Text(this.loadError.length>0?this.loadError:this.reportText).fontSize(13).maxLines(12).textOverflow({overflow:TextOverflow.Ellipsis})Button('复制报告').enabled(this.reportText.length>0).onClick(()=>{DiagnosticsCopyService.copy(this.reportText);})}}}

这段 ArkUI 示例故意没有在页面里读取题库、历史或答案。设置页越克制，导出边界越清楚；后续即使换复制 API 或分享入口，也不会影响脱敏规则。

用敏感样本做反向验收

诊断能力最怕只在正常样本下点一次通过。真正要验证的是“敏感内容不会出现”。可以准备一套本地测试题库，题目里故意包含姓名、手机号、地址、长文本和私密答案，然后触发抽取失败、导入失败、收藏失败，再导出报告。

敏感样本： deckName=家庭决策 questionText=测试姓名-A phone_138****8000 周五是否要转账 answerText=不要把 bank_secret_keyword 告诉任何人 expected=报告里不出现 测试姓名-A、phone_138****8000、bank_secret_keyword、家庭决策

静态检查也可以很直接，不必复杂。导出样例落到release/diagnostics/safe_report.txt后，用关键词反查一次。

rg-n"测试姓名-A|phone_138\*\*\*\*8000|bank_secret_keyword|questionText|answerText|deckName"release/diagnostics

如果这条命令有命中，就不要解释“只是测试数据”。对用户可发送报告来说，测试数据泄露和真实数据泄露在工程性质上是同一个问题，都说明边界没有收住。

常见问题先按入口排查

诊断报告不是越详细越好，而是要让开发者能按入口继续查。下面这张表可以直接放进团队检查记录里。

落地时给诊断能力留一条交付记录

如果把这套方案改进到真实项目里，交付记录至少写四件事：本次新增了哪些安全事件码，哪些业务入口会写账本，导出报告保存在哪里，敏感样本扫描结果是什么。没有这些证据，只能说明代码片段看起来合理，不能说明诊断能力已经可交付。

本文提供的是一种诊断导出设计方式，不等于已经在某个真实 HAP 里完成真机验证。落地到项目时，还要结合实际包名、页面入口、复制/分享方式和发布流程补齐验证截图。

小结

诊断导出要服务排障，但不能复制原始hilog。把安全事件写进业务账本，把脱敏和报告组装收进DiagnosticsReportService，再用敏感样本反向扫描，就能同时保留排查线索和隐私边界。对用户来说，能预览、能理解、能安全发送；对开发者来说，能定位阶段、错误码和版本，不需要拿到用户正文。