printer and driver setup

# Odoo 标签打印工作站配置手册（Windows 11 + Zebra ZD421）

本手册用于在一台**全新的、专门用于打印的 Windows 11 电脑**上，从零搭建 Odoo 标签自动打印环境。
按顺序做完第 1～6 步即可投入使用，全程约 30～40 分钟。

最后更新：2026-09-14

[【附件】setup-package.zip](/media/attachment/2026/09/setup-package.zip)
---

## 0. 这套系统是怎么工作的

Odoo 里点"打印"后，标签文件会被浏览器下载到本机的一个固定文件夹，两个常驻后台程序盯着这个文件夹，
自动把标签送到斑马打印机。整个过程不需要人点"打印"对话框，也不依赖打印机驱动的纸张/方向设置。

```
                    ┌──────────────────────────────────────────────┐
Odoo (网页)  ──下载──►   C:\OdooZPLPrint                            │
                    │                                              │
                    │  ① *.zpl / *.txt  ──► OdooZplAutoPrint.ps1 ──┼──► ZD421 打印
                    │     (产品/批号标签，Odoo 直接生成 ZPL)        │
                    │                                              │
                    │  ② Label-*.pdf    ──► ShipLabelTo4x6.py ──┐   │
                    │     (承运商运输标签，整页 PDF)            │   │
                    │                              裁剪成 4x6   │   │
                    │                              转成 ZPL ────┘   │
                    └──────────────────────────────────────────────┘
```

两条打印链路：

| 链路 | 来源 | 处理程序 | 说明 |
|---|---|---|---|
| ① 产品/批号标签 | Odoo 标签模板 `owen-zebra6×4in` 直接生成 ZPL | `OdooZplAutoPrint.ps1` | 原样送打印机，不做任何转换 |
| ② 运输标签 | EasyPost/FedEx/UPS 返回的 PDF | `ShipLabelTo4x6.py` → `OdooZplAutoPrint.ps1` | FedEx 返回的是 Letter 整页，先裁成 4x6 再转 ZPL |

**关键设计点**：标签是以 ZPL 原始指令直接送进打印机的（RAW 模式），完全绕开 Windows 打印驱动的
纸张大小、方向、缩放设置。所以驱动那边基本不用调，也不会出现"打印出来是竖的/被缩放了"的问题。

---

## 1. 准备清单

**硬件**

- Zebra ZD421，203 dpi（重要：手册里的所有参数都是按 203 dpi 写的）
- 4 x 6 英寸热敏标签纸（间隙纸/Gap，非连续纸）
- USB 数据线

**软件（都要装在这台打印电脑上）**

- Google Chrome
- Python 3.13（用于运输标签的 PDF 裁剪）
- Zebra ZDesigner 打印驱动（**ZPL 版本**，不是 EPL 版本）

**账号**

- 一个能登录 Odoo（`https://uat.mis.filmax.tech`，正式环境换成正式域名）且能看到库存模块的账号

**需要从旧电脑拷过来的文件**

`setup-package.zip`（随本手册一起提供）里的 6 个脚本文件。

---

## 2. 第一步：安装打印机驱动

1. 到 Zebra 官网下载 **ZDesigner Windows Driver**（zebra.com → Support → ZD421 → Drivers），
   或使用随机附带的 **Zebra Setup Utilities**。
2. 先装驱动，装到提示"连接打印机"时再插 USB 线并开机。
3. 选择型号时选 **ZD421 (203 dpi) — ZPL**。
4. 装完后打开"设置 → 蓝牙和其他设备 → 打印机和扫描仪"，确认打印机名称是：

```
   ZDesigner ZD421-203dpi ZPL
   ```

> ⚠️ **这个名字很重要**：后台脚本是按名字找打印机的。如果安装出来的名字不一样（比如多了
   > "(副本 1)"或者是 EPL 版本），有两个办法：把打印机重命名成上面这个名字，或者修改
   > `OdooZplAutoPrint.ps1` 第 3 行的 `$PrinterName` 改成实际名字。两者必须完全一致。

