家庭、小公司、小团队只有一台打印机，几台电脑却都要用？每台装驱动、来回插线太折腾。CUPS（Common UNIX Printing System）是 Linux/Unix 上最常用的打印中间件——装在 NAS、树莓派或小服务器上，局域网里的电脑、手机都能往它提交任务，由它统一转发到你的网络打印机。
本文带你 5 分钟 Docker 一键部署 CUPS：用轩辕镜像加速拉取 anujdatar/cups，一条 docker run（或 Compose）启动，Web 界面添加 HP Smart Tank 210-220 网络打印机并打出测试页——全程基于 Ubuntu 24.04 实测，命令可直接复制。
一、CUPS 是什么？
CUPS 是开源打印系统，负责接收客户端打印任务、管理队列、选择驱动，再把作业交给本地 USB 或网络打印机。OpenPrinting 维护的现代 CUPS 默认支持 IPP Everywhere™——不少新打印机无需单独厂商驱动即可工作。
镜像 anujdatar/cups 把 CUPS 打进容器，典型场景：
| 场景 | 说明 |
|---|---|
| 网络打印机共享 | 家庭 / 小公司 / 小团队共用一台打印机，省去每台装驱动 |
| 家庭 / 树莓派 | 轻量容器常开，不用长期开某台 PC |
| USB 打印机共享 | 挂载 /dev/bus/usb 后，把本机 USB 打印机共享到局域网（本文以网络打印机为例，无需挂载 USB） |
架构示意：
客户端设备 ──HTTP:631──▶ CUPS 容器 ──IPP/Socket──▶ 网络打印机
管理浏览器 ──http://服务器IP:631──▶ CUPS Web 界面
二、环境要求
| 项目 | 建议 |
|---|---|
| 操作系统 | Linux（本文 Ubuntu 24.04） |
| Docker | 已安装 Docker 与 Docker Compose V2 |
| 内存 | ≥ 256 MB（CUPS 容器极轻量） |
| CPU | 单核即可 |
| 磁盘 | ≥ 500 MB（镜像 + /etc/cups 配置持久化） |
| 端口 | 631（CUPS 默认 Web / IPP） |
| 网络 | 服务器与打印机在同一局域网，能互访 |
验证 Docker：
docker --version
docker compose version
若尚未安装 Docker，可使用轩辕镜像一键脚本：
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)
三、拉取镜像
使用轩辕镜像加速拉取（版本标签 26.07.01）：
docker pull docker.xuanyuan.run/anujdatar/cups:26.07.01
实测输出（摘要）：
26.07.01: Pulling from anujdatar/cups
...
Digest: sha256:d4a850f6c9af254411966011ac47521b97dde7d7184c16c5c92727cfc5f43d21
Status: Downloaded newer image for docker.xuanyuan.run/anujdatar/cups:26.07.01
docker.xuanyuan.run/anujdatar/cups:26.07.01
镜像页（可复制）：
https://xuanyuan.cloud/zh/r/anujdatar/cups
四、检查端口与持久化目录
4.1 确认 631 未被占用
ss -tlnp | grep 631
无输出表示端口空闲。若宿主机已装系统 CUPS，可先停用：
sudo systemctl stop cups
sudo systemctl disable cups
实测服务器上 未安装 系统 cups.service（提示 Unit cups.service not loaded），可忽略，直接进入下一步。
4.2 创建配置目录
CUPS 配置在容器 /etc/cups，挂载到宿主机后，重建容器也能保留打印机设置：
mkdir -p /www/wwwroot/webtop/cups-data
五、启动容器（docker run）
本文实测路径为 /www/wwwroot/webtop，网络打印机场景无需 --device /dev/bus/usb。
docker run -d \
--name cups \
--restart unless-stopped \
-p 631:631 \
-e TZ="Asia/Shanghai" \
-e CUPSADMIN=admin \
-e CUPSPASSWORD='123456' \
-v /www/wwwroot/webtop/cups-data:/etc/cups \
docker.xuanyuan.run/anujdatar/cups:26.07.01
| 参数 | 说明 |
|---|---|
-p 631:631 |
映射 CUPS Web / IPP 端口 |
TZ |
时区，国内建议 Asia/Shanghai |
CUPSADMIN / CUPSPASSWORD |
Web 管理登录凭据（下文界面使用 admin / 123456） |
-v ...:/etc/cups |
持久化打印机队列与配置 |
安全提示：示例密码
123456仅便于演示。生产环境务必改为强密码，且建议仅在内网访问 631，勿将管理口裸暴露到公网。
5.1 验证容器
docker ps | grep cups
docker logs cups
正常时 docker ps 类似：
374ab7cbfd55 docker.xuanyuan.run/anujdatar/cups:26.07.01 "/entrypoint.sh" ... Up ... 0.0.0.0:631->631/tcp, [::]:631->631/tcp, 5353/udp cups
日志关键片段：
+ useradd -r -G lpadmin -M admin
+ echo admin:123456
+ chpasswd
...
Current default time zone: 'Asia/Shanghai'
...
+ exec /usr/sbin/cupsd -f
说明管理员用户已创建，时区已设为上海，cupsd 前台运行中。
六、Docker Compose 方式（可选）
若偏好 Compose 管理，可在 /www/wwwroot/webtop 创建 docker-compose.yml：
services:
cups:
image: docker.xuanyuan.run/anujdatar/cups:26.07.01
container_name: cups
restart: unless-stopped
ports:
- "631:631"
environment:
- TZ=Asia/Shanghai
- CUPSADMIN=admin
- CUPSPASSWORD=123456
volumes:
- ./cups-data:/etc/cups
启动：
cd /www/wwwroot/webtop
mkdir -p cups-data
docker compose up -d
docker compose ps
docker compose logs -f cups
注意：同一台机器不要同时用
docker run和 Compose 起两个名为cups的容器。已用docker run部署成功则无需再 Compose；下文实测均基于docker run。
若以后要接 USB 打印机，在 Compose 中增加：
devices:
- /dev/bus/usb:/dev/bus/usb
或在 docker run 时追加 --device /dev/bus/usb。
七、确认打印机网络可达
添加前先在服务器上探测打印机（本文打印机 IP 为 192.168.1.20）：
ping -c 3 192.168.1.20
curl -I http://192.168.1.20
实测：
ping：0% 丢包，网络可达curl：HTTP 301，响应头识别为 HP Smart Tank 210-220 series (3D4L4A)
HTTP/1.1 301 Moved Permanently
Server: HP HTTP Server; HP Smart Tank 210-220 series - 3D4L4A; ...
Location: https://192.168.1.20/
若执行 curl -I ipp://192.168.1.20/ipp/print 报 Protocol "ipp" not supported，属正常现象——宿主机 curl 多数未编译 IPP 协议，不代表打印机不支持 IPP。以 CUPS Web 界面添加为准。
八、打开 CUPS 管理界面
浏览器访问（将 IP 换成你的 CUPS 服务器地址）：
http://你的服务器IP:631
实测地址为 http://192.168.1.18:631。首页显示 OpenPrinting CUPS 2.4.10，说明服务已就绪。
图 1：CUPS 首页 OpenPrinting CUPS 2.4.10
点顶部 Administration，浏览器会弹出登录框：
图 2：登录管理后台，用户名 admin，密码为启动容器时设置的 CUPSPASSWORD
输入启动容器时设置的账号密码（实测 admin / 123456），点 登录。
进入管理页后，左侧 Printers 区域有 Add Printer；右侧 Server Settings 可勾选 Share printers connected to this system、Allow remote administration（远程管理本机界面时需要），保存后点 Change Settings。
图 3：Administration 管理页，点击 Add Printer
九、添加网络打印机（HP Smart Tank）
9.1 选择连接协议
点 Add Printer，进入「添加打印机」向导。
Discovered Network Printers 可能为空（不会自动发现所有打印机，属正常）。向下找到 Other Network Printers，选中 互联网打印协议 (ipp) / Internet Printing Protocol (ipp)，点 Continue。
图 4：选择 IPP 协议（不要选 USB）
若 IPP 失败，可改选 AppSocket/HP JetDirect，连接串为
socket://192.168.1.20:9100。HP Smart Tank 系列优先 IPP。
9.2 填写连接 URI
在 Connection 输入框填写（本文实测可用）：
ipp://192.168.1.20/ipp/print
其他常见备选（按需再试）：
ipp://192.168.1.20:631/ipp/print
ipp://192.168.1.20/ipp/printer
点 Continue。
图 5：Connection 填写打印机 IPP 地址
9.3 命名并共享
| 字段 | 实测值 | 说明 |
|---|---|---|
| Name | HP-Home |
队列名，不要空格，勿含 /、# |
| Description | my Printer |
可读描述，可随意 |
| Location | （空） | 可选，如「客厅」 |
| Sharing | Share This Printer 勾选 | 局域网其他设备可通过本 CUPS 共享打印 |
点 Continue。
图 6：命名 HP-Home 并勾选共享
9.4 选择厂商与驱动
Make 列表中选择 HP，点 Continue。
图 7：厂商选择 HP
Model 列表中选择 IPP Everywhere™（列表顶部），然后点 Add Printer。
图 8：驱动选择 IPP Everywhere™
HP Smart Tank 210-220 原生支持 IPP Everywhere，无需精确到具体 hpcups 型号驱动。若列表中有 HP Smart Tank 210-220 series，亦可选用。
9.5 设置默认选项
进入「设置打印机选项」。实测将 Media Size 设为 A4，其余如 Media Type=Stationery、cupsPrintQuality=Normal、Output Mode=RGB，点 Set Default Options。
图 9：默认纸张设为 A4
9.6 确认添加成功
顶部点 Printers，进入打印机详情。状态应为：Idle, Accepting Jobs, Shared；驱动为 IPP Everywhere (color)；连接为 ipp://192.168.1.20/ipp/print。
图 10：HP-Home 就绪，Idle / Accepting Jobs / Shared
十、打印测试页
在打印机详情页打开 Maintenance 下拉菜单，选择 Print Test Page。
图 11：Maintenance → Print Test Page
页面提示测试页已提交：
Test page sent; job ID is HP-Home-1.
图 12：测试页已发送，Job ID 为 HP-Home-1
返回打印机页可见任务状态变为 Processing，Jobs 列表中 HP-Home-1 显示 Rendering completed：
图 13：作业处理中，Rendering completed
打印机吐出 CUPS 测试页（含 CMYK / RGB 色块、Job ID、ippeve.ppd 驱动信息等），则部署路径闭环成功。
图 14：物理测试页成功出纸
十一、局域网客户端怎么用？
打印机已勾选 Share This Printer 后，其他设备可通过 CUPS 服务器打印（队列名实测为 HP-Home）：
| 系统 | 大致步骤 |
|---|---|
| Windows | 添加打印机 → 按 IP → http://CUPS服务器IP:631/printers/HP-Home |
| macOS | 系统设置 → 打印机 → IP → 协议 IPP，地址填 CUPS 服务器 IP，队列填 HP-Home |
| Linux | lpadmin 或系统设置添加 IPP 打印机，URI 同上 |
| 浏览器 | 打开 http://CUPS服务器IP:631，在 Printers 中查看队列 |
把 CUPS服务器IP 换成你的地址（文中实测为 192.168.1.18）。
十二、常见问题 FAQ
Q1：浏览器打不开 http://IP:631？
docker ps确认容器为Up，端口映射631->631ss -tlnp | grep 631确认无冲突- 本机
curl -I http://127.0.0.1:631是否有响应 - ufw / 云安全组是否放行 631（建议仅内网）
Q2：Discovered Network Printers 是空的？
正常。许多网络打印机不会自动出现在发现列表，需手动选 Internet Printing Protocol (ipp) 并填写 URI。
Q3：curl ipp://... 报 Protocol not supported？
宿主机 curl 不支持 IPP，与打印机无关，直接在 CUPS Web 里添加即可。
Q4：IPP 页面一直转圈或失败？
- 先
ping打印机 IP - 浏览器打开
http://打印机IP看能否访问管理页 - 依次试
ipp://IP/ipp/print、ipp://IP:631/ipp/print、socket://IP:9100
Q5：如何升级镜像？
docker pull docker.xuanyuan.run/anujdatar/cups:26.07.01
docker stop cups && docker rm cups
# 重新执行第五节 docker run（保留同一 cups-data 卷）
Q6：如何停止与卸载？
# 停止并删除容器（保留配置）
docker stop cups && docker rm cups
# Compose 方式
cd /www/wwwroot/webtop && docker compose down
# 连同配置目录一起删（慎用）
rm -rf /www/wwwroot/webtop/cups-data
Q7：631 能暴露到公网吗？
不建议。CUPS 管理面暴露在公网风险高。只开放内网，或走 VPN / 反向代理并做好认证。
十三、命令速查
| 操作 | 命令 | |
|---|---|---|
| 拉取镜像 | docker pull docker.xuanyuan.run/anujdatar/cups:26.07.01 |
|
| 快速启动 | 见第五节 docker run |
|
| Compose 启动 | cd /www/wwwroot/webtop && docker compose up -d |
|
| 查看状态 | `docker ps \ | grep cups` |
| 查看日志 | docker logs -f cups |
|
| 管理界面 | http://服务器IP:631 |
|
| 停止 | docker stop cups |
|
| 删除（保留数据） | docker rm cups（cups-data 仍在） |
总结
CUPS = 家庭与小团队局域网打印共享，5 分钟一条命令就能跑：
- 使用轩辕镜像加速拉取
anujdatar/cups:26.07.01 docker run或 Compose 一键映射 631，持久化cups-data- Web 添加网络打印机：
ipp://打印机IP/ipp/print+ IPP Everywhere™ - Maintenance → Print Test Page，确认物理出纸
延伸阅读（复制打开）：
anujdatar/cups 轩辕镜像页：
https://xuanyuan.cloud/zh/r/anujdatar/cups
项目源码：
https://github.com/anujdatar/cups-docker
轩辕镜像首页：
https://xuanyuan.cloud
轩辕镜像使用手册：
https://xuanyuan.cloud/usage
如果你在拉取 Docker 镜像时遇到速度慢、超时等问题，可以试试轩辕镜像的加速服务。欢迎收藏 anujdatar/cups 镜像页，获取最新标签与更新说明：
https://xuanyuan.cloud/zh/r/anujdatar/cups
本文基于 anujdatar/cups:26.07.01 镜像（OpenPrinting CUPS 2.4.10），Ubuntu 24.04 服务器实测
