一台打印机全办公室共用：5 分钟 Docker 一键部署 CUPS

本文基于 anujdatar/cups:26.07.01 镜像（OpenPrinting CUPS 2.4.10），Ubuntu 24.04 服务器实测

家里有一台联网打印机，却只有插在旁边的那台电脑能打？想给手机、笔记本、家里别的电脑都用上，又懒得每台装驱动？CUPS（Common UNIX Printing System）是 Linux/Unix 世界里最常用的打印中间件——装在服务器上，局域网设备都能往它提交任务，由它转发到你的网络打印机。

本文带你完成一次 CUPS Docker 一键部署：用 轩辕镜像 加速拉取 anujdatar/cups，docker run（或 Compose）启动，在 Web 管理界面添加 HP Smart Tank 210-220 网络打印机，打出测试页——全程基于 Ubuntu 24.04 实测，命令可直接复制，文末附 14 张截图。

实测环境：CUPS 服务器 IP 192.168.1.18，打印机 IP 192.168.1.20。国内拉取使用加速域 docker.xuanyuan.run。项目说明见 GitHub anujdatar/cups-docker。

---

一、CUPS 是什么？

CUPS 是开源打印系统，负责接收客户端打印任务、管理队列、选择驱动，再把作业交给本地 USB 或网络打印机。OpenPrinting 维护的现代 CUPS 默认支持 IPP Everywhere™——不少新打印机无需单独厂商驱动即可工作。

镜像 anujdatar/cups 把 CUPS 打进容器，典型场景：

架构示意：

text
客户端设备 ──HTTP:631──▶ CUPS 容器 ──IPP/Socket──▶ 网络打印机
管理浏览器 ──http://服务器IP:631──▶ CUPS Web 界面

---

二、环境要求

验证 Docker：

bash
docker --version
docker compose version

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

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

更多安装说明见 轩辕镜像使用手册。

---

三、拉取镜像

使用轩辕镜像加速拉取（版本标签 26.07.01）：

bash
docker pull docker.xuanyuan.run/anujdatar/cups:26.07.01

实测输出（摘要）：

text
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

镜像页：anujdatar/cups。其他标签见该页「标签列表」。

---

四、检查端口与持久化目录

4.1 确认 631 未被占用

bash
ss -tlnp | grep 631

无输出表示端口空闲。若宿主机已装系统 CUPS，可先停用：

bash
sudo systemctl stop cups
sudo systemctl disable cups

实测服务器上 未安装 系统 cups.service（Failed to stop cups.service: Unit cups.service not loaded.），可忽略该提示，直接进入下一步。

4.2 创建配置目录

CUPS 配置在容器 /etc/cups，挂载到宿主机后，重建容器也能保留打印机设置：

bash
mkdir -p /www/wwwroot/webtop/cups-data

---

五、启动容器（docker run）

本文实测路径为 /www/wwwroot/webtop，网络打印机场景无需 --device /dev/bus/usb。

bash
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

安全提示：示例密码 123456 仅便于演示。生产环境务必改为强密码，且建议仅在内网访问 631，勿将管理口裸暴露到公网。

5.1 验证容器

bash
docker ps | grep cups
docker logs cups

正常时 docker ps 类似：

text
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

日志关键片段：

text
+ 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：

yaml
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

启动：

bash
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 中增加：

yaml
    devices:
      - /dev/bus/usb:/dev/bus/usb

或在 docker run 时追加 --device /dev/bus/usb。

---

七、确认打印机网络可达

添加前先在服务器上探测打印机（本文打印机 IP 为 192.168.1.20）：

bash
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)

text
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，说明服务已就绪。

点顶部 Administration，浏览器会弹出登录框：

输入启动容器时设置的账号密码（实测 admin / 123456），点 登录。

进入管理页后，左侧 Printers 区域有 Add Printer；右侧 Server Settings 可勾选 Share printers connected to this system、Allow remote administration（远程管理本机界面时需要），保存后点 Change Settings。

---

九、添加网络打印机（HP Smart Tank）

9.1 选择连接协议

点 Add Printer，进入「添加打印机」向导。

Discovered Network Printers 可能为空（不会自动发现所有打印机，属正常）。向下找到 Other Network Printers，选中 互联网打印协议 (ipp) / Internet Printing Protocol (ipp)，点 Continue。

若 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。

9.3 命名并共享

点 Continue。

9.4 选择厂商与驱动

Make 列表中选择 HP，点 Continue。

Model 列表中选择 IPP Everywhere™（列表顶部），然后点 Add Printer。

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.6 确认添加成功

顶部点 Printers，进入打印机详情。状态应为：Idle, Accepting Jobs, Shared；驱动为 IPP Everywhere (color)；连接为 ipp://192.168.1.20/ipp/print。

---

十、打印测试页

在打印机详情页打开 Maintenance 下拉菜单，选择 Print Test Page。

页面提示测试页已提交：

text
Test page sent; job ID is HP-Home-1.

返回打印机页可见任务状态变为 Processing，Jobs 列表中 HP-Home-1 显示 Rendering completed：

打印机吐出 CUPS 测试页（含 CMYK / RGB 色块、Job ID、ippeve.ppd 驱动信息等），则部署路径闭环成功。

---

十一、局域网客户端怎么用？

打印机已勾选 Share This Printer 后，其他设备可通过 CUPS 服务器打印（队列名实测为 HP-Home）：

把 CUPS服务器IP 换成你的地址（文中实测为 192.168.1.18）。

---

十二、常见问题 FAQ

Q1：浏览器打不开 http://IP:631？

• docker ps 确认容器为 Up，端口映射 631->631
• ss -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：如何升级镜像？

bash
docker pull docker.xuanyuan.run/anujdatar/cups:26.07.01
docker stop cups && docker rm cups
# 重新执行第五节 docker run（保留同一 cups-data 卷）

Q6：如何停止与卸载？

bash
# 停止并删除容器（保留配置）
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 / 反向代理并做好认证。

---

十三、命令速查

---

十四、延伸阅读

• 轩辕镜像页：anujdatar/cups
• 项目源码：anujdatar/cups-docker
• OpenPrinting CUPS：项目首页与文档
• 轩辕镜像 Docker 安装与加速：使用手册

至此，从拉镜像、起容器、添加 HP Smart Tank（192.168.1.20）到吐出测试页，整条链路已在 Ubuntu 24.04 上跑通。把队列共享出去，家里其他设备就可以统一通过这台 CUPS 服务器打印了。