打印代理安装与配置
1. 功能说明
EyPrint 打印代理是安装在工位电脑上的本地打印客户端。业务页面（如快速收货、扫描发货、复核验货）通过它直接调用工位的标签打印机，实现扫码后自动、静默打印标签，不需要浏览器弹窗或手动选择打印机。
新版打印代理同时支持两种模式：
| 模式 | 说明 |
|---|---|
| 本地打印代理 | 浏览器与本机/局域网内的打印代理直连（wss://127.0.0.1:18999），适用于网页和打印机在同一台电脑（或同一局域网）的工位 |
| 云打印 | 打印代理反向连接云端派单服务器，由服务端“云打印管理”统一配置和派单，适用于多网点远程集中打印 |
适用人员：仓库收货员、发货员、复核员等一线操作人员；云打印配置由管理员在服务端完成。
2. 使用前提
- 工位电脑为 Windows、macOS 或 Linux，且已连接打印机并安装好打印机驱动。
- 标签纸已装好，纸张规格与业务标签一致（如 135×200mm、100×150mm 电子面单）。
- 使用本地模式：业务页面所在电脑与打印代理在同一台电脑或同一局域网。
- 使用云打印：管理员已在服务端“云打印管理”完成配置，工位保持代理运行即可。
3. 软件下载与安装
3.1 下载
打开下载地址（如
https://print.renowtrade.com/download），按操作系统选择安装包：
- macOS：Intel 芯片选 x64 版；Apple 芯片（M 系列）选 ARM64 版。
- Windows：日常使用请选 Hidden（后台运行） 版；调试时可选手动运行版。
- Linux：选择对应平台的可执行文件。
截图来自旧版配置说明，安装入口以实际下载页面为准。
3.2 macOS 安装与启动
- 解压 APP 压缩包。
- 将 APP 移动到“应用程序”目录。
- 双击启动打印代理。
- 首次运行如果被系统拦截：
- 点击弹窗中的“完成/打开”；
- 打开“系统设置 → 隐私与安全性”，在下方提示处点击 “仍要打开”；
- 按提示输入开机指纹或密码，允许系统使用该 APP 并信任其证书。
- 启动成功后，屏幕右上角菜单栏（系统托盘）出现打印代理图标。
3.3 Windows 安装与启动
- 双击运行 Hidden（后台运行） 版 exe。
- 首次运行如果被 SmartScreen 拦截，点击 “更多信息 → 仍要运行”。
- 运行成功后，屏幕右下角系统托盘出现打印代理图标。
3.4 确认运行成功
- 系统托盘出现打印代理图标，鼠标悬停可查看版本号。
- 点击托盘图标，菜单中显示
Version: x.x.x和Running on port: 18999，说明代理已正常运行。
3.5 系统托盘功能说明
右键（或左键）点击系统托盘图标，菜单包含以下功能：
| 菜单项 | 功能说明 | 操作方式 |
|---|---|---|
Version: x.x.x |
显示当前打印客户端版本号 | 查看（静态） |
Running on port: 18999 |
显示本地服务及 WebSocket 连接监听的端口号 | 查看（静态） |
Download Latest Version |
打开更新与下载主页 https://print.renowtrade.com/download |
点击自动调用默认浏览器打开 |
Open Debug Panel |
打开高保真标签/指令在线调试面板 | 点击自动调用默认浏览器打开 |
| Local Network Info（子菜单） | 局域网连接配置 | 展开子菜单 |
└ WebSocket: wss://<本机局域网IP>:18999/ws |
复制安全的 WSS 长连接地址 | 点击一键复制 |
└ Trust Cert: https://<本机局域网IP>:18999/api/printers |
复制证书信任校验地址，用于浏览器信任自签根证书（CA） | 点击一键复制 |
└ Open Printer Settings Page |
打开该打印机的可视化高级参数配置与管理页面（/settings） |
点击自动调起浏览器 |
| Cloud Connect Info（子菜单） | 云端连接绑定信息 | 展开子菜单 |
└ Device ID: <设备ID> |
复制本机生成的物理设备唯一识别码，用于云端平台绑定企业账户 | 点击一键复制 |
└ Token: <令牌> |
复制连接云端系统的鉴权安全令牌 | 点击一键复制 |
Update Templates |
手动强制拉取并更新本地缓存的入库/出库面单等最新 JSON 渲染模板 | 点击执行更新 |
Quit |
安全退出：关闭后台 WebSocket 监听与打印聚合队列，释放内存并退出 | 点击退出 |
菜单中显示的本机局域网 IP 和端口以当前工位实际显示为准。
4. 首次使用：信任本地证书（本地模式必做）
业务页面通过 HTTPS 与本机打印代理通信时，浏览器会拦截未信任的本地证书。首次使用请先信任证书：
- 点击系统托盘图标，打开 Local Network Info 菜单。
- 点击 Trust Cert 一键复制证书信任地址（形如
https://<本机局域网IP>:18999/api/printers；同一台电脑上也可使用https://127.0.0.1:18999/api/printers）。 - 用浏览器打开该地址，按提示点击“继续访问/高级→继续前往”信任本地证书。
- 回到业务页面（如快速收货、扫描发货），刷新后即可检测到打印服务。
提示：托盘菜单会自动获取并显示本机局域网物理 IP；如果业务页面通过局域网访问其他电脑上的代理，信任地址以该代理电脑托盘显示的
Trust Cert为准。
5. 选择打印机与测试打印
- 确认打印机已开机并连接工位电脑，系统已安装对应驱动。
- 打开业务页面（如快速收货），在顶部打印机下拉框选择实际使用的打印机，并勾选“自动打印”。
- 打印一张测试标签，核对方向、内容、清晰度和纸张位置。
- 也可以在托盘菜单点击 Open Debug Panel，浏览器打开高保真标签/指令在线调试面板，选择打印机后发送测试指令或预览标签。
6. 打印机纸张参数设置
标签内容错位、超出或内容不全时，可在本地设置页面调整纸张参数：
- 点击托盘菜单 Open Printer Settings Page（或浏览器打开
https://127.0.0.1:18999/settings）。 - 选择打印机，设置：
- 方向（dmOrientation）：竖向（Portrait）或横向（Landscape）；
- 纸张宽度 / 纸张高度：单位为 0.1mm，例如 100mm 宽填
1000，150mm 高填1500。
- 保存后重新打印测试。
Windows 系统注意：Windows 不支持实时传递自定义纸张尺寸，需要先在“控制面板 → 打印机”中配置对应打印机的打印首选项（页面设置），配置好后再回到业务页面打印。
7. 云打印模式（配合服务端云打印管理）
云打印由管理员在服务端配置，一线员工只需保证代理正常运行：
- 管理员登录服务端，进入“工具模块 → 云打印管理”。
- 点击“新增”，选择打印平台，填写设备信息，点击“获取设备连接列表”。
- 选择工位对应的打印机，提交配置。
- 提交后在列表点击“刷新打印机状态”，确认代理在线，再点击“打印测试”验证。
- 工位员工日常使用：保持打印代理运行即可；需要提供设备信息时，点击托盘图标 → Cloud Connect Info，复制 Device ID 和 Token 给管理员。
8. 开机自启动
新版打印代理支持开机自动运行（v1.4.7 起）。如果重启电脑后代理没有自动启动：
- macOS：参考“系统设置 → 通用 → 登录项”或 LaunchAgents 配置（旧版配置说明有截图流程）。
- Windows：可将代理快捷方式放入“启动”文件夹，或使用任务计划程序设置开机启动。
9. 软件更新
- 点击托盘菜单 Download Latest
Version，浏览器自动打开下载主页（
https://print.renowtrade.com/download），下载对应系统的最新安装包。 - 先退出当前正在运行的旧版打印代理（托盘菜单 → Quit）。
- 运行新版本。
- 将鼠标移到托盘图标上确认版本号已更新。
10. 配置与日志位置
- macOS：
~/Library/Application Support/EyPrint - Windows：
C:\Users\<用户名>\AppData\Roaming\EyPrint
目录说明：
| 目录 | 内容 | 注意事项 |
|---|---|---|
configs |
代理配置（含设备 ID、Token、打印机参数） | 不要删除；删除后设备 ID/Token 会重新生成，云打印配置失效，需要重新配置 |
logs |
打印日志 | 打印异常时用于排查问题，保留即可 |
11. 常见问题
业务页面提示“未检测到打印服务”
- 确认打印代理已启动（系统托盘有图标）。
- 首次使用按第 4 节信任本地证书后刷新页面。
- 确认业务页面与本机/局域网代理端口一致（以托盘显示的端口为准）。
无法获取设备连接列表 / 打印测试失败
检查操作系统是否已正确安装打印机驱动，先用系统自带的“打印测试页”或其他软件打印验证，正常后再回到业务页面。
打印内容错位、超出、内容不全
按第 6 节在打印机设置页核对纸张宽度/高度；如果只是超出一点，可把纸张宽度调小 1~2mm 再试。
Windows 下纸张尺寸设置不生效
Windows 不支持实时传递自定义纸张尺寸，需要在“控制面板 → 打印机 → 打印首选项”中配置页面设置，再回到业务页面打印。
重启电脑后代理没有启动
按第 8 节开启开机自启动。
设备 ID / Token 为什么会变
设备 ID 和 Token 是代理首次运行时自动生成的，存放在 configs
目录。请勿删除该目录，删除后需要重新配置云打印。
更新后没有生效
先退出旧版代理，再运行新版，最后确认托盘显示的版本号。
云打印在线但打印失败
先确认打印机本身可以正常打印，再检查纸张设置和标签模板；仍失败时把托盘中的 Device ID 和打印日志提供给管理员排查。