# CUPS 打印服务一键配置脚本

适用于 Armbian / Debian / Ubuntu 系统，支持 x86_64 和 ARM 架构。

## 功能特性

- 一键安装 CUPS 打印服务
- 自动配置远程访问和局域网共享
- 中文 Web 管理界面（含常见驱动选项动态汉化）
- AirPrint 支持（iOS/macOS 自动发现）
- 虚拟 PDF 打印机（测试连接用）
- 多种打印机驱动可选
- 驱动管理器（默认仅允许内网访问）
- 驱动管理器账号密码可通过脚本菜单修改
- 网络和打印服务守护（断网自动切 DHCP，CUPS 卡死自动恢复）
- 静态 IP 支持网关变更自愈：先切 DHCP，再按原静态 IP 尾号迁移到新网段
- 独立程序更新（保留配置和密码，更新前备份，失败自动回滚）
- 支持一键卸载

## 快速安装

```bash
# 方式一：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
```

## 卸载

```bash
# 下载脚本
wget -O setup_cups.sh https://git.workyai.cn/237899745/S905L3A/raw/branch/master/setup_cups.sh
chmod +x setup_cups.sh

# 执行卸载
./setup_cups.sh --uninstall
```

## 修改驱动管理器账号密码

```bash
# 方式一：从主菜单选择“修改驱动管理器用户名和密码”
./setup_cups.sh

# 方式二：直接进入账号密码修改流程
./setup_cups.sh --driver-manager-auth
```

驱动管理器默认最大上传 `512MB`，单个安装命令默认超时 `900` 秒。需要调整时可在服务环境变量中设置 `DRIVER_MANAGER_MAX_UPLOAD_MB` 和 `DRIVER_MANAGER_COMMAND_TIMEOUT`。

## 驱动选项

安装时可选择以下驱动：

| 选项 | 说明 |
|------|------|
| 1 | 通用驱动（推荐，支持大多数打印机） |
| 2 | HP 打印机 (hplip) |
| 3 | 爱普生 (gutenprint) |
| 4 | 兄弟 (brlaser) |
| 5 | 奔图 Pantum |
| 6 | 全部安装（不含奔图） |
| 7 | 虚拟 PDF 打印机（测试用） |
| 0 | 仅安装 CUPS（不安装驱动） |

默认选项：`1 7`（通用驱动 + PDF 打印机）

## 客户端连接

### 局域网环境

| 客户端 | 连接方式 |
|--------|----------|
| **macOS/iOS** | 自动发现（AirPrint），无需配置 |
| **Android** | 安装 Mopria Print Service，自动发现 |
| **Windows** | 设置 → 打印机 → 添加打印机 |
| **Linux** | 自动发现或 `ipp://IP:631/printers/打印机名` |

### 管理界面

- 地址：`https://服务器IP:631`
- 用户名：`root`
- 密码：SSH 登录密码

## 服务端口

| 服务 | 端口 | 用途 |
|------|------|------|
| CUPS | 631 | 打印服务/Web管理界面 |
| Avahi | 5353 | mDNS/AirPrint 自动发现 |
| 驱动管理器 | 632 | 内网上传安装打印机驱动（可选） |

## 自动守护

安装脚本会自动启用两个 systemd timer：

| 守护 | 作用 |
|------|------|
| `cups-network-watchdog.timer` | 每分钟检测网络，连续失败后自动把网卡切回 DHCP |
| `cups-print-watchdog.timer` | 每分钟检测 CUPS/Avahi/驱动管理器，卡死或异常后自动重启 |

配置文件：

```bash
# 网络守护配置，可在里面设置固定 IP、网关、DNS
nano /etc/cups-watchdog/network-watchdog.conf

# 手动切回配置里的固定 IP
/opt/cups-watchdog/network-watchdog.sh static

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

# 打印服务守护配置
nano /etc/cups-watchdog/print-watchdog.conf

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

## 常用命令

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

# 重启 CUPS
systemctl restart cups

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

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

# 检查 USB 打印机
lsusb | grep -i print
lpinfo -v | grep usb
```

## 支持架构

- x86_64 / amd64
- aarch64 / arm64
- armv7l / armhf

## 文件说明

```
├── setup_cups.sh              # 安装/卸载/更新菜单
├── update_cups.py             # 独立更新器（Python 3.9+）
├── watchdog/                  # 网络和打印服务守护脚本
├── cups-templates-zh_CN/      # 中文界面模板（65个文件）
├── cups-docroot-zh_CN/        # CUPS 中文首页和前端汉化脚本
├── README.md                  # 本文档
└── 刷机教程.md                # Armbian 刷机教程
```

## 常见问题

### 手机打印提示"不再接受加密的作业"
脚本现在配置为 `DefaultEncryption IfRequested`，允许 HTTP，也接受客户端主动发起的 HTTPS。如仍提示，通常是客户端缓存了旧队列，删除后重新发现打印机即可。