5. **校准纸张**：装好标签纸，长按打印机上的进纸键（FEED）直到指示灯闪烁后松开，打印机会自动走
   一两张空白标签完成间隙校准。或者用 Zebra Setup Utilities → "配置打印机质量" → 校准。
6. **驱动首选项**（可选，只影响用驱动打印 PDF 的场景，ZPL 打印不受影响）：
   打印机右键 → 打印首选项 → 标签尺寸设为 4.00 x 6.00 英寸，介质类型"热敏"，追踪模式"间隙/缺口"。

**验证驱动是否正常**：打开 Zebra Setup Utilities → 选中打印机 → "打开与打印机通讯"，粘贴下面这段
按回车，打印机应该打出一张写着 TEST 的标签：

```zpl
^XA
^FO50,50^A0N,60,60^FDTEST^FS
^XZ
```

打不出来就说明驱动/连线有问题，先解决这一步再往下走。

---

## 3. 第二步：安装 Python 和依赖库

1. 到 python.org 下载 **Python 3.13**（Windows installer 64-bit）。
2. 安装时勾选 **Add python.exe to PATH**，选"Customize installation"，把安装路径设为：

```
   C:\Python313
   ```

> 路径不一样也行，但要同步修改 `StartAutoPrint.ps1` 和 `SetupAutostart.ps1` 里的
   > `C:\Python313\pythonw.exe`。装在默认的用户目录下路径会很长，建议就用 `C:\Python313`。

3. 打开 PowerShell，安装三个库：

```powershell
   C:\Python313\python.exe -m pip install pypdfium2 pypdf pillow
   ```

4. 验证：

```powershell
   C:\Python313\python.exe -c "import pypdfium2, pypdf, PIL; print('OK')"
   ```

显示 `OK` 就算成功。

| 库 | 用途 |
|---|---|
| pypdfium2 | 把 PDF 页面渲染成图像（用于找出标签实际位置并生成打印点阵） |
| pypdf | 生成裁剪后的 4x6 PDF 存档 |
| pillow | 图像裁剪、旋转、转黑白 |

---

## 4. 第三步：部署脚本

1. 新建文件夹 `C:\OdooZPLPrint`（其余子文件夹程序会自动创建）。
2. 把 `setup-package.zip` 解压，**6 个文件全部**放进 `C:\OdooZPLPrint`：

| 文件 | 作用 | 是否需要改 |
|---|---|---|
| `OdooZplAutoPrint.ps1` | ZPL 打印监听：把文件夹里的 `*.zpl` / `*.txt` 用 RAW 模式送打印机，打完移到 `printed\` | 打印机名不一致时改第 3 行 |
| `ShipLabelTo4x6.py` | 运输标签裁剪：`Label-*.pdf` → 找出标签区域 → 裁成 4x6 → 转 ZPL | 一般不用改 |
| `StartAutoPrint.ps1` | 启动上面两个后台程序（已在运行的不重复启动） | Python 路径不一致时改 |
| `CheckAutoPrint.ps1` | 静默检查两个程序是否在运行，没运行时弹提示框 | 一般不用改 |
| `run-hidden.vbs` | 隐藏启动器，让上面的脚本运行时不弹黑色命令行窗口 | 不用改 |
| `SetupAutostart.ps1` | 一次性配置：开机自启 + 桌面快捷方式 + 状态检查计划任务 | Python 路径不一致时改 |

3. 解除文件的"网络来源"锁定（从网上/U 盘拷来的 ps1 可能被 Windows 拦截）：

```powershell
   Get-ChildItem C:\OdooZPLPrint -File | Unblock-File
   ```

### 需要确认的两个参数

```powershell
# OdooZplAutoPrint.ps1 第 2-3 行
param(
    [string]$WatchFolder = 'C:\OdooZPLPrint',
    [string]$PrinterName = 'ZDesigner ZD421-203dpi ZPL'   # ← 必须和实际打印机名一致
)
```

```python
# ShipLabelTo4x6.py 的设置区（一般不用动）
WATCH_DIR = r"C:\OdooZPLPrint"     # 监听文件夹
WATCH_PATTERNS = ["Label-*.pdf"]   # 认这个文件名的才当运输标签处理
DPI = 203                          # 打印机分辨率，换 300dpi 机型要改成 300
LABEL_W_IN, LABEL_H_IN = 4.0, 6.0  # 标签尺寸（英寸）
```

---

## 5. 第四步：设置 Chrome 下载目录

Odoo 的标签是通过浏览器下载到本机的，所以必须让 Chrome 把文件直接存到监听文件夹。

1. Chrome → 右上角三个点 → 设置 → 下载内容
2. **位置**改为 `C:\OdooZPLPrint`
3. **关闭**"下载前询问每个文件的保存位置"

> 这台电脑既然是专门用来打印的，就不要再用它下载别的文件了，否则各种文档会混进这个文件夹
> （不影响打印，程序只认 `.zpl` / `.txt` 和 `Label-*.pdf`，但文件夹会很乱）。

登录 Odoo 后建议把常用页面存成书签，并让 Chrome 记住登录状态。

---

## 6. 第五步：开机自启和状态提示

在 `C:\OdooZPLPrint` 里右键 `SetupAutostart.ps1` → "使用 PowerShell 运行"；
或者在 PowerShell 里执行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File C:\OdooZPLPrint\SetupAutostart.ps1
```

