原始协议数据留存

按协议、服务或连接把采集到的原始数据保存到本地专用文件夹。默认关闭；与脱敏事件的本地 WAL、NDJSON 和 Dataway 输出独立。

文件格式与可见性

输入	文件	内容
network	.pcap	通过采集过滤、成功关联到已识别 TCP/UDP 连接的原始网络包，保留捕获时间和链路类型
endpoint	.stream	被分析器接受的明文 Protobuf 帧，保留方向、偏移、时间和进程归因；可用于 stream 回放
两者	对应的 .json	OPEN 身份、连接、协议、服务、段序号、事件 ID、完整性和关闭状态

网络上的 TLS/QUIC 包仍是密文。端点文件是应用侧明文流，不是原始加密网络包，也不伪造成 PCAP。两种来源可以同时保存；capture.application_source 继续决定哪个来源参与应用规则，留存不会增加重复的应用观察。

只保存已识别协议；无法识别、过滤前丢失或无效的数据不会成为完整档案。TCP 识别前的前缀缓冲最多 5 秒且受字节配额限制，单独的尾部 ACK 可能处于连接生命周期之外。端点保留的是探针与适配器实际交付的数据，不承诺恢复采集之前的丢失。

启用本地文件夹

把下列片段合并到主配置，协议必须已安装：

{
  "recording": {
    "enabled": true,
    "directory": "/var/lib/netflowscout/captures",
    "mode": "continuous",
    "sources": ["network", "endpoint"],
    "protocols": ["http", "mysql", "postgresql", "redis"],
    "services": ["billing"],
    "max_file_bytes": 16777216,
    "max_total_bytes": 268435456,
    "max_files": 256,
    "buffer_bytes": 33554432,
    "max_flows": 512
  }
}

directory 相对配置文件解析。分析器创建 0700 目录和 0600 文件；已有目录必须归运行用户所有且没有组/其他用户权限。目录只能存放本功能管理的文件，禁止符号链接和多个分析器共用；不要指定已有业务文件夹。安装包默认可写 /var/lib/netflowscout，其他路径需要为 analyzer 的 systemd 单元增加 ReadWritePaths，并确保运行用户可写。

sources 默认为两种来源；protocols 必填，["*"] 表示所有已识别协议。services、connection_ids 为空表示不限，非空按完整值匹配。dns 同时选择 UDP 和 TCP DNS。留存配置变更需要重启主服务与分析器；TUI 可使用 recording 表单或 JSON 草稿、校验和协调激活。

netflowscout check --config /etc/netflowscout/netflowscout.json
sudo systemctl restart netflowscout.service

完整源码示例见 examples/recording.json；它使用示例服务，默认不开启网卡抓包，需要按实际输入配置接口或端点。

由检测事件触发

例如仅在访问指定 URL 后保存连接前后文：

rule "export_request" do
  on "http.transaction"
  when http.path == "/admin/export"
  emit "http.export" do
    severity = "warning"
    message = "Export requested"
  end
end

将 recording 中的模式改为：

{"mode":"event","event_names":["http.export"],"pre_seconds":10,"post_seconds":20}

此片段合并到 recording，其余选择器和容量配置仍需保留。前后秒数均为 0..300，默认 0；按分析器接收/触发的本机时间计算。事件触发仅用于在线 run + analyze；analyze --pcap 配置 event 模式会拒绝启动。先在有界内存中保留前文，匹配事件提交 WAL 后通知分析器，把当前可用前文写出，并继续保存后文；连接关闭会提前结束。事件提交时连接已经关闭，仍可在保留期内关联并写出。重复触发延长现有连接的后置截止时间，不订阅未来新连接。即使可用前文为空，仍会对尚存活的匹配连接启用后置采集；已经丢失的前文会标记不完整。

逐记录事件携带 connection_id。窗口规则若按连接分组则精确关联；否则必须按 service 分组，才能关联到该服务当前保留的已选连接。未按服务或连接分组的窗口事件不会触发留存，计入 recording_trigger_unscoped_total。前文不足、后置窗口先于连接结束或存储失败会标记 incomplete；事件触发不能保证完整 TCP 握手或应用事务上下文。

continuous 模式下也会把已提交事件关联到文件索引；event_names 为空关联所有事件，非空只关联这些名称。每段最多保留 32 个不同事件 ID，超限标记 event_index_limit。

轮转、配额与故障

每连接按记录边界轮转，不切开单个包或帧。max_file_bytes 默认 16 MiB、范围 1 MiB..1 GiB；max_total_bytes 默认 256 MiB，至少为单段上限加 32 KiB，最大 1 TiB。每段预留 32 KiB 索引预算，总预算包含数据和预留；max_files 默认 256、最多 4096，按数据段计数。

超限只回收最旧的未保护已关闭段和对应索引；活动段或受保护段占满时丢弃新留存数据并计数，不阻塞抓包。单条记录放不进段也会丢弃并标记。异步输入队列和前文环各受 buffer_bytes 限制，默认各 32 MiB；max_flows 默认 512。网络分片原包关联另有 4 MiB / 1024 组缓冲。最多保留 32 个打开的数据文件，复用有界写入缓冲及一份 PCAP 暂存缓冲；缓冲复用可能增加空闲常驻内存。这些并不是整个分析进程的 RSS 上限。

