fxqq/cups-virtual-pdf-printer repository overview

⁠CUPS 虚拟 PDF 打印机

轻量级局域网虚拟 PDF 打印机。支持从任何设备（包括安卓平板、学习机等）打印，自动保存为 PDF 文件。

⁠为什么选择这个镜像？

相比原版 CUPS 镜像，本镜像提供：

• ✅ 开箱即用 - 预配置 cups-pdf，无需手动安装和配置
• ✅ mDNS 自动发现 - 内置 Avahi 广播，安卓/iOS 设备可直接搜索到打印机
• ✅ PDF 输出已调通 - 输出路径已配置为挂载卷，避免路径权限问题

适合不懂 CUPS、只想让学习机/平板能打印存 PDF 的用户。

⁠功能特性

• 🖨️ 虚拟 PDF 打印机 - 模拟网络打印机，将打印任务转换为 PDF
• 📡 mDNS/Bonjour 自动发现 - 同局域网设备可自动发现打印机
• 📱 安卓兼容 - 支持安卓设备（学而思学习机等）
• 🔒 无外部依赖 - 所有处理在本地完成
• 💾 持久化存储 - PDF 文件保存到挂载目录

⁠快速开始

version: "3"
services:
  cups-pdf:
    image: fxqq/cups-virtual-pdf-printer:latest
    container_name: cups-virtual-pdf-printer
    network_mode: host  # mDNS 发现必须使用 host 网络
    volumes:
      - /path/to/pdf/output:/var/spool/cups-pdf/ANONYMOUS
    environment:
      - CUPSADMIN=admin
      - CUPSPASSWORD=admin
    restart: unless-stopped

重要提示: 必须使用 network_mode: host，否则 mDNS 服务发现无法工作，设备将无法找到打印机。

⁠环境变量

⁠挂载目录

⁠访问方式

• CUPS 管理界面: http://your-server-ip:631⁠
• IPP 打印机地址: ipp://your-server-ip:631/printers/CUPS-PDF

⁠使用方法

⁠自动发现（推荐）

大多数现代设备（包括安卓平板、iOS 设备和桌面操作系统）会通过 mDNS/Bonjour 自动发现打印机：

1. 确保设备在同一局域网
2. 在任意应用中打开打印对话框
3. 在打印机列表中查找 "Virtual PDF Printer" 或 "CUPS-PDF"
4. 选择并打印 - PDF 将保存到挂载目录

⁠手动配置

如果自动发现不工作，可以手动添加打印机：

Android/iOS:

• 使用 IPP 协议: ipp://your-server-ip:631/printers/CUPS-PDF

Windows/macOS:

• 使用上述 IPP 地址添加网络打印机
• 或使用 AirPrint/IPP Everywhere 支持

Linux:

lpadmin -p Virtual-PDF -E -v ipp://your-server-ip:631/printers/CUPS-PDF -m everywhere

⁠故障排除

⁠打印机无法被发现

1. 检查网络模式 - 必须使用 network_mode: host
2. 验证 mDNS 是否运行 - 检查容器日志: docker logs cups-virtual-pdf-printer
3. 防火墙规则 - 确保 UDP 5353 (mDNS) 和 TCP 631 (IPP) 已放行
4. 网络隔离 - 路由器不能开启 AP 隔离
5. 重启学习机/平板 - 如果学习机里不能自动发现 CUPS 虚拟打印机，建议重启一下学习机，让设备重新扫描网络中的 mDNS 服务

⁠PDF 未生成

1. 检查目录权限 - 确保挂载目录可写
2. 检查 CUPS 日志 - 访问 http://your-server-ip:631⁠ → Administration → View Log File
3. 验证打印机状态 - CUPS 管理界面 → 打印机 → CUPS-PDF

⁠无法访问管理界面

1. 检查容器是否运行 - docker ps | grep cups
2. 验证 631 端口是否可访问 - curl -I http://your-server-ip:631
3. 检查凭据 - 使用环境变量设置的用户名密码

⁠技术细节

• 基础镜像: Ubuntu 22.04
• CUPS 版本: Ubuntu 22.04 仓库最新版本
• 协议: IPP (Internet Printing Protocol), mDNS/DNS-SD
• 打印机型号: 通用 CUPS-PDF 虚拟打印机

