🖨️ CUPS Web — 网页打印管理

基于 CUPS 的网页版打印管理工具。通过浏览器上传文件、远程提交打印任务，支持多用户管理与打印记录追踪，适合家庭和小型办公室使用。

📸 界面预览

文件上传	打印机选择
实时预览	管理后台

✨ 功能特性

打印能力

• 多格式支持：PDF、图片（JPG/PNG/GIF/HEIC）、Office 文档（doc/docx/xls/xlsx/ppt/pptx）、OFD、纯文本
• 自动转换：Office 文档通过 LibreOffice 转 PDF；OFD 通过内置 Java 转换器（基于 ofdrw）转 PDF；文本/图片在服务端渲染为 PDF
• 多图片合并打印：一次选择多张图片自动合并为一份 PDF
• 打印选项：份数、单双面、彩色/黑白、纸张大小、纸张类型、页面方向、页码范围、缩放、镜像打印
• 实时预览：支持 PDF 预览、纸张方向的可视化预览、页数估算

内置打印机驱动

hanxi/cups 镜像出厂即预装了一批常见品牌的打印机驱动，免去用户在容器里手动 apt install 或翻官网下载 .deb 的麻烦。除非另行说明，下面列出的驱动都同时覆盖 linux/amd64 + linux/arm64 + linux/arm/v7（少数厂商无 ARM 二进制的会标注）。

通用驱动包（apt 安装）：

• printer-driver-all：Debian 维护的驱动 meta 包，包含 splix、c2050、m2300w、ptouch 等数十种小众驱动
• printer-driver-cups-pdf：虚拟 PDF 打印机，无实体打印机也可调试
• printer-driver-escpr：Epson ESC/P-R 标准款（覆盖大部分 Epson 喷墨老机型）
• printer-driver-foo2zjs：ZjStream / Hiperc / OAKT 协议机型（部分 HP / Konica / Minolta 老款激光机）
• printer-driver-brlaser：Brother 老款激光机（HL-L2300D、HL-1110、DCP-7055 等，issue #32）
• printer-driver-gutenprint：覆盖 Epson / Canon / HP / Lexmark 等大量老机型；仅 amd64 / arm64（trixie armhf 上游未提供 binary）
• foomatic-db-compressed-ppds + openprinting-ppds：Foomatic / OpenPrinting 海量 PPD 库
• hplip + hpijs-ppds + hp-ppd：HP 全系打印/扫描套件（LaserJet、OfficeJet、DeskJet、Envy 等）
• ipp-usb + CUPS 内置 driverless 模型：把 USB 直连的 IPP Everywhere / AirPrint / Mopria 打印机自动识别为网络打印机（新款 Brother DCP-T425W、HP Tango、Canon PIXMA TS 系列等大多走这条路）

厂商专有驱动（脚本另行下载/编译）：

💡 表中标注为「仅 amd64」或「amd64 / arm64」的驱动，在未覆盖的架构（如树莓派 armv7）上会被脚本静默 skip，不影响其他驱动的使用。如果你的打印机不在以上列表中，仍可访问 CUPS 管理界面（http://localhost:631）通过自带的 PPD 库或上传自定义 PPD 添加。

📱 苹果 AirPrint 选不到 A4 纸（issue #48）：foo2zjs 上游 HP 1020 PPD 的默认纸张是 Letter，iPhone 通过 AirPrint 连接时按 media-default 渲染首屏，A4 会被折叠/隐藏。容器启动时 entrypoint.sh 会自动把已添加的 HP 1020 打印机 PPD 默认纸张从 Letter 切到 A4（备份保留为 *.bak-cupsweb-issue48）；新加打印机时也可以直接选 CUPS 列表里的 HP LaserJet 1020 Foomatic/foo2zjs-z1 A4 (cups-web) 变体。

用户与权限

• 多用户系统：支持 admin / user 两种角色
• 默认管理员：首次启动自动创建 admin/admin，admin 账号受保护无法被删除或重命名
• 打印记录：完整保存每次打印的文件、页数、份数、双面/彩色选项、状态等

管理后台

• 用户管理：创建、编辑、删除用户；修改角色与联系信息
• 打印记录查询：可按用户名、时间范围过滤
• 数据保留策略：按天数自动清理过期打印记录和对应文件（每小时巡检一次）

安全

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

🛠️ 技术栈

• 后端：Go 1.26 · Gorilla Mux · SQLite（modernc.org/sqlite，纯 Go 实现，无需 CGO）
• 打印协议：OpenPrinting/goipp（IPP）
• 前端：Vue 3 · Vite 7 · Nuxt UI v4 · Tailwind CSS v4 · Vue Router（hash 模式）
• 文档转换：LibreOffice（Office → PDF）· ofdrw（OFD → PDF，Java 17）
• 打印服务：CUPS

🚀 快速开始

提供两种部署方式：

• Docker 部署（推荐，一键拉起 CUPS + Web）
• 二进制部署（适合已有 CUPS 服务的场景）

Docker 部署

前置要求

• Docker 与 Docker Compose
• USB 打印机（若使用本地打印机）

1. 创建 docker-compose.yml

