共享打印服务器搭建
CUPS Web。它能让你用任何设备的浏览器，随时随地远程打印，不用装多余APP、不用复杂设置，纯小白也能轻松部署，彻底告别所有打印糟心事。
完全开源免费，无广告、无会员、无功能限制，实打实解决日常打印难题。
一、这个神器，到底能解决哪些闹心问题？
简单来说，CUPS Web就是给你的打印机装了一个超简单的网页控制面板。只要把它部署在一台常年开机的设备上（家里的NAS、小主机、树莓派、甚至一直不关的旧电脑都行），再连上打印机，不管你用手机、平板、电脑，只要打开浏览器，就能上传文件直接打印，不受设备、距离限制，怎么用都方便。
它精准戳中每一个日常打印痛点，每一点都超实用：
1. 全设备通用，有浏览器就能打，告别驱动/APP烦恼
再也不用给每个手机、电脑装专属打印APP，不用挨个设备安装打印机驱动，不用纠结系统兼容问题。
苹果安卓手机、Windows/Mac电脑、平板，通通兼容，打开浏览器就能用，老人孩子看一眼就会，再也不用手把手教操作。
2. 全格式兼容，不用手动转格式，杜绝打印报错
平时打印最闹心的就是格式问题：手机里的Word、Excel打不开，PPT无法直接打印，图片还要调整尺寸，稍微复杂点就打印失败，折腾半天白忙活。
有了CUPS Web，这些问题全解决：
PDF、JPG/PNG/GIF图片，上传就能预览打印；
Word/Excel/PPT等Office文档，自动转换成PDF，不用你手动操作；
就连普通TXT文本、OFD格式文件，也能完美支持，真正做到传什么就能打什么，再也不担心格式报错。
3. 远程随时随地打印，不用守在打印机旁
只要部署设备和打印机正常开机，哪怕你在外地、在公司，都能通过浏览器上传文件，让家里的打印机直接工作。
孩子在家要打印作业、试卷，你在公司就能远程操作；出门在外急需打印证件、资料，家人只需帮忙取件就行，不用非要等你回家、不用非要守在打印机旁才能打印。
4. 多用户共用，家庭/工作室都适配，互不干扰
自带独立账号管理系统，分管理员和普通用户。
家里给老人、孩子各开一个账号，各自登录打印，不会乱删乱改；小型工作室、门店，给每个同事开账号，还能查看所有打印记录、按时间/人员筛选，甚至导出记录，轻松管控打印成本，避免浪费。
5. 安全有保障，部署超灵活
安全方面完全放心，密码加密存储，还有专业登录防护，不用担心陌生人恶意连接、乱打印浪费纸张。
部署方式对新手超友好：
纯新手直接选Docker一键部署，复制命令就能运行，几分钟彻底搞定；
如果你的设备已经在用CUPS打印服务，直接下载对应系统的程序就能直接运行，Linux、macOS、Windows三大系统，全都支持。
二、一分钟看懂：CUPS Web和CUPS的关系
很多人看到名字会懵，用大白话讲清楚：
- CUPS：是打印机的底层核心，相当于打印机的心脏和发动机，真正负责和打印机沟通、处理打印任务，没有它打印机就无法工作。
- CUPS Web：是套在CUPS上面的简易操作界面，CUPS本身操作复杂、普通人根本不会用，而CUPS Web把复杂操作全部简化，变成人人都能看懂的网页，让普通人轻松用上专业打印服务。
简单类比：CUPS是汽车发动机，CUPS Web就是方向盘和仪表盘，没有CUPS打印机没法工作，没有CUPS Web，普通人根本用不明白CUPS。
三、小白零难度一键部署教程
给大家讲最简单、最不容易出错的Docker部署方式，完全不用懂代码，跟着步骤来就行。
1. 前置准备
1. 一台常年开机的设备（NAS、树莓派、闲置小主机、旧电脑都可以）
2. 设备上装好Docker和Docker Compose（本文，我们以飞牛的Docker部署为例进行演示）
3. 打印机已经连接到这台设备
2. 部署步骤
首先在服务器中创建Docker的数据存放目录，我们创建了Docker文件夹，并在文件夹中创建了cups-web。
在cups-web目录下创建“.env”文件，用于保存CUPS的管理员账号等信息。
# CUPS 管理员账号（用于管理打印机）
XML/HTML代码
- CUPSADMIN=admin
- CUPSPASSWORD=your_cups_password
创建完成后，整个目录结构如下docker-compose.yml和.env 在一个目录。
接下来，我们开始配置Docker，这里我们通过Docker Compose安装进行演示。
接下来编辑docker-compose.yml代码
XML/HTML代码
- services:
- cups:
- image:
- docker.1ms.run/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:
- docker.1ms.run/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
或者直接命令下载
XML/HTML代码
- wget https://raw.githubusercontent.com/hanxi/cups-web/master/docker-compose.yml
然后 docker-compose up -d 启动即可。
此时已经成功创建了两个容器，分别为：
1. cups-web-web-1（cups-web端）
2. cups-web-cups-1（cups-服务端）
至此，cups-web的整个安装过程就完成了！
3. 配置步骤
打开浏览器，输入 http://你的设备IP:631 ，用.env文件中设置好的账号密码登录，添加自家打印机。
点击“Administration”菜单，开始添加打印机。
在这里我们输入我们在env文件中配置的账号密码，点击登录按钮，进入打印机管理界面。
点击“Add Printer”按钮
如果你的打印机在你的NAS或部署cups的主机上，这里会自动检测到打印机型号，如果没有检测到，可以根据你的实际情况选择。
我这选择了通过“ipp”添加，然后点击“Continue”按钮继续。
在“Connection”中输入打印机的IP地址，如“http://192.168.31.64”，然后点击“Continue”按钮，进入下一步。
Name：输入打印机名称，描述和位置是可选的。
注意：如果您使用 CUPS 作为打印服务器，其他客户端通过这个打印机的 CUPS 打印，请选择" Share this printer "。（务必把打印机设为【共享】状态，否则网页端无法识别！）
然后点击“Continus”进入下一步。
Make：这里我们选择打印机的品牌，如HP，如果列表中没有，可以选择“Generic”（通用）。
点击“Continus”继续。
Model这里我们选择打印机的具体型号，条目比较多，我们可以通过“Ctrl+F”进行搜索。
如果没有找到适配的驱动，我们可以选择“Generic IPP Everywhere Printer (en)”（通用 IPP 打印机）。
选择后点击“Add Printer”按钮，开始安装打印机驱动！
当显示如下图界面，这表示你的打印机已经成功安装！
接下来，在浏览器地址栏输入：http://你的机器IP:1180/，打开CUPS-Web界面
输入账号和密码后，点击登录。（默认账号和密码都是：admin，首次登录后，一定要修改密码！）
登录成功后，我们就可以看到刚才添加的打印机了！
在管理界面，我们可以添加，修改和删除用户，并且可以查看详细的打印记录！
配置完成后，不管是家里局域网，还是在外用手机流量，只要能访问该地址，就能随时打印。
外网访问需要你的网络有公网IP，没有的话需要通过异地组网的方式实现服务的访问！
保姆级教程｜使用EasyTier内网穿透+异地主网，小白10分钟上手（无公网IP也能用）
公网IP难搞？这篇内网穿透/异地组网工具大合集，从新手到极客全覆盖
四、这些场景用它，幸福感直接拉满
✅ 家庭带娃：孩子作业、学习资料，打开浏览器就能打印，老人也能独立操作，再也不用熬夜开电脑折腾
✅ 居家办公：文档、报表不用在手机电脑间来回传输，浏览器上传直接打印，效率翻倍
✅ 小型工作室/门店：多人共用一台打印机，不用每台设备配驱动，账号分开管理，清晰又方便
✅ 异地远程：人在外地，随时远程打印文件，不用跑打印店，急事不耽误
五、最后贴心提醒
1. 安全第一：首次登录务必修改默认管理员密码，避免他人滥用
2. 驱动问题：若CUPS识别不到打印机，在容器内安装对应型号驱动即可
3. 格式问题：复杂Office文档转换失败，可先手动转成PDF再上传
这个开源工具最难得的是，没有花里胡哨的功能，没有任何收费套路，专门解决普通人打印难、打印麻烦的痛点，把复杂的专业打印服务，变成了人人都能上手的网页工具。
如果你家里、工作室有打印机，还在被各种打印糟心事困扰，一定要试试这个神器，直接让你的打印体验提升好几个档次！
功能特性
多品牌兼容
使用ipp标准协议和cups标准命令，理论上可兼容大部分支持ipp协议的打印机
已在Canon_G3881完成测试，其他打印机请自行验证
文件管理
支持 PDF、DOC、DOCX、PPT、PPTX、XLS、XLSX、TXT、RTF 以及图片格式（JPG、JPEG、PNG、GIF、BMP、SVG）
支持拖拽上传
文件在线预览（电脑端PDF，移动端图片）
文件列表查看和删除
打印设置
纸张大小: 办公A1-A4/照片5-10 寸等
纸张材质: 普通纸/光面照片纸等
色彩模式: 彩色/黑白打印
双面打印: 单面/双面（长边装订）/双面（短边装订）
打印方向: 纵向/横向
打印份数: 支持 1-99 份
页面范围: 支持指定页面范围（如 1-5 8 10-12）
打印缩放: 自动/适应/填充/无缩放
页面镜像: 支持水平翻转
任务管理
打印机在线状态检测(限ipp打印机)
实时任务状态监控（已提交/处理中/已完成/失败/已取消）
任务进度显示（基于时间和cups队列估算）
任务取消功能
打印队列实时查看
纸盒信息（IPP 协议）
墨盒信息（IPP 协议）
打印机信息（运行时间、固件版本、告警等）
安全防护
路径遍历攻击防护
文件类型白名单验证
文件大小限制（100MB）
日志自动轮换
删除文件自动清理预览缓存
中英双语切换
中文界面 http://localhost:5000/zh
英文界面 http://localhost:5000/en
技术栈
后端: Python 3.9+ + Flask 3.0+
前端: HTML5 + Tailwind CSS (CDN)
打印服务: CUPS 2.0+
文档转换: LibreOffice 6.0+
PDF 处理: poppler-utils (pdftoppm), pdftk
IPP 协议: ipptool (cups-client)
部署指导-容器安装(推荐)
1. 部署容器
# 特权模式为usb打印机需要，如使仅使用网络打印机可以去除usb挂载和特权模式
XML/HTML代码
- docker run -d \
- --name cups-web-print \
- --hostname=cups-web-print \
- --restart unless-stopped \
- --privileged \
- -p 5000:5000 \
- -p 631:631 \
- -v /var/run/dbus:/var/run/dbus \
- -v /dev/bus/usb:/dev/bus/usb \
- -v cups-etc:/etc/cups \
- -v cups-spool:/var/spool/cups \
- -v cups-log:/var/log/cups \
- -v cups-uploads:/app/uploads \
- -v cups-previews:/app/previews \
- ghcr.io/wishday/cups-web-print:latest
2. 添加cups打印机
以网络打印机为例，其他打印机手动进入容器，参考cups官方文档操作
# 建议打印机固定ip，避免复杂mDNS解析
XML/HTML代码
- docker exec cups-web-print lpadmin -p Canon_G3881 -v ipp://192.168.1.16:631/ipp/print -m everywhere -E
3. 使用 Web 界面
打开浏览器访问 http://localhost:5000，局域网内设备访问 http://cups服务器ip:5000
部署指导-本地安装
1. 下载源代码
方式一：从 GitHub 克隆（推荐）
# 克隆项目到本地
XML/HTML代码
- git clone https://github.com/wishday/cups-web-print.git
# 进入项目目录
XML/HTML代码
- cd cups-web-print
方式二：下载 ZIP 压缩包
# 下载并解压
XML/HTML代码
- wget https://github.com/wishday/cups-web-print/archive/refs/heads/main.zip
- unzip main.zip
- cd cups-web-print-main
2. 安装依赖
安装系统依赖
XML/HTML代码
- sudo apt-get update
- sudo apt-get install -y cups cups-client \
- libreoffice-writer libreoffice-calc libreoffice-impress \
- poppler-utils pdftk python3-pip
安装 Python 依赖
XML/HTML代码
- pip3 install -r requirements.txt
3. 配置打印机
启动 CUPS 服务
XML/HTML代码
- sudo systemctl start cups
- sudo systemctl enable cups
添加打印机
# 添加ipp网络打印机示例(建议打印机固定ip，避免复杂mDNS解析)
XML/HTML代码
- sudo lpadmin -p Canon_G3881 -v ipp://192.168.1.16:631/ipp/print -m everywhere -E
# 查看可用打印机
XML/HTML代码
- lpstat -p -v
4. 启动服务
XML/HTML代码
- python3 app.py
#添加开机自启动后台运行(可选)
XML/HTML代码
- crontab -e
#添加以下一行(替换实际项目路径)
XML/HTML代码
- @reboot nohup python3 /your-path-to/app.py > /dev/null 2>&1 &
服务将在 http://localhost:5000 启动
5. 使用 Web 界面
打开浏览器访问 http://localhost:5000，局域网内设备访问 http://cups服务器ip:5000
上传文件（点击上传区域或拖拽）
选择打印机
配置打印设置
点击"提交打印"
目录结构
XML/HTML代码
- cups-web-print/
- ├── app.py # Flask 应用主文件
- ├── ipp_client.py # 通过 IPP 获取纸盒、墨盒等状态信息
- ├── printer_checker.py # 通过 IPP、BJNP 等协议确认打印机在线状态
- ├── requirements.txt # Python 依赖
- ├── README.md # 项目文档
- ├── static/ # 页面资源文件
- │ └── favicon.png
- ├── uploads/ # 上传文件目录
- ├── previews/ # 预览文件目录
- ├── templates/ # HTML 模板
- │ ├── index.html # 中文主页
- │ └── index_en.html # 英文主页
项目地址
故障排查
问题：lpadmin添加打印机失败
XML/HTML代码
- 故障排查
- 问题：lpadmin添加打印机失败
- # 重启 CUPS 服务再试
- sudo systemctl restart cups
- # 检查打印机 IP 是否能 ping 通
- ping 192.168.1.16
- # 检查 IPP 地址是否正确（不同品牌地址不同）
- # 佳能：ipp://ip:631/ipp/print
- # 惠普：ipp://ip:631/ipp/print
- # 爱普生：ipp://ip:631/ipp/printer
- # 查看 CUPS 错误日志
- cat /var/log/cups/error_log
- # 尝试使用驱动less模式（everywhere）
- sudo lpadmin -p 打印机名 -v ipp://打印机IP:631/ipp/print -m everywhere -E
- # 启用打印机并接受任务
- sudo cupsenable 打印机名
- sudo cupsaccept 打印机名
问题：访问5000端口无反应
XML/HTML代码
- # 检查服务是否正常启动
- ps -ef | grep app.py
- # 检查 5000 端口是否监听
- sudo lsof -i:5000
- sudo netstat -tulpn | grep 5000
- # 防火墙放行端口（Ubuntu/Debian）
- sudo ufw allow 5000/tcp
- # 检查 Flask 绑定地址是否为 0.0.0.0（必须修改才能局域网访问）
- # 确保 app.py 中使用：app.run(host='0.0.0.0', port=5000)
- 问题：打开页面列表无可用打印机
- # 检查 CUPS 服务状态
- sudo systemctl status cups
- # 启动 CUPS 服务
- sudo systemctl start cups
- # 确保 CUPS 已配置有可用打印机
- lpstat -p
问题：文档转换失败
XML/HTML代码
- # 验证 LibreOffice 是否安装
- libreoffice --version
- # 重新安装 LibreOffice
- sudo apt-get install --reinstall libreoffice-writer libreoffice-calc libreoffice-impress
问题：PDF 预览无法生成
XML/HTML代码
- # 验证 pdftoppm 是否安装
- pdftoppm -h
- # 安装 poppler-utils
- sudo apt-get install poppler-utils
问题：页面范围提取失败
XML/HTML代码
- # 验证 pdftk 是否安装
- pdftk --version
- # 安装 pdftk
- sudo apt-get install pdftk
问题：打印机墨盒/纸盒信息无法获取
XML/HTML代码
- # 验证 ipptool 是否安装
- ipptool --version
- # 安装 cups-client
- sudo apt-get install cups-client
- # 测试 IPP 连接
- ipptool -t ipp://打印机 IP:631/ipp/print get-printer-attributes.test
问题：打印任务提交失败，打印提示成功但无输出
XML/HTML代码
- 确保cups打印机已正确配置，本项目打印office文档会转换成pdf，依赖cups将pdf转为打印机支持的光栅化格式，使用lpadmin添加打印机时确保带有-m everywhere参数，确保cups正确识别打印机支持的光栅化格式
- 确定cups的驱动和pdd文件是否正常，可能需要安装打印机厂商cups专属驱动或PDD文件
- 检查打印机是否处于空闲状态：lpstat -p
- 查看 CUPS 日志：/var/log/cups/error_log
- 检查打印机在线
第一个项目功能更全面更强大，第二个简单。
