极简指南：利用 CUPS Web 将老旧 USB 打印机升级为网络网页打印中心

在家庭或小型办公场景中，往往有一台功能完好的老款 USB 打印机。为了让手机、平板、Mac 和 Windows 设备都能便捷使用，通常需要折腾复杂的系统共享设置或网络发现。

CUPS Web 是一个基于 CUPS（Common UNIX Printing System）的开源自托管网页打印管理系统。它通过在服务端（如 NAS、树莓派或闲置小主机）集中管理驱动、格式转换和打印队列，为局域网内的所有设备提供了一个免驱动、跨平台的网页端打印入口。用户只需通过浏览器上传文件，即可直接提交打印任务。

---

核心特性

• 免驱跨平台： 客户端设备（iOS/Android/Mac/Windows）无需安装任何打印驱动或配置网络共享，只要能打开浏览器即可打印。
• 内置格式转换： 服务端内置 LibreOffice 与相关转换组件，不仅支持 PDF 和常规图片（含 HEIC），还支持 Word 文档以及国内常用的 OFD 格式。
• 打印优化体验： 支持多图片合并为 PDF 打印、打印前实时预览以及页数估算，大幅提升移动端打印的实用性。
• 轻量用户界面： 相比 Linux 原生 CUPS 复杂的管理员后台，CUPS Web 专门为最终使用者设计了直观、简便的业务操作界面。

---

部署前的准备工作

CUPS Web 的网页前端极易部署，但其底层仍然依赖 CUPS 与物理硬件的通信。在部署前，请确保满足以下条件：

1. 硬件就绪： 拥有一台可长期运行的设备，如 NAS、树莓派、软路由或闲置小主机，并已通过 USB 连接打印机。
2. 驱动识别： 宿主机系统必须能够识别该打印机。官方 Docker 镜像已预装 HP、Epson、Canon、Brother 等常见品牌的通用驱动库。若打印机型号较老或冷门，可能需要准备对应的 PPD 驱动文件。

---

使用 Docker Compose 快速部署

使用 Docker Compose 是最推荐的部署方式，一条命令即可同时拉起 CUPS 服务底座与 Web 管理前端。

1. 编写配置文件

在本地目录中创建 docker-compose.yml 文件：

services:
  cups:
    image: hanxi/cups:latest
    user: root
    environment:
      - CUPSADMIN=${CUPSADMIN}
      - CUPSPASSWORD=${CUPSPASSWORD}
    ports:
      - "631:631"
    devices:
      - /dev/bus/usb:/dev/bus/usb
    volumes:
      - ./.etc:/etc/cups
    restart: unless-stopped

  web:
    image: hanxi/cups-web:latest
    user: root
    environment:
      - CUPS_HOST=cups:631
    volumes:
      - ./.data:/data
      - ./.uploads:/uploads
    ports:
      - "1180:8080"
    depends_on:
      - cups
    restart: unless-stopped

2. 配置环境变量

在同级目录下新建 .env 文件，用于设置 CUPS 的管理员账号与密码：

代码段

CUPSADMIN=admin
CUPSPASSWORD=your_secure_password

3. 启动服务

在终端运行以下命令后台启动容器：

docker-compose up -d

部署完成后，可通过浏览器访问 http://<宿主机IP>:1180 进入打印管理页面。

---

部署与运维要点

⚠️ 运维避坑指南

• 开启打印机共享： 在 CUPS 管理后台（端口 631）添加物理打印机后，务必勾选“Shared（共享）”状态，否则前端 Web 页面将无法检索到该打印机。
• 即时修改默认凭据： CUPS Web 前端的默认管理账号密码为 admin/admin，首次登录后请立即进入后台修改。
• 存储空间管理： 系统在处理打印任务时，会缓存原始文件、转换后的 PDF 以及打印日志。建议定期清理 uploads 目录以防磁盘空间被占满。
• 安全与网络隔离： 官方镜像默认采用不加密的 HTTP 协议传输，且由于打印文件多涉及合同、发票或隐私文档，强烈建议仅在局域网内使用。切勿直接将 1180 端口暴露至公网。若需远程打印，应配合 VPN、Tailscale、ZeroTier 或配置反向代理及强认证。

---

项目资源

• 源码与文档： GitHub 项目主页