本文基于 hanxi/cups-web:v0.2.3Ubuntu 24.04实测。文末链路含登录、添加打印机、上传打印与出纸等21张截图。家里只有一台 USB 喷墨机、小办公室角落放着一台激光机——这是最常见的配置。麻烦不在「有没有打印机」而在「谁都能方便地用上它」Windows 要装厂商套件macOS 偶发驱动不匹配Linux 还得翻 PPD手机拍完合同、平板改完表格却只能先传到某台「专职打印电脑」再点打印笔记本换了、重装系统了驱动又要从头来一遍。USB 打印机尤其吃亏线插在哪台主机上哪台才能打同事来回拔线、抢那台开机的 PC打印这件事就被绑死在物理位置上。即便换成网络打印机、或在 NAS / 小主机上跑一套CUPSCommon UNIX Printing System也只是解决了「中间件能转发作业」这一层。CUPS 自带的 Web 管理页默认:631偏运维添加队列、选驱动、打测试页可以但对家里老人、前台同事、出差只带浏览器的人不友好——他们要的是「打开网页、上传文件、选打印机、点打印」以及「我打过什么、打成功没有」而不是登录 CUPS 管理后台、理解队列与 PPD。共享目录里丢 PDF、微信传文件再找人代打既难审计也容易把合同扫描件、工资条这类材料散落在聊天记录和私人电脑里。公有云「在线打印」或厂商云打印能少装驱动但文档要先上传到对方平台按页或按账号计费内网断公网、合规要求「文件不出域」、或只想在客厅 NAS / 办公室小主机上常开一台打印门户时就不合适。你需要的是打印机仍接在自己机器上打印服务跑在自己 Docker 里浏览器打开内网地址就能用——上传的原稿与转换后的 PDF、用户账号与打印记录都落在本地卷而不是某家 SaaS。手工在宿主机装 CUPS、配 LibreOffice 转 Office、再写一层上传网站对多数家庭与小团队成本偏高。CUPS WebGitHub: hanxi/cups-web把这件事收成一条 Compose官方镜像把cupsd 网页打印门户打进同一容器AIO。浏览器登录后可上传 PDF、图片含 HEIC、多图合并、Office、OFD、文本等服务端转换并带预览后再提交到 CUPS支持多用户与角色、打印历史、管理员侧的驱动扫描 / 一键安装以及数据保留策略。它不是「再换一台物理打印机」而是站在打印机前面的自托管网页打印站——普通用户走:1180上传打印管理员仍可用:631管队列或在 Web「驱动」页装厂商驱动。上手要点镜像坐标用hanxi/cups-web推荐钉死v0.2.3勿再跟早期文档的「hanxi/cupshanxi/cups-web双服务」。宿主机映射1180→8080Web、631→631CUPS。Web 首次默认admin/admin登录后立刻改密CUPS 管理员由环境变量提供本文实测print/123456。长期运行必须挂载.etc/.data/.uploads/.drivers四套目录——漏挂.drivers等于手动装过的第三方驱动重启后全丢。USB 场景请用目录挂载/dev/bus/usbdevice_cgroup_rules支持热插拔不要用一次性的devices:局域网网络打印机请在:631手动填 IPP驱动页扫描经常为空属正常添加后务必勾选Share This Printer。本文按「能跟做」写完整链路用 轩辕镜像加速拉取hanxi/cups-web:v0.2.3Compose 拉起单容器浏览器登录 Web、在 CUPS 用 IPP 添加 HP Smart Tank再上传 Word 完成一次远程打印并出纸。另附发票/身份证模式、备份升级与 FAQ。若只要「CUPS 中间件、在:631添加网络打印机」而不需要上传门户与多用户可另见本站 anujdatar/cups 教程。镜像说明见 hanxi/cups-web 镜像页标签列表见 tags。一、CUPS Web 是什么一句话CUPS Web 自托管网页打印门户 内置 CUPS。用户在浏览器里上传文件、选打印机、调份数/双面等管理员管用户、记录、驱动与数据保留。1.1 和「只跑 CUPS」差在哪只跑 CUPS如 anujdatar/cupsCUPS Web本文管理界面偏运维:631面向普通用户的上传 / 预览 / 打印一般不自带多用户门户admin/user角色 打印记录文档转换要自己配镜像内 LibreOffice / OFD / 字体等开箱驱动靠手动进容器装Web「驱动」页 持久化.drivers1.2 核心能力能力说明多格式打印PDF、图片含 HEIC、多图合并、Office、OFD、文本/Markdown/HTML打印模式标准打印、发票打印、身份证正反面排版打印选项份数、单双面、彩/黑白、纸张、方向、页码范围、缩放等用户体系默认admin/admin可建普通用户管理后台用户、全站打印记录、数据保留天数驱动管理扫描打印机、一键安装厂商驱动、上传.ppd/.deb管理员安全Session、CSRF、bcrypt 存密1.3 架构本文 Compose AIO浏览器 ──HTTP:1180──▶ cups 容器(:8080 cups-web) │ ├── cupsd (:631同容器) ├── ./.data → /data ├── ./.uploads → /uploads ├── ./.etc → /etc/cups └── ./.drivers → /opt/cups-drivers/data 管理浏览器 ──HTTP:631──▶ 同一容器内 CUPS 管理页添加/共享打印机 网络打印机 ──IPP──▶ ipp://192.168.1.29/ipp/print本文实测二、环境要求项目建议系统Linux 建议Ubuntu 24.04本文实测DockerEngine Compose V2docker compose内存演示建议 ≥12 GB含 LibreOffice / OFD 转换时更吃内存磁盘镜像约2.45 GB本地docker images 上传文件增长端口1180Web、631CUPS均勿被占用打印机USB 直连或同网段网络打印机本文为 HP Smart Tank 网络机目录/www/wwwroot/cups-webdocker--versiondockercompose versionLinux 未装 Docker 可使用轩辕镜像一键安装脚本bash(wget-qO- https://xuanyuan.cloud/docker.sh)更多见 轩辕镜像使用手册。无 USB 的环境可删掉 Compose 里/dev/bus/usb、/run/udev与device_cgroup_rules仅用网络打印机本文即此场景。三、标签怎么选标签说明推荐v0.2.3本文实测稳定版与latest同 digest试用 / 生产钉死首选latest跟踪最新稳定构建仅临时试用生产请钉v0.2.xmaster跟踪主分支构建偏开发勿当生产默认v0.2.2/v0.2.0等历史版本回滚或对照 issue 时使用标签列表xuanyuan.cloud/r/hanxi/cups-web/tags。勿混用旧双容器文档早期 README 曾写hanxi/cupshanxi/cups-web两个服务。当前官方仓库已改为单镜像 AIO请以本文 Compose 为准。四、拉取镜像轩辕镜像加速sudomkdir-p/www/wwwroot/cups-webcd/www/wwwroot/cups-webdockerpull docker.xuanyuan.run/hanxi/cups-web:v0.2.3实测拉取输出Ubuntu 24.04v0.2.3: Pulling from hanxi/cups-web 4f4fb700ef54: Pull complete 062e450697fa: Pull complete 2c69eb8fdb6b: Pull complete bb8ea9eb6151: Pull complete 72af2644f066: Pull complete 65ede3d2ae82: Pull complete 12c8fbb8377f: Pull complete a860f1da36ae: Pull complete 20f2a973b235: Pull complete 37994f0a3f11: Pull complete 82a26b58e8a9: Pull complete 933bdaecd794: Pull complete 6930b50503cb: Pull complete 18c72b7b1760: Pull complete bef7d948fcdf: Pull complete 730994c57352: Pull complete 90c0316a86ea: Pull complete 538e0991238d: Pull complete 60176d4044db: Pull complete 44c6a71272e8: Pull complete fbd265df4376: Pull complete 0866d0a24c34: Pull complete 467ad5ac18b0: Pull complete fc6b237492e3: Pull complete 2fe597f62258: Download complete Digest: sha256:f0cb0560b873740f30a82e056353480393c226b422f2f9156e6954846c9c2dd4 Status: Downloaded newer image for docker.xuanyuan.run/hanxi/cups-web:v0.2.3 docker.xuanyuan.run/hanxi/cups-web:v0.2.3确认本地镜像dockerimages实测可见类似IMAGE ID DISK USAGE CONTENT SIZE docker.xuanyuan.run/hanxi/cups-web:v0.2.3 f0cb0560b873 2.45GB 698MB官方镜像轩辕镜像加速拉取hanxi/cups-web:v0.2.3docker pull docker.xuanyuan.run/hanxi/cups-web:v0.2.3五、Compose 部署推荐5.1 创建目录与环境变量cd/www/wwwroot/cups-webmkdir-p.etc .data .uploads .driverscat.envEOF CUPSADMINprint CUPSPASSWORD123456 TZAsia/Shanghai EOF本文实测CUPSPASSWORD123456仅作演示。生产请改成强密码并限制.env权限如chmod 600 .env。不写.env时镜像默认print/print。5.2 编写docker-compose.yml以下与官方仓库对齐镜像坐标改为轩辕加速前缀并钉死v0.2.3services:cups:image:docker.xuanyuan.run/hanxi/cups-web:v0.2.3container_name:cupsuser:rootsecurity_opt:-apparmor:unconfinedenvironment:-CUPSADMIN${CUPSADMIN:-print}-CUPSPASSWORD${CUPSPASSWORD:-print}-TZ${TZ:-Asia/Shanghai}ports:-631:631-1180:8080volumes:-./.etc:/etc/cups-./.data:/data-./.uploads:/uploads-./.drivers:/opt/cups-drivers/data-/dev/bus/usb:/dev/bus/usb-/run/udev:/run/udev:rodevice_cgroup_rules:-c 189:* rmwrestart:unless-stopped变体说明场景改法无 USB / 无/dev/bus/usb删除 USB、/run/udev、device_cgroup_rules三处Docker 不支持device_cgroup_rules删除该字段改privileged: true权限更宽无/run/udev删除该 volume 行即可端口冲突改左侧1631:631、1180:8080等5.3 启动与验证dockercompose up-ddockercomposepsdockercompose logs--tail80cups实测psNAME IMAGE COMMAND SERVICE CREATED STATUS PORTS cups docker.xuanyuan.run/hanxi/cups-web:v0.2.3 /entrypoint.sh cups 10 seconds ago Up 9 seconds 0.0.0.0:631-631/tcp, [::]:631-631/tcp, 0.0.0.0:1180-8080/tcp, [::]:1180-8080/tcp实测日志关键行Current default time zone: Asia/Shanghai [entrypoint] dispatching hplj1020 in background; log: /var/log/cups/hp-firmware.log ... 2026/07/31 11:30:28 default admin created: admin 2026/07/31 11:30:28 [SECURITY WARNING] 已创建默认管理员 admin/admin请立即登录并修改密码 listening on :8080浏览器访问按实测 IPWeb 门户http://192.168.1.10:1180CUPS 管理http://192.168.1.10:631六、浏览器首次使用配图线上地址统一为https://img.xuanyuan.dev/docker/blog/cups-web-{N}.webp共21张。6.1 登录 Web 门户打开http://192.168.1.10:1180使用默认账号admin/admin登录页脚可见v0.2.3。首次登录后请立刻修改默认密码。登录后进入「打印」主界面可选打印机、标准/发票/身份证三种模式左侧上传文件与打印参数右侧预览与记录。此时若尚未添加打印机「选择打印机」为空属正常。6.2 在 CUPS 添加局域网打印机推荐先分清两条路USB 直连可用 Web「驱动」页扫描。局域网网络打印机驱动页「扫描」经常为空Docker bridge 下 mDNS 发现不可靠属常见情况。请走本节在:631手动填 IPP。6.2.1 先确认打印机 IP 可达添加前在宿主机探测把 IP 换成你的本文正确地址为192.168.1.29ping-c3192.168.1.29实测曾误填192.168.1.20宿主机 ping 全丢、:631Add Printer 报Host is down。以打印机面板 / 路由器 DHCP 为准IP 写错时任何驱动都救不了。另镜像内可能没有ping命令docker exec cups ping会报 not found宿主机能 ping 通即可容器侧可用/dev/tcp测端口。6.2.2 打开 CUPS 管理页并登录浏览器打开http://192.168.1.10:631可见OpenPrinting CUPS 2.4.19首页。点顶部Administration或「CUPS for Administrators」里的 Adding Printers。访问管理功能时浏览器会弹出登录框用户名填print即.env的CUPSADMIN密码填你设置的CUPSPASSWORD本文为123456。进入 Administration 后在 Printers 区域点Add Printer。建议勾选Share printers connected to this system、Allow remote administration按需再Change Settings。6.2.3 选择 IPP 并填写 ConnectionDiscovered Network Printers 为空可忽略。滚到Other Network Printers选中Internet Printing Protocol (ipp)点Continue。Connection 填入本文实测ipp://192.168.1.29/ipp/print也可尝试ipp://192.168.1.29:631/ipp/print、ipp://192.168.1.29/ipp/printer若 IPP 不通而 9100 通改选 AppSocket填socket://192.168.1.29:9100。6.2.4 命名并勾选共享Name 例如HP-HomeDescription 随意务必勾选Share This Printer否则 Web 门户列表看不到。点Continue。6.2.5 选择厂商与型号Make 选HP→ Continue。Model 优先选列表顶部的IPP Everywhere™现代网络机通用再点Add Printer。若列表有具体型号亦可。6.2.6 默认选项与确认进入 Set Default OptionsMedia Size 建议A4按需设置纸型与质量点Set Default Options。成功提示Printer HP-Home default options have been set successfully.打开Printers→HP-Home状态应为Idle, Accepting Jobs, SharedConnection 为ipp://192.168.1.29/ipp/print。本文驱动显示为Smart Tank 210-220 series - IPP Everywhere (color)。6.3 回到 Web选机、上传、打印返回http://192.168.1.10:1180在「选择打印机」下拉选中HP-Home点刷新右侧「打印机状态」应显示空闲。除标准打印外还可切换发票打印适合票据类多文件上传可强制黑白等身份证打印分别上传正反面可选 A4 / A5 排版标准打印实测上传开户确认书.docx约 11 KB系统提示已转换为 PDF可以打印右侧出现 A4 预览。调好彩色/双面/份数后点开始打印。提交成功会弹出打印任务已提交含任务 ID如ipp://localhost:631/jobs/2。「打印记录」出现已打印条目「打印机状态」可看到墨盒余量、纸盒信息等取决于打印机上报能力。打印机吐出的纸件与预览一致即整条链路跑通。支持格式摘要PDF图片 jpg/png/gif/heic可多图合并Office doc(x)/xls(x)/ppt(x)OFDtxt/md/html。6.4 管理后台与驱动页管理员导航管理用户管理、全站打印记录、数据保留天数0 永久。导航驱动更适合 USB / 可扫描机型的一键装驱动局域网机优先用上文:631IPP 流程。上传.deb会以 root 执行安装脚本只信来源可信的包。七、生产注意与备份改密Webadmin、CUPSCUPSPASSWORD都要改勿把 1180/631 无防护裸奔公网建议内网 反向代理 HTTPS 防火墙。钉版本生产用v0.2.3勿裸跟latest/master。备份四件套cd/www/wwwroot/cups-webcp./.data/cups-web.db /backup/cups-web-$(date%F).dbtar-czf/backup/cups-uploads-$(date%F).tar.gz ./.uploads/tar-czf/backup/cups-etc-$(date%F).tar.gz ./.etc/tar-czf/backup/cups-drivers-$(date%F).tar.gz ./.drivers/删掉或忘记挂载.drivers 手动安装的第三方驱动全部丢失需在「驱动」页重装。HTTPS用 Nginx / Caddy 反代http://127.0.0.1:1180并设置X-Forwarded-*。八、升级与迁移cd/www/wwwroot/cups-webdockerpull docker.xuanyuan.run/hanxi/cups-web:v0.2.3# 或更新后的新版本号# 先改 docker-compose.yml 中的 tagdockercompose up-d数据在宿主机卷内一般升级不丢库大版本仍建议先备份四件套。跨架构迁移.drivers时列表可能提示架构不符需重装驱动。九、常见问题 FAQQ1Web「驱动」页扫描不到局域网打印机常见且多半正常。扫描依赖发现协议在 Dockerbridge下对局域网 mDNS 往往无效。网络机请到http://服务器IP:631选Other Network Printers → ipp手动填ipp://打印机IP/ipp/print见第六节。Q2Add Printer 报Unable to connect to …:631: Host is down表示 CUPS 连不上该 IP主机不可达或端口未开。实测常见原因是打印机 IP 写错例如误用.20、实际为.29。按序查面板/DHCP 确认 IP → 宿主机ping→ 再填 IPP631 不通可试socket://IP:9100。Q3docker exec cups ping提示 not found镜像可能未装ping属正常。在宿主机 ping 即可容器内可用dockerexeccupsbash-ctimeout 5 bash -c echo /dev/tcp/192.168.1.29/631 echo ok || echo failQ4Web 里看不到已添加的打印机确认添加时勾选了Share This Printer状态含Shared在 Web 点「刷新」或docker compose restart cups。Q5USB 打印机后开机识别不到须用目录挂载/dev/bus/usbdevice_cgroup_rules或privileged: true不要用一次性的devices:。Q6忘记 Web 管理员密码停服务后删除数据库会重置为admin/admin清空全部用户与记录dockercompose downrm./.data/cups-web.dbdockercompose up-dQ7Office / OFD 转换失败转换有约60 秒超时。可本地先转 PDF 再上传查日志docker compose logs -f cups。Q8和本站 anujdatar/cups 教程什么关系anujdatar/cups侧重纯 CUPS本文侧重上传门户 多用户。网络打印机 IPP 添加步骤可互相对照。Q9Apparmor DENIED / 打印失败PVE LXC 等保留security_opt: apparmor:unconfined官方针对 issue #91。十、命令速查cd/www/wwwroot/cups-webdockerpull docker.xuanyuan.run/hanxi/cups-web:v0.2.3dockercompose up-ddockercomposepsdockercompose logs-fcupsdockercompose restart cupsdockercompose downdockerexeccups driver-listdockerexeccups driver-install canon-ufr2十一、延伸阅读hanxi/cups-web 镜像页标签列表GitHub hanxi/cups-webDocker Hub hanxi/cups-web本站 anujdatar/cups 部署教程纯 CUPS轩辕镜像使用手册总结用 轩辕镜像 加速拉取并钉死hanxi/cups-web:v0.2.3Digestf0cb0560b873…单容器 AIOCompose 映射1180/631挂载.etc/.data/.uploads/.driversWeb 默认admin/adminCUPS 用.env账号本文print/123456——均需改密局域网机用ipp://打印机IP/ipp/print手动添加并勾选Share This Printer本文192.168.1.29浏览器上传 Word/PDF → 预览 → 开始打印发票/身份证模式开箱可用