日志导出

2026/10/30大约 9 分钟

日志导出

功能简介

在访问日志页点击 导出日志，可以把 SQLite、MySQL 或 PostgreSQL 中的访问日志与安全事件，按指定时间范围导出为 JSONL、CSV 或加密 SQLite。导出在后台执行，任务进度、取消、删除和下载都在同一个弹窗里完成。

导出内容仅限 access_log 和 security_event 的结构化元数据，不包含 event_payload 中的请求/响应报文，也不包含旧版 web_logs。安全事件在页面详情里能查看报文，并不表示导出包会携带报文。两张表可能记录同一次请求，不应把两表行数相加当作独立请求数。

前置条件

使用已启用的 超级管理员（superAdmin） 后台账号登录。其他角色及 OpenAPI Key 不能创建、管理导出任务或申请下载票据；每个创建者只能查看和操作自己的任务。
实际运行目录的 conf/config.yml 中开启总开关，修改后重启 SamWaf：

export_download: true

开关关闭时仍可查看、取消或删除已有任务，但不能新建导出、申请票据或下载。导出入口保持可见，点击后会显示权限、接口可用性及开关状态；开关关闭时弹窗会提示开启方法。

操作步骤

1. 选择内容与范围

打开管理端 防护日志 → 访问日志（/waf/wafvisitlog），点击 导出日志。
选择 访问日志（access_log）、安全事件（security_event），默认两项全选，至少保留一项。
默认填入 最近4小时。可选 精确时间、按整天 或 全部现存日志。按整天只需选择起止日期，允许选同一天，包含两端日期的完整数据，按当前浏览器时区换算为开始日零点至结束日次日零点（不含）；例如10月29日至30日涵盖这两天。全部范围数据可能较大，建议先选较短时间。
选择格式，点击创建任务。

范围按日志时间计算，包含开始时刻、不包含结束时刻（开始 ≤ 日志时间 < 结束），精度为秒；全部模式也只导出截至创建任务时刻的数据。导出范围由弹窗设置，访问日志列表中的网站、IP、URL、当前页和归档下拉筛选不会自动成为导出条件。

2. 选择适合的格式

格式	建议用途	注意事项
JSONL（默认）	大量日志的逐行读取、脚本处理和数据分析管道	每行一个 JSON 对象；整数需按64位精度读取，避免转换为浮点数丢失精度。
CSV	电子表格筛选、汇总和人工分析	UTF-8 BOM及表头；每卷最多10万条或约128MiB，达到任一阈值分卷。空字符串与NULL均为空单元格；公式样式文本会加单引号，长标识和时间按文本处理。
加密 SQLite	需要保留表结构并进行离线 SQL 查询	包内为 `logs.encrypted.db`，需兼容的加密SQLite驱动和本实例日志库密钥才能打开；包内不提供密钥，普通SQLite工具不能直接打开。不是一键导入或还原备份。

JSONL 按约256MiB分卷，JSONL/CSV均按表分目录。字节阈值在记录边界切分，单条较大的记录可能使一卷超过该值。加密SQLite将所选两表放在一个数据库文件中，不按上述文本阈值分卷。

保存好导出文件

下载得到的是ZIP。JSONL/CSV数据在解压后为明文；加密SQLite仅数据库文件加密，清单和说明仍可读取。请按日志数据的权限要求存放与传递。

3. 查看任务与处理结果

任务列表显示创建时间、任务编号、表与格式、时间范围、状态、阶段、来源处理数、写入行数/字节数与过期时间。可点击任务编号或详情查看任务。

状态	含义与操作
queued / running / packaging	排队、读取或打包中；可以取消。关闭弹窗不影响后台执行。
cancelling / cancelled	正在取消或已取消；取消结束后可删除。
ready	导出完成，可以下载；0行导出也会生成有效文件与清单。
partial	部分来源读取失败；可下载已生成的数据，必须核对manifest中的失败来源，不能视为完整结果。
failed	任务失败，按错误说明检查来源、磁盘空间、预算或执行时限，处理后重新创建。
expired	文件过期，不能继续下载，需要重新导出。
deleted	文件已删除，任务记录可暂时保留。

任务完成后，管理端WebSocket会推送完成通知（LOG_EXPORT_READY），点击可定位到对应任务。通知未到达时也可以重新打开弹窗刷新列表查看实际状态。

对执行中的任务点击删除，可能先进入取消状态，待取消结束后再次删除；下载中的文件需等待传输结束再删除。取消和删除导出任务不会删除源日志。

4. 下载日志包

对 ready 或 partial 且未过期的任务点击下载，管理端先申请 60秒有效的一次性下载票据，再下载完整ZIP。票据绑定任务、账号与来源IP；链接不能作为长期分享地址。下载中断、链接过期或再次下载时，请在任务里重新点击下载。

