当前位置：

社区首页

电脑数码

存储设备

网络存储

文章详情

CUPS Web 教程：用浏览器远程管理打印

还在为共享打印机装驱动发愁？还在把文件拷到 U 盘跑去打印机旁边操作？CUPS Web 让你通过浏览器上传文件、远程提交打印任务，告别"打印靠走"的时代。

一、CUPS Web 是什么？

CUPS Web 是一个基于 CUPS（通用 Unix 打印系统）的网页版打印管理工具。简单说，它在你家的打印机和你之间加了一层网页界面——你不需要装驱动、不需要坐在打印机旁边，只要打开浏览器就能打印。

适合谁用？

🏠 家里有一台 USB 打印机，想让全家人都能无线打印
🏢 小型办公室，几台电脑共享一台打印机，不想折腾驱动
🖥️ 有 NAS 或家庭服务器的玩家，想把打印管理也容器化
📱 想从手机/平板远程打印的人（配合 AirPrint 也能用）

核心能力一览：

能力说明多格式支持 PDF、图片（JPG/PNG/GIF/HEIC）、Office 文档、OFD、纯文本自动转换 Office→PDF（LibreOffice）、OFD→PDF（ofdrw）、图片/文本→PDF 多图合并一次选多张图片，自动合并成一份 PDF 打印丰富的打印选项份数、单双面、彩色/黑白、纸张大小、页码范围、缩放、镜像实时预览打印前预览 PDF，确认页数和排版多用户管理 admin/user 两种角色，打印记录完整追踪内置打印机驱动预装 Epson、Canon、HP、Brother 等常见品牌驱动

二、整体架构：两个容器，各司其职

CUPS Web 采用双容器架构，非常清晰：

cups 容器：负责实际的打印服务，管理打印机驱动，连接物理打印机
cups-web 容器：提供网页界面，处理文件上传、格式转换、用户管理，通过 IPP 协议与 cups 通信

这两个容器通过 Docker 网络内部通信，对外只暴露两个端口。

三、部署方式选择

场景推荐方式从零开始，没有 CUPS 服务 ✅ Docker 部署（一键拉起两个容器）已有 CUPS 服务在运行 ✅ 二进制部署（只装 Web 部分）

绝大多数用户建议用 Docker 部署，省心省力。

四、Docker 部署：手把手操作

4.1 前置准备

确保你的机器上已经安装了：

Docker + Docker Compose
一台 USB 打印机（通过网络连接的打印机也可以，但 USB 打印机需要把设备映射进容器）

4.2 创建项目目录

mkdir cups-web && cd cups-web

4.3 创建 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

💡 也可以直接下载官方的配置文件：
wget https://raw.githubusercontent.com/hanxi/cups-web/master/docker-compose.yml

关键配置解释：

配置项说明 devices: /dev/bus/usb 把宿主机的 USB 设备映射进容器，USB 打印机必须配这一行 volumes: ./.etc:/etc/cups CUPS 配置持久化，重启不丢失打印机设置 volumes: ./.data:/data Web 数据库持久化，存储用户和打印记录 volumes: ./.uploads:/uploads 上传文件持久化 CUPS_HOST=cups:631 Web 容器通过 Docker 内部网络访问 cups 容器

4.4 配置环境变量

在同一目录下创建 .env 文件：

CUPSADMIN=admin CUPSPASSWORD=your_secure_password

⚠️ CUPSPASSWORD 请设置一个强密码，这是 CUPS 管理界面的登录密码。

4.5 启动服务

docker-compose up -d

等镜像拉取完成后，两个容器就都跑起来了。可以验证一下：

docker-compose ps

看到两个容器状态都是 Up 就说明启动成功。

4.6 配置打印机

这是最关键的一步！

打开 CUPS 管理界面：浏览器访问 http://你的服务器IP:631
登录：使用 .env 中设置的 CUPSADMIN / CUPSPASSWORD
添加打印机：
- 点击顶部 Administration 标签
- 点击 Add Printer
- 选择你的打印机设备（Local Printers 下应该能看到 USB 打印机）
- 按向导选择驱动、设置名称和描述
⚠️ 设为共享：添加完成后，在打印机页面勾选 Shared 选项

