基于 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 系列等大多走这条路）
厂商专有驱动（脚本另行下载/编译）：
| 驱动 | 版本 | 架构覆盖 | 适用机型 |
|---|---|---|---|
| Epson ESC/P-R 2（源码编译） | 1.2.39 | amd64 / arm64 / armv7 | 新款 Epson 喷墨：ET-18100、L8050、L8160、WF-7840 等（含无边距打印，issue #30） |
Epson 国行专有驱动（epson-inkjet-printer-201601w + epson-printer-utility） |
1.0.1 / 1.2.2 | 仅 amd64 | Epson 中国区早期机型 L380、L455 等（原厂墨水检测/尺寸预设更完整） |
Canon UFR II / UFRII LT 官方驱动（cnrdrvcups-ufr2-uk） |
6.30-1.07 | amd64 / arm64 | i-SENSYS LBP/MF、imageCLASS、imageRUNNER (iR)、imagePRESS (iPR) 等所有走 UFR II / UFRII LT 协议的 Canon 激光机（issue #34） |
柯尼卡美能达 bizhub 3000MF 黑白激光驱动（bizhub3000mfpdrvchn） |
1.0.0-1 | amd64 / arm64 | Konica Minolta bizhub 3000MF 多功能一体机（issue #35） |
💡 表中标注为「仅 amd64」或「amd64 / arm64」的驱动，在未覆盖的架构（如树莓派 armv7）上会被脚本静默
skip，不影响其他驱动的使用。如果你的打印机不在以上列表中，仍可访问 CUPS 管理界面（http://localhost:631）通过自带的 PPD 库或上传自定义 PPD 添加。
- 多用户系统：支持
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 与 Docker Compose
- USB 打印机（若使用本地打印机）
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也可直接下载仓库内的 docker-compose.yml：
wget https://raw.githubusercontent.com/hanxi/cups-web/master/docker-compose.yml在同目录创建 .env：
CUPSADMIN=admin
CUPSPASSWORD=your_cups_passworddocker-compose up -d访问 CUPS 管理界面：http://localhost:631，使用 .env 中的账号登录并添加打印机。
⚠️ 重要：添加打印机后，必须在 CUPS 管理后台将其设为 Shared（共享） 状态，否则 Web 端无法发现该打印机。
浏览器打开 http://localhost:1180，使用默认账号登录：
- 用户名：
admin - 密码：
admin
⚠️ 首次登录请立即修改默认密码。
适合已有 CUPS 服务的场景。
从 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-amd64export 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（或手动改源码中的路径）。
浏览器打开 http://localhost:8080，使用 admin/admin 登录。
| 变量名 | 说明 | 默认值 |
|---|---|---|
LISTEN_ADDR |
Web 服务监听地址 | :8080 |
DB_PATH |
SQLite 数据库路径 | data/cups-web.db |
UPLOAD_DIR |
上传文件目录 | uploads |
CUPS_HOST |
CUPS 服务地址（host 或 host:port） |
localhost |
| 参数 | 说明 |
|---|---|
-addr |
监听地址，优先级高于 LISTEN_ADDR |
| 变量名 | 说明 |
|---|---|
CUPSADMIN |
CUPS 管理员用户名（必填） |
CUPSPASSWORD |
CUPS 管理员密码（必填） |
- CUPS：
631 - Web：容器内
8080，docker-compose.yml默认映射到宿主机1180
Docker 默认卷映射：
./.data→ 数据库./.uploads→ 上传的原始文件与转换后 PDF./.etc→ CUPS 配置
| 类型 | 扩展名 | 处理方式 |
|---|---|---|
.pdf |
直接打印 | |
| 图片 | .jpg .jpeg .png .gif .heic |
转换为 PDF（支持多张合并） |
| Office | .doc .docx .xls .xlsx .ppt .pptx |
通过 LibreOffice 转换 |
| OFD | .ofd |
通过 ofdrw 转换 |
| 文本 | .txt .md .html |
服务端渲染为 PDF |
- 选择打印机
- 上传文件（支持多图）
- 预览转换后的 PDF、调整打印参数
- 确认提交，系统自动落库并下发到 CUPS
- 用户管理：创建、编辑、删除；默认
admin账号不可删除、不可改名、角色固定 - 打印记录：查看全站记录，按用户名/日期过滤，下载原始文件
- 系统设置：数据保留天数（
0表示永久保留）
通过反向代理（例如 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- 检查打印机是否在 CUPS 中正常列出（http://localhost:631）
- 确认打印机设置为 Shared
- 容器化部署时确认
CUPS_HOST指向正确的 CUPS 服务地址 - 重启 CUPS：
docker-compose restart cups
- 转换有 60 秒超时，复杂文档可能超时
- 确认文档本身未损坏；可尝试本地先另存为 PDF 再上传
- 查看日志：
docker-compose logs -f web
在「管理后台 → 系统设置」中设置「数据保留天数」为大于 0 的值，维护任务每小时巡检一次，自动清理过期记录与文件。
docker-compose logs -f web
docker-compose logs -f cups欢迎提 Issue 和 Pull Request。开发者文档请参阅 AGENTS.md。
如果这个项目对你有帮助，欢迎点击右上角的 ⭐ Star 让更多人发现它！
如果这个项目对你有帮助，欢迎通过以下方式支持：
点击右上角的 ⭐ Star 按钮，让更多人发现这个项目。
- 💝 爱发电 — 持续支持项目发展
- 扫码请作者喝杯奶茶 ☕
感谢你的支持！❤️
本项目采用 MIT 许可证，详见 LICENSE。