它会自动做三件事：

1. **开机自启**：在"启动"文件夹放两个快捷方式，登录 Windows 后两个后台程序静默启动（无窗口、无任务栏图标）。
2. **桌面快捷方式「启动标签打印」**：任何时候想手动启动/确认状态，双击它即可。
   已经在运行的不会重复启动，会提示"一切正常"。
3. **计划任务 `OdooLabelPrint Status Check`**：每 30 分钟静默检查一次。
   一切正常时什么都不做；发现程序没运行才弹提示框问"现在启动吗？"，点"是"立即启动，
   点"否"则 4 小时内不再提示。

配置完成后，**双击桌面「启动标签打印」图标**做第一次启动。

验证是否在运行：

```powershell
Get-CimInstance Win32_Process | Where-Object {
    $_.CommandLine -like '*OdooZplAutoPrint.ps1*' -or $_.CommandLine -like '*ShipLabelTo4x6.py*'
} | Select ProcessId, Name
```

应该看到两条：一个 `powershell.exe`（ZPL 打印监听）、一个 `pythonw.exe`（运输标签裁剪）。

---

## 7. 第六步：Odoo 端设置

> Odoo 服务器端的模板、按钮、动作**已经配置好了**，是所有电脑共用的，新电脑不需要重新配置。
> 只需要给这台电脑要使用的操作员账号设一个默认模板。

### 7.1 设置默认标签模板（每个账号设一次）

1. 打开 `https://uat.mis.filmax.tech/odoo/users`，点开要用的用户
2. **Preferences（偏好设置）**标签页 → **Custom Labels** 区域
3. **Default Template** 选 `owen-zebra6×4in`
4. 保存

不设的话，每次打印向导里都要手动把模板从 `Label 57x38 mm` 改成 `owen-zebra6×4in`。

### 7.2 服务器端已有的配置（仅供参考/排查用）

| 项目 | 内容 |
|---|---|
| 标签模板 | `owen-zebra6×4in`（模板 id 13），152 x 101 mm 横向，203 dpi，旋转 R |
| 纸张格式 | `Label: owen-box Zebra ZD421 4x6in Landscape`（id 37） |
| 标签内容 | 产品名称 / `PART NO.` = 产品内部参考(default_code) / `ROLL / SERIAL` = 批号 + Code128 条码 |
| 打印向导按钮 | 向导里的 **PDF** / **ZPL** 两个按钮（服务器动作 887 / 886），点 ZPL = 保存并立即下载打印 |
| 产品页批量打印 | 产品页 Print 菜单 → **Custom Roll Labels (In-Stock Lots)**（服务器动作 885），自动带出该产品所有在库批号 |
| 批号页打印 | 批号页 Print 菜单 → `Filmax Roll Label (ZPL)` 或自定义标签向导 |
| 保护机制 | 模板需要批号但某行没选批号时，点打印会拦截并提示，避免打出 ROLL/SERIAL 空白的标签 |

