本文基于 hanxi/cups-web:v0.2.3，Ubuntu 24.04实测。文末链路含登录、添加打印机、上传打印与出纸等21张截图。

家里只有一台 USB 喷墨机、小办公室角落放着一台激光机——这是最常见的配置。麻烦不在「有没有打印机」，而在「谁都能方便地用上它」：Windows 要装厂商套件，macOS 偶发驱动不匹配，Linux 还得翻 PPD；手机拍完合同、平板改完表格，却只能先传到某台「专职打印电脑」再点打印；笔记本换了、重装系统了，驱动又要从头来一遍。USB 打印机尤其吃亏：线插在哪台主机上，哪台才能打，同事来回拔线、抢那台开机的 PC，打印这件事就被绑死在物理位置上。

即便换成网络打印机、或在 NAS / 小主机上跑一套CUPS（Common UNIX Printing System），也只是解决了「中间件能转发作业」这一层。CUPS 自带的 Web 管理页（默认:631）偏运维：添加队列、选驱动、打测试页可以，但对家里老人、前台同事、出差只带浏览器的人不友好——他们要的是「打开网页、上传文件、选打印机、点打印」，以及「我打过什么、打成功没有」；而不是登录 CUPS 管理后台、理解队列与 PPD。共享目录里丢 PDF、微信传文件再找人代打，既难审计，也容易把合同扫描件、工资条这类材料散落在聊天记录和私人电脑里。

公有云「在线打印」或厂商云打印能少装驱动，但文档要先上传到对方平台，按页或按账号计费，内网断公网、合规要求「文件不出域」、或只想在客厅 NAS / 办公室小主机上常开一台打印门户时，就不合适。你需要的是：打印机仍接在自己机器上，打印服务跑在自己 Docker 里，浏览器打开内网地址就能用——上传的原稿与转换后的 PDF、用户账号与打印记录，都落在本地卷，而不是某家 SaaS。

手工在宿主机装 CUPS、配 LibreOffice 转 Office、再写一层上传网站，对多数家庭与小团队成本偏高。CUPS Web（GitHub: hanxi/cups-web）把这件事收成一条 Compose：官方镜像把cupsd + 网页打印门户打进同一容器（AIO）。浏览器登录后可上传 PDF、图片（含 HEIC、多图合并）、Office、OFD、文本等，服务端转换并带预览后再提交到 CUPS；支持多用户与角色、打印历史、管理员侧的驱动扫描 / 一键安装，以及数据保留策略。它不是「再换一台物理打印机」，而是站在打印机前面的自托管网页打印站——普通用户走:1180上传打印，管理员仍可用:631管队列，或在 Web「驱动」页装厂商驱动。

上手要点：镜像坐标用hanxi/cups-web（推荐钉死v0.2.3；勿再跟早期文档的「hanxi/cups+hanxi/cups-web双服务」）。宿主机映射1180→8080（Web）、631→631（CUPS）。Web 首次默认admin/admin，登录后立刻改密；CUPS 管理员由环境变量提供（本文实测print/123456）。长期运行必须挂载.etc/.data/.uploads/.drivers四套目录——漏挂.drivers等于手动装过的第三方驱动重启后全丢。USB 场景请用目录挂载/dev/bus/usb+device_cgroup_rules（支持热插拔），不要用一次性的devices:；局域网网络打印机请在:631手动填 IPP（驱动页扫描经常为空，属正常），添加后务必勾选Share This Printer。

本文按「能跟做」写完整链路：用 轩辕镜像加速拉取hanxi/cups-web:v0.2.3，Compose 拉起单容器，浏览器登录 Web、在 CUPS 用 IPP 添加 HP Smart Tank，再上传 Word 完成一次远程打印并出纸。另附发票/身份证模式、备份升级与 FAQ。若只要「CUPS 中间件、在:631添加网络打印机」而不需要上传门户与多用户，可另见本站 anujdatar/cups 教程。

镜像说明见 hanxi/cups-web 镜像页，标签列表见 tags。

一、CUPS Web 是什么？

一句话：CUPS Web = 自托管网页打印门户 + 内置 CUPS。用户在浏览器里上传文件、选打印机、调份数/双面等；管理员管用户、记录、驱动与数据保留。

1.1 和「只跑 CUPS」差在哪？

1.2 核心能力

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（本文实测）

二、环境要求

docker--versiondockercompose version

Linux 未装 Docker 可使用轩辕镜像一键安装脚本：

