第 11 章:故障排查
第 11 章:故障排查
打印服务出现故障时,快速准确地定位和解决问题至关重要。本章将系统地介绍 CUPS 故障排查的方法、工具和最佳实践。
11.1 故障排查流程
11.1.1 通用排查流程
┌─────────────────────────────────────────────────┐
│ CUPS 故障排查流程 │
│ │
│ 1. 症状确认 │
│ └── 用户报告什么问题? │
│ │
│ 2. 基本检查 │
│ ├── CUPS 服务是否运行? │
│ ├── 打印机是否在线? │
│ └── 网络是否连通? │
│ │
│ 3. 日志分析 │
│ ├── error_log (错误日志) │
│ ├── access_log (访问日志) │
│ └── page_log (页面日志) │
│ │
│ 4. 配置检查 │
│ ├── cupsd.conf 配置 │
│ ├── printers.conf 打印机配置 │
│ └── PPD 文件 │
│ │
│ 5. 诊断工具 │
│ ├── lpstat │
│ ├── lpinfo │
│ ├── cupsfilter │
│ └── ipptool │
│ │
│ 6. 解决问题 │
│ └── 修复配置/重启服务/更换驱动 │
└─────────────────────────────────────────────────┘
11.1.2 快速诊断清单
#!/bin/bash
# quick-diag.sh - CUPS 快速诊断脚本
echo "=== CUPS 快速诊断 ==="
echo ""
# 1. 检查 CUPS 服务状态
echo "1. CUPS 服务状态"
if systemctl is-active cups > /dev/null 2>&1; then
echo " ✅ CUPS 服务正在运行"
else
echo " ❌ CUPS 服务未运行"
echo " 修复: sudo systemctl start cups"
fi
echo ""
# 2. 检查 cupsd 进程
echo "2. cupsd 进程"
if pgrep cupsd > /dev/null; then
echo " ✅ cupsd 进程存在 (PID: $(pgrep cupsd))"
else
echo " ❌ cupsd 进程不存在"
fi
echo ""
# 3. 检查端口监听
echo "3. 端口监听"
if ss -tlnp | grep -q ":631"; then
echo " ✅ 端口 631 正在监听"
else
echo " ❌ 端口 631 未监听"
fi
echo ""
# 4. 检查打印机状态
echo "4. 打印机状态"
printer_count=$(lpstat -p 2>/dev/null | wc -l)
if [ "$printer_count" -gt 0 ]; then
echo " ✅ 共有 $printer_count 台打印机"
lpstat -p | head -5
else
echo " ⚠️ 没有配置打印机"
fi
echo ""
# 5. 检查打印队列
echo "5. 打印队列"
queue_count=$(lpstat -o 2>/dev/null | wc -l)
if [ "$queue_count" -gt 0 ]; then
echo " ⚠️ 队列中有 $queue_count 个任务"
lpstat -o | head -5
else
echo " ✅ 队列为空"
fi
echo ""
# 6. 检查最近错误
echo "6. 最近错误 (error_log)"
if [ -f /var/log/cups/error_log ]; then
errors=$(grep -i "error" /var/log/cups/error_log | tail -5)
if [ -n "$errors" ]; then
echo " ⚠️ 发现错误:"
echo "$errors" | sed 's/^/ /'
else
echo " ✅ 没有发现错误"
fi
else
echo " ⚠️ error_log 文件不存在"
fi
echo ""
# 7. 检查磁盘空间
echo "7. 磁盘空间"
spool_usage=$(du -sh /var/spool/cups 2>/dev/null | awk '{print $1}')
echo " 打印队列使用: ${spool_usage:-未知}"
echo ""
# 8. 检查配置文件语法
echo "8. 配置文件语法"
if cupsd -t 2>/dev/null; then
echo " ✅ 配置文件语法正确"
else
echo " ❌ 配置文件语法错误"
fi
echo ""
echo "=== 诊断完成 ==="
11.2 常见问题及解决方案
11.2.1 打印机无法识别
症状:打印机未出现在打印机列表中
排查步骤:
# 1. 检查 USB 连接
lsusb | grep -i "printer\|hp\|canon\|epson\|brother"
# 2. 检查 CUPS 后端
lpinfo -v | grep -i usb
# 3. 检查后端权限
ls -la /usr/lib/cups/backend/
# 4. 检查设备文件
ls -la /dev/usb/lp*
# 5. 检查内核模块
lsmod | grep usblp
# 6. 检查 udev 规则
ls /etc/udev/rules.d/ | grep -i cups
解决方案:
# 加载 usblp 模块
sudo modprobe usblp
# 修复后端权限
sudo chmod 755 /usr/lib/cups/backend/*
sudo chmod 700 /usr/lib/cups/backend/usb
# 重新检测打印机
sudo lpinfo -v
# 如果使用 HP 打印机
hp-probe
11.2.2 打印任务卡在队列中
症状:打印任务显示为 “processing” 但不打印
排查步骤:
# 1. 查看任务状态
lpstat -o
# 2. 查看任务详情
lpstat -l -o myprinter-123
# 3. 查看错误日志
grep "myprinter-123" /var/log/cups/error_log
# 4. 检查打印机状态
lpstat -p myprinter
解决方案:
# 取消卡住的任务
cancel myprinter-123
# 取消所有任务
cancel -a myprinter
# 重启打印机
sudo cupsdisable myprinter
sudo cupsenable myprinter
# 重启 CUPS 服务
sudo systemctl restart cups
# 如果问题持续,检查打印机硬件
# - 检查纸张
# - 检查墨粉/墨水
# - 检查错误指示灯
11.2.3 打印质量差
症状:打印输出模糊、颜色偏差、有条纹
排查步骤:
# 1. 打印测试页
sudo lp -d myprinter /usr/share/cups/data/testprint
# 2. 检查打印选项
lpoptions -p myprinter -l | grep -i "resolution\|quality"
# 3. 检查 PPD 配置
grep -i "resolution" /etc/cups/ppd/myprinter.ppd
# 4. 检查驱动
lpstat -p myprinter -l
解决方案:
# 调整打印质量
lp -d myprinter -o Resolution=600dpi document.pdf
# 调整颜色设置
lp -d myprinter -o ColorModel=RGB document.pdf
# 清洁打印头(HP 打印机)
hp-clean -p myprinter
# 校准打印头(HP 打印机)
hp-align -p myprinter
# 更换驱动(如果问题持续)
# 尝试使用不同的 PPD 文件
sudo lpadmin -p myprinter -P /path/to/alternative.ppd
11.2.4 网络打印机连接失败
症状:无法连接到网络打印机
排查步骤:
# 1. 测试网络连通性
ping 192.168.1.100
# 2. 测试端口连通性
telnet 192.168.1.100 9100 # Socket
telnet 192.168.1.100 631 # IPP
# 3. 使用 nmap 扫描
nmap -p 9100,631 192.168.1.100
# 4. 测试 IPP 连接
ipptool -tv ipp://192.168.1.100/ipp/print get-printer-attributes.test
# 5. 检查 DNS 解析
nslookup printer-hostname
解决方案:
# 使用 IP 地址而不是主机名
sudo lpadmin -p myprinter -v socket://192.168.1.100:9100
# 检查防火墙
sudo ufw status
sudo iptables -L -n
# 开放打印端口
sudo ufw allow 9100/tcp
sudo ufw allow 631/tcp
# 测试不同协议
# 尝试 Socket
sudo lpadmin -p myprinter -v socket://192.168.1.100:9100
# 尝试 IPP
sudo lpadmin -p myprinter -v ipp://192.168.1.100/ipp/print
# 尝试 LPD
sudo lpadmin -p myprinter -v lpd://192.168.1.100/PASSTHRU
11.2.5 驱动不兼容
症状:打印输出乱码、错误页面
排查步骤:
# 1. 查看当前驱动
lpstat -p myprinter -v
# 2. 查看 PPD 文件
head -20 /etc/cups/ppd/myprinter.ppd
# 3. 查看支持的驱动
lpinfo -m | grep -i "打印机型号"
# 4. 测试不同驱动
# 使用通用 PostScript 驱动
sudo lpadmin -p myprinter -P /usr/share/ppd/Generic/PostScript.ppd
解决方案:
# 安装正确的驱动
sudo apt install -y printer-driver-gutenprint
sudo apt install -y hplip
sudo apt install -y printer-driver-foo2zjs
# 使用 IPP Everywhere(无驱动)
sudo lpadmin -p myprinter -m "everywhere" \
-v "ipp://192.168.1.100/ipp/print"
# 使用通用 PCL 驱动
sudo lpadmin -p myprinter -m "HP LaserJet Series" \
-v socket://192.168.1.100:9100
# 使用 Raw 队列(不做任何处理)
sudo lpadmin -p myprinter -m raw \
-v socket://192.168.1.100:9100
11.2.6 Web 界面无法访问
症状:浏览器无法打开 http://localhost:631
排查步骤:
# 1. 检查 CUPS 服务
sudo systemctl status cups
# 2. 检查端口监听
ss -tlnp | grep 631
# 3. 检查防火墙
sudo ufw status
sudo iptables -L -n
# 4. 检查配置文件
grep "Listen" /etc/cups/cupsd.conf
解决方案:
# 重启 CUPS 服务
sudo systemctl restart cups
# 检查监听地址
# 如果只监听 localhost,修改为所有接口
sudo vim /etc/cups/cupsd.conf
# 修改: Listen 0.0.0.0:631
# 开放防火墙端口
sudo ufw allow 631/tcp
# 检查 SELinux/AppArmor
getenforce
sudo aa-status
# 检查 WebInterface 配置
sudo cupsctl WebInterface=yes
11.3 日志分析
11.3.1 日志文件说明
| 日志文件 | 内容 | 位置 |
|---|---|---|
error_log | 错误和调试信息 | /var/log/cups/error_log |
access_log | HTTP 访问记录 | /var/log/cups/access_log |
page_log | 打印页面记录 | /var/log/cups/page_log |
11.3.2 错误日志分析
# 查看最新错误
tail -f /var/log/cups/error_log
# 搜索特定错误
grep -i "error" /var/log/cups/error_log
# 搜索特定打印机错误
grep "myprinter" /var/log/cups/error_log | grep -i "error"
# 搜索特定时间范围的错误
awk '/May 10 09:/' /var/log/cups/error_log | grep -i "error"
# 统计错误类型
grep -i "error" /var/log/cups/error_log | \
awk '{print $NF}' | sort | uniq -c | sort -rn | head -10
常见错误信息:
| 错误信息 | 含义 | 解决方案 |
|---|---|---|
Unable to connect to printer | 无法连接打印机 | 检查网络/USB 连接 |
Printer not responding | 打印机无响应 | 检查打印机电源和网络 |
Filter failed | 过滤器执行失败 | 检查过滤器和依赖 |
Job canceled | 任务被取消 | 查看取消原因 |
Out of memory | 内存不足 | 增加系统内存或减小任务 |
Permission denied | 权限拒绝 | 检查文件权限 |
No such device | 设备不存在 | 检查打印机连接 |
11.3.3 访问日志分析
# 查看最新访问
tail -f /var/log/cups/access_log
# 统计访问 IP
awk '{print $1}' /var/log/cups/access_log | sort | uniq -c | sort -rn | head -10
# 统计 HTTP 状态码
awk '{print $9}' /var/log/cups/access_log | sort | uniq -c | sort -rn
# 统计请求的打印机
grep "POST /printers/" /var/log/cups/access_log | \
awk '{print $7}' | sort | uniq -c | sort -rn
# 查看认证失败
grep "401\|403" /var/log/cups/access_log
11.3.4 页面日志分析
# 查看最新打印记录
tail -f /var/log/cups/page_log
# 统计每个用户的打印量
awk '{print $2}' /var/log/cups/page_log | sort | uniq -c | sort -rn
# 统计每个打印机的打印量
awk '{print $1}' /var/log/cups/page_log | sort | uniq -c | sort -rn
# 统计每日打印量
awk -F'[:/]' '{print $1"/"$2"/"$3}' /var/log/cups/page_log | \
sort | uniq -c
# 统计打印页数
awk '{sum += $6} END {print sum}' /var/log/cups/page_log
11.3.5 日志分析脚本
#!/bin/bash
# cups-log-report.sh - CUPS 日志报告生成脚本
REPORT_DATE=${1:-$(date +%Y-%m-%d)}
ACCESS_LOG="/var/log/cups/access_log"
ERROR_LOG="/var/log/cups/error_log"
PAGE_LOG="/var/log/cups/page_log"
echo "=========================================="
echo " CUPS 日志报告 - $REPORT_DATE"
echo "=========================================="
echo ""
# 1. 概览
echo "1. 概览"
echo "----------------------------------------"
echo "总访问次数: $(grep "$REPORT_DATE" $ACCESS_LOG | wc -l)"
echo "错误数量: $(grep "$REPORT_DATE" $ERROR_LOG | grep -i error | wc -l)"
echo "打印任务数: $(grep "$REPORT_DATE" $PAGE_LOG | wc -l)"
echo "打印页数: $(grep "$REPORT_DATE" $PAGE_LOG | awk '{sum+=$6}END{print sum}')"
echo ""
# 2. 热门打印机
echo "2. 热门打印机 (Top 5)"
echo "----------------------------------------"
grep "$REPORT_DATE" $PAGE_LOG | awk '{print $1}' | sort | uniq -c | sort -rn | head -5
echo ""
# 3. 活跃用户
echo "3. 活跃用户 (Top 10)"
echo "----------------------------------------"
grep "$REPORT_DATE" $PAGE_LOG | awk '{print $2}' | sort | uniq -c | sort -rn | head -10
echo ""
# 4. 错误统计
echo "4. 错误统计"
echo "----------------------------------------"
grep "$REPORT_DATE" $ERROR_LOG | grep -i error | \
sed 's/.*error: //' | cut -d: -f1 | sort | uniq -c | sort -rn | head -5
echo ""
# 5. 安全事件
echo "5. 安全事件"
echo "----------------------------------------"
auth_failures=$(grep "$REPORT_DATE" $ACCESS_LOG | grep -c "401\|403")
echo "认证失败次数: $auth_failures"
echo ""
# 6. 性能指标
echo "6. 性能指标"
echo "----------------------------------------"
echo "平均每任务页数: $(grep "$REPORT_DATE" $PAGE_LOG | awk '{sum+=$6; n++}END{if(n>0)print sum/n; else print 0}')"
echo ""
echo "=========================================="
echo " 报告生成完成"
echo "=========================================="
11.4 调试模式
11.4.1 启用调试日志
# 方法 1: 修改配置文件
sudo vim /etc/cups/cupsd.conf
# 修改 LogLevel 为 debug 或 debug2
LogLevel debug
# 重启 CUPS
sudo systemctl restart cups
# 方法 2: 使用 cupsctl 命令
sudo cupsctl --debug-logging
# 方法 3: 前台调试模式
sudo cupsd -f -c /etc/cups/cupsd.conf
# 所有日志输出到终端
11.4.2 调试日志级别
| 级别 | 说明 | 使用场景 |
|---|---|---|
none | 无日志 | 生产环境 |
emerg | 紧急 | 系统不可用 |
alert | 警报 | 需要立即处理 |
crit | 严重 | 严重错误 |
error | 错误 | 一般错误 |
warn | 警告 | 潜在问题 |
notice | 通知 | 重要事件 |
info | 信息 | 一般信息(默认) |
debug | 调试 | 详细调试信息 |
debug2 | 详细调试 | 非常详细的调试信息 |
# 设置调试级别
sudo cupsctl --debug-logging # debug
sudo cupsctl --debug2-logging # debug2
# 恢复正常日志
sudo cupsctl --no-debug-logging # 恢复到 info
11.4.3 过滤器调试
# 测试过滤器
cupsfilter -v -m application/postscript document.pdf 2>&1
# 详细调试
cupsfilter -vv -m application/postscript document.pdf 2>&1
# 测试特定打印机
cupsfilter -d myprinter -v document.pdf 2>&1
# 查看过滤器链
cupsfilter -t application/pdf 2>&1
11.4.4 IPP 调试
# 使用 ipptool 调试 IPP 通信
ipptool -tv ipp://localhost/printers/myprinter get-printer-attributes.test
# 测试远程打印机
ipptool -tv ipp://192.168.1.100/ipp/print get-printer-attributes.test
# 测试打印任务
ipptool -tv ipp://localhost/printers/myprinter \
-d /usr/share/cups/data/testprint \
print-job.test
# 使用 curl 调试 IPP
curl -v -X POST \
-H "Content-Type: application/ipp" \
--data-binary @request.ipp \
http://localhost:631/printers/myprinter
11.4.5 后端调试
# 测试后端发现
/usr/lib/cups/backend/socket
/usr/lib/cups/backend/ipp
/usr/lib/cups/backend/dnssd
# 测试特定后端
/usr/lib/cups/backend/socket 1 1 user "test" 1 "" /dev/null
# 查看后端输出
lpinfo -v 2>&1
11.5 性能问题排查
11.5.1 打印速度慢
可能原因:
| 原因 | 检查方法 | 解决方案 |
|---|---|---|
| 高分辨率设置 | 查看打印选项 | 降低分辨率 |
| 大文件 | 检查文件大小 | 压缩文件 |
| 网络延迟 | ping 打印机 | 优化网络 |
| 过滤器效率 | 查看日志 | 使用更高效的过滤器 |
| 打印机内存 | 打印机规格 | 减少每页数据量 |
# 检查打印任务大小
ls -lh /var/spool/cups/
# 检查网络延迟
ping -c 10 192.168.1.100
# 检查过滤器处理时间
time cupsfilter document.pdf > /dev/null
# 优化建议
# 1. 使用较低分辨率
lp -o Resolution=300dpi document.pdf
# 2. 使用灰度模式
lp -o ColorModel=Gray document.pdf
# 3. 使用原始格式(跳过过滤器)
lp -o raw document.ps
11.5.2 CUPS 服务响应慢
# 检查 CUPS 进程状态
ps aux | grep cupsd
# 检查内存使用
free -h
# 检查 CPU 使用
top -p $(pgrep cupsd)
# 检查磁盘 I/O
iostat -x 1
# 检查队列大小
lpstat -o | wc -l
# 清理旧任务
sudo cancel -a
sudo cupsctl --purge-jobs
# 限制并发任务
# 在 cupsd.conf 中设置
# MaxClients 50
11.6 高级诊断工具
11.6.1 使用 strace 调试
# 跟踪 CUPS 系统调用
sudo strace -f -p $(pgrep cupsd) -o /tmp/cups-strace.log
# 跟踪特定操作
sudo strace -e trace=open,read,write -p $(pgrep cupsd)
# 跟踪打印任务
sudo strace -f -p $(pgrep cupsd) 2>&1 | grep "myprinter"
11.6.2 使用 tcpdump 抓包
# 捕获 IPP 流量
sudo tcpdump -i eth0 port 631 -w /tmp/ipp-traffic.pcap
# 捕获网络打印流量
sudo tcpdump -i eth0 port 9100 -w /tmp/print-traffic.pcap
# 实时查看
sudo tcpdump -i eth0 port 631 -A
11.6.3 使用 Wireshark 分析
# 1. 使用 tcpdump 捕获流量
sudo tcpdump -i eth0 port 631 -w /tmp/cups.pcap
# 2. 在 Wireshark 中打开
wireshark /tmp/cups.pcap
# 3. 过滤 IPP 协议
# 过滤器: ipp
# 4. 分析 IPP 操作
# 可以看到 Print-Job, Get-Printer-Attributes 等操作
11.7 自动化监控
11.7.1 监控脚本
#!/bin/bash
# cups-monitor.sh - CUPS 监控脚本
ALERT_EMAIL="[email protected]"
CUPS_LOG="/var/log/cups/error_log"
QUEUE_THRESHOLD=10
# 检查 CUPS 服务
if ! systemctl is-active cups > /dev/null 2>&1; then
echo "ALERT: CUPS service is down" | mail -s "CUPS Alert" "$ALERT_EMAIL"
systemctl restart cups
fi
# 检查打印队列
queue_count=$(lpstat -o 2>/dev/null | wc -l)
if [ "$queue_count" -gt "$QUEUE_THRESHOLD" ]; then
echo "ALERT: Print queue has $queue_count jobs (threshold: $QUEUE_THRESHOLD)" | \
mail -s "CUPS Queue Alert" "$ALERT_EMAIL"
fi
# 检查最近错误
recent_errors=$(tail -100 "$CUPS_LOG" | grep -i "error" | wc -l)
if [ "$recent_errors" -gt 10 ]; then
echo "ALERT: $recent_errors errors in last 100 log entries" | \
mail -s "CUPS Error Alert" "$ALERT_EMAIL"
fi
# 检查磁盘空间
spool_usage=$(df /var/spool/cups | tail -1 | awk '{print $5}' | sed 's/%//')
if [ "$spool_usage" -gt 90 ]; then
echo "ALERT: Spool disk usage at ${spool_usage}%" | \
mail -s "CUPS Disk Alert" "$ALERT_EMAIL"
fi
11.7.2 Prometheus 监控
# prometheus.yml
scrape_configs:
- job_name: 'cups'
static_configs:
- targets: ['localhost:9102']
metrics_path: /metrics
# cups-exporter 配置
# 需要安装 cups-prometheus-exporter
# pip install cups-prometheus-exporter
11.8 业务场景
11.8.1 场景一:批量打印故障
# 症状:大批量打印时打印机卡住
# 1. 暂停打印机
sudo cupsdisable myprinter
# 2. 清理队列
cancel -a myprinter
# 3. 重启打印机
sudo cupsenable myprinter
# 4. 分批打印
split -l 100 large-file.txt chunk_
for chunk in chunk_*; do
lp -d myprinter "$chunk"
sleep 5 # 等待 5 秒
done
11.8.2 场景二:驱动冲突
# 症状:升级系统后打印机不工作
# 1. 检查驱动
lpinfo -m | grep "旧驱动名称"
# 2. 重新安装驱动
sudo apt install --reinstall printer-driver-gutenprint
# 3. 重新配置打印机
sudo lpadmin -p myprinter -P /usr/share/ppd/new-driver.ppd
# 4. 测试打印
lp -d myprinter /usr/share/cups/data/testprint
11.8.3 场景三:网络打印中断
# 症状:网络打印机间歇性断连
# 1. 检查网络稳定性
ping -c 100 192.168.1.100 | tail -5
# 2. 配置后备后端
sudo lpadmin -p myprinter \
-v "beh:/3/5/socket/socket://192.168.1.100:9100"
# 3. 增加超时设置
# 在 cupsd.conf 中
# JobRetryTimeout 30
# 4. 监控脚本
while true; do
if ! ping -c 1 192.168.1.100 > /dev/null 2>&1; then
echo "Printer offline at $(date)" >> /var/log/printer-monitor.log
fi
sleep 60
done
11.9 扩展阅读
| 资源 | 链接 |
|---|---|
| CUPS 故障排查 | https://www.cups.org/doc/troubleshooting.html |
| CUPS 错误代码 | https://www.cups.org/doc/ipp-status-codes.html |
| Linux 打印故障排查 | https://wiki.archlinux.org/title/CUPS/Troubleshooting |
| Wireshark | https://www.wireshark.org/ |
11.10 本章小结
| 主题 | 关键要点 |
|---|---|
| 排查流程 | 症状确认 → 基本检查 → 日志分析 → 配置检查 → 解决 |
| 常见问题 | 打印机识别、队列卡住、打印质量、网络连接、驱动兼容 |
| 日志分析 | error_log/access_log/page_log 三种日志 |
| 调试模式 | LogLevel debug/debug2、cupsfilter -v、ipptool -tv |
| 性能优化 | 降低分辨率、灰度模式、清理队列、优化网络 |
| 监控 | 自动化监控脚本、Prometheus 集成 |
下一章预告:我们将学习 CUPS 最佳实践,包括运维规范、监控策略、安全基线和生产环境部署。
11.11 练习题
诊断题:使用快速诊断脚本检查你的 CUPS 环境,列出发现的问题。
日志题:分析 error_log 中的错误,找出最常见的 3 种错误类型及其原因。
调试题:启用 CUPS 调试模式,执行一次打印操作,分析调试日志。
监控题:编写监控脚本,当打印队列超过 20 个任务时发送告警。
场景题:一个用户报告打印输出是乱码,请列出你的排查步骤和解决方案。