家庭、小公司、小团队只有一台打印机，几台电脑却都要用？每台装驱动、来回插线太折腾。**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） |

架构示意：

```text
客户端设备 ──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：

```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
```

镜像页（可复制）：

```
https://xuanyuan.cloud/zh/r/anujdatar/cups
```

---

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

### 4.1 确认 631 未被占用

```bash
ss -tlnp | grep 631
```

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

```bash
sudo systemctl stop cups
sudo systemctl disable cups
```

实测服务器上 **未安装** 系统 `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
```

| 参数 | 说明 |
|------|------|
| `-p 631:631` | 映射 CUPS Web / IPP 端口 |
| `TZ` | 时区，国内建议 `Asia/Shanghai` |
| `CUPSADMIN` / `CUPSPASSWORD` | Web 管理登录凭据（下文界面使用 `admin` / `123456`） |
| `-v ...:/etc/cups` | 持久化打印机队列与配置 |

> **安全提示**：示例密码 `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**，说明服务已就绪。

![OpenPrinting CUPS 2.4.10 首页：导航含 Home / Administration / Printers](https://developer.qcloudimg.com/http-save/yehe-2813964/68bf3ee02a7e128da90b98f1dbec2c5e.png)


*图 1：CUPS 首页 OpenPrinting CUPS 2.4.10*

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

![CUPS 登录框：地址 192.168.1.18:631，用户名 admin](https://developer.qcloudimg.com/http-save/yehe-2813964/97b89150c9c04e176955644d1d59e9f7.png)


*图 2：登录管理后台，用户名 admin，密码为启动容器时设置的 CUPSPASSWORD*

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

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

![Administration 管理页：Add Printer 与服务器共享选项](https://developer.qcloudimg.com/http-save/yehe-2813964/aba50a5e15d6ea9803c6ab1e024d94e2.png)


*图 3：Administration 管理页，点击 Add Printer*

---

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

### 9.1 选择连接协议

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

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

![添加打印机：选择 Internet Printing Protocol (ipp)](https://developer.qcloudimg.com/http-save/yehe-2813964/7d5225d826c68edf51fe5d7c0a98b8b7.png)


*图 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**。

![添加打印机：Connection 填入 ipp://192.168.1.20/ipp/print](https://developer.qcloudimg.com/http-save/yehe-2813964/b8ad067e7bfe8718091824ca3ca79ce0.png)


*图 5：Connection 填写打印机 IPP 地址*

### 9.3 命名并共享

| 字段 | 实测值 | 说明 |
|------|--------|------|
| Name | `HP-Home` | 队列名，**不要空格**，勿含 `/`、`#` |
| Description | `my Printer` | 可读描述，可随意 |
| Location | （空） | 可选，如「客厅」 |
| Sharing | **Share This Printer** 勾选 | 局域网其他设备可通过本 CUPS 共享打印 |

点 **Continue**。

![命名打印机 HP-Home 并勾选 Share This Printer](https://developer.qcloudimg.com/http-save/yehe-2813964/4fc34ed22853aee468fe3bbd4dbaff24.png)


*图 6：命名 HP-Home 并勾选共享*

### 9.4 选择厂商与驱动

**Make** 列表中选择 **HP**，点 **Continue**。

![选择厂商 Make：HP](https://developer.qcloudimg.com/http-save/yehe-2813964/d614b060bcbd7dd35e1f12dfe8d388e3.png)


*图 7：厂商选择 HP*

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

![选择驱动 Model：IPP Everywhere™](https://developer.qcloudimg.com/http-save/yehe-2813964/34ef497ebafb7a71427eeadcfda5ae26.png)


*图 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**。

![设置默认选项：Media Size 为 A4](https://developer.qcloudimg.com/http-save/yehe-2813964/9b4def9c19c57de31ef52bae584b27bf.png)


*图 9：默认纸张设为 A4*

### 9.6 确认添加成功

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

![打印机 HP-Home 状态 Idle，连接 ipp://192.168.1.20/ipp/print](https://developer.qcloudimg.com/http-save/yehe-2813964/6930154c645eac37b53d1c5619e39cc3.png)


*图 10：HP-Home 就绪，Idle / Accepting Jobs / Shared*

---

## 十、打印测试页

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

![Maintenance 菜单：选择 Print Test Page](https://developer.qcloudimg.com/http-save/yehe-2813964/604e51e7cac12ea61526b8a89a8814f2.png)


*图 11：Maintenance → Print Test Page*

页面提示测试页已提交：

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

![打印测试页成功：job ID 为 HP-Home-1](https://developer.qcloudimg.com/http-save/yehe-2813964/03900c8a39afe597d4fdd2b3bf41535c.png)


*图 12：测试页已发送，Job ID 为 HP-Home-1*

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

![作业 HP-Home-1 处理中，Rendering completed](https://developer.qcloudimg.com/http-save/yehe-2813964/00ea2af69012e0dfae942e06745d734e.png)


*图 13：作业处理中，Rendering completed*

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

![物理测试页：Printer test page，Job ID HP-Home-1，Driver ippeve.ppd](https://developer.qcloudimg.com/http-save/yehe-2813964/3b4dcdbddce461d22084850c2097504c.png)


*图 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->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 / 反向代理并做好认证。

---

## 十三、命令速查

| 操作 | 命令 |
|------|------|
| 拉取镜像 | `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 服务器实测*

## 延伸阅读

- 轩辕镜像页：[anujdatar/cups](https://xuanyuan.cloud/zh/r/anujdatar/cups)
- 项目源码：[anujdatar/cups-docker](https://github.com/anujdatar/cups-docker)
- 轩辕镜像 Docker 安装与加速：[使用手册](https://xuanyuan.cloud/usage)


家庭、小公司、小团队只有一台打印机，几台电脑却都要用？每台装驱动、来回插线太折腾。CUPS（Common UNIX Printing System）是 Linux/Unix 上最常用的打印中间件——装在 NAS、树莓派或小服务器上，局域网里的电脑、手机都能往它提交任务，由它统一转发到你的网络打印机。

5 分钟共享打印机：用 Docker 一键部署 CUPS

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

运维

开发工具

硬件

5分钟Docker部署CUPS打印服务器，实现局域网共享打印机。通过anujdatar/cups镜像快速搭建，支持HPSmartTank等网络打印机，无需每台设备安装驱动。提供详细步骤：拉取镜像、配置端口、Web界面添加打印机、打印测试页，适合家庭和小团队使用。

访问管理

代码解释

中间件

服务器

云安全

Windows

容器

Docker

Linux

Unix

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

5 分钟共享打印机：用 Docker 一键部署 CUPS-腾讯云开发者社区-腾讯云

5 分钟共享打印机：用 Docker 一键部署 CUPS

5 分钟共享打印机：用 Docker 一键部署 CUPS

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