hanxi/cups-web repository overview

⁠🖨️ 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 预览、纸张方向的可视化预览、页数估算

⁠扫描能力（Issue #111⁠）

镜像内置 scanimage + libsane-hpaio，Web 界面「扫描」入口对所有登录用户开放：

• 单页平板扫描：MVP 支持单张扫描；ADF / 双面暂未接入
• 输出格式：PNG（无损）/ JPEG（较小）/ PDF（先扫成 PNG，再用 Ghostscript 合成，规避不同 SANE 后端对 --format=pdf 支持不一致的问题）
• 可选参数：模式（Color / Gray / Lineart）、分辨率（75–600 dpi）、来源（Flatbed / ADF，按设备实际能力显示）
• 异步任务 + 实时日志：提交后立即返回 jobId，页面每 1.5 秒轮询进度并展示 scanimage / gs 的实时输出；硬超时 5 分钟
• 历史记录持久化：扫描件默认存到 SCAN_DIR（docker-compose.yml 里挂到 ./.scans:/scans），元数据落 scan_records 表，普通用户只看得到自己的记录，管理员可看全站

⁠打印机驱动

镜像内预装了 Debian printer-driver-all 等通用驱动包，覆盖大部分常见打印机。对于特定品牌打印机，提供按需手动安装的驱动脚本和 Web 管理界面：

预装通用驱动（开箱即用）：

• 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 老款激光机
• foomatic-db-compressed-ppds + openprinting-ppds：海量 PPD 库
• hplip + hpijs-ppds + hp-ppd：HP 全系打印套件
• ipp-usb + CUPS 内置 driverless：IPP Everywhere / AirPrint / Mopria 自动识别

可选厂商驱动（通过 Web 界面或命令行按需安装，安装后自动持久化）：

⁠驱动管理（Web 界面）

驱动管理页面仅管理员可见（登录后导航栏的「驱动」入口）：

• 自动检测：扫描 USB / 网络打印机，自动匹配推荐驱动
• 一键安装：检测到打印机后一键安装驱动，并自动 lpadmin 添加到 CUPS（默认纸张设为 A4）
• 驱动列表：查看所有可用驱动的安装状态、安装时间与支持架构，一键安装 / 卸载
• 上传自定义驱动：支持上传 PPD 文件（.ppd）或 Debian 包（.deb），仅这两种扩展名
• 驱动持久化：安装的驱动文件自动快照到 .drivers 持久卷，容器重建后自动恢复

⁠安装过程是异步的，请耐心等待

点击「安装」后接口会立刻返回，真正的安装在后台执行，页面上会出现一个进度卡片，每 2 秒刷新一次并实时展示编译 / 安装日志：

• 需要编译的驱动（Canon CAPT、HP foo2zjs 固件、arm64 上的 Epson ESC/P-R 2）可能要几分钟到十几分钟，页面一直显示滚动日志是正常的，不是卡住了
• 这期间请不要刷新页面、不要重复点击。刷新虽然不会中断后台安装，但页面上的实时日志会丢失，只能改用 docker compose logs -f cups 观察
• 后台任务的硬超时是 30 分钟，页面等待上限 35 分钟

⁠同一时刻只能跑一个驱动任务

apt / dpkg 本身持有全局锁，并发安装只会互相失败。因此后端限制同时只允许一个驱动任务（安装 / 卸载 / 一键安装并添加），任务进行中再发起第二个会被直接拒绝，并提示「已有驱动任务正在执行，请等待其完成后重试」；有任务在跑时上传 .deb 也会被同样拒绝。

⁠.ppd 与 .deb 都会自动恢复

.deb 的真正安装动作发生在包内的安装脚本里，光把文件拷回来并不能让驱动生效 —— 所以它走的是"归档整个包、重启时重新安装一遍"的路子，而不是逐个文件还原。重复安装是安全的：已经装上且版本不更旧的包会被跳过。

也可以通过命令行安装驱动（命令行是同步执行的，会一直占用终端直到结束）：

# 查看可用驱动
docker exec cups driver-list

# 安装驱动
docker exec cups driver-install canon-ufr2

# 查看已安装驱动
docker exec cups driver-list --installed

# 卸载驱动
docker exec cups driver-remove canon-ufr2

⁠用户与权限

• 多用户系统：支持 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 21）
• 打印服务：CUPS⁠（源码编译 2.4.x，覆盖 apt 版本）

⁠🚀 快速开始

提供两种部署方式：

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

⁠Docker 部署

⁠前置要求

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

⁠1. 创建 docker-compose.yml

services:
  cups:
    image: hanxi/cups-web:latest
    container_name: cups
    user: root
    hostname: CUPS
    # mDNS/DNS-SD 依赖局域网组播，桥接模式下发现不了网络打印机、
    # AirPrint 也广播不出去，必须用 host 网络（issue #107）
    network_mode: host
    security_opt:
      - apparmor:unconfined
    environment:
      - CUPSADMIN=${CUPSADMIN:-print}
      - CUPSPASSWORD=${CUPSPASSWORD:-print}
      - TZ=${TZ:-Asia/Shanghai}
      # host 网络下 Web 直接监听宿主端口，默认 1180（与旧版端口映射一致）
      - LISTEN_ADDR=${LISTEN_ADDR:-:1180}
      # 扫描件输出目录，落在下面 ./.scans:/scans 卷里
      - SCAN_DIR=${SCAN_DIR:-/scans}
    volumes:
      - ./.etc:/etc/cups
      - ./.data:/data
      - ./.uploads:/uploads
      - ./.drivers:/opt/cups-drivers/data
      - ./.scans:/scans
      - /dev/bus/usb:/dev/bus/usb
      - /run/udev:/run/udev:ro
    device_cgroup_rules:
      - 'c 189:* rmw'
    # 特权模式：ARM / 嵌入式平台上 libusb 需要完整 sysfs 访问才能枚举 USB
    # 打印机（issue #110）。如果你确认 x86 平台不需要，可注释掉这行。
    privileged: true
    restart: unless-stopped

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

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

⁠2. 配置环境变量（可选）

在同目录创建 .env：

CUPSADMIN=print
CUPSPASSWORD=your_cups_password
TZ=Asia/Shanghai

⁠3. 启动服务

docker compose up -d

⁠4. 安装打印机驱动（按需）

大部分打印机靠镜像预装的通用驱动即可直接使用，只有特定品牌机型才需要这一步。

通过 Web 界面安装（推荐）：

1. 访问 http://localhost:1180⁠，使用 admin/admin 登录
2. 点击导航栏「驱动」进入驱动管理页面（仅管理员可见）
3. 点击「扫描打印机」自动检测已连接的打印机
4. 对检测到的打印机点击「一键安装并添加」

或通过命令行安装：

docker exec cups driver-install canon-ufr2

⁠5. 配置打印机

如果没有通过上面的自动检测添加打印机，也可以手动配置：

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

⁠6. 访问 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

⁠3. 访问 Web

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

⁠⚙️ 配置说明

⁠环境变量

⁠命令行参数

⁠默认端口

• CUPS：631（管理界面 + IPP 协议）。Docker 部署使用 host 网络模式（Issue #107⁠），cupsd 直接占用宿主机 631
• Web：二进制部署默认监听 8080；Docker 部署由 LISTEN_ADDR 环境变量决定，docker-compose.yml 默认 :1180（与旧版桥接时代的端口映射保持一致）

⁠数据持久化目录

Docker 默认卷映射：

此外还有两个非数据类的挂载，用于 USB 打印机识别与热插拔：

⁠其他 compose 选项说明

⁠📖 使用指