不支持 Range 分段请求、断点续传或多线程下载。带Range的请求会返回 EXPORT_RANGE_UNSUPPORTED，应重新申请票据后整包下载。

产物默认保留 24小时，以任务显示的过期时间为准。到期后不可申请票据或下载，后台会回收文件；任务记录可能继续保留一段时间。删除或回收不会替代源日志自己的保留策略。

ZIP结构与完整性核对

JSONL示例（CSV将扩展名改为.csv，大数据可能有多卷）：

manifest.json
README.txt
access_log/part-000001.jsonl
security_event/part-000001.jsonl

SQLite包包含 manifest.json、README.txt 和 logs.encrypted.db。

清单提供版本、任务编号、格式、所选表、请求/实际时间范围、时区、来源驱动与状态、字段定义、各表计数，以及每个数据文件的 name、rows、bytes、sha256。manifest.json与README.txt本身不在数据文件校验列表中。

解压后可逐文件计算SHA256，与 manifest.json 的 files 数组对照。例如在提供sha256sum的终端中：

sha256sum "access_log/part-000001.jsonl"

得到的十六进制摘要应与该文件的 sha256 完全相同，文件字节数及数据行数也应匹配。CSV表头不计入行数，字段可能包含换行，不能只用文本换行数来统计CSV记录。清单中的 counts 按表提供读取、去重、冲突和实际写入数量。同表按 req_uuid 去重，先读取来源优先；两表之间仍可能有重叠。

来源快照与partial

每个来源使用只读快照，但多个来源的快照在不同时间建立，不是全局同一时刻的数据库备份。清单的 consistency 和 sources[].snapshot_time 记录这一口径。

来源读取失败时，部分成功的任务标记为 partial，清单会注明失败来源。历史表或字段缺失也可能体现在 sources 的状态和 missing_columns 中。分析前应检查这些信息；需要完整结果时，修复来源并重新导出。

资源预算

运维可在 conf/config.yml 的 log_export 下调整预算，修改后重启；无配置时使用默认值。无效或超出范围的配置会使用默认值。

配置项	默认值	允许范围
queue_limit	2个排队名额，另有1个执行中任务	0–10
timeout_minutes	30分钟	1–120
max_uncompressed_gib	10GiB未压缩输出预算	1–1024
temp_quota_gib	20GiB单任务临时文件预算	1–2048
min_free_gib	保留2GiB可用磁盘空间	1–1024
retention_hours	24小时产物保留期	1–168
sqlite_wal_max_gib	2GiB来源WAL压力上限	1–1024

数据较多时优先缩小时间范围，再评估磁盘空间与预算。排队已满会提示 EXPORT_BUSY；执行器重启导致任务中断时需要重新创建任务。

旧接口迁移与常见问题

原接口 GET /api/v1/waflog/attack/export 与 GET /api/v1/waflog/attack/download 返回 EXPORT_API_CHANGED 和迁移提示。请更新管理端；已有后台Token调用程序应按以下顺序迁移：

GET /api/v1/waflog/exports/capabilities 检查 allowed/enabled/formats。
POST /api/v1/waflog/exports，传唯一 request_id、format、tables和range_mode；自定义范围传带时区的RFC3339 start_time/end_time。
GET /api/v1/waflog/exports/:id 轮询到 ready 或 partial。
POST /api/v1/waflog/exports/:id/download-ticket 申请票据。
GET /api/v1/waflog/exports/:id/download?ticket=...&X-Request-Time=...&X-Request-Id=... 下载；Unix秒时间戳与随机请求标识放在查询串中，每次请求使用新的标识。

普通管理API使用X-Token与防重放请求头，返回结果还需检查业务 code，不能只看HTTP200；新下载路由凭短效票据访问。迁移不会开放OpenAPI Key导出权限。

为什么看不到按钮？ 检查是否超级管理员、前后端是否均已更新；关闭总闸时弹窗会提示配置方法。
导出0行是否失败？ 不是。核对时间范围、时区和已保存日志情况；空结果仍有表结构或空数据文件及清单。
为什么没有完整请求/响应？ 本功能严格限定两张元数据表，报文表与旧版日志表不在导出范围。
为什么下载链接失效？ 票据一次性、60秒有效且绑定来源IP；回到任务重新点击下载，不要复用旧URL。
哈希不匹配怎么办？ 重新下载并检查代理/传输链路；在通过校验前，不把文件用于完整性分析。

更新记录

日期	适用版本	说明
2026-10-29	v1.3.25-beta.9	统一三种日志库的后台导出、JSONL/CSV/加密SQLite、任务管理、短效下载票据与清单校验。