237899745/S905L3A

Fork 0

Files

yuyx 00d512f9d9 feat: add CUPS watchdog timers

2026-06-09 14:58:13 +08:00

5.7 KiB

Raw Blame History

CUPS 打印服务配置交接文档

概述

本文档记录了 CUPS 打印服务的完整配置过程，包括一键安装脚本、中文汉化、远程访问配置等。

一、一键安装

Gitea 仓库

https://git.workyai.cn/237899745/S905L3A.git

一键安装命令

# 方式一：curl
curl -fsSL https://git.workyai.cn/237899745/S905L3A/raw/branch/master/setup_cups.sh | bash

# 方式二：wget
wget -qO- https://git.workyai.cn/237899745/S905L3A/raw/branch/master/setup_cups.sh | bash

脚本功能

自动检测系统架构（x86_64/ARM64/ARMhf）
可选更换国内镜像源（清华大学）
安装 CUPS + Avahi（AirPrint 支持）
多种打印机驱动可选（通用/HP/爱普生/兄弟/奔图）
自动配置远程访问权限
安装中文界面模板
安装网络和打印服务守护脚本

二、已安装的服务

服务	端口	用途
CUPS	631	打印服务/Web管理界面
Avahi	5353	mDNS/AirPrint 自动发现
驱动管理器	632	内网上传安装打印机驱动（可选）
网络守护	systemd timer	断网后自动切换网卡为 DHCP
打印守护	systemd timer	CUPS 卡死或异常后自动重启恢复

三、客户端连接方式

局域网环境（推荐）

客户端	连接方式
macOS/iOS	自动发现（AirPrint），无需配置
Android	安装 Mopria Print Service，自动发现
Linux	自动发现或手动添加 `ipp://IP:631/printers/打印机名`
Windows	`\\局域网IP\打印机名` 或 IPP 协议

公网环境

不建议把 CUPS 或驱动管理器直接暴露到公网。本项目默认按内网使用配置，访问范围使用 @LOCAL，驱动管理器也会拒绝非私有网段来源。

四、CUPS 管理界面

访问地址

http://服务器IP:631
https://服务器IP:631

登录凭据

用户名：root
密码：SSH 登录密码

常用操作

添加打印机：Administration → Add Printer
管理打印队列：Printers → 选择打印机
查看任务：Jobs

五、重要配置文件

文件路径	说明
`/etc/cups/cupsd.conf`	CUPS 主配置文件
`/etc/cups/printers.conf`	打印机配置
`/etc/cups/ssl/`	SSL 证书目录
`/usr/share/cups/templates-zh_CN/`	中文界面模板
`/opt/cups-driver-manager/`	驱动管理器安装目录（可选）
`/opt/cups-watchdog/`	守护脚本安装目录
`/etc/cups-watchdog/network-watchdog.conf`	网络守护配置，可设置固定 IP、网关、DNS
`/etc/cups-watchdog/print-watchdog.conf`	打印服务守护配置
`/var/log/cups-watchdog/`	守护脚本日志目录

六、关键配置说明

cupsd.conf 关键配置

# 监听所有网络接口
Listen 0.0.0.0:631

# 允许任何主机名访问
ServerAlias *

# 内网允许 HTTP，同时接受客户端主动 HTTPS
DefaultEncryption IfRequested

# 中文界面
DefaultLanguage zh

# 允许远程访问
<Location />
  Order allow,deny
  Allow @LOCAL
</Location>

# 允许远程打印
<Location /printers>
  Order allow,deny
  Allow @LOCAL
</Location>

七、常用命令

# 查看打印机列表
lpstat -p -d

# 重启 CUPS
systemctl restart cups

# 查看 CUPS 日志
tail -f /var/log/cups/error_log

# 检查端口监听
ss -tlnp | grep -E "631|632"

# 查看守护状态
systemctl status cups-network-watchdog.timer cups-print-watchdog.timer

# 手动切 DHCP
/opt/cups-watchdog/network-watchdog.sh dhcp

# 按配置文件手动切回固定 IP
/opt/cups-watchdog/network-watchdog.sh static

# 查看守护日志
tail -f /var/log/cups-watchdog/network.log
tail -f /var/log/cups-watchdog/print.log

八、故障排除

问题1：Windows 无法连接 IPP 打印机

原因：常见原因是客户端缓存了旧队列、服务器 IP 变化，或没有在同一内网网段。解决：删除旧打印机后重新添加，使用 http://服务器IP:631/printers/打印机名 或 Windows 设置里的“添加打印机”重新发现。

问题2：驱动管理器无法打开

原因：驱动管理器默认只允许内网来源访问，且需要安装时生成的 admin 密码。解决：

确认客户端和打印服务器在同一内网
查看密码：cat /opt/cups-driver-manager/.password
查看服务状态：systemctl status cups-driver-manager

问题3：打印任务卡住

解决：

# 取消所有任务
cancel -a
# 重启 CUPS
systemctl restart cups

问题4：中文界面不生效

解决：

# 确保中文模板已安装
ls /usr/share/cups/templates-zh_CN/
# 检查 locale 设置
locale -a | grep zh_CN

问题5：网络守护自动切 DHCP 后要切回固定 IP

解决：

nano /etc/cups-watchdog/network-watchdog.conf
/opt/cups-watchdog/network-watchdog.sh static

九、文件清单

/root/yuyx/B863AV3.2M刷Armbian教程/
├── setup_cups.sh              # 一键安装脚本
├── watchdog/                  # 网络和打印服务守护脚本
├── cups-templates-zh_CN/      # 中文界面模板（65个文件）
├── 刷机教程.md                # Armbian 刷机教程
└── CUPS打印服务配置交接文档.md # 本文档

十、待测试项目

局域网 Windows IPP/CUPS 连接
局域网 macOS/iOS AirPrint 自动发现
局域网 Android Mopria 打印
真实 USB 打印机连接测试
断网后网络守护自动切 DHCP
CUPS 异常后打印守护自动重启恢复

文档创建时间：2025-11-30 配置环境：Ubuntu 22.04 / CUPS 2.4

5.7 KiB Raw Blame History Unescape Escape