OpenMed 事务化 Trace 脱敏恢复基于本地日志的崩溃安全原语实战指南【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmedopenmed.multimodal.trace_recovery为 OpenMed 的 trace 文件原地脱敏提供了一层本地、崩溃安全的边界当进程在产生脱敏输出之后、完成目标文件替换之前意外中断时它可以保证不丢结果、不留裸数据。读完本文你将掌握redact_trace_file与recover_trace_redaction的完整用法、事务阶段机、无值日志value-free journal设计与 fail-closed 恢复语义并能基于 OpenMed 仓库源码与测试理解其底层实现。为什么需要事务化 Trace 脱敏恢复OpenMed 的 trace 文件JSONL可能携带临床 NER 与 PII 识别过程中产生的敏感内容。常规脱敏流程是在内存中把新值算出来然后用新值替换源文件。问题在于计算完成与替换完成之间是一个脆弱的窗口——进程一旦在这两步之间停止磁盘上就会留下一个没有归属记录的 staging 文件而源文件仍保留原始敏感内容之后无法确定该删除哪个、该提交哪个。openmed.multimodal.trace_recovery实现位于 openmed/multimodal/trace_recovery.py通过目标文件旁的一本小日志 指纹校验 原子替换把这段窗口变成可恢复的短事务。它的设计要点如下全程本地、确定性处理恢复过程不调用任何网络服务日志journal只记录内容指纹与事务状态从不包含源文本、脱敏文本、路径或异常细节提交commit前会再次校验输入与输出指纹只有通过校验的 staging 产物才会被原子替换恢复recovery是幂等的重复调用不会重复执行脱敏器。快速上手一行 API 完成可恢复的原地脱敏从openmed.multimodal直接导入即可使用该模块已在 openmed/multimodal/init.py 中统一导出from openmed.multimodal import redact_trace_file def redact(text: str) - str: return text.replace(SYNTHETIC-PATIENT-771, [PATIENT]) result redact_trace_file(trace.jsonl, redact)redact_trace_file的完整签名与默认值对应源码 trace_recovery.pydef redact_trace_file( path: str | Path, redactor: TraceRedactor, # Callable[[str], str | bytes] *, journal_path: str | Path | None None, recovery: Literal[resume, rollback] resume, encoding: str utf-8, max_bytes: int DEFAULT_MAX_TRACE_BYTES, # 64 MiB max_recovery_attempts: int DEFAULT_MAX_RECOVERY_ATTEMPTS, # 3 phase_hook: TraceRecoveryHook | None None, ) - TraceRedactionResult关键参数说明参数默认值作用与约束path必填目标 trace 文件。必须是恰好一个硬链接的普通文件拒绝符号链接与硬链接输入见下文安全属性redactor必填接收源文本并返回str或 UTF-8bytes的脱敏函数其返回值会被校验编码合法性encodingjournal_path自动推导自定义日志路径不传时按目标路径指纹在同目录生成.openmed-trace-recovery-*.jsonrecoveryresume发现遗留事务时的处理策略resume用传入的redactor恢复提交rollback先回滚再开始新事务encodingutf-8目标文件的文本编码解码失败抛trace_encoding_invalidmax_bytes64 MiB目标/输出/日志读取的大小上限超过抛trace_size_limitmax_recovery_attempts3恢复尝试次数上限超过则日志进入blocked阶段并抛recovery_attempt_limitphase_hookNone每个持久化阶段转换后回调主要用于崩溃注入测试与运维检查点一次完整调用会在内存中计算输入与输出 SHA-256 指纹 → 把输出写入同目录 staging 产物.openmed-trace-stage-*.bin→ 指纹双校验通过后用os.replace原子替换源文件。源文件永远不会被复制进日志。事务阶段机prepared → staged → committing → committed源码中以TraceRecoveryPhase定义了六个阶段trace_recovery.pyTraceRecoveryPhase Literal[ prepared, # 已计算指纹并写入日志 staged, # staging 产物已写入并校验 committing, # 提交前最终双校验 committed, # 原子替换完成事务终结 rolled_back, # 已回滚事务终结 blocked, # 目标失配或尝试次数耗尽禁止恢复 ]正常路径下日志的推进顺序为prepared读取源文件、计算输入指纹、运行redactor、计算输出指纹日志写入phasepreparedstagedstaging 文件以O_CREAT | O_EXCL | O_NOFOLLOW创建并fsync落盘日志更新为phasestagedcommitting再次核对目标文件指纹仍等于日志中的输入指纹、staging 指纹仍等于输出指纹然后os.replace(staging, target) 目录fsync见 _commit_stagingcommitted替换后验证目标为单链接普通文件、文件身份一致、目标指纹等于输出指纹日志更新为phasecommitted事务终结。任何阶段被中断日志中都会留下可判定的状态进程可能停在staging 已存在但日志停留在 prepared/staged也可能停在替换已完成但日志停留在 committing。这正是恢复逻辑的依据。无值日志只记指纹不记内容日志是原子写入的 JSON体积有硬性上限MAX_JOURNAL_BYTES 8 KiB每个目标最多默认 3 次恢复尝试。日志记录的内容对应TraceRecoveryJournaltrace_recovery.pyschema_version当前为TRACE_RECOVERY_SCHEMA_VERSION 1target_fingerprint目标路径的不透明身份指纹对绝对路径字节做 SHA-256sha256:前缀 64 位十六进制input_fingerprint/output_fingerprint/staging_fingerprint输入、输出、staging 内容指纹phase当前事务阶段recovery_decision与recovery_attempts恢复决策与已尝试次数。日志不披露目标文件名默认日志名由目标路径指纹派生而来_resolve_journaltrace_recovery.py# 默认日志路径同目录 .openmed-trace-recovery-{target_fingerprint[7:]}.json # staging 产物路径同目录名字里同时携带目标指纹与输出指纹 .openmed-trace-stage-{target_fingerprint[7:]}-{output_fingerprint[7:]}.bin日志写入本身也是事务化的_write_journaltrace_recovery.py先通过tempfile.mkstemp在同目录创建临时文件前缀.openmed-trace-journal-...写入并fsync后os.replace到日志路径再fsync目录。读取日志时_load_journal会拒绝符号链接、非普通文件以及超过 8 KiB 的日志。恢复resume 与 rollback当进程中断留下一个已验证的 staging 产物时恢复可以不调用脱敏器直接完成提交from openmed.multimodal import recover_trace_redaction # 恢复并继续提交不重新运行 redactor直接用已校验的 staging 产物 recover_trace_redaction(trace.jsonl, decisionresume)如果希望保留原始文件、仅删除事务持有的 staging 产物recover_trace_redaction(trace.jsonl, decisionrollback)recover_trace_redaction的签名trace_recovery.pydef recover_trace_redaction( path: str | Path, *, journal_path: str | Path | None None, decision: Literal[resume, rollback] resume, max_bytes: int DEFAULT_MAX_TRACE_BYTES, max_recovery_attempts: int DEFAULT_MAX_RECOVERY_ATTEMPTS, phase_hook: TraceRecoveryHook | None None, ) - TraceRedactionResult恢复遵循以下幂等与 fail-closed语义对应_recover_transactiontrace_recovery.pyredact_trace_file发现遗留事务时会自动用传入的redactor恢复并直接返回一个已完成的TraceRedactionResult不会再次调用该redactor因此重复调用完全幂等测试test_trace_redaction_journal_is_value_free_and_deterministic验证了已提交事务再次调用时脱敏器调用次数为 0见 tests/unit/multimodal/test_trace_recovery.py恢复时若目标或 staging 指纹与日志不匹配则fail closed不替换目标、不触碰任何未知产物目标失配会把日志标记为blockedblocked的日志只有显式传入decisionrollback且目标当前指纹仍等于日志记录的输入指纹时才允许回滚清理自有 staging 并标记rolled_back若目标是失配导致的 block则始终保持 fail-closed抛recovery_blocked恢复尝试次数累计超过max_recovery_attempts时日志置为blocked并抛recovery_attempt_limit测试test_recovery_is_bounded_and_rejects_tampered_owned_artifact完整覆盖了篡改 → 拒绝 → 次数耗尽 → 显式回滚链路见 tests/unit/multimodal/test_trace_recovery.pystaging 缺失时如果调用方提供了redactor即走redact_trace_file会用redactor重新计算输出且校验新输出指纹必须等于日志中的输出指纹output_fingerprint_mismatch否则 block如果没有任何redactor即直接调用recover_trace_redaction则安全回滚而不是凭空生成输出——想重新计算输出应调用redact_trace_file回滚只删除事务自己持有的 staging 产物删除前会先校验其指纹与文件身份_remove_owned_staging篡改过的 staging 不会被删除测试test_rollback_rejects_tampered_staging_without_deleting_it。安全属性硬链接、符号链接与路径切换防护模块对目标文件施加了严格的形态约束_prepare_targettrace_recovery.py目标必须是普通文件否则抛target_not_regular目标不允许是符号链接symlink_target_unsupported目标必须恰好一个硬链接st_nlink 1。拒绝多链接输入的原因很关键若目标存在其他目录项别名原子替换其中一个目录项后未脱敏的原始文件仍可通过另一个名字访问等于脱敏失效测试test_hardlinked_target_is_rejected_without_leaving_raw_alias验证了拒绝后两个别名均保持原始内容tests/unit/multimodal/test_trace_recovery.py。此外读写全程使用O_NOFOLLOW并以lstat/fstat做打开前、打开后、读取后的文件快照比对_open_checked_regular_file系列能够拒绝 TOCTOU 式的符号链接切换攻击test_target_symlink_swap_is_rejected_before_external_content_is_read证明在打开瞬间把目标换成指向外部文件的符号链接时事务在读取任何外部内容之前就以target_read_failed失败且脱敏器从未被调用test_staging_symlink_swap_cannot_replace_target_with_external_file证明staging 被换成符号链接时恢复以owned_artifact_conflict/owned_artifact_unreadable失败目标与外部文件均不被触碰。错误处理只有稳定原因码没有敏感信息TraceRecoveryErrortrace_recovery.py是模块对外唯一的异常类型reason被刻意设计成短常量风格的稳定代码正则[a-z][a-z0-9_]{1,63}校验非法时兜底为recovery_failed异常消息形如trace recovery failed: reason绝不包含路径、输入文本、输出文本或底层 OS 错误信息因此可以安全地交给错误日志系统。主要稳定原因码速查reason触发场景no_recovery_staterecover_trace_redaction找不到日志journal_target_mismatch日志中的目标指纹与当前目标路径指纹不一致journal_invalid/journal_conflict/journal_too_large日志缺失字段、非普通文件/符号链接、超过 8 KiBtarget_missing/target_not_regular/hardlink_target_unsupported/symlink_target_unsupported目标形态校验失败trace_encoding_invalid/trace_size_limit编码解码失败 / 超过max_bytesredactor_failed/redactor_result_invalid脱敏函数抛异常 / 返回值编码不合法owned_artifact_conflict/owned_artifact_unreadablestaging 被篡改、缺失或文件形态异常target_changed提交或恢复前目标指纹与日志输入指纹不一致会 blockoutput_fingerprint_mismatch用 redactor 重算的输出与日志输出指纹不一致会 blockrecovery_attempt_limit恢复尝试次数超过上限会 blockrecovery_blocked日志处于blocked且不允许回滚commit_failed/output_verification_failedos.replace失败 / 替换后指纹或身份校验失败测试test_redactor_errors_are_safe_to_log与test_redactor_trace_recovery_errors_are_wrappedtests/unit/multimodal/test_trace_recovery.py证明即使脱敏器抛出包含敏感字符串的异常包括TraceRecoveryError本身对外暴露的reason恒为redactor_failed敏感内容不会泄漏到异常消息中。审计报告指纹与有界元数据TraceRedactionResult.to_audit_report()与TraceRecoveryJournal.to_audit_report()返回可序列化字典[trace_recovery.py](https://link.gitcode.com/i/933af84e596504d98c954fcda41a6c49#L126-L132, L201-L216)内容仅为type: trace_redaction_recovery与schema_versiontarget_fingerprint/input_fingerprint/output_fingerprintphase、recovery_decision、recovery_attemptsresumed是否由恢复完成、changed是否实际发生内容变化、output_size。这些报告永不包含源文本、脱敏文本、路径或异常细节可直接写入审计日志。测试test_trace_redaction_journal_is_value_free_and_deterministic专门断言了日志文本与审计报告中均不出现敏感原文。源码与测试的进一步阅读模块完整实现openmed/multimodal/trace_recovery.py1200 行涵盖阶段机、日志读写、staging 管理、TOCTOU 防护与全部校验公共导出openmed/multimodal/init.py同时导出redact_trace_in_place、transactional_trace_redact两个语义别名便于使用in place / transactional术语的既有调用方离线回归测试tests/unit/multimodal/test_trace_recovery.py使用phase_hook注入崩溃覆盖恢复幂等、回滚只删自有产物、篡改拒绝、硬链接/符号链接防护、错误包装等 11 个场景设计文档docs/privacy/trace-recovery.md。边界与最佳实践最后需要明确这是一个崩溃恢复原语不是合规认证也不是临床决策保证。使用时应遵循以下原则保持 redactor 本地化模块的恢复路径不调用任何网络服务redactor 也应在本地运行并确保其输出对 trace 的目标读者是安全的比如通过 OpenMed 的 NER/PII 管线产出替代值而非直接删除合理设置max_bytes默认 64 MiB 是上限日志 8 KiB 有界超大 trace 应拆批处理或调大上限前先评估内存占用善用phase_hook做检查点它既可用于测试中的崩溃注入也可在运维侧记录每个阶段转换帮助定位中断点恢复策略选择默认resume适合脱敏结果已产出、希望尽力完成提交的场景rollback适合保留原始文件、后续重跑的场景两者都幂等可放心重复调用异常统一按reason处理不要把TraceRecoveryError的消息直接拼进面向用户的提示消息本身只有稳定代码配合to_audit_report()记录指纹即可满足审计需要。【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/18 10:47:55 · 阅读 1.2k OpenMed 事务化 Trace 脱敏恢复：基于本地日志的崩溃安全原语实战指南
OpenMed 事务化 Trace 脱敏恢复基于本地日志的崩溃安全原语实战指南【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmedopenmed.multimodal.trace_recovery为 OpenMed 的 trace 文件原地脱敏提供了一层本地、崩溃安全的边界当进程在产生脱敏输出之后、完成目标文件替换之前意外中断时它可以保证不丢结果、不留裸数据。读完本文你将掌握redact_trace_file与recover_trace_redaction的完整用法、事务阶段机、无值日志value-free journal设计与 fail-closed 恢复语义并能基于 OpenMed 仓库源码与测试理解其底层实现。为什么需要事务化 Trace 脱敏恢复OpenMed 的 trace 文件JSONL可能携带临床 NER 与 PII 识别过程中产生的敏感内容。常规脱敏流程是在内存中把新值算出来然后用新值替换源文件。问题在于计算完成与替换完成之间是一个脆弱的窗口——进程一旦在这两步之间停止磁盘上就会留下一个没有归属记录的 staging 文件而源文件仍保留原始敏感内容之后无法确定该删除哪个、该提交哪个。openmed.multimodal.trace_recovery实现位于 openmed/multimodal/trace_recovery.py通过目标文件旁的一本小日志 指纹校验 原子替换把这段窗口变成可恢复的短事务。它的设计要点如下全程本地、确定性处理恢复过程不调用任何网络服务日志journal只记录内容指纹与事务状态从不包含源文本、脱敏文本、路径或异常细节提交commit前会再次校验输入与输出指纹只有通过校验的 staging 产物才会被原子替换恢复recovery是幂等的重复调用不会重复执行脱敏器。快速上手一行 API 完成可恢复的原地脱敏从openmed.multimodal直接导入即可使用该模块已在 openmed/multimodal/init.py 中统一导出from openmed.multimodal import redact_trace_file def redact(text: str) - str: return text.replace(SYNTHETIC-PATIENT-771, [PATIENT]) result redact_trace_file(trace.jsonl, redact)redact_trace_file的完整签名与默认值对应源码 trace_recovery.pydef redact_trace_file( path: str | Path, redactor: TraceRedactor, # Callable[[str], str | bytes] *, journal_path: str | Path | None None, recovery: Literal[resume, rollback] resume, encoding: str utf-8, max_bytes: int DEFAULT_MAX_TRACE_BYTES, # 64 MiB max_recovery_attempts: int DEFAULT_MAX_RECOVERY_ATTEMPTS, # 3 phase_hook: TraceRecoveryHook | None None, ) - TraceRedactionResult关键参数说明参数默认值作用与约束path必填目标 trace 文件。必须是恰好一个硬链接的普通文件拒绝符号链接与硬链接输入见下文安全属性redactor必填接收源文本并返回str或 UTF-8bytes的脱敏函数其返回值会被校验编码合法性encodingjournal_path自动推导自定义日志路径不传时按目标路径指纹在同目录生成.openmed-trace-recovery-*.jsonrecoveryresume发现遗留事务时的处理策略resume用传入的redactor恢复提交rollback先回滚再开始新事务encodingutf-8目标文件的文本编码解码失败抛trace_encoding_invalidmax_bytes64 MiB目标/输出/日志读取的大小上限超过抛trace_size_limitmax_recovery_attempts3恢复尝试次数上限超过则日志进入blocked阶段并抛recovery_attempt_limitphase_hookNone每个持久化阶段转换后回调主要用于崩溃注入测试与运维检查点一次完整调用会在内存中计算输入与输出 SHA-256 指纹 → 把输出写入同目录 staging 产物.openmed-trace-stage-*.bin→ 指纹双校验通过后用os.replace原子替换源文件。源文件永远不会被复制进日志。事务阶段机prepared → staged → committing → committed源码中以TraceRecoveryPhase定义了六个阶段trace_recovery.pyTraceRecoveryPhase Literal[ prepared, # 已计算指纹并写入日志 staged, # staging 产物已写入并校验 committing, # 提交前最终双校验 committed, # 原子替换完成事务终结 rolled_back, # 已回滚事务终结 blocked, # 目标失配或尝试次数耗尽禁止恢复 ]正常路径下日志的推进顺序为prepared读取源文件、计算输入指纹、运行redactor、计算输出指纹日志写入phasepreparedstagedstaging 文件以O_CREAT | O_EXCL | O_NOFOLLOW创建并fsync落盘日志更新为phasestagedcommitting再次核对目标文件指纹仍等于日志中的输入指纹、staging 指纹仍等于输出指纹然后os.replace(staging, target) 目录fsync见 _commit_stagingcommitted替换后验证目标为单链接普通文件、文件身份一致、目标指纹等于输出指纹日志更新为phasecommitted事务终结。任何阶段被中断日志中都会留下可判定的状态进程可能停在staging 已存在但日志停留在 prepared/staged也可能停在替换已完成但日志停留在 committing。这正是恢复逻辑的依据。无值日志只记指纹不记内容日志是原子写入的 JSON体积有硬性上限MAX_JOURNAL_BYTES 8 KiB每个目标最多默认 3 次恢复尝试。日志记录的内容对应TraceRecoveryJournaltrace_recovery.pyschema_version当前为TRACE_RECOVERY_SCHEMA_VERSION 1target_fingerprint目标路径的不透明身份指纹对绝对路径字节做 SHA-256sha256:前缀 64 位十六进制input_fingerprint/output_fingerprint/staging_fingerprint输入、输出、staging 内容指纹phase当前事务阶段recovery_decision与recovery_attempts恢复决策与已尝试次数。日志不披露目标文件名默认日志名由目标路径指纹派生而来_resolve_journaltrace_recovery.py# 默认日志路径同目录 .openmed-trace-recovery-{target_fingerprint[7:]}.json # staging 产物路径同目录名字里同时携带目标指纹与输出指纹 .openmed-trace-stage-{target_fingerprint[7:]}-{output_fingerprint[7:]}.bin日志写入本身也是事务化的_write_journaltrace_recovery.py先通过tempfile.mkstemp在同目录创建临时文件前缀.openmed-trace-journal-...写入并fsync后os.replace到日志路径再fsync目录。读取日志时_load_journal会拒绝符号链接、非普通文件以及超过 8 KiB 的日志。恢复resume 与 rollback当进程中断留下一个已验证的 staging 产物时恢复可以不调用脱敏器直接完成提交from openmed.multimodal import recover_trace_redaction # 恢复并继续提交不重新运行 redactor直接用已校验的 staging 产物 recover_trace_redaction(trace.jsonl, decisionresume)如果希望保留原始文件、仅删除事务持有的 staging 产物recover_trace_redaction(trace.jsonl, decisionrollback)recover_trace_redaction的签名trace_recovery.pydef recover_trace_redaction( path: str | Path, *, journal_path: str | Path | None None, decision: Literal[resume, rollback] resume, max_bytes: int DEFAULT_MAX_TRACE_BYTES, max_recovery_attempts: int DEFAULT_MAX_RECOVERY_ATTEMPTS, phase_hook: TraceRecoveryHook | None None, ) - TraceRedactionResult恢复遵循以下幂等与 fail-closed语义对应_recover_transactiontrace_recovery.pyredact_trace_file发现遗留事务时会自动用传入的redactor恢复并直接返回一个已完成的TraceRedactionResult不会再次调用该redactor因此重复调用完全幂等测试test_trace_redaction_journal_is_value_free_and_deterministic验证了已提交事务再次调用时脱敏器调用次数为 0见 tests/unit/multimodal/test_trace_recovery.py恢复时若目标或 staging 指纹与日志不匹配则fail closed不替换目标、不触碰任何未知产物目标失配会把日志标记为blockedblocked的日志只有显式传入decisionrollback且目标当前指纹仍等于日志记录的输入指纹时才允许回滚清理自有 staging 并标记rolled_back若目标是失配导致的 block则始终保持 fail-closed抛recovery_blocked恢复尝试次数累计超过max_recovery_attempts时日志置为blocked并抛recovery_attempt_limit测试test_recovery_is_bounded_and_rejects_tampered_owned_artifact完整覆盖了篡改 → 拒绝 → 次数耗尽 → 显式回滚链路见 tests/unit/multimodal/test_trace_recovery.pystaging 缺失时如果调用方提供了redactor即走redact_trace_file会用redactor重新计算输出且校验新输出指纹必须等于日志中的输出指纹output_fingerprint_mismatch否则 block如果没有任何redactor即直接调用recover_trace_redaction则安全回滚而不是凭空生成输出——想重新计算输出应调用redact_trace_file回滚只删除事务自己持有的 staging 产物删除前会先校验其指纹与文件身份_remove_owned_staging篡改过的 staging 不会被删除测试test_rollback_rejects_tampered_staging_without_deleting_it。安全属性硬链接、符号链接与路径切换防护模块对目标文件施加了严格的形态约束_prepare_targettrace_recovery.py目标必须是普通文件否则抛target_not_regular目标不允许是符号链接symlink_target_unsupported目标必须恰好一个硬链接st_nlink 1。拒绝多链接输入的原因很关键若目标存在其他目录项别名原子替换其中一个目录项后未脱敏的原始文件仍可通过另一个名字访问等于脱敏失效测试test_hardlinked_target_is_rejected_without_leaving_raw_alias验证了拒绝后两个别名均保持原始内容tests/unit/multimodal/test_trace_recovery.py。此外读写全程使用O_NOFOLLOW并以lstat/fstat做打开前、打开后、读取后的文件快照比对_open_checked_regular_file系列能够拒绝 TOCTOU 式的符号链接切换攻击test_target_symlink_swap_is_rejected_before_external_content_is_read证明在打开瞬间把目标换成指向外部文件的符号链接时事务在读取任何外部内容之前就以target_read_failed失败且脱敏器从未被调用test_staging_symlink_swap_cannot_replace_target_with_external_file证明staging 被换成符号链接时恢复以owned_artifact_conflict/owned_artifact_unreadable失败目标与外部文件均不被触碰。错误处理只有稳定原因码没有敏感信息TraceRecoveryErrortrace_recovery.py是模块对外唯一的异常类型reason被刻意设计成短常量风格的稳定代码正则[a-z][a-z0-9_]{1,63}校验非法时兜底为recovery_failed异常消息形如trace recovery failed: reason绝不包含路径、输入文本、输出文本或底层 OS 错误信息因此可以安全地交给错误日志系统。主要稳定原因码速查reason触发场景no_recovery_staterecover_trace_redaction找不到日志journal_target_mismatch日志中的目标指纹与当前目标路径指纹不一致journal_invalid/journal_conflict/journal_too_large日志缺失字段、非普通文件/符号链接、超过 8 KiBtarget_missing/target_not_regular/hardlink_target_unsupported/symlink_target_unsupported目标形态校验失败trace_encoding_invalid/trace_size_limit编码解码失败 / 超过max_bytesredactor_failed/redactor_result_invalid脱敏函数抛异常 / 返回值编码不合法owned_artifact_conflict/owned_artifact_unreadablestaging 被篡改、缺失或文件形态异常target_changed提交或恢复前目标指纹与日志输入指纹不一致会 blockoutput_fingerprint_mismatch用 redactor 重算的输出与日志输出指纹不一致会 blockrecovery_attempt_limit恢复尝试次数超过上限会 blockrecovery_blocked日志处于blocked且不允许回滚commit_failed/output_verification_failedos.replace失败 / 替换后指纹或身份校验失败测试test_redactor_errors_are_safe_to_log与test_redactor_trace_recovery_errors_are_wrappedtests/unit/multimodal/test_trace_recovery.py证明即使脱敏器抛出包含敏感字符串的异常包括TraceRecoveryError本身对外暴露的reason恒为redactor_failed敏感内容不会泄漏到异常消息中。审计报告指纹与有界元数据TraceRedactionResult.to_audit_report()与TraceRecoveryJournal.to_audit_report()返回可序列化字典[trace_recovery.py](https://link.gitcode.com/i/933af84e596504d98c954fcda41a6c49#L126-L132, L201-L216)内容仅为type: trace_redaction_recovery与schema_versiontarget_fingerprint/input_fingerprint/output_fingerprintphase、recovery_decision、recovery_attemptsresumed是否由恢复完成、changed是否实际发生内容变化、output_size。这些报告永不包含源文本、脱敏文本、路径或异常细节可直接写入审计日志。测试test_trace_redaction_journal_is_value_free_and_deterministic专门断言了日志文本与审计报告中均不出现敏感原文。源码与测试的进一步阅读模块完整实现openmed/multimodal/trace_recovery.py1200 行涵盖阶段机、日志读写、staging 管理、TOCTOU 防护与全部校验公共导出openmed/multimodal/init.py同时导出redact_trace_in_place、transactional_trace_redact两个语义别名便于使用in place / transactional术语的既有调用方离线回归测试tests/unit/multimodal/test_trace_recovery.py使用phase_hook注入崩溃覆盖恢复幂等、回滚只删自有产物、篡改拒绝、硬链接/符号链接防护、错误包装等 11 个场景设计文档docs/privacy/trace-recovery.md。边界与最佳实践最后需要明确这是一个崩溃恢复原语不是合规认证也不是临床决策保证。使用时应遵循以下原则保持 redactor 本地化模块的恢复路径不调用任何网络服务redactor 也应在本地运行并确保其输出对 trace 的目标读者是安全的比如通过 OpenMed 的 NER/PII 管线产出替代值而非直接删除合理设置max_bytes默认 64 MiB 是上限日志 8 KiB 有界超大 trace 应拆批处理或调大上限前先评估内存占用善用phase_hook做检查点它既可用于测试中的崩溃注入也可在运维侧记录每个阶段转换帮助定位中断点恢复策略选择默认resume适合脱敏结果已产出、希望尽力完成提交的场景rollback适合保留原始文件、后续重跑的场景两者都幂等可放心重复调用异常统一按reason处理不要把TraceRecoveryError的消息直接拼进面向用户的提示消息本身只有稳定代码配合to_audit_report()记录指纹即可满足审计需要。【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考