services:
  cups:
    image: hanxi/cups:latest
    user: root
    environment:
      - CUPSADMIN=${CUPSADMIN}
      - CUPSPASSWORD=${CUPSPASSWORD}
    ports:
      - "631:631"
    # USB 打印机热插拔支持（issue #81）：用 volume 目录挂载 /dev/bus/usb
    # 而非 devices:，让「后开机」的打印机新建的设备节点能实时传播进容器；
    # device_cgroup_rules 放开 USB 字符设备（major 189）的访问权限。
    volumes:
      - ./.etc:/etc/cups
      - /dev/bus/usb:/dev/bus/usb
      - /run/udev:/run/udev:ro
    device_cgroup_rules:
      - 'c 189:* rmw'
    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

也可直接下载仓库内的 docker-compose.yml：

wget https://raw.githubusercontent.com/hanxi/cups-web/master/docker-compose.yml

2. 配置环境变量

在同目录创建 .env：

CUPSADMIN=admin
CUPSPASSWORD=your_cups_password

3. 启动服务

docker-compose up -d

4. 配置打印机

访问 CUPS 管理界面：http://localhost:631，使用 .env 中的账号登录并添加打印机。

⚠️ 重要：添加打印机后，必须在 CUPS 管理后台将其设为 Shared（共享） 状态，否则 Web 端无法发现该打印机。

5. 访问 Web

浏览器打开 http://localhost:1180，使用默认账号登录：

• 用户名：admin
• 密码：admin

⚠️ 首次登录请立即修改默认密码。

二进制部署

适合已有 CUPS 服务的场景。

1. 下载二进制

从 GitHub Releases 下载对应平台的二进制：

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

2. 配置并运行

export CUPS_HOST=localhost:631
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

⚠️ OFD 打印仅在 Docker 镜像中开箱即用。二进制部署若需支持 OFD，需要另行安装 Java 17 并把 ofd-converter.jar 放到 /ofd-converter.jar（或手动改源码中的路径）。

3. 访问 Web

浏览器打开 http://localhost:8080，使用 admin/admin 登录。

⚙️ 配置说明

环境变量

命令行参数

CUPS 容器环境变量

默认端口

• CUPS：631
• Web：容器内 8080，docker-compose.yml 默认映射到宿主机 1180

数据持久化目录

Docker 默认卷映射：

• ./.data → 数据库
• ./.uploads → 上传的原始文件与转换后 PDF
• ./.etc → CUPS 配置

📖 使用指南

支持的文件格式

打印流程

1. 选择打印机
2. 上传文件（支持多图）
3. 预览转换后的 PDF、调整打印参数
4. 确认提交，系统自动落库并下发到 CUPS

管理员功能

• 用户管理：创建、编辑、删除；默认 admin 账号不可删除、不可改名、角色固定
• 打印记录：查看全站记录，按用户名/日期过滤，下载原始文件
• 系统设置：数据保留天数（0 表示永久保留）

🔧 进阶配置

使用 HTTPS

通过反向代理（例如 Nginx）提供 HTTPS：

server {
    listen 443 ssl;
    server_name 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;
    }
}

修改端口

编辑 docker-compose.yml：

services:
  web:
    ports:
      - "你的端口:8080"

数据备份

cp ./.data/cups-web.db /backup/location/
tar -czf uploads-backup.tar.gz ./.uploads/
tar -czf cups-config-backup.tar.gz ./.etc/

❓ 常见问题

忘记管理员密码怎么办？

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

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

Web 端看不到打印机？

1. 检查打印机是否在 CUPS 中正常列出（http://localhost:631）
2. 确认打印机设置为 Shared
3. 容器化部署时确认 CUPS_HOST 指向正确的 CUPS 服务地址
4. 重启 CUPS：docker-compose restart cups

打印机后开机就识别不到，要重启容器才行？（USB 热插拔）

打印机比容器晚开机时,CUPS 枚举不到 USB 设备——典型场景是 NAS 长期开机、用时才开打印机（issue #81）。原因是旧版 docker-compose.yml 用 devices: 绑定 USB,而 devices: 只在容器启动那一刻绑定一次,「后开机」打印机新建的 /dev/bus/usb/... 节点不会传播进容器。

按上方最新的 docker-compose.yml 改用 volume 目录挂载 /dev/bus/usb + device_cgroup_rules 即可支持热插拔:

docker-compose down && docker-compose up -d

之后先启动容器、再开打印机也能被识别。若你的 Docker 环境不支持 device_cgroup_rules（部分旧版本 / rootless / cgroup v1）,删掉该字段并改用 privileged: true 即可,效果相同、权限更宽。

Office / OFD 转换失败？

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

上传文件一直堆积占空间？

在「管理后台 → 系统设置」中设置「数据保留天数」为大于 0 的值，维护任务每小时巡检一次，自动清理过期记录与文件。

如何查看日志？

docker-compose logs -f web
docker-compose logs -f cups

🤝 贡献

欢迎提 Issue 和 Pull Request。开发者文档请参阅 AGENTS.md。

📈 Star History

💖 支持项目

如果这个项目对你有帮助，欢迎通过以下方式支持：

⭐ Star 项目

点击右上角的 ⭐ Star 按钮，让更多人发现这个项目。

💰 赞赏支持

• 💝 爱发电 — 持续支持项目发展
• 扫码请作者喝杯奶茶 ☕

感谢你的支持！❤️

📄 许可证

本项目采用 MIT 许可证，详见 LICENSE。