日志与日志包

诊断日志记什么、怎么控制占用，以及日志包里有什么、绝不包含什么、怎么导出和查看。

排查「预览打不开」「这台打印机总是失败」这类问题时，一个错误码往往不够用。日志包把定位一次故障需要的上下文打成一个 ZIP，由你手动保存后交给管理员或附在问题反馈里。

诊断日志记什么

PrintLink 在本机记录启动、预览、打印、扫描等阶段的运行情况，只留下脱敏后的元数据：参数怎么一步步定下来的、渲染与送打过程、打印机能力读取结果。

事件按四个领域分开存放，查一件事只需要看一个文件：

领域	记什么
打印	参数确定过程、渲染、预览、送打、任务状态
打印机	打印机发现、能力读取、耗材采集
扫描	扫描仪发现、扫描参数与执行过程
应用	服务自身：启动、监听、接口调用、安全、存储

分开的好处是互不淹没：一次大批量打印不会把几天前的耗材记录挤掉。

设置与占用

控制台「设置 → 诊断日志」：

设置项	默认	说明
记录诊断日志	开启	关闭后不再写日志文件；错误仍留在内存里，「错误与诊断」页照常可用
保留天数	7 天	可设 1–30 天，超期自动删除
占用上限	32 MiB	可设 16–128 MiB，写满后淘汰最旧日志

同一页还会显示当前日志的覆盖范围（最早到最新一条事件），按你设置的显示时区展示——导出之前就能确认包里是否包含出问题那个时间点。

也可以临时打开详细记录 15 分钟或 1 小时，到期自动恢复。「立即清理」会删掉本机日志（已导出的日志包不受影响）。

预览渲染自检

「预览渲染自检」用自带样张走一遍与真实预览相同的渲染路径，用来判断本机预览链路是否正常。只在你点击时运行，不读取你的任何文件。建议在导出日志包前先跑一次，结果会一并带上。

导出日志包

三个入口导出的是同一份文件：

「设置 → 诊断日志」的导出日志包；
「打印机健康」页的导出日志包；
界面本身出错时，兜底页面上的导出日志包。

点击后弹出系统保存对话框，文件名形如 printlink-logs-….zip，保存位置由你决定。 打印服务没启动时也能导出——端口被占、监听失败时恰恰最需要它。

包里有什么

文件	内容
`manifest.json`	清单：版本、生成时间、时区、事件覆盖范围与条数、各文件校验和
`system.json`	PrintLink 版本与构建、操作系统与版本、诊断存储状态
`devices.json`	打印机与扫描仪的设备信息（见下）
`summary.json`	脱敏后的配置摘要、任务概况、健康告警
`events/*.jsonl`	按领域分开的事件，一行一条，可直接用 `rg` / `jq` 查
`error-counts.json`	最近的错误码与事件计数
`self-tests/`	你刚跑过的自检结果（没跑则没有）

devices.json 是为「这台机器怎么了」准备的：

打印机：名称、驱动、连接方式、是否默认、当前状态与原因码，以及 逐个耗材来源的采集结论——「墨量读不出来」的答案通常就在这里；
扫描仪：型号、连接方式、支持进纸源、状态与原因码；
扫描执行时间线：最近几次扫描各自走到哪一步、每步多久、断在哪里。

时间按你设置的时区

包里所有给人看的时间（生成时间、事件覆盖范围、每条事件、甚至 ZIP 文件名）都按控制台「设置」里选的显示时区渲染，并带上偏移量，例如 2026-09-09T17:20:58.123+08:00。

理由很直接：你报障时说的是「下午 5 点 20 那次」，包里也应该是同一个钟点，而不是让人去心算 UTC。带偏移量则保证这串时间仍然是无歧义的时刻。

保持默认的「系统时区（自动）」用的就是本机时区。

绝不包含什么

打印文档、渲染成品、扫描图像等任何内容；
令牌等凭据；
图片、字体等二进制素材；
文件路径、设备地址，以及被允许连接的站点名单。

打印机名称会带上

日志包会带上本机打印机的名称与驱动名，方便对照「哪一台总是失败」。如果队列名里含场地、部门或人名，分享前请先知悉。设备的网络地址不会带上。

怎么打开

日志包是普通 ZIP：

资源管理器里双击，或：

Expand-Archive .\printlink-logs-….zip -DestinationPath .\bundle

解开后，查打印参数问题从 events/print.jsonl 开始，查耗材从 events/printer.jsonl 加 devices.json 开始。

不会自动上传

日志包只保存到你选定的位置。PrintLink 不会因为出错就在后台联网，也不会去请求任何上传地址。