本地打印机AirPrint桥接Docker镜像

![Docker镜像大小]([] ![构建状态]([] ![许可证]([] ![DockerHub拉取量]([] ![DockerHub星标]([] ![GitHub星标]([] ![贡献者]([] ![]([] ![GitHub赞助]([***]

镜像概述

主要用途

运行集成CUPS和Avahi（mDNS/Bonjour）服务的容器，将网络中的本地打印机通过AirPrint协议暴露给iOS/macOS设备，实现无线打印功能。

核心功能与特性

• 多架构支持：定期自动构建，适配多种硬件架构
• CUPS与Avahi集成：内置CUPS打印服务和Avahi mDNS/Bonjour服务，无需额外配置
• 环境变量配置：通过环境变量灵活配置CUPS管理员账户、打印机参数等
• 多种打印机配置方式：支持通过环境变量、Web界面或配置文件添加打印机
• 可选Google Cloud Print支持：可配置集成Google Cloud Print服务
• 网络隔离：支持通过macvlan网络赋予容器独立IP，避免端口冲突

环境要求

• Linux主机：仅支持Linux主机运行（macOS因网络限制暂不支持，详见：docker/for-mac#3447）
• 独立IP地址：容器需分配独立IP，避免与主机或其他服务的CUPS/Avahi端口冲突（通常主机已运行CUPS和/或Avahi服务）
• CUPS驱动：需为打印机准备对应CUPS驱动（暂不支持将Windows共享打印机的驱动作为CUPS"代理"使用）

注意事项

• Windows共享打印机需允许***访问，或在设备URI中指定用户名密码（格式：smb://user:pass@host/printer）

使用方法

快速体验（仅Linux主机）

macOS不支持此功能（详见：Docker for Mac网络限制）

# 启动临时容器（含Web管理界面）
docker run -d --rm -e CUPS_WEBINTERFACE="yes" -e CUPS_REMOTE_ADMIN="yes" --hostname mycups --name cups-setup drpsychick/airprint-bridge

# 重要：仅当主机名/IP匹配时才能进行管理！（不支持端口转发等）
# 主机名不匹配时CUPS错误：`Request from "172.17.42.1" using invalid Host: field "localhost:6310"`
echo "CUPS管理地址：[***] inspect --format '{{ .NetworkSettings.Networks.bridge.IPAddress }}' cups-setup):631"
# -> 访问上述地址配置打印机

# 导出打印机配置文件（获取设备ID等关键信息）
docker cp cups-setup:/etc/cups/printers.conf ./

环境变量配置

重要：Docker环境变量仅支持单行且无双引号！

添加打印机

通过环境变量自动配置

设置以CUPS_LPADMIN_PRINTER为前缀的环境变量，容器启动时将自动执行lpadmin命令添加打印机：

# 示例1：添加IPP打印机
CUPS_LPADMIN_PRINTER1=lpadmin -p test -D '测试打印机' -m raw -v ipp://myhost/printer

# 示例2：添加"通用"类型打印机
CUPS_LPADMIN_PRINTER2=lpadmin -p second -D '另一台打印机' -m everywhere -v ipp://myhost/second

# 示例3：添加带驱动和选项的Samba打印机
CUPS_LPADMIN_PRINTER3=lpadmin -p third -D 'Samba打印机' -m '驱动字符串' -o PageSize=A4 -v smb://user:pass@host/printer

# 启用打印机
CUPS_LPADMIN_PRINTER3_ENABLE=cupsenable third

通过Web界面手动配置

1. 启用Web界面：设置环境变量CUPS_WEBINTERFACE="yes"和CUPS_REMOTE_ADMIN="yes"（建议仅临时启用）
2. 手动修改配置文件（如需持久化）：

   # cupsd.conf配置示例
   Listen *:631
   WebInterface Yes
   <Location />
     Order allow,deny
     Allow from all
   </Location>
   <Location /admin>
     Order allow,deny
     Allow from all
   </Location>
   

3. 访问管理界面：https://<容器IP>:631/admin或https://<容器主机名>:631，使用CUPS管理员账户登录配置

通过文件自动配置

1. 先通过Web界面或lpadmin命令配置并测试打印机
2. 导出配置文件：

   # 从容器复制配置文件
   docker cp cups-test:/etc/cups/printers.conf ~/mycups/
   docker cp cups-test:/etc/cups/ppd/PrinterName.ppd ~/mycups/
   

3. 构建自定义镜像：

   # ~/mycups/Dockerfile
   FROM drpsychick/airprint-bridge:latest
   COPY printers.conf /etc/cups/
   COPY PrinterName.ppd /etc/cups/ppd/
   

4. 使用自定义镜像创建容器：

   docker build -t mycups:latest ~/mycups/
   docker run -d --name my-airprint-bridge mycups:latest
   

配置AirPrint

无需额外配置，添加打印机后自动通过Avahi服务广播AirPrint协议，iOS/macOS设备可自动发现。

配置Google Cloud Print

默认禁用，需通过以下步骤配置（基于"快速体验"中创建的容器）：

1. 进入容器生成配置文件：

   docker exec -it cups-setup /bin/bash
   # 执行配置工具，按提示完成设置（生成gcp-cups-connector.config.json）
   (cd /etc/gcp-connector; gcp-connector-util init)
   

2. 设置以下环境变量启用服务：

   GCP_ENABLE_LOCAL="false"          # 是否启用本地GCP服务
   GCP_ENABLE_CLOUD="false"          # 是否启用云端GCP服务
   GCP_XMPP_JID="从配置文件获取"       # XMPP JID
   GCP_REFRESH_TOKEN="从配置文件获取"  # 刷新令牌
   GCP_PROXY_NAME="从配置文件获取"     # 代理名称
   

部署专用AirPrint桥接容器

Linux主机网络配置

为使容器在本地子网可见，需创建macvlan网络接口（主机需与容器通信时需要）：

eth=eth0                          # 物理网络接口
mac=AA:AA:AA:AA:AA                # 物理接口MAC地址
mac2=AA:AA:AA:AA:AB               # 容器虚拟MAC地址

# 启用混杂模式（支持多个MAC地址）
sudo ifconfig $eth promisc

# 创建macvlan接口
sudo ip link add mac0 link $eth address $mac type macvlan mode bridge

# 刷新网络配置
sudo -- bash -c '(
dhclient -r $eth && ip addr flush dev $eth && ip neigh flush all
dhclient mac0 && service resolvconf restart || dhclient $eth
)'

创建Docker网络与容器

1. 创建macvlan网络（替换为实际子网和网关）：

   # 若无需主机与容器通信，parent可直接使用物理接口（如eth0）
   docker network create --driver macvlan --subnet 192.168.2.0/24 --gateway 192.168.2.1 -o parent=mac0 localnet
   

2. 创建并启动容器：

   cups_ip=192.168.2.100             # 容器IP
   cups_name=cups.home               # 容器主机名
   
   docker create --name cups-airprint \
     --net=localnet --ip=$cups_ip --hostname=$cups_name \
     --memory=100M \
     -p 137:137/udp -p 139:139/tcp -p 445:445/tcp \
     -p 631:631/tcp -p 5353:5353/udp \
     -e CUPS_ADMIN_USER=admin -e CUPS_ADMIN_PASSWORD=secr3t \
     -e CUPS_LPADMIN_PRINTER1="lpadmin -p epson -D '爱普生打印机' -m raw -v smb://user:pass@192.168.2.2/epson" \
     drpsychick/airprint-bridge:latest
   
   # 启动容器
   docker start cups-airprint
   

测试打印机

1. iOS/macOS设备：在"设置-打印机"中，默认标签页应显示前缀为"AirPrint"的打印机
2. Web界面测试：登录CUPS管理界面，在打印机"维护"下拉菜单中选择"打印测试页"
3. iOS打印测试：打开任意文件，点击"分享-打印"，选择目标打印机完成打印

常见问题

QNAP设备提示

QNAP设备不支持macvlan，需使用qnet驱动创建网络：

docker network create --driver=qnet --ipam-driver=qnet --ipam-opt=iface=bond0 --subnet <子网> <网络名称>

其他问题

详见项目issue跟踪：drpsychick/docker-cups-airprint/issues

致谢

基于以下项目的出色工作：

• jstrader/airprint-cloudprint
• tjfontaine/airprint-generate

贡献

欢迎通过以下方式贡献：

• 提交issue反馈问题或建议
• 创建讨论参与功能规划
• 提交Pull Request改进代码