bash<(wget-qO- https://xuanyuan.cloud/docker.sh)

更多见 轩辕镜像使用手册。

无 USB 的环境：可删掉 Compose 里/dev/bus/usb、/run/udev与device_cgroup_rules，仅用网络打印机（本文即此场景）。

三、标签怎么选

标签列表：xuanyuan.cloud/r/hanxi/cups-web/tags。

勿混用旧双容器文档：早期 README 曾写hanxi/cups+hanxi/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.04）：

v0.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

五、Compose 部署（推荐）

5.1 创建目录与环境变量

cd/www/wwwroot/cups-webmkdir-p.etc .data .uploads .driverscat>.env<<'EOF' CUPSADMIN=print CUPSPASSWORD=123456 TZ=Asia/Shanghai EOF

本文实测CUPSPASSWORD=123456仅作演示。生产请改成强密码，并限制.env权限（如chmod 600 .env）。不写.env时镜像默认print/print。

5.2 编写docker-compose.yml

以下与官方仓库对齐，镜像坐标改为轩辕加速前缀，并钉死v0.2.3：

services: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:8080"volumes:-./.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:* rmw'restart:unless-stopped

变体说明：

5.3 启动与验证

dockercompose up-ddockercomposepsdockercompose logs--tail=80cups

实测ps：

NAME 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

浏览器访问（按实测 IP）：

• Web 门户：http://192.168.1.10:1180
• CUPS 管理：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.29）：

ping-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 并填写 Connection

Discovered 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-Home，Description 随意；务必勾选Share This Printer，否则 Web 门户列表看不到。点Continue。

6.2.5 选择厂商与型号

Make 选HP→ Continue。

Model 优先选列表顶部的IPP Everywhere™（现代网络机通用），再点Add Printer。若列表有具体型号亦可。

6.2.6 默认选项与确认

进入 Set Default Options：Media Size 建议A4，按需设置纸型与质量，点Set Default Options。

成功提示：Printer HP-Home default options have been set successfully.

打开Printers→HP-Home，状态应为Idle, Accepting Jobs, Shared；Connection 为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)；OFD；txt/md/html。

6.4 管理后台与驱动页（管理员）

导航管理：用户管理、全站打印记录、数据保留天数（0= 永久）。
导航驱动：更适合 USB / 可扫描机型的一键装驱动；局域网机优先用上文:631IPP 流程。上传.deb会以 root 执行安装脚本，只信来源可信的包。

七、生产注意与备份

1. 改密：Webadmin、CUPSCUPSPASSWORD都要改；勿把 1180/631 无防护裸奔公网（建议内网 + 反向代理 HTTPS + 防火墙）。
2. 钉版本：生产用v0.2.3，勿裸跟latest/master。
3. 备份四件套：

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= 手动安装的第三方驱动全部丢失，需在「驱动」页重装。

4. 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时，列表可能提示架构不符，需重装驱动。

九、常见问题 FAQ

Q1：Web「驱动」页扫描不到局域网打印机？
常见且多半正常。扫描依赖发现协议，在 Dockerbridge下对局域网 mDNS 往往无效。网络机请到http://服务器IP:631选Other Network Printers → ipp，手动填ipp://打印机IP/ipp/print（见第六节）。

Q2：Add Printer 报Unable to connect to …:631: Host is down？
表示 CUPS 连不上该 IP（主机不可达或端口未开）。实测常见原因是打印机 IP 写错（例如误用.20、实际为.29）。按序查：面板/DHCP 确认 IP → 宿主机ping→ 再填 IPP；631 不通可试socket://IP:9100。

Q3：docker exec cups ping提示 not found？
镜像可能未装ping，属正常。在宿主机 ping 即可；容器内可用：

dockerexeccupsbash-c'timeout 5 bash -c "echo >/dev/tcp/192.168.1.29/631" && echo ok || echo fail'

Q4：Web 里看不到已添加的打印机？
确认添加时勾选了Share This Printer，状态含Shared；在 Web 点「刷新」，或docker compose restart cups。

Q5：USB 打印机后开机识别不到？
须用目录挂载/dev/bus/usb+device_cgroup_rules（或privileged: true），不要用一次性的devices:。

Q6：忘记 Web 管理员密码？
停服务后删除数据库会重置为admin/admin，清空全部用户与记录：

dockercompose downrm./.data/cups-web.dbdockercompose up-d

Q7：Office / OFD 转换失败？
转换有约60 秒超时。可本地先转 PDF 再上传；查日志：docker compose logs -f cups。

Q8：和本站 anujdatar/cups 教程什么关系？
anujdatar/cups侧重纯 CUPS；本文侧重上传门户 + 多用户。网络打印机 IPP 添加步骤可互相对照。

Q9：Apparmor 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-web
• Docker Hub hanxi/cups-web
• 本站 anujdatar/cups 部署教程（纯 CUPS）
• 轩辕镜像使用手册

总结

• 用 轩辕镜像 加速拉取并钉死hanxi/cups-web:v0.2.3（Digestf0cb0560b873…）
• 单容器 AIO：Compose 映射1180/631，挂载.etc/.data/.uploads/.drivers
• Web 默认admin/admin；CUPS 用.env账号（本文print/123456）——均需改密
• 局域网机用ipp://打印机IP/ipp/print手动添加，并勾选Share This Printer（本文192.168.1.29）
• 浏览器上传 Word/PDF → 预览 → 开始打印；发票/身份证模式开箱可用