### 手机发送打印任务很慢
脚本已配置 `HostNameLookups Off` 解决此问题。如果仍然慢，检查网络连接。

### 更换路由器或网关后找不到打印服务器
网络守护会在连续检测失败后先切换到 DHCP 恢复连接。如果发现 DHCP 获取到的新网关和原静态网关不同，会保留原静态 IP 的最后一段，例如 `192.168.11.219` 的 `219`，自动改成新网段下的 `x.x.x.219`。

### 界面显示英文
确保安装时下载了中文模板、中文首页和前端汉化脚本。重新运行安装脚本可以修复。

### 找不到 USB 打印机
1. 确认打印机已通过 USB 连接到服务器
2. 运行 `lsusb` 检查是否识别
3. 刷新 CUPS 添加打印机页面

## 仓库地址

- Gitea: https://git.workyai.cn/237899745/S905L3A
- Gitee: https://gitee.com/yu-yon/S905L3A（镜像）

## 回归测试

需要 Python 3.9+、Flask 和 Bash。在仓库根目录运行：

```bash
python3 -B -m unittest discover -s tests -v
```

测试会模拟系统命令和驱动安装，不会修改真实网络、安装驱动或重启服务。
覆盖守护锁释放与连续失败恢复、多网卡地址选择、APT 等待/超时、PDF 备用驱动、DEB 架构筛选和基础访问控制。
更新器测试使用临时安装目录和模拟的 systemctl，覆盖预览、取消、配置保留、重复更新、服务状态恢复、写入失败及中断回滚。
通过这些测试不等于通过实机验证；systemd 更新流程、USB 打印、AirPrint、NetworkManager/netplan 切换仍需在目标设备验证。

## 更新已部署设备

更新 Git 仓库不会自动更新设备上的程序。请在打印服务器的 **root 终端** 执行以下命令，
或下载最新版 `setup_cups.sh` 后选择菜单 **8：更新已安装程序**。旧版安装脚本没有更新入口，需要先获取新版。

```bash
# 下载最新版脚本并进入更新流程（显示文件清单后需要输入 y 确认）
curl -fsSL https://git.workyai.cn/237899745/S905L3A/raw/branch/master/setup_cups.sh | bash -s -- --update

# 仅检查和预览，不修改已安装文件、不停止服务
curl -fsSL https://git.workyai.cn/237899745/S905L3A/raw/branch/master/setup_cups.sh | bash -s -- --update --dry-run

# 已有最新版脚本时；非交互环境可追加 --yes，明确确认更新
bash setup_cups.sh --update --yes
```

需要 Linux、systemd、Bash 和 Python 3.9+；缺少依赖时会退出，不会自动安装软件包。
默认从 Gitea 的 `master` 下载，并检查压缩包路径和程序语法。下载失败会退出，不自动切到可能尚未同步的镜像。
可信的离线仓库副本也可使用 `python3 update_cups.py --source-dir . --dry-run` 检查，去掉 `--dry-run` 后确认更新。

- 只替换已经安装且内容有变化的驱动管理器、两个守护脚本、中文模板和首页脚本；没有变化时不会重启服务。不会补装缺失的可选组件或新增文件，也不会执行安装脚本中的配置迁移。
- 不改打印机队列、CUPS/网络/守护配置、账号密码、systemd 服务文件及开机启用状态；不升级系统软件包、不重启 CUPS。手工修改过的程序文件或中文页面会被仓库版本替换，请先看预览清单。
- 更新前在 `/var/backups/cups-project/` 保存旧程序文件、校验值及原服务状态。先暂停原本运行的守护定时器，等待正在运行的守护检查结束，再替换文件。驱动管理器代码有变化时，其 Web 页面会短暂不可用。
- 请在没有驱动上传/安装或手动守护操作时更新。检测到仍在运行的守护或驱动安装子进程会取消；不会强杀它们。确认守护空闲后，更新器会清理默认 `/run/cups-watchdog/` 中旧版遗留的空锁目录，无需为此重启设备。
- 替换或服务启动检查失败时，会尝试自动恢复旧文件和原服务运行状态；备份始终保留。断电、磁盘损坏或强制杀进程不能保证自动回滚，应根据报错及备份内的 `manifest.json` 人工恢复。

## 更新日志

- 2026-09-11: 新增菜单第 8 项及 `--update`，支持更新预览、配置保留、备份校验、失败回滚和隔离回归测试。
- 2026-09-11: 修复守护锁、多网卡静态 IP、APT 等待、PDF 备用驱动和多架构 DEB 安装问题，添加隔离回归测试。
- 2024-12-01: 添加卸载功能、优化打印速度
- 2024-11-30: 修复 CSS 兼容 CUPS 2.4.7、添加 PDF 打印机选项