🔴 必须设为 Shared！ 这是新手最常踩的坑——如果打印机不是 Shared 状态，Web 端无法发现它。

4.7 访问 Web 界面

浏览器打开 http://你的服务器IP:1180，用默认账号登录：

用户名：admin
密码：admin

⚠️ 首次登录后请立即修改默认密码！ 在管理后台的用户管理中修改。

五、二进制部署：适合已有 CUPS 的场景

如果你已经在服务器上跑着 CUPS 服务，只需要加一个 Web 前端，用二进制部署更轻量。

5.1 下载二进制

从 GitHub Releases 下载对应平台的文件：

平台架构文件名 Linux amd64 cups-web-linux-amd64 Linux arm64 cups-web-linux-arm64 Linux armv7 cups-web-linux-armv7 Linux loong64 cups-web-linux-loong64 macOS amd64 cups-web-darwin-amd64 macOS arm64 cups-web-darwin-arm64 Windows amd64 cups-web-windows-amd64.exe

wget https://github.com/hanxi/cups-web/releases/latest/download/cups-web-linux-amd64 chmod +x cups-web-linux-amd64

5.2 配置环境变量并运行

export CUPS_HOST=localhost:631 # 指向你已有的 CUPS 服务 export DB_PATH=./data/cups-web.db export UPLOAD_DIR=./uploads export LISTEN_ADDR=:8080 ./cups-web-linux-amd64

也可以用命令行参数（优先级高于环境变量）：

./cups-web-linux-amd64 -addr :8080

5.3 访问

打开 http://localhost:8080，默认账号 admin/admin。

⚠️ OFD 格式仅在 Docker 镜像中开箱即用。二进制部署需要自行安装 Java 17 并放置 ofd-converter.jar。

六、使用指南

6.1 打印文件

登录后进入主页面，打印流程只需四步：

选择打印机 → 上传文件 → 调整参数 → 确认打印

支持的文件格式：

类型扩展名转换方式 PDF .pdf 直接打印，无需转换图片 .jpg .png .gif .heic 服务端转为 PDF，支持多张合并 Office .doc .docx .xls .xlsx .ppt .pptx LibreOffice 转 PDF OFD .ofd ofdrw 转 PDF（仅 Docker）文本 .txt .md .html 服务端渲染为 PDF

打印参数说明：

份数：打印几份
单双面：节省纸张的好帮手
彩色/黑白：黑白文档选黑白省墨
纸张大小：A4、Letter 等
纸张类型：普通纸、照片纸等
页面方向：纵向/横向
页码范围：如 1-3,5,7-9，只打印需要的页
缩放：适配纸张或按原始大小
镜像打印：特殊场景使用（如热转印）

6.2 多图合并打印

一次选择多张图片，系统会自动合并成一份 PDF。适合打印照片集、扫描件等场景。

6.3 实时预览

上传文件后，在确认打印前可以预览转换后的 PDF，确认页数和排版效果。这是避免浪费纸张的关键步骤——打印前先预览！

6.4 管理员操作

管理员（admin 角色）可以：

用户管理：创建、编辑、删除普通用户；修改角色与联系信息
打印记录查询：按用户名、时间范围过滤，查看每次打印的详细信息
系统设置：配置数据保留天数（0 = 永久保留），自动清理过期记录和文件

注意：默认的 admin 账号受保护，无法被删除或重命名。

七、内置打印机驱动：开箱即用

CUPS Web 的 Docker 镜像预装了大量打印机驱动，免去了手动安装的麻烦。以下是主要覆盖的品牌和机型：

通用驱动（覆盖大量机型）

驱动包覆盖范围 printer-driver-all Debian 维护的数十种小众驱动 printer-driver-cups-pdf 虚拟 PDF 打印机（无实体打印机也能调试） printer-driver-escpr Epson 老款喷墨机 hplip + hp-ppd HP 全系（LaserJet、OfficeJet、DeskJet、Envy） printer-driver-gutenprint Epson/Canon/HP/Lexmark 老机型 foomatic-db + openprinting-ppds 海量 PPD 库 ipp-usb USB 直连的 AirPrint/Mopria 打印机自动识别

