PrintLink安全
谁能连接 PrintLink、能做什么、怎么随时收回授权；来源白名单、配对与权限的关系。
最后更新
PrintLink 的安全模型一句话：默认只接受本机连接；页面要打印必须由本机用户 批准；放开网络可达性需要在控制台显式确认，并且随时可以一键收回。
四层检查
一次网页调用要依次通过四层互不替代的检查：
| 层 | 检查什么 | 在哪管理 |
|---|---|---|
| 监听范围 | 服务在哪些地址上接受连接 | 控制台「设置」 |
| 来源白名单 | 哪些网段可以建立连接 | 控制台「安全与站点 → 网络访问」 |
| 配对授权 | 哪些页面被允许调用（用户在电脑上确认） | 控制台「安全与站点」 |
| 接口权限 | 这个页面具体能做什么 | 配对时授予，随时可收回 |
两条通道：来源地址与令牌
谁能访问由两条互相独立的通道决定，满足其一即可。这一点值得先记住：
┌─ 带令牌 ──────────────► 认令牌（不需要 IP 授权）
客户端连接 ─────────┤
└─ 不带令牌 ────────────► 看来源地址（白名单 / 待确认）| 传输 | 带令牌 | 不带令牌 |
|---|---|---|
WebSocket（/ws） | 放行，不需要 IP 授权 | 走来源地址规则 |
HTTP（/rpc） | 放行，不看来源地址 | 拒绝（PAIRING_REQUIRED） |
HTTP 上没有「不带令牌但来源可信」这条路：HTTP 没有连接，每个请求都是独立的， 把来源地址当成逐请求凭据，等于让同网段任何一台机器自动获得与「用户批准过的 程序」同等的调用能力。一句话：有令牌就不需要 IP 授权。
令牌由用户在控制台签发
令牌（plk_ 开头）是独立凭据：它自己就证明了身份，不绑定来源地址、
也不绑定页面地址。明文只在签发那一刻出现一次，PrintLink 只保存它的 SHA-256
哈希。请把令牌当作真正的凭据保管。
签发方式是在控制台「安全中心 → 令牌」里主动创建，而不是由客户端申请：
- 创建时勾选权限（能调什么）与传输（允许在 WS / HTTP 上用，至少一项）；
- 可选有效期与备注；
- 名称为必填——令牌不绑来源，名字是唯一能帮你认出「这把是给谁的」的东西；
- 签发后明文只显示一次，请立即复制并交给需要它的程序。
v1.0.10 起：客户端不再能自己申请到令牌
旧版本的 auth.pair 会在用户批准后把令牌回给申请方。现在它只触发来源地址
授权：WS 上被放行的地址本来就能用，因此会得到「你不需要令牌」的提示；HTTP
上则需要用户先在控制台签发一个。
理由是令牌可以被复制、被带到另一台机器上使用——这种凭据的签发权应当明确 落在人手里，而不是由「谁先连上来申请」决定。
来源（Origin）只是记录，不是门槛
页面的 Origin 是站点自己发出的请求头，非浏览器程序可以任意书写，用它做准入
既拦不住真正的攻击者，又容易把「同一个应用换了端口」「http 改成 https」误判成
越权。因此 Origin 继续被记录（任务的「来源」列、报表都读它），但既不决定
谁能访问，也不出现在令牌列表里。
控制台里能做什么
「安全中心」分两个标签页：
- IP 授权：哪个地址能连。清单外的远程来源进入待确认队列；批准时可顺手 勾选「仅此 IP / 本网段 / 更大一段」。本机回环恒定放行。
- 令牌：哪个程序能连。在这里创建令牌、查看已签发的令牌（名称、权限、 传输、有效期），并逐个撤销；HTTP 接入总开关也在这一页。
撤销是精确的
- 撤销令牌：立即断开持有该令牌的连接，其它令牌与 IP 授权不受影响。
- 拉黑来源：该地址的请求被直接拒绝，不再进入待确认队列。
需要断开某一个程序时用前者，不要用拉黑整个来源——那会连带影响同一台机器上 其它正常的程序。
监听范围
| 范围 | 含义 | 附加要求 |
|---|---|---|
| 仅本机（默认） | 只接受来自本机的连接 | 无 |
| 局域网 | 绑定显式选择的私网地址 | 地址必须从本机网卡里逐个确认 |
| 公网 | 绑定显式选择的公网可达地址 | 危险确认 + 强烈建议收窄来源白名单 |
- 端口、范围、绑定地址与来源白名单是同一个事务：任何一步失败都会完整回滚， 旧服务持续可用。
- 范围收紧（公网 → 局域网 → 仅本机）会立即断开不再被允许的远程连接。
- 不提供内置 TLS。公网范围意味着明文连接，请配合 VPN 或反向代理使用。 令牌不能替代 TLS。
来源白名单
监听范围放开后，可以配置来源 IP 规则（IPv4 / IPv6 均支持）：
- 拒绝优先：命中拒绝列表的来源直接断开，即使它也在允许列表里。
- 配置了允许列表后，未命中即拒绝。
- 过宽的规则需要额外的危险确认。
- 白名单只控制网络可达性，配对与权限仍然逐一生效。
- 审批局域网新站点时，可以直接勾选「仅此 IP / 本网段」把来源写进允许清单。
哪些连接被当作「本机」
浏览器连接一定带 Origin；PrintLink 自己的界面和同机自动化程序不带。
缺少 Origin 不是身份：
| 连接 | 来自 | 结果 |
|---|---|---|
无 Origin | 本机 | 可信本机会话，拥有全部权限 |
无 Origin | 局域网或公网 | 拒绝（REMOTE_NATIVE_CLIENT_DENIED），并记入审计 |
有 Origin | 任意 | 走浏览器规则：白名单 → 配对 → 权限 |
反向代理不要剥掉 Origin
在 PrintLink 前放同机反向代理时，代理必须原样转发 Origin：PrintLink 看到的对端
是回环地址，一旦 Origin 被剥掉，所有经代理的远程连接都会被误认为可信本机客户端。
远程服务暂时不能直连
没有 Origin 的远程连接一律被拒绝，这是刻意的：面向远程非浏览器客户端的
服务 / 设备令牌体系还没有。在那之前请用受控远程连接里
列出的替代做法。
审计与脱敏
- 授权、拒绝、配置变更、监听迁移都会写入审计记录（保留天数可配置）。
- 审计与诊断输出不包含文档内容、令牌明文或二进制素材——只有事件类型、 来源、时间与脱敏后的上下文。
- 扫描是高风险能力，权限不在默认授予范围内，且每次扫描都要在桌面端确认。
调试台不是可信管理界面
调试台运行你自己输入的代码，虽然跑在沙箱里，但它调用的是真实的本机服务。 站点管理、报表、诊断这些可信操作只在控制台（桌面端）提供。
给接入方的建议
- 只申请用得到的权限；打印和预览分开按需申请。
- 监听范围保持「仅本机」，除非确有跨机器打印需求；跨机器优先局域网 + 精确白名单
- 精确绑定地址，不要一上来就开放公网。
- 处理好「需要授权 / 等待授权 / 权限不足」这几种结构化错误码， 不要引导用户「把安全设置关掉」。
- 远程服务进程不要试图省略
Origin直连；用受控的网页接入或同机桥接进程。