最先知道的是用打印的人
队列不动、面板报错，等有人跑到机器前，已经过去一段时间。
服务器停在哪一步，通常没人说得清
打印系统出问题，最难的不是修，是发现和定位。
知道打不了，不知道为什么
是数据库、授权，还是某个服务断了？没有读数就只能凭经验猜。
同一个问题反复出现
没人记录从什么时候开始、间隔多久，也就没法提前处理。
三步工作
采集、判定、通知，各管一段，不互相耦合。
01
小助手采集
Windows 小助手以服务方式运行，通常装在 PaperCut 服务器上，每 5 分钟调用一次 PaperCut System Health 接口（HTTP 9191 / HTTPS 9192）。
02
判定与收敛
HTTP 500 记为故障；200 但 status=warning 记为警告；组件本身没启用则显示「未启用」，不算故障。连续 3 次异常才推送，同一项 30 分钟内不重复。
03
通知与恢复
告警落到企业微信、钉钉或飞书的群机器人；恢复正常也会推一条。不用的模块可以单独忽略。
11 项检查
全部来自 PaperCut 的 System Health 接口，一项对应一个组件。
| # | 检查项 | 接口字段 | 看什么 |
|---|---|---|---|
| 01 | 系统总体 | summary | 整体状态，先看这一项 |
| 02 | 数据库 | database | 数据库连通与状态 |
| 03 | 应用服务器（磁盘） | application_server | 应用服务器状态，含磁盘 |
| 04 | 授权 | license | 授权的有效期与状态 |
| 05 | 设备在线数 | devices | 当前在线的设备数量 |
| 06 | 打印机错误数 | printers | 处于错误状态的打印机数量 |
| 07 | 作业工单服务 | job_ticketing | 作业工单服务的状态 |
| 08 | 移动打印服务器 | mobility_print | 移动打印服务的状态 |
| 09 | 站点服务器 | site_servers | 多站点部署时的站点服务状态 |
| 10 | 打印提供程序 | print_providers | 打印提供程序的状态 |
| 11 | 网页打印服务器 | web_print | 网页打印服务的状态 |
组件未启用时显示「未启用」，不计为故障；也可以直接在后台忽略，不再参与告警。
告警策略
少打扰、不遗漏，靠的是三条规则加一个开关。
连续 3 次才推
单次抖动不打扰人，连续三轮异常才推送。
同项 30 分钟静默
同一项 30 分钟内不重复推送，避免刷屏。
恢复必通知
恢复正常也推一条，知道什么时候好回来的。
可对不用的模块忽略
例如没启用移动打印，就把这一项忽略，不参与告警。
告警落点
企业微信 / 钉钉 / 飞书群机器人；微信服务号认证后提供。
三个视图
同一份读数，按三种人看的方式呈现。
平台视图
看原始响应，排障时用；返回什么就看什么，不做二次解释。
经销商视图
站点卡片 + 今日错误 / 队列 / 页数趋势，多个客户一起看。
客户门户
只读视图，客户自己看状态，不用把 PaperCut 后台权限给出去。
另外两项
看板之外，还有两个容易漏的口子。
读数断流看门狗
设备超过 3 小时没有上报读数就提醒，避免抄表数据悄悄断流。
数据体检
13 项检查：重复建档、计数回退、口径漂移、未挂合同等，把账面上的问题先找出来。
使用前提 这几条是能力边界，写在前面比写在合同附件里好。
只做汇总级
- 不提供逐台打印机的明细。PaperCut 各版本的 XML-RPC 没有开放打印机枚举——24.1.9 实测 api.listPrinters 不存在，所以只能做到汇总级。
- 能看的是设备在线数、打印机错误数这类总数，不是某一台机器的状态。
版本范围
- 支持 PaperCut 20.0+。System Health 从 20.0 开始提供，更低的版本没有这个接口。
只读，不接管
- 只读取健康接口，不修改 PaperCut 配置，也不接管计费。
- 不做自动修复。看板负责发现和通知，处理仍然由人来做。
环境与端口
按这张表准备，一般一次就能接通。
| 项目 | 要求 | 说明 |
|---|---|---|
| 支持版本 | PaperCut MF 20.0+ | System Health 从 20.0 起提供 |
| 采集接口 | PaperCut System Health | HTTP 9191 / HTTPS 9192 |
| 采集周期 | 每 5 分钟一轮 | Windows 小助手（服务） |
| 小助手出站 | 443 到 app.printlink.cn | 主通道不通时回退 80 到 121.41.117.34 |
| 告警通道 | 企微 / 钉钉 / 飞书群机器人 | 微信服务号认证后提供 |
| 读取方式 | 只读 | 不改配置、不接管计费 |
准备清单
五件事，缺一件都接不通。
- PaperCut 20.0+，并在 Options → Advanced → System Health 里开启，生成 API Token。
- 防火墙放行 9191 / 9192。
- 安装小助手，通常装在 PaperCut 服务器上。
- 小助手出站 443 到 app.printlink.cn；主通道不通时回退 80 到 121.41.117.34。
- 告警落到企微 / 钉钉 / 飞书群机器人；微信服务号认证后提供。
常见问题
对 PaperCut 版本有什么要求？
20.0 及以上。System Health 从 20.0 开始提供，更低的版本没有这个接口，看板采集不到数据。
要不要改 PaperCut 配置？
除了在 Options → Advanced → System Health 里开启功能并生成 API Token，不需要改其他配置；看板本身只读。
会不会影响正常打印？
看板只调用健康接口，不在打印链路上；即使看板停掉，PaperCut 照常打印。
告警发到哪里？
企业微信、钉钉、飞书的群机器人；微信服务号需要认证后提供。
能不能只看某台打印机？
不能。只能到汇总级，看设备在线数、打印机错误数这类总数。PaperCut 各版本 XML-RPC 没开放打印机枚举，24.1.9 实测 api.listPrinters 不存在。
组件没启用会不会一直告警？
不会。未启用的组件显示「未启用」，不算故障，也可以直接忽略。
先确认版本，再决定怎么接
告诉我们 PaperCut 版本、服务器系统和能放行的端口，我们先判断能不能采到 11 项，再约一次看板演示。