bgernert/docker-cups

基于Alpine Linux的CUPS打印服务器镜像（含cups-pdf）

镜像概述

本镜像基于轻量级Alpine Linux构建，集成了CUPS（通用Unix打印系统）及cups-pdf组件。CUPS作为跨平台打印服务标准，提供网络打印协议支持（如IPP、LPD、SMB）；cups-pdf则实现PDF虚拟打印功能，可将打印任务直接输出为PDF文件。镜像体积小、资源占用低，适合快速部署轻量级网络打印服务。

核心功能与特性

• 轻量级基础：基于Alpine Linux，镜像体积小于100MB，启动速度快，系统资源占用低
• 完整打印服务：集成CUPS核心组件，支持网络打印机管理、打印队列配置、打印任务监控
• PDF虚拟打印：内置cups-pdf模块，可将任何打印任务输出为PDF文件，无需物理打印机
• 多协议支持：兼容IPP（互联网打印协议）、LPD（行式打印机守护进程）、SMB（Windows共享打印）等主流协议
• 灵活配置：支持通过环境变量、卷挂载自定义管理员账户、打印队列及PDF输出路径
• 多架构兼容：支持x86_64、armhf等主流架构，适配物理机及嵌入式设备

使用场景与适用范围

• 家庭/小型办公室网络打印：快速搭建集中式打印服务，实现多设备共享物理打印机
• 开发/测试环境：作为虚拟打印服务，生成PDF格式的打印测试文件，避免消耗实体纸张
• 轻量级服务器部署：在资源受限的边缘设备或容器集群中提供打印功能，如NAS、树莓派等
• 自动化文档生成：结合应用系统实现打印任务自动转换为PDF文件，用于报表、凭证存档等场景

使用方法与配置说明

快速启动（Docker Run）

通过以下命令快速启动CUPS服务器容器：

bash
docker run -d \
  --name cups-server \
  -p 631:631 \
  -e CUPS_USER_ADMIN=admin \
  -e CUPS_PASSWORD=securepassword \
  -v /path/to/cups-config:/etc/cups \
  -v /path/to/pdf-output:/var/spool/cups-pdf \
  -v /dev/bus/usb:/dev/bus/usb \  # 如需连接USB打印机，添加此挂载
  --restart unless-stopped \
  alpine-cups-with-pdf

参数说明：

• -p 631:631：映射CUPS管理端口（Web界面及打印协议端口）
• -e CUPS_USER_ADMIN：管理员用户名（默认：admin）
• -e CUPS_PASSWORD：管理员密码（建议设置强密码）
• -v /path/to/cups-config:/etc/cups：持久化CUPS配置（包含打印机队列、权限等）
• -v /path/to/pdf-output:/var/spool/cups-pdf：自定义PDF输出目录（cups-pdf生成的文件将保存在此）
• -v /dev/bus/usb:/dev/bus/usb：挂载USB总线（仅物理机部署且需连接USB打印机时使用）

Docker Compose配置

创建docker-compose.yml文件，实现更便捷的服务管理：

yaml
version: '3'
services:
  cups-server:
    image: alpine-cups-with-pdf
    container_name: cups-server
    ports:
      - "631:631"
    environment:
      - CUPS_USER_ADMIN=admin
      - CUPS_PASSWORD=your_secure_password
      - CUPS_LOG_LEVEL=info  # 日志级别：debug/info/warn/error
    volumes:
      - ./cups-config:/etc/cups  # 持久化配置文件
      - ./pdf-output:/var/spool/cups-pdf  # PDF输出目录
      - ./printers:/etc/printers  # 打印机驱动/PPD文件目录（可选）
      - /var/run/dbus:/var/run/dbus  # 如需使用Avahi网络发现（可选）
    devices:
      - /dev/bus/usb:/dev/bus/usb  # USB打印机设备映射（可选）
    restart: unless-stopped

启动服务：

bash
docker-compose up -d

核心配置说明

环境变量

卷挂载路径

端口映射

Web管理界面访问

容器启动后，通过浏览器访问 http://<宿主机IP>:631 进入CUPS管理界面：

1. 首次访问需输入管理员账户（CUPS_USER_ADMIN）及密码（CUPS_PASSWORD）
2. 通过 Administration 标签页添加打印机、配置打印队列
3. 通过 Printers 标签页管理已添加的打印机及打印任务
4. cups-pdf虚拟打印机默认名称为 PDF，打印任务将输出至 /var/spool/cups-pdf/<用户名> 目录

自定义cups-pdf配置

如需修改cups-pdf输出路径、文件名格式等参数，可通过挂载自定义配置文件实现：

1. 在宿主机创建 cups-pdf.conf 文件（可从容器内 /etc/cups/cups-pdf.conf 复制默认配置）
2. 修改配置参数（如 Out ${HOME}/PDF 改为 Out /var/spool/cups-pdf/custom）
3. 通过卷挂载覆盖容器内配置：

   bash
   -v /path/to/custom/cups-pdf.conf:/etc/cups/cups-pdf.conf
   

注意事项

• 安全性：生产环境中需修改默认管理员密码（CUPS_PASSWORD），并限制631端口访问来源（如通过防火墙仅允许信任IP）
• 打印机驱动：部分物理打印机需安装特定驱动，可将PPD文件放入 /etc/printers 并在Web界面添加打印机时选择
• 权限问题：宿主机挂载目录需确保权限正确（建议设置UID/GID为1000，避免容器内权限不足）
• 日志排查：通过 docker logs cups-server 查看容器日志，定位打印服务异常问题