事件通道不用公网
用钉钉 Stream 模式接收事件，服务端主动出站建长连接，不需要准备公网回调地址。
为什么单独做钉钉版
同样是聊天工具入口，钉钉的接入条件和飞书、企业微信不一样，不能照搬。
四项功能在一个服务里
扫码登录、打印通知与卡片释放、云打印、通讯录同步，一套服务、一份配置。
数据不出内网
人员、作业与日志都留在客户自己的服务器和内网，不上传到我们这边。
授权绑 server.uuid
离线 license 按功能位授权，绑定服务器 UUID，换机需要重新授权。
四项功能
都围绕一件事：让员工在钉钉里完成打印动作，不用再记一套账号。
钉钉扫码登录 MFD
复合机面板显示二维码，员工用钉钉确认后登录；服务把钉钉身份映射到 PaperCut 用户，作业跟着人走。
- 面板二维码
- 钉钉确认
- 映射 PaperCut 用户
打印通知 + 互动卡片释放
提交后推钉钉消息，卡片上直接释放或取消；只有任务所有者能操作，重复点击也只执行一次。
- 幂等
- 仅任务所有者
- 卡片内释放
钉钉云打印
把 PDF、图片或 Office 文件发给机器人，服务转成 PDF 后投进专用的 Hold 队列，到机刷卡再出纸。
- PDF / 图片 / Office
- 转 PDF
- 专用 Hold 队列
通讯录同步
从钉钉通讯录同步部门与人员；默认不删除本地账号，避免误删历史用量。
- 部门与人员
- 默认不删除
- 保留历史用量
架构上的三条链路
装之前先把这三条链路的网络确认掉，后面会省很多事。
事件通道
钉钉 Stream，服务端出站 443，不需要公网回调地址。
打印服务
本机调用 PaperCut XML-RPC 9191，读写作业与用户。
扫码登录
需要一个手机可达的 redirect_uri：公网 HTTPS、反向代理或 VPN 任选其一。
使用前提 钉钉版对公网的要求比传闻里低，但也不是完全没有。
网络
- 事件通道走 Stream 出站 443，不需要公网回调地址。
- 扫码登录需要一个手机可达的 redirect_uri：公网 HTTPS、反向代理或 VPN 都可以。纯内网、手机又连不进来时，扫码登录用不了，其他功能不受影响。
部署环境
- 与 PaperCut 同机或同网段；Windows Server 2019+ / Windows 10+。
- 运行时 Python 3.10+，单服务部署。
- 需要 PaperCut 开启 Web Services API。
授权与依赖
- 离线 license，按功能位授权。
- 云打印需要 LibreOffice，以及一条专用的 Hold 队列。
- 扫码登录与卡片释放在钉钉后台以互动卡片模板的形式维护，需要先建模板再填 ID。
部署与技术规格
常规项目的起点配置，实际按现场调整。
| 项目 | 要求 | 说明 |
|---|---|---|
| 网络位置 | 内网，与 PaperCut 同机或同网段 | 不要求服务器放在公网 |
| 操作系统 | Windows Server 2019+ / Windows 10+ | 不支持的系统需要先确认 |
| 运行时 | Python 3.10+ | 单服务部署 |
| 事件接入 | 钉钉 Stream 长连接（出站 443） | 无公网回调 |
| 扫码登录 | 手机可达的 redirect_uri | 公网 HTTPS / 反向代理 / VPN |
| 授权 | 离线 license，按功能位 | 绑定 server.uuid |
| PaperCut 依赖 | Web Services API | 读写作业与用户 |
| 云打印 | LibreOffice + 专用 Hold 队列 | Office 先转 PDF |
常见问题
真的不需要公网吗？
事件通道不需要：Stream 是服务端主动出站的长连接，不用开公网回调。但扫码登录需要一个手机可达的 redirect_uri，纯内网环境要用反向代理或 VPN 把它暴露出来。
为什么要建卡片模板？
互动卡片的按钮、文案和回调地址在钉钉后台以模板形式维护，服务里填模板 ID。不建模板，卡片发不出去。
支持哪些 PaperCut 版本？
需要开启 Web Services API 的 PaperCut MF；具体版本以联调结果为准，我们不做「全版本可用」的承诺。
能复用现有的钉钉应用吗？
同一个钉钉应用只能有一个 Stream 连接。生产和调试建议用两个应用分开，避免互相把连接顶掉。
云打印支持什么格式？
PDF、图片和 Office 文件。Office 会先由 LibreOffice 转成 PDF，再投进专用 Hold 队列。
授权怎么算？
离线 license，按功能位授权，绑定服务器 UUID。具体开通哪几项，按你实际需要的能力定。
先确认三条链路通不通
把网络结构、PaperCut 版本和钉钉应用情况发给我们，先确认 Stream、9191 和 redirect_uri 这三条能不能通。