⁠许可证

本 Docker 镜像按原样提供，可用于个人和商业用途。

CUPS 采用 Apache License 2.0 许可证。

⁠CUPS Virtual PDF Printer

A lightweight virtual PDF printer for LAN environments. Print from any device (including Android tablets, learning machines, etc.) and automatically save output as PDF files.

⁠Why Choose This Image?

Compared to vanilla CUPS images, this image provides:

• ✅ Out of the box - Pre-configured cups-pdf, no manual installation needed
• ✅ mDNS auto-discovery - Built-in Avahi broadcast, Android/iOS devices can find the printer directly
• ✅ PDF output ready - Output path configured as mounted volume, avoiding permission issues

Perfect for users who don't know CUPS and just want their learning tablets to print and save as PDF.

⁠Features

• 🖨️ Virtual PDF Printer - Simulates a network printer, converts print jobs to PDF
• 📡 mDNS/Bonjour Discovery - Automatically discovered by devices on the same network
• 📱 Android Compatible - Works with Android-based devices (Xueersi, etc.)
• 🔒 No External Dependencies - All processing happens locally
• 💾 Persistent Storage - PDFs saved to mounted volume

⁠Quick Start

version: "3"
services:
  cups-pdf:
    image: fxqq/cups-virtual-pdf-printer:latest
    container_name: cups-virtual-pdf-printer
    network_mode: host  # Required for mDNS discovery
    volumes:
      - /path/to/pdf/output:/var/spool/cups-pdf/ANONYMOUS
    environment:
      - CUPSADMIN=admin
      - CUPSPASSWORD=admin
    restart: unless-stopped

Important: network_mode: host is required for mDNS service discovery to work. Bridge mode will prevent devices from finding the printer.

⁠Environment Variables

⁠Volumes

⁠Access

• CUPS Web Interface: http://your-server-ip:631⁠
• IPP Printer URL: ipp://your-server-ip:631/printers/CUPS-PDF

⁠Usage

⁠Auto-Discovery (Recommended)

Most modern devices (including Android tablets, iOS devices, and desktop OSes) will automatically discover the printer via mDNS/Bonjour:

1. Ensure your device is on the same network
2. Open the print dialog in any app
3. Look for "Virtual PDF Printer" or "CUPS-PDF" in the printer list
4. Select and print - the PDF will be saved to the mounted volume

⁠Manual Configuration

If auto-discovery does not work, manually add the printer:

Android/iOS:

• Use IPP protocol: ipp://your-server-ip:631/printers/CUPS-PDF

Windows/macOS:

• Add network printer using the IPP URL above
• Or use AirPrint/IPP Everywhere support

Linux:

lpadmin -p Virtual-PDF -E -v ipp://your-server-ip:631/printers/CUPS-PDF -m everywhere

⁠Troubleshooting

⁠Printer Not Discovered

1. Check network mode - Must use network_mode: host
2. Verify mDNS is running - Check container logs: docker logs cups-virtual-pdf-printer
3. Firewall rules - Ensure UDP 5353 (mDNS) and TCP 631 (IPP) are allowed
4. Network isolation - Router must not have AP isolation enabled
5. Restart learning machine/tablet - If the learning machine cannot automatically discover the CUPS virtual printer, try restarting the device to force it to rescan for mDNS services on the network

⁠PDFs Not Generated

1. Check volume permissions - Ensure the mounted directory is writable
2. Check CUPS logs - Access http://your-server-ip:631⁠ → Administration → View Log File
3. Verify printer status - CUPS web interface → Printers → CUPS-PDF

⁠Cannot Access Web Interface

1. Check container is running - docker ps | grep cups
2. Verify port 631 is accessible - curl -I http://your-server-ip:631
3. Check credentials - Use the CUPSADMIN and CUPSPASSWORD environment variables

⁠Technical Details

• Base Image: Ubuntu 22.04
• CUPS Version: Latest from Ubuntu 22.04 repositories
• Protocols: IPP (Internet Printing Protocol), mDNS/DNS-SD
• Printer Model: Generic CUPS-PDF virtual printer

⁠License

This Docker image is provided as-is for personal and commercial use.

CUPS is licensed under the Apache License 2.0.