数据处理、PII 与遥测

概览

本页说明核心引擎如何处理数据：它会读取哪些内容、在进程内存中保留哪些内容、写出哪些内容，会对审计包应用哪些确定性 PII 脱敏转换，以及可选遥测路径如何工作。

边界。 本页描述库的行为。部署层面的数据驻留（residency）——你的文档在哪个司法管辖区内处理、临时文件写到何处、输出保留多久，以及哪个遥测 backend（后端，如有）接收 span——这些都由集成者负责，并非库的责任。引擎提供 fail-closed（默认拒绝）的安全默认值与一组脱敏转换；它无法替你决定数据驻留或法律依据。

安装

composer require nextpdf/core:^3

PII 脱敏器与遥测拦截器是核心包的一部分；除非存在 OpenTelemetry SDK 且调用端已接入该拦截器，否则遥测路径处于停用状态。

概念总览

就 ISO/IEC 29100 的意义而言（iso_iec_29100#3.x56），引擎是你交付数据的处理者（processor）：它依集成者的指示对文档内容进行操作。它不会主动回传数据（phone home）、不会在你要求的输出之外保留内容，也不会将文档内容传送到任何由 NextPDF 运营的 endpoint（端点）。

有三个数据面需要关注：

文档 I/O。 输入从你提供的路径或 stream（流）读取；输出写入你提供的路径或 stream。中间缓冲区在渲染期间存在于进程内存中，并会在渲染完成时释放。
审计包。 启用审计后，引擎可发出一份诊断包。在序列化之前，该包会先经过确定性的 PII 脱敏器处理。
遥测。 可选的 OpenTelemetry 拦截器可以发出 span 与指标。除非已安装 SDK 且已构造该拦截器，否则它处于关闭状态；span 属性会经过属性清理器处理。

这一隐私处理方式遵循 GDPR 第 32 条的原则：假名化（pseudonymisation）与最小化是其中列举的防护措施。应用这些防护措施是控制者（controller）的责任（eu_gdpr#x50）。库提供脱敏机制。控制者决定法律依据、保留期限与数据驻留。

API 接口

本页不重复记录审计或遥测的 API（请见 /modules/core/audit/ 一节）。与信任相关的组件，是应用于审计包的默认 PII 清理器，以及 OpenTelemetry 拦截器的属性清理器；以下按效果而非函数签名来描述它们的行为。

代码示例——快速上手

默认行为是：除非你主动要求，否则没有任何内容会离开该进程。没有任何代码会启用网络输出；没有这类代码，正是默认状态：

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

// Input read from disk, output written to disk. No telemetry SDK loaded,
// so the telemetry path completes in sub-microsecond no-ops. No content
// is transmitted anywhere.
$doc = Document::open('input.pdf');
$doc->save('output.pdf');

代码示例——生产环境

生成审计包时，确定性的 PII 脱敏器会在序列化之前遮蔽常见类别。此转换是纯函数（无时钟、无随机性），因此对于给定输入，同一个包在字节级保持稳定：

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Audit\DefaultPiiSanitiser;

$scrubber = new DefaultPiiSanitiser();
// E-mail → [EMAIL], IPv4 → [IPV4], IPv6 → [IPV6], X.500 DN attributes
// beyond CN → keyword preserved, value [REDACTED]. Deterministic.
$safe = $scrubber->sanitise($rawAuditField);

边界案例与陷阱

脱敏器是尽力而为，并非保证。 DefaultPiiSanitiser 只遮蔽它能识别的类别（RFC 5321 电子邮件、IPv4/IPv6，以及数个 RFC 4514 DN 属性）。若自由文本字段中含有姓名，或含有这些模式无法匹配的标识符，则不会被遮蔽。请将它视为一道纵深防御层，而非一项免除操作者审查义务的合规控制。
临时文件是部署方的职责。 引擎采用安全的临时文件处理方式。你的 TMPDIR 位于何处，以及 TMPDIR 是否位于正确司法管辖区的加密存储上，都属于部署层面的决定。库无法强制执行数据驻留。
遥测是可选且经过清理的，但并非毫无风险。 接入后，OpenTelemetry 拦截器会让 span 属性经过一个强制执行零信任数据策略的属性清理器。你导出到哪个 backend（后端），以及它的保留期限与所在位置，完全由集成者选择。
法律依据并非库的决定。 处理某份特定文档是否合法、以及基于何种依据，是由控制者依 GDPR 与当地法律判定（eu_gdpr#x50）；库对此没有可见性。

性能

PII 脱敏器是一组无 I/O 的纯 regex 转换。遥测拦截器只会在构造时检查一次 SDK 是否存在，并缓存结果。未安装任何 SDK 时，每次遥测调用都在亚微秒时间内完成，因此保护隐私的默认设置（关闭遥测）同时也是零额外开销的默认设置。

安全注意事项

数据处理的边界规则，面向审查者重述如下：

没有隐蔽的数据外传。 引擎不会将任何文档内容传送到任何由 NextPDF 运营的端点。对外网络访问只会发生在已明确启用且限定 scheme 的资源抓取，以及已配置的 TSA/OCSP/CRL 端点上；每一项都受 SSRF 防护把关。
确定性、有界的脱敏。 审计包的 PII 转换是确定性的，并在序列化之前应用；它是符合 GDPR 第 32 条（eu_gdpr#x50）精神的最小化辅助，而非匿名化认证。
数据驻留是集成者的责任。 依 NIST Privacy Framework（隐私框架）（nist_privacy_framework_1_1#x9.x1.p3），盘点与映射数据的处理地点是一项组织层面的活动；库提供控制项，由集成者执行映射。
角色由外部决定。 部署究竟是控制者还是处理者、以及相应义务，是一项 ISO/IEC 29100 的角色判定（iso_iec_29100#3.x56），库无法替你作出。

符合性

这不是一份符合性配置文件。本页引用 GDPR 第 32 条、ISO/IEC 29100 与 NIST 隐私框架，用于界定库行为与控制者责任之间的边界；它并未主张符合 GDPR、符合 ISO/IEC 29100，或取得任何隐私认证。这些判定由数据控制者在部署层面作出，而非由库作出。