RootFlow 打印程序安装与配置手册

版本：0.3.6 · 发布日期：2026-10-28

1. 选择安装包

程序是调用操作系统驱动的打印代理，不代替打印机厂商驱动。安装前先在操作系统中添加打印机，并确认系统测试页可以打印。Type-C 只是连接接口，不能据此判断设备是否可打印。

Windows、Linux 构建检查不等于已完成各型号真机验收；首次使用应打印一份实际面单核对方向、纸型及二维码。Mac 包采用临时签名，Windows 包未做商业代码签名。

2. Windows 安装

1. 安装打印机厂商提供的 Windows x64 驱动，在“打印机和扫描仪”中添加设备，完成系统测试打印。
2. 从 SumatraPDF 官方网站 安装 64 位 SumatraPDF。它是 Windows PDF 打印引擎，本安装包没有捆绑该第三方软件。
3. 运行安装程序，按提示安装到当前用户目录。可勾选“用户登录时自动启动”。无需为本程序申请管理员权限；驱动安装可能需要管理员权限。
4. 从桌面或开始菜单运行 RootFlow Print Agent，浏览器将打开本机控制台。
5. 若提示找不到 SumatraPDF，在控制台“配置”中将 PDF 引擎路径设置为真实存在的 SumatraPDF.exe 完整路径，例如 C:\Program Files\SumatraPDF\SumatraPDF.exe，保存后再试。

程序目录：%LOCALAPPDATA%\Programs\RootFlowPrintAgent。 数据目录：%LOCALAPPDATA%\RootFlowPrintAgent。

升级前暂停云任务领取，等待在途任务结束并退出旧程序，再运行新安装包。卸载保留数据目录，避免丢失设备身份与任务核对记录。

3. Mac 安装

1. 安装对应机型的 macOS 打印机驱动，在“系统设置 → 打印机与扫描仪”添加打印机并测试。
2. 打开 DMG，将 RootFlowPrintAgent 拖入 Applications，然后从“应用程序”启动。
3. 首次打开若被系统拦截，确认下载来源和 SHA-256 后，按系统“隐私与安全性”的提示允许该应用打开；不需要关闭系统安全功能。
4. 浏览器会打开本机控制台。关闭浏览器不等于停止后台代理。

数据目录：~/Library/Application Support/RootFlowPrintAgent。

如已有此前安装的登录启动服务，不要另开一套数据目录。新版启动器会复用使用相同 API Key 的本机服务；要切换到新版，请先结束在途任务、退出旧服务，再启动新版。安装 DMG 本身不会覆盖已有登录服务中的旧二进制文件。

需要用户登录后自启时，在“系统设置 → 通用 → 登录项”添加应用程序中的 RootFlowPrintAgent。无人登录时不保证运行。

4. Linux 安装

以 Debian 12 / Ubuntu 24.04 及更新的 amd64 系统为目标。ARM Linux、RPM 发行版、Ubuntu 22.04 不在本次安装包的验证范围内。

sudo apt update
sudo apt install ./rootflow-print-agent_0.3.6_amd64.deb

安装并启动系统 CUPS、配置打印机及厂商驱动，然后先确认 lpstat -e 能列出系统队列。桌面环境可从应用菜单启动 RootFlow Print Agent，也可运行：

rootflow-print-agent serve --open-ui

无需桌面时，不加 --open-ui：

rootflow-print-agent serve

可选的用户登录启动服务（先退出手动运行的代理）：

systemctl --user daemon-reload
systemctl --user enable --now rootflow-print-agent.service
systemctl --user status rootflow-print-agent.service

用户服务与桌面手动启动二选一，避免两个进程争用端口。数据默认保存在 ~/.local/share/RootFlowPrintAgent；设置 XDG_DATA_HOME 时保存在该目录的 RootFlowPrintAgent 子目录。不要用 sudo 启动代理，否则会使用 root 的另一套数据。

卸载：sudo apt remove rootflow-print-agent。用户服务移除前可运行 systemctl --user disable --now rootflow-print-agent.service。用户配置与记录保留。

5. 进入控制台并选择初始化方式

