概述

• 目标：在 NAS 上部署 CUPS（Common UNIX Printing System），实现局域网打印共享并兼顾安全性与兼容性。
• 适用对象：基于 Debian/Ubuntu 的 NAS（例如 OpenMediaVault）、TrueNAS、以及通过 Docker 在 Synology/QNAP 上运行 CUPS 的场景。
• 成果：可复现的安装命令、cupsd.conf 配置示例、Samba/IPP 共享、TLS 配置、客户端接入说明、故障排查和网络/流程图（Mermaid）。

准备工作与要求

• 网络：NAS 有固定局域网 IP（建议静态或 DHCP 保留），客户端能访问该 IP。
• 权限：需在 NAS 上能以 root 或管理员身份执行命令或运行容器。
• 必要软件：CUPS、Avahi（mDNS）、Samba（如需 SMB 打印）、openssl/nginx/certbot（可选 TLS）、Docker（容器化方案）。
• 端口：开放 631/tcp（IPP/CUPS）；若用 Samba 则打开 139/445；若使用 HTTPS 反向代理则打开 443/80（仅在需要时）。

---

部署方式概述

本教程提供三种实战方案：

1. 原生安装（Debian/OMV/Ubuntu）——最直接，适合能 apt 安装的软件环境。
2. TrueNAS（CORE/ SCALE）——CORE 使用 jail，SCALE 可用容器镜像。
3. 容器化（Docker）——适合 Synology/QNAP 或不建议改宿主系统的场景。

---

一、在 Debian / OpenMediaVault 上原生安装（详细步骤）

1. 更新系统并安装 CUPS 与 Avahi：

sudo apt update && sudo apt upgrade -y
sudo apt install -y cups avahi-daemon printer-driver-all

2. 将管理用户加入 lpadmin 组（允许通过 Web UI 管理打印机）：

sudo usermod -aG lpadmin youruser

3. 启用并启动服务：

sudo systemctl enable --now cups avahi-daemon

4. 编辑 CUPS 主配置文件 /etc/cups/cupsd.conf，以下为推荐的关键段，按需替换网段或主机名：

Listen *:631
Browsing On
BrowseAddress @LOCAL

<Location />
  Order allow,deny
  Allow @LOCAL
</Location>

<Location /admin>
  AuthType Default
  Require user @SYSTEM
  Order allow,deny
  Allow @LOCAL
</Location>

# 若只允许指定子网访问（示例 192.168.1.0/24）
<Location />
  Allow 192.168.1.0/24
</Location>

LogLevel warn

5. 重启 CUPS：

sudo systemctl restart cups

6. 在浏览器访问 CUPS Web UI：http://<NAS_IP>:631/，使用系统用户登录，添加打印机并安装 PPD/驱动。

---

二、TrueNAS（CORE / SCALE）要点

• TrueNAS SCALE：基于 Linux，可按 Debian 步骤或使用应用容器部署。
• TrueNAS CORE（FreeBSD）：推荐在 jail 中安装：

pkg install -y cups avahi
# 编辑 /usr/local/etc/cups/cupsd.conf（同上示例）
service cupsd enable
service cupsd start
service avahi-daemon enable
service avahi-daemon start

注：TrueNAS GUI 可管理插件或容器，需根据所用版本选择最合适的部署方式。

---

三、Synology / QNAP：容器化方案（推荐）

• Synology（DSM）与 QNAP（Container Station）上建议使用 Docker 容器运行 CUPS，避免修改底层系统。
• 示例 docker-compose.yml（示例仅供参考，需按宿主路径/权限调整）：

version: '3'
services:
  cups:
    image: olbat/cups
    restart: unless-stopped
    network_mode: "host"
    volumes:
      - /volume1/docker/cups/config:/etc/cups
      - /dev/bus/usb:/dev/bus/usb  # 若需 USB 打印机直通

• 启动后访问：http://<NAS_IP>:631/。若使用 USB 打印机直通，宿主需支持设备映射。

---

四、共享与发现（Avahi + IPP + Samba）

• Avahi（mDNS）：允许 macOS 和 Linux 自动发现网络打印机，确保 avahi-daemon 在 NAS 上运行。
• IPP（推荐）：CUPS 默认提供 IPP，可使用类似 ipp://<NAS_IP>/printers/<printername> 的地址直连。
• Samba（为旧版 Windows 兼容）：安装并配置 Samba，使 Windows 能通过 SMB/打印服务访问（示例）：

[global]
  workgroup = WORKGROUP
  server string = NAS CUPS Server
  load printers = yes
  printing = cups
  printcap name = cups

[printers]
  comment = All Printers
  path = /var/spool/samba
  browseable = no
  guest ok = yes
  printable = yes
  create mode = 0700

sudo systemctl restart smbd

注：现代 Windows / macOS 优先推荐 IPP/IPP-over-HTTPS，而非 SMB 打印。

---

五、安全建议（认证、TLS、防火墙、反向代理）

• 管理认证：在 cupsd.conf 中对 /admin 路径使用 Require user @SYSTEM，仅系统用户可管理。
• TLS：可用 nginx 或 CUPS 自带 TLS 支持。推荐使用反向代理 + Let’s Encrypt（若能对外访问或使用 DNS 验证）。

示例 nginx 反向代理（简化）：

server {
  listen 443 ssl;
  server_name cups.example.local;
  ssl_certificate /etc/letsencrypt/live/cups.example.local/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/cups.example.local/privkey.pem;

  location / {
    proxy_pass http://127.0.0.1:631;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

• 防火墙规则示例（仅允许内网）：

sudo ufw allow from 192.168.1.0/24 to any port 631 proto tcp

警告：不推荐将 CUPS 直接暴露到公网；若确有需求须严格使用 TLS、身份验证和白名单。

---

六、客户端接入（快速指南）

• Linux：“添加打印机” → 协议选择 IPP → 地址 ipp://<NAS_IP>:631/printers/<printername>。
• macOS：系统偏好 → 打印机与扫描仪 → 点击 + → 选择 IP 标签 → 协议 IPP → 地址填 ipp://<NAS_IP>/printers/<printername>。
• Windows 10/11：添加打印机 → 手动添加网络打印机 → 选择 IPP（或使用 \\<NAS_IP>\\<printershare> 若配置 Samba）。

---

七、常见故障排查

• 无法访问 CUPS Web UI：
  • 检查服务：sudo systemctl status cups。
  • 检查端口：ss -tlnp | grep 631。
• 打印任务卡住：
  • 查看作业：lpstat -o。
  • 取消全部作业：cancel -a。
• Windows 找不到驱动：建议在 CUPS 端安装合适 PPD，或在 Windows 上安装厂商驱动并通过 IPP 连接。
• 容器中无法识别 USB 打印机：确认容器已挂载 /dev/bus/usb，且使用 network_mode: host（或相应权限）。

---

八、备份与维护

• 备份 CUPS 配置与 PPD：

sudo tar czvf cups-backup-$(date +%F).tgz /etc/cups /var/spool/cups /usr/share/cups/drv

• 更新策略：定期更新系统与 CUPS（使用 apt/pkg 或更新容器镜像）。
• 日志位置：/var/log/cups/error_log，需要时可在 cupsd.conf 调整 LogLevel debug。

---

网络拓扑与请求流程

网络拓扑

CUPS 请求处理流程

---

关键文件路径（参考）

• cupsd.conf: /etc/cups/cupsd.conf
• PPD 存放: /etc/cups/ppd/
• CUPS 日志: /var/log/cups/error_log

---