厂商专有驱动

品牌适用机型架构 Epson ESC/P-R 2 新款喷墨（ET-18100、L8050、L8160 等） amd64/arm64/armv7 Canon UFR II i-SENSYS、imageCLASS、imageRUNNER 激光机 amd64/arm64 柯尼卡美能达 bizhub 3000MF amd64/arm64 HP LaserJet 1020 1020 系列 host-based 打印机全架构

💡 如果你的打印机不在列表中，仍可通过 CUPS 管理界面（http://localhost:631）上传自定义 PPD 添加。

八、进阶配置

8.1 配置 HTTPS（推荐）

通过 Nginx 反向代理提供 HTTPS 访问：

server { listen 443 ssl; server_name print.example.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location / { proxy_pass http://localhost:1180; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

配置好 SSL 证书后，就可以通过 https://print.example.com 安全访问了。

8.2 修改端口

编辑 docker-compose.yml 中 web 服务的 ports 映射：

services: web: ports: - "8080:8080" # 改成你想要的端口

8.3 数据备份

定期备份数据库和上传文件：

# 备份数据库 cp ./.data/cups-web.db /backup/location/ # 备份上传文件 tar -czf uploads-backup-$(date +%Y%m%d).tar.gz ./.uploads/ # 备份 CUPS 配置 tar -czf cups-config-backup-$(date +%Y%m%d).tar.gz ./.etc/

建议加入 crontab 自动执行：

# 每天凌晨 3 点自动备份 0 3 * * * cp /path/to/cups-web/.data/cups-web.db /backup/cups-web-$(date +%Y%m%d).db

8.4 数据自动清理

在管理后台的「系统设置」中设置「数据保留天数」，系统每小时巡检一次，自动清理过期的打印记录和对应文件。设为 0 则永久保留。

九、常见问题排查

Q1：Web 端看不到打印机？

这是最常见的问题，按顺序检查：

访问 http://localhost:631，确认打印机在 CUPS 中正常列出
确认打印机设为 Shared（最常见的遗漏）
检查 CUPS_HOST 环境变量是否正确指向 cups 容器
重启 cups 容器：docker-compose restart cups

Q2：Office 文档转换失败？

转换有 60 秒超时，复杂文档可能超时
确认文档本身未损坏，可尝试先另存为 PDF 再上传
查看日志定位原因：docker-compose logs -f web

Q3：忘记管理员密码？

删除数据库重启即可重置为 admin/admin（会丢失全部数据）：

docker-compose down rm ./.data/cups-web.db docker-compose up -d

Q4：上传文件占空间越来越多？

在管理后台设置数据保留天数，系统会自动清理。

Q5：AirPrint 选不到 A4 纸？

这是已知问题（foo2zjs 驱动默认纸张为 Letter），容器启动时会自动将 HP 1020 打印机的默认纸张切换为 A4。添加新打印机时，选 CUPS 列表中的 HP LaserJet 1020 Foomatic/foo2zjs-z1 A4 (cups-web) 变体即可。

Q6：如何查看日志？

# Web 服务日志 docker-compose logs -f web # CUPS 服务日志 docker-compose logs -f cups

十、安全注意事项

CUPS Web 内置了多层安全机制：

机制说明 Session 认证基于 Gorilla securecookie（加密+签名），密钥自动生成并持久化 CSRF 防护所有非 GET/HEAD/OPTIONS 请求校验 X-CSRF-Token 密码安全 bcrypt 加密存储

你的责任：

✅ 首次登录后立即修改默认密码
✅ 为 CUPS 管理员设置强密码
✅ 生产环境务必配置 HTTPS
✅ 不要把服务直接暴露在公网，使用 VPN 或内网穿透

十一、环境变量速查表

变量名说明默认值必填 CUPS_HOST CUPS 服务地址 localhost ✅ LISTEN_ADDR Web 监听地址 :8080 ❌ DB_PATH 数据库路径 data/cups-web.db ❌ UPLOAD_DIR 上传目录 uploads ❌ CUPSADMIN CUPS 管理员用户名 — ✅（cups 容器） CUPSPASSWORD CUPS 管理员密码 — ✅（cups 容器）