jdrtronix/cups-hplip

cups-hplip

一个开箱即用的CUPS打印与扫描服务器，通过专有HP HPLIP插件提供完整的HP打印机支持，专为家庭实验室和小型办公场景设计。

核心功能

• 打印支持：Windows、macOS、Linux系统可通过IPP/IPPS协议打印
• 扫描支持：Windows通过NAPS2（eSCL协议，端口8090）扫描；Linux通过SANE网络协议（端口6566）扫描
• 预装HP专有插件：支持多数现代HP打印机的必备组件
• 自动检测扫描仪：打印机开机时通过主机udev规则自动识别
• 自动生成SSL证书：首次启动时生成自签名SSL证书
• 基于Debian 13 slim：轻量稳定的基础镜像

使用场景

• 家庭实验室的打印扫描集中管理
• 小型办公室的多设备共享打印扫描服务
• 需要HP打印机专有功能支持的场景

配置说明

快速开始

1. 创建配置目录

bash
mkdir -p /opt/cups/config /opt/cups/sane

2. docker-compose.yml配置

yaml
services:
  cups:
    image: jdrtronix/cups-hplip:latest
    container_name: cups
    restart: unless-stopped
    privileged: true
    network_mode: host
    volumes:
      - /opt/cups/config:/etc/cups
      - /opt/cups/sane:/etc/sane.d
    devices:
      - /dev/bus/usb:/dev/bus/usb

3. 启动服务

bash
docker compose up -d

CUPS web UI地址：http://<主机IP>:631

添加打印机

1. 打开CUPS web UI：http://<主机IP>:631
2. 进入「Administration」→「Add Printer」
3. 选择你的HP USB打印机并跟随引导完成配置

Windows打印设置（IPP协议）

1. 打开「设置」→「蓝牙和设备」→「打印机和扫描仪」→「添加设备」→「手动添加」
2. 选择「使用IP地址或主机名添加打印机」
3. 协议：IPP；地址：<主机IP>；端口：631；资源：/printers/<打印机名称>

Windows扫描设置（NAPS2）

1. 下载安装免费开源扫描工具NAPS2
2. 打开NAPS2 →「设备」→「添加设备」
3. 驱动：ESCL → 点击「手动IP」
4. IP/主机：<主机IP>；端口：8090；HTTPS：关闭 → 点击「连接」

打印机断电重启自动恢复

当打印机断电重启后，USB设备编号会变化，需通过主机udev规则自动重启容器：

1. 查找打印机USB产品ID：

bash
lsusb | grep -i hp
# 示例输出：ID 03f0:042a HP, Inc LaserJet M1132 MFP

2. 创建udev规则（替换042a为你的产品ID）：

bash
mkdir -p /etc/udev/rules.d
cat > /etc/udev/rules.d/99-hp-printer.rules << 'EOF'
ACTION=="add", SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="03f0", ATTR{idProduct}=="042a", RUN+="/usr/bin/docker restart cups"
EOF
udevadm control --reload-rules

允许网络扫描（SANE）

1. 编辑/opt/cups/sane/saned.conf添加你的子网：

text
10.9.8.0/24
localhost

2. 重启容器：docker restart cups

测试硬件

• HP LaserJet M1132 MFP
• 其他需要HPLIP插件的HP打印机（可参考HPLIP支持设备列表）

端口说明

源码地址

github.com/jdrtronix/cups-hplip