---

## 8. 日常使用流程

### 打产品/批号标签

1. Odoo 里进批号页面，或产品页 Print → **Custom Roll Labels (In-Stock Lots)**
2. 在打印向导的表格里勾选要打的行，确认 **Lot/Serial** 列有值
3. 点 **ZPL** 按钮 → 文件自动下载 → 2 秒内自动打印

### 打运输标签

1. 发货单上正常生成承运商标签（EasyPost）
2. 在发货单上下载 `Label-xxx.pdf`
3. 程序自动裁剪成 4x6 并打印，原始 PDF 和裁好的 4x6 PDF 存到 `shipping-labels\`

### 手动补打某个 PDF 运输标签

把 PDF 文件拖进 `C:\OdooZPLPrint\ship\` 文件夹，会自动裁剪打印（文件名不限）。

---

## 9. 文件夹结构

```
C:\OdooZPLPrint\
├─ OdooZplAutoPrint.ps1        ZPL 打印监听（常驻）
├─ ShipLabelTo4x6.py           运输标签裁剪（常驻）
├─ StartAutoPrint.ps1          手动/开机启动
├─ CheckAutoPrint.ps1          状态检查（计划任务每 30 分钟调用）
├─ run-hidden.vbs              隐藏启动器
├─ SetupAutostart.ps1          一次性配置脚本
├─ printed\                    打印成功的 ZPL 文件（按时间戳归档）
├─ shipping-labels\            运输标签存档（原始 PDF + 裁好的 4x6 PDF）
├─ ship\                       手动拖放区：放进来的 PDF 会被裁剪打印
├─ errors\                     日志和出错的文件
│   ├─ autoprint-errors.log    打印失败记录
│   ├─ shiplabel.log           运输标签裁剪记录
│   ├─ watchdog.log            启动/状态检查记录
│   └─ alert-snooze.txt        提示框"稍后处理"的到期时间
└─ _to_delete\                 清理时移走的旧文件，确认无用后可整个删掉
```

---

## 10. 故障排查

| 症状 | 原因 | 处理 |
|---|---|---|
| 点了 ZPL，文件下载了但不打印 | 后台程序没运行 | 双击桌面「启动标签打印」 |
| 文件一直停在 `C:\OdooZPLPrint` 根目录不动 | 同上 | 同上 |
| `errors\autoprint-errors.log` 里出现 `Cannot open printer` | 打印机名字对不上，或打印机离线 | 对比 `Get-Printer` 的实际名字和脚本第 3 行的 `$PrinterName`；检查 USB 和电源 |
| 打印出来是空白标签 / 走纸不停 | 纸张没校准 | 长按 FEED 键重新校准 |
| 打印内容偏移、被截断 | 标签纸不是 4x6，或打印机不是 203 dpi | 换纸；300 dpi 机型要改 `ShipLabelTo4x6.py` 里的 `DPI = 300` |
| 运输标签没被裁剪，还是整页 | 文件名不是 `Label-` 开头 | 把文件拖进 `ship\` 文件夹，或改 `WATCH_PATTERNS` |
| 运输标签裁剪报错 | 看 `errors\shiplabel.log`，出错的 PDF 会被移到 `errors\` | 按日志内容处理，多半是 PDF 损坏或没装 Python 库 |
| 弹出"标签打印助手没有运行"提示框 | 后台程序被关掉或崩溃 | 点"是"启动；频繁出现就看 `errors\` 下的日志 |
| 打印向导报 `Nothing to print` | 在向导页面按了 F5 刷新 | 不要刷新，退回批号/产品页重新进入打印向导 |
| ROLL/SERIAL 打出来是空的 | 向导某行没选批号 | 在 Lot/Serial 列选批号，或从批号页面/`Custom Roll Labels (In-Stock Lots)` 进入 |
| FedEx 运输标签源文件是整页 Letter | EasyPost/FedEx 接口返回的就是这个尺寸（服务端连接器未传 `label_size` 参数） | 本机的裁剪程序已自动处理；要从源头解决需要改 Odoo 的 `fmx_delivery_easypost_oca` 模块代码 |

### 查看日志

```powershell
Get-Content C:\OdooZPLPrint\errors\autoprint-errors.log -Tail 20   # 打印失败
Get-Content C:\OdooZPLPrint\errors\shiplabel.log -Tail 20          # 运输标签裁剪
Get-Content C:\OdooZPLPrint\errors\watchdog.log -Tail 20           # 启动/状态检查
```

### 手动重启后台程序

```powershell
# 停止
Get-CimInstance Win32_Process | Where-Object {
    $_.CommandLine -like '*OdooZplAutoPrint.ps1*' -or $_.CommandLine -like '*ShipLabelTo4x6.py*'
} | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }

# 启动（或直接双击桌面图标）
powershell -NoProfile -ExecutionPolicy Bypass -File C:\OdooZPLPrint\StartAutoPrint.ps1
```

### 单独测试运输标签裁剪（不打印）

```powershell
C:\Python313\python.exe C:\OdooZPLPrint\ShipLabelTo4x6.py --convert "C:\路径\某个标签.pdf"
```

会在同目录生成 `-4x6.pdf`、`-4x6.zpl`、`-4x6.png`（png 是打印效果预览，可以先看效果再决定要不要打）。

---

## 11. 日常维护

- `printed\`、`shipping-labels\`、`_to_delete\` 会一直累积，建议每季度清理一次（直接删文件即可，不影响程序）。
- 打印机换过、驱动重装过之后，务必确认打印机名字没变，否则打印会失败。
- Windows 更新或重装 Python 后，如果路径变了，记得同步修改 `StartAutoPrint.ps1` 和 `SetupAutostart.ps1`。
- 这套配置只在**登录 Windows 后**运行。如果这台电脑要无人值守长期开着，把 Windows 设成自动登录、
  并关闭休眠/睡眠。

---

## 附录 A：ZPL 常用测试指令

在 Zebra Setup Utilities 的"打开与打印机通讯"窗口里粘贴，可用于快速判断是打印机问题还是软件问题。

```zpl
; 打印一张测试标签
^XA^FO50,50^A0N,60,60^FDTEST^FS^XZ

; 打印机配置标签（会打出当前所有设置）
~WC

; 4x6 标签边框测试（确认纸张尺寸对不对，四边应该都在纸内）
^XA^PW812^LL1218^FO0,0^GB812,1218,4^FS^XZ
```

> 参数换算：203 dpi 下 1 英寸 = 203 点，所以 4 x 6 英寸 = 812 x 1218 点。

## 附录 B：本套系统的关键参数速查

| 项目 | 值 |
|---|---|
| 监听文件夹 | `C:\OdooZPLPrint` |
| 打印机名称 | `ZDesigner ZD421-203dpi ZPL` |
| 打印机端口 | USB001 |
| 打印分辨率 | 203 dpi |
| 标签尺寸 | 4 x 6 英寸 = 812 x 1218 点 |
| Python 路径 | `C:\Python313\python.exe` / `pythonw.exe` |
| Python 依赖 | pypdfium2、pypdf、pillow |
| 计划任务名 | `OdooLabelPrint Status Check`（每 30 分钟） |
| 桌面快捷方式 | 「启动标签打印」 |
| Odoo 标签模板 | `owen-zebra6×4in` |
| Odoo 地址 | `https://uat.mis.filmax.tech`（UAT 测试环境） |