默认入口：http://127.0.0.1:18188/。在安装打印机的电脑上访问此地址。这里的 127.0.0.1 指当前电脑，每台工作电脑都要安装自己的代理。

自贴单用户初始化

适用于用户在自己的电脑上打印。

1. 打开“配置”，选择“自贴单用户初始化”。
2. 选择已在操作系统安装好的本机打印机，完成初始化。
3. 打开“打印监测”，设置纸型与方向，上传 PDF 测试。

此方式仅支持本机打印，不注册云端设备、不创建云队列、不连接嘉兴云服务；无需仓库、工位、打印机编号或配对码。

仓库端初始化

适用于嘉兴仓工作位置接收云打印任务。

完成初始化后，设备归属对应仓库集群并获得专属任务队列。代理通过 WebSocket 接收通知，再通过 HTTPS 领取任务和回传结果；不需要向公网开放本机 18188 端口。仓库网络应允许访问云服务 HTTPS/WSS 443 以及 PDF 文件存储域名。

关闭浏览器后代理仍可领取任务；电脑休眠、关机或代理退出会中断领取。已有设备升级保留绑定，不要反复初始化。初始化响应丢失时使用原参数和配对码重试。

初始化类型不是随时切换的开关。 已完成的类型和绑定不允许直接覆盖。更换用途或电脑前先联系管理员处理设备身份，勿删除 cloud.json 或数据库来强行重置。控制台当前使用本机管理会话，主系统统一登录不在此版本中提供。

6. 保存默认纸型和打印参数

在“打印监测”设置参数后，点击 保存为默认，无需上传文件也能保存。重启或刷新后继续使用，直到再次更改。仓库端已绑定设备的默认配置也会同步云端；同步失败应按页面提示处理。

当前嘉兴 KM-202MD 的用户指定参数为：宽 70 mm，高 50 mm，适应页面，不旋转，单面，1 份。这只是该工位实际配置，不是所有打印机的通用默认值。新安装的空白配置初始纸型为 60 × 40 mm，应按自己的纸张修改并保存。

• 宽度：横跨打印头方向；高度：走纸方向。
• 使用自定义宽高时，清空“纸型名称”；填写纸型名称后，它的优先级更高。
• PDF 内容已有正确方向时选“不旋转”；确实需要时才额外旋转 90/180/270 度。
• “适应页面”用于将完整 PDF 放入当前纸型；“原尺寸”保留原始大小，可能超出小尺寸标签。
• 宽度不能凭内容长度随意填为 200 mm。参数必须符合纸张与驱动可用范围。
• Windows 自定义纸型需先在系统/厂商驱动中创建，使用驱动支持的纸型名称；不要把 CUPS 的 Custom.70x50mm 当作通用 Windows 纸型名。

Mac 快麦驱动使用的毫米到点转换由程序完成，控制台仍填写毫米，不需要手动换算。

7. 本机与云端接入

本机打印：业务调用安装电脑的 http://127.0.0.1:18188，业务 API 使用该电脑数据目录 api-key.txt 的 Bearer Key。跨站网页需在控制台配置允许的网页来源。浏览器对 HTTPS 网页调用本机 HTTP 的限制因版本和策略而异，应在目标浏览器实际验证，不能假定所有网页都可以直接调用。

云打印：业务后端将 PDF 上传对象存储，再使用受授权的仓库业务凭据向 https://jiaxing.rootflow.cn/iot 对应队列提交请求；仓库代理领取任务完成打印。云端凭据只放业务后端，不放网页、安装包或公开文档。私有对象 URL 必须保证代理可下载，例如有效期覆盖排队和下载时间的签名 URL。业务不直接控制用户电脑的 USB。

完整接口、队列查询、任务提交、幂等和状态说明请参阅同一下载目录的《打印使用与嵌入接入说明》及示例资料包。不要将 submitted 解释为纸张已经实际打印完毕。

8. 状态核对与故障处理

导出日志前脱敏；数据目录 api-key.txt、cloud.json、数据库、凭据文件不要上传到公共存储或分享给其他用户。安装包应只从公开下载入口获取，使用同目录 SHA256SUMS 校验完整性。