原始留存是尽力而为，不继承事件 WAL 的至少一次保证。每秒仅刷新并同步发生变化的数据与索引，封段时立即同步。已关闭段的新增事件关联也由周期刷新或正常关闭保存；空闲段不反复写盘。管理性停止或输入断开而没有连接结束通知时标记不完整；崩溃尾部可能不完整。重启只盘点旧文件，不追加旧段，closed:false 表示未正常封段。触发通知使用有界本地 socket 队列，失败或关闭时可能丢失；事件本身仍遵循 WAL 投递契约。

netflowscout status --component analyzer --config ... 的 recording 包含目录、活动状态、内存/磁盘记账及计数。分析指标包括 collector_recording_queue_drops、collector_recording_buffer_drops、collector_recording_storage_drops、collector_recording_write_errors、collector_recording_files_evicted；主服务报告 recording_trigger_failures_total 和 recording_trigger_drops_total。不要仅凭文件存在判定采集完整。

retention_hours 为已关闭段的最大年龄（小时），0 禁用按时间删除；event_retention_hours 为关联事件之后的自动保护时长，0 禁用自动保护，均为 0..8760。每分钟及启动时执行过期回收。保护同时阻止年龄和容量回收，但不放宽硬配额；已封段的早期轮转段仍可能独立到期，查询会标记缺段。手动 pin 持续大于 0、最多 8760h，作用于整个采集标识（含其他片段和未来轮转）；unpin 不取消事件自动保护。过期、保护标记错误分别计入 files_expired、retention_errors。保留期按本机墙钟计算。

可在生成配置时显式启用：

netflowscout configure --service billing --executable /opt/billing/server \
  --recording-dir /var/lib/netflowscout/captures --recording-protocols http,mysql \
  --recording-retention-hours 24 --recording-event-retention-hours 168

只有提供 --recording-dir 才开启。生成器默认仅留存所选服务和采集来源，模式为 continuous；event 模式须额外指定 --recording-mode event --recording-events EVENT_NAME，默认前后各 5 秒。目录的 systemd 写权限仍需满足前述要求。

查找与回放

数据文件使用 nfs-<采集标识>-000001.pcap 或 .stream，旁边是 .json 索引。版本 2 索引增加 episode、episode_start 和开始/结束时间：同一连接的不同事件捕获片段独立处理，轮转段只在同一片段内拼接。

netflowscout recording list --config ./netflowscout.json --event-id EVENT_ID
netflowscout recording export --config ./netflowscout.json --event-id EVENT_ID --out /private/new-evidence
netflowscout recording replay --config ./netflowscout.json --event-id EVENT_ID
netflowscout recording pin --config ./netflowscout.json --event-id EVENT_ID --for 168h
netflowscout recording unpin --config ./netflowscout.json --id CAPTURE_ID

也可按 --connection-id、--service、--protocol 或 --id CAPTURE_ID:EPISODE 筛选；--directory 可读取既有留存或导出目录，不要求当前开启留存。导出、回放和保护必须显式选择范围。查询只展示索引元数据，不展示请求/响应内容。

正在写入的未封段文件拒绝导出；活动连接须先结束或停止分析器。写入进程已停止时，崩溃遗留的未封段文件仍可导出，并标记 unclean_tail/incomplete，损坏尾部的回放可能失败。目标目录必须不存在、位于受管理目录之外，创建为 0700，文件为 0600；失败删除本次创建的不完整导出。保留原始分段和索引，manifest.json 记录 UID、时间、每个文件的 SHA256 与字节数。这些摘要用于完整性核对，不是发布者签名。原始字节不经过脱敏。

回放自动构造每个捕获片段的输入：stream 按序保留一个 OPEN，PCAP 重写一个文件头；缺前段、未封段、索引/大小不一致会明确报告。已有不完整标记会传给规则记录；重复 OPEN、格式损坏或链路类型变化拒绝拼接。每个片段独立运行正式解析器和规则，结果经过输出脱敏，scope=per_capture_isolated，不写事件 WAL、不投递。它不模拟多个连接共同组成的窗口。最多一次回放 128 个片段。

兼容版本 1 stream 时通过段首 OPEN 分离片段；无法恢复的旧 PCAP 事件片段边界按段保守隔离。配额已删除的原文不能恢复。

TUI 的 9 Recordings 可筛选、查看完整性并执行查询、回放、导出和保护；6 Events 对选中事件提供相同操作。导出与保护需要 --control、确认及可写控制审计。8 Config → recording 提供选择器、触发窗口、保留期和配额表单，沿用校验、差异、协调激活和恢复流程。

原始内容与访问权限

完整原始字节可能包含密码、Authorization、cookie、令牌、SQL 和个人数据；原始文件和索引不经过事件脱敏，privacy.raw_fields 不控制它们。事件仍按原有策略脱敏后才进入 WAL 和输出。只有明确需要原始取证的服务才开启留存，并按本地敏感数据管理目录和备份。原始文件不会发送到 Dataway，也不会放入诊断包。