简介这份 CUPS 2.3.3 源码包面向 Linux、BSD、macOS 等类 Unix 系统的开发者与运维人员用于在本地编译、定制和部署开源打印系统解决网络打印作业管理、驱动过滤与打印服务配置等实际问题。包内共 1294 个文件以模板文件、C 源码、HTML 文档、头文件及测试脚本为主另有构建配置、手册页、策略示例和图片资源压缩包约 7.76MB源码目录涵盖服务端、库、过滤器、文档、策略与测试等模块结构完整便于按模块查阅和二次开发。已有 928 人学习关注。借助这套源码读者可对照 configure 与自动化构建体系完成环境适配理解 IPP 打印作业处理、过滤器驱动模型、Web 管理接口与 SSL/TLS 传输安全等实现思路并基于示例策略和测试用例开展本地验证适合需要深入掌握 CUPS 架构、定制打印方案或参与社区贡献的中高级技术人员。1. 从一台 cupsd 起来了但纸出不来的机器说起某公司内网有一台打印服务器发行版自带的那套打印组件版本偏旧接某台网络打印机时队列能建、作业能提交纸就是不出来。折腾半天决定上源码锁 CUPS 2.3.3。CUPS 2.3.3 源码安装这件事麻烦的从来不是 make 那几分钟而是 configure 时少装了一个开发包、cups-files.conf 里 User 写错、装完发现和系统自带的老 cupsd 抢 631 端口。这类问题编译期一声不吭全在运行期以「队列停住」「Forbidden」「Filter failed」的形式冒出来。下面这份记录从依赖清单一路写到一张纸真的从机器里出来第一次源码编 CUPS 的人可以照着走手里已经有 2.3.3 包、只想核对参数的人也能直接翻到 configure 那节对一遍。2. 装前把依赖对齐CUPS 2.3.3 编译要过哪几道关2.1 为什么很多环境还锁在 2.3.3CUPS 2.3.3 属于 2.3 系列构建方式还是 autotools 那一套./configure探一遍环境make编译make install落地。这个系列在配置文件的划分上已经定型——cupsd.conf管监听、访问控制和日志级别cups-files.conf管运行用户、目录、日志文件路径。网上流传的很多老教程还停留在「把 User 写进 cupsd.conf」的年代照着抄到 2.3.3 上cupsd 重启后直接起不来日志里只丢一句配置文件解析失败这是最常见的版本坑。选源码而不是直接用系统包通常有三个理由系统仓库里的版本太老缺 IPP Everywhere 或者缺 avahi 支持需要自己指定 TLS 后端让证书链路和现有环境对齐需要把 CUPS 装到/usr下和系统里其它依赖 libcups 的组件共用一套库。三种理由里任何一种成立源码编译就是唯一路径。反过来如果只是想要一个能打本地 USB 打印机的环境系统包通常更省事不必折腾编译。还要提醒一句2.3.3 是一个源码包不是二进制包tar.gz 解出来是完整源码树没有预编译产物也没有安装脚本所有路径和开关都得自己在 configure 阶段定下来。2.2 依赖清单分 apt 系和 dnf 系列一遍CUPS 的依赖分两类必需的和「有就编进去、没有就静默跳过」的。后者是翻车重灾区configure 不会因为缺 avahi 就停下它只是把 Bonjour 发现功能关掉你以为装好了实际网络打印机在客户端列表里根本看不见。所以依赖要一次性列全。组件作用apt 系包名dnf/yum 系包名gcc / make编译器和构建工具build-essentialgcc gcc-c makezlibPDF 与位图数据压缩zlib1g-devzlib-devellibpngPNG 图像 filterlibpng-devlibpng-devellibjpegJPEG 图像 filterlibjpeg-devlibjpeg-turbo-devellibtiffTIFF 图像 filterlibtiff-devlibtiff-develfreetype / fontconfig字体渲染文字类 filter 依赖libfreetype6-dev libfontconfig1-devfreetype-devel fontconfig-devellibusb-1.0USB backend本地 USB 打印机必需libusb-1.0-0-devlibusb1-develavahi-clientBonjour / DNS-SD 设备发现libavahi-client-devavahi-develgnutls 或 opensslTLS加密 IPP 连接libgnutls28-dev 或 libssl-devgnutls-devel 或 openssl-develPAM管理认证libpam0g-devpam-devellibpaper默认纸张尺寸libpaper-devlibpaper-develgettext本地化消息gettextgettext安装命令按包管理器分两条先更新索引再装不要图快直接上。# apt 系一次装齐缺一个都可能让某个 filter 静默失效 apt-get update apt-get install -y build-essential pkg-config \ zlib1g-dev libpng-dev libjpeg-dev libtiff-dev \ libfreetype6-dev libfontconfig1-dev libusb-1.0-0-dev \ libavahi-client-dev libgnutls28-dev libpam0g-dev \ libpaper-dev gettext# dnf/yum 系注意 libjpeg 在这里叫 libjpeg-turbo-devel dnf install -y gcc gcc-c make pkgconfig \ zlib-devel libpng-devel libjpeg-turbo-devel libtiff-devel \ freetype-devel fontconfig-devel libusb1-devel \ avahi-devel gnutls-devel pam-devel \ libpaper-devel gettext这里的取舍点在于 TLS 后端gnutls 和 openssl 装哪个configure 就优先用哪个两个都装的时候结果取决于探测顺序。我一般只装一个让链接目标确定下来省得后面排查证书问题时还要先确认 cupsd 到底链的哪套库。2.3 编译前自检pkg-config 名字和包名不是一回事装完包别急着 configure先拿 pkg-config 过一遍。库的 pkg-config 名字和包管理器里的包名经常对不上比如libtiff-dev对应的探测名是libtiff-4libusb-1.0-0-dev对应libusb-1.0。名字写错pkg-config 返回非零configure 就当这个库不存在。# 逐个探测 CUPS 会用到的库MISSING 的那行回去补包 for p in zlib libpng libjpeg libtiff-4 freetype2 fontconfig \ libusb-1.0 avahi-client gnutls; do printf %-14s $p pkg-config --modversion $p 2/dev/null || echo MISSING done输出里出现 MISSING 就去补对应的开发包全部有版本号再往下走。这一步看着啰嗦但比 configure 完事之后发现「怎么 avahi 没编进去」再重来一遍省时间。3. 编译与安装configure 开关怎么取、文件最终落在哪3.1 解包与看帮助拿到 cups-2.3.3-source.tar.gz 之后先确认顶层目录名再解压。# 先看一眼包的顶层目录正常应该是 cups-2.3.3/ tar -tzf cups-2.3.3-source.tar.gz | head -5 tar -xzf cups-2.3.3-source.tar.gz cd cups-2.3.3进目录后不要直接 configure先看一遍帮助里跟目录和功能相关的开关把实际支持的选项名记下来因为有些第三方重新打包过的源码包会改掉个别开关名。# 只看目录类、功能类开关输出不长值得逐条读 ./configure --help | grep -E ^ --(with|enable|disable) | head -40我习惯直接在源码目录里 configure不走 out-of-tree 构建。CUPS 的 Makefile 对 VPATH 的支持不算好out-of-tree 编完再 install偶尔会出现路径拼接对不上的情况为省这点磁盘空间不值得。源码目录留在/usr/local/src或者/opt/src下编完不急着删后面排查时要回来看编译日志。3.2 configure 关键开关逐条过下面是 2.3.3 上我常用的一套参数前缀定在/usr和系统里其它组件共用一套路径。./configure \ --prefix/usr \ --sysconfdir/etc \ --localstatedir/var \ --with-cups-userlp \ --with-cups-grouplp \ --with-dnssdavahi \ --with-tlsopenssl \ --disable-debug \ --disable-static逐条说清楚每个参数改了什么--prefix/usr程序本体装到/usr/sbin、/usr/lib/cups、/usr/share/cups。如果不想覆盖系统包把前缀改成/opt/cups代价是后面所有路径、systemd 单元、客户端默认 socket 位置都得跟着改。--sysconfdir/etc配置文件进/etc/cups。这是 CUPS 约定俗成的路径改到别处会出现 cupsd 找不到cups-files.conf的情况除非同步改启动参数。--localstatedir/var队列暂存、日志、状态文件落在/var/spool/cups、/var/log/cups、/var/cache/cups。--with-cups-user/--with-cups-groupcupsd 运行身份默认就是lp。系统里已有别的打印服务占用这个用户时这里改成专用账户后面cups-files.conf里也要同步。--with-dnssdavahi启用 Bonjour 发现。不需要局域网自动发现就写--with-dnssdno能少一个运行期依赖。--with-tlsopenssl显式指定 TLS 后端。你手上这份包如果不认这个开关--help里搜 tls 就能看到它实际认什么写法别硬套。--disable-debug关掉调试符号二进制小一圈。要抓 cupsd 的详细日志时LogLevel debug就够用不需要重新编译。--disable-static只生成共享库libcups.so不生成.a。除非有老程序必须静态链接否则没必要。configure 跑完会输出一屏检测结果逐行扫一遍yes/no。重点看 avahi、openssl/gnutls、usb、pam 这几项期望是 yes 的项显示 no就回去补开发包再重新 configure不要带着残缺的探测结果继续 make。3.3 make 与 make install以及装完之后的目录对照编译按 CPU 核数并行装的时候必须 root。# 并行编译nproc 拿到核数编译失败时先看最后 30 行 make -j$(nproc) # 安装已经装过旧版的话这一步会覆盖二进制但一般不动已有配置 make install # 装到 /usr/lib 下的共享库刷新一下缓存否则 cupsd 启动时报找不到 libcups.so.2 ldconfig装完之后对照下面这张表确认落地位置后面配置和排错全靠这些路径。路径内容备注/usr/sbin/cupsd调度器主程序-f前台运行-t只测配置/usr/lib/cups/backend/后端usb://、ipp://、socket://都靠它必须是可执行权限/usr/lib/cups/filter/格式转换 filter缺 cups-filters 时这里会很少/etc/cups/cupsd.conf监听、访问控制、日志级别常用改这里/etc/cups/cups-files.conf运行用户、组、目录、日志路径User/Group 在这/etc/cups/printers.conf队列定义由 lpadmin 自动写别手改/var/spool/cups/作业暂存属主必须是运行用户/var/log/cups/error_log主要排错入口tail -f常驻/run/cups/cups.sock本地域套接字客户端默认走这里4. 启动与最小配置cups-files.conf、cupsd.conf 和 systemd4.1 运行用户与 lpadmin 组cupsd 以什么身份跑、谁能做管理操作这两件事都在cups-files.conf里定不在cupsd.conf。这是 2.x 和更早版本最大的差别。# /etc/cups/cups-files.conf User lp Group lp # 管理组组内成员能通过认证执行增删队列等操作 SystemGroup lpadmin # 日志文件位置 AccessLog /var/log/cups/access_log ErrorLog /var/log/cups/error_log PageLog /var/log/cups/page_log把日常运维账号加进管理组让它不用 root 也能 lpadmin# 组不存在时先建再把人加进去 getent group lpadmin || groupadd -r lpadmin usermod -aG lpadmin deploy # deploy 换成你自己的账号 # 加组后必须重新登录或 newgrp lpadmin才生效 idid输出里没看到 lpadmin 就别急着测 lpadmin那是没生效不是权限配错。另外/var/spool/cups的属主要和这里的 User 一致装过旧版 CUPS 的机器上这个目录可能属于别的用户启动时会报目录不可写。4.2 cupsd.conf 里必须动的地方默认生成的cupsd.conf是监听所有地址的内网打印服务器这样配问题不大但如果是台有公网口的机器631 端口敞开意味着任何人都能提交作业。最小改动是只监听需要的地址。# /etc/cups/cupsd.conf # 只监听本机回环和内网地址需要别的机器直连就换成对应 IP Listen 127.0.0.1:631 Listen 192.168.10.20:631 Listen /run/cups/cups.sock # Web 管理界面方便看队列状态不需要就改 No WebInterface Yes DefaultAuthType Basic LogLevel warn MaxLogSize 1m PreserveJobHistory Yes # 访问控制Order 决定先看 Allow 还是先看 Deny Location / Order allow,deny Allow LOCAL /Location # 管理接口只放开本地子网别用 Allow all Location /admin Order allow,deny Allow LOCAL /Location Location /admin/conf Order allow,deny Allow LOCAL /LocationAllow LOCAL表示同网段来源放行比Allow all安全得多。Order allow,deny的判定顺序是先匹配 Allow 再匹配 Deny写反了会出现「明明在同网段却一直 403」。改完先别重启用cupsd -t做语法检查它会明确告诉你哪一行有问题。# 只检查配置不启动 /usr/sbin/cupsd -t4.3 systemd 托管与开机自启源码安装不会自动生成服务单元自己写一个。关键是Type如果 configure 时没开 systemd 相关支持cupsd 不会发 sd_notify 通知Typenotify会让 systemd 一直等到超时然后判失败。# /etc/systemd/system/cups.service [Unit] DescriptionCUPS Scheduler Afternetwork.target [Service] # 没编进 systemd 支持就用 simple别用 notify Typesimple ExecStart/usr/sbin/cupsd -f ExecReload/bin/kill -HUP $MAINPID Restarton-failure RestartSec3 [Install] WantedBymulti-user.target-f是前台运行交给 systemd 托管时必须加否则 cupsd 自己 daemon 化systemd 会以为进程退了然后反复重启。systemctl daemon-reload systemctl enable --now cups systemctl status cups --no-pager4.4 加第一个队列lpinfo 找设备lpadmin 建队列设备用lpinfo -v列驱动用lpinfo -m列。前者输出里direct usb://...是本地 USBnetwork ipp://...是网络打印机。# 列出 cupsd 当前能看到的设备 lpinfo -v # 列可用 PPD/驱动输出很长按关键字过滤 lpinfo -m | grep -i -E postscript|pcl|everywhere | head建队列分两种情形。打印机支持 IPP Everywhere 就直接用-m everywhere不依赖厂商 PPD老机器只能走 PPD。# 支持 IPP Everywhere 的网络打印机 lpadmin -p office-a -E \ -v ipp://192.168.10.50/ipp/print \ -m everywhere \ -o printer-is-sharedtrue # 只有 PPD 的老机器-E 表示启用并接受作业 lpadmin -p lab-b -E \ -v usb://Vendor/Model%20Name \ -P /usr/share/cups/model/vendor-model.ppd # 设默认打印机并放行 lpadmin -d office-a lpstat -p -d-E不能省它同时做两件事启用队列、接受作业。少了它队列建出来是停用状态lpstat -p显示 disabled提交的作业全堆在那不动。5. 常见问题排查源码装 CUPS 最容易翻车的五处5.1 编译期报找不到 zlib 或 libpng现象configure 输出里zlib一行是 no或者 make 阶段报cannot find -lpng但包管理器明明显示已安装。原因装的是运行库不是开发包头文件没落地。另一种情况是库装在非标准前缀下pkg-config 搜不到.pc文件。解决确认装的是-dev/-devel结尾的包再回 2.3 节那段 pkg-config 循环过一遍。库在自定义路径时补环境变量export PKG_CONFIG_PATH/opt/lib/pkgconfig:$PKG_CONFIG_PATHconfigure 前设好。还有一种罕见情况系统里同时存在两个版本的 zlib链接时取到了老的ldconfig -p | grep libz看一眼实际指向。5.2 cupsd 启动即退出日志里是 Address already in use现象systemctl start cups立刻 failed/var/log/cups/error_log里是Unable to bind socket for address 0.0.0.0:631。原因系统自带的老 cupsd 还在跑端口被占或者上一次 cupsd 异常退出留下了 socket 文件没清。解决先看谁占着端口停掉旧服务再启新的。ss -lntp | grep 631 systemctl stop cups # 老服务名可能相同源码安装后会被覆盖先停再启 rm -f /run/cups/cups.sock systemctl start cups如果是源码装到了/opt/cups而系统服务还在两个服务同名会互相覆盖这种情况建议直接卸掉系统包或者禁用它别让两套共存。5.3 lpadmin 报 Forbidden 或 Unauthorized现象执行lpadmin -p ...返回lpadmin: Forbidden或者 Web 界面进/admin一直弹认证框。原因当前账号不在cups-files.conf的SystemGroup里加进组后没有重新登录会话里还是旧的组信息或者cupsd.conf里/admin的访问控制没放开LOCAL。解决id看一眼有没有 lpadmin没有就newgrp lpadmin或者重新登录。确认SystemGroup lpadmin这行没写错改完systemctl reload cups。认证方式如果是DefaultAuthType Basic密码走的是系统 PAM账号本身要能登系统。5.4 作业一直 pendingerror_log 里是 Filter failed现象lpstat -o能看到作业状态停在 pending 或者 processing纸一动不动error_log里反复出现Filter failed。原因多半是 filter 缺依赖。CUPS 本体只带基础 filterPDF 转光栅要靠 cups-filters 和 ghostscript这两样源码包里没有得单独装。另一种是/usr/lib/cups/filter/下的脚本丢了执行权限。解决补装 cups-filters 和 ghostscript然后检查 filter 权限。# 看某台打印机最近一次作业的详细日志 grep -A 20 $(lpstat -W completed -o | tail -1 | awk {print $1}) /var/log/cups/error_log # filter 目录下所有文件都该有可执行位 ls -l /usr/lib/cups/filter/ | grep -v ^-rwx权限修复用chmod 755批量补一遍。如果是 PPD 引用了不存在的 filter那只能换驱动日志里会写出具体缺哪个二进制。5.5 打印出来是空白页或者乱码现象作业状态显示 completedpage_log也有记录纸出来是白的或者一堆乱码字符。原因PPD 和实际机型不匹配最常见的是拿 PostScript 驱动去驱动只支持 PCL 的机器或者页面尺寸配错内容被推到纸外。解决先确认机型支持什么页面描述语言再换对应 PPD。临时验证可以用-o覆盖页面尺寸发一个测试作业看是不是尺寸问题。# 发一个纯文本测试页绕开 PPD 的格式转换 lp -d lab-b -o mediaA4 /etc/cups/cupsd.conf # 查作业实际用了什么参数 lpstat -l -o纯文本能打、PDF 打不出来问题就在 PDF 到光栅的那段 filter 上回 5.4 处理。两种都空白基本可以断定是驱动选错。6. 验证跑通从 lpstat 到一张真正出来的纸配置改完、服务起来别急着提交作业按下面这条链路一层层验出问题时能立刻定位到哪一段断了。顺序命令期望结果不对时看哪1cups-config --version输出 2.3.3装的还是系统旧版查which cups-config2cupsd -t无输出退出码 0报行号就是配置语法错3systemctl is-active cupsactivejournalctl -u cups -n 504lpstat -rscheduler is runningcupsd 没起或 socket 路径不对5lpinfo -v至少列出一个设备backend 目录权限或设备没插好6lpstat -p -d队列 idle默认打印机有标记队列 disabled重跑 lpadmin -E7发作业纸出来tail -f /var/log/cups/error_log真正提交作业的时候建议同时开两个终端一个tail -f /var/log/cups/error_log一个跑命令。# 终端 A盯着日志作业进来会立刻打印处理链路 tail -f /var/log/cups/error_log # 终端 B发一个测试作业然后看队列和页计数 lp -d office-a /etc/cups/cupsd.conf lpstat -o tail -3 /var/log/cups/page_logpage_log里出现一行记录说明作业走完了整个 filter 链、被 backend 送出去了。这时候纸还没出来问题就已经不在 CUPS 这一层了去查打印机本身、网络连通性和队列名对不对。日志里如果卡在[Job xx] Started filter之后不动那就是 filter 环节回 5.4卡在Started backend之后就是设备侧先lpinfo -v确认设备还在不在。队列卡死清理用cancel -a把待处理作业全清掉再重来比一个个 cancel 快。验证阶段还有一个容易忽略的点preserve job history开着的时候历史作业会一直占着/var/spool/cups测试阶段无所谓长期跑建议定期cancel -a或者关掉历史保留。从那以后我每次源码装完 CUPS都会强制走一遍这七步验证哪怕只是给测试机搭个环境——因为「服务起来了」和「能打纸」之间隔着 filter、backend、权限三道门肉眼是看不出来的只有日志和 page_log 会说实话。这份 cups-2.3.3-source.tar.gz 拿到手先对一下顶层目录名是不是cups-2.3.3再按第 3 章那套 configure 参数走一遍剩下的就是耐心看日志。希望帮到你。本文还有配套的精品资源点击获取
简介这份 CUPS 2.3.3 源码包面向 Linux、BSD、macOS 等类 Unix 系统的开发者与运维人员用于在本地编译、定制和部署开源打印系统解决网络打印作业管理、驱动过滤与打印服务配置等实际问题。包内共 1294 个文件以模板文件、C 源码、HTML 文档、头文件及测试脚本为主另有构建配置、手册页、策略示例和图片资源压缩包约 7.76MB源码目录涵盖服务端、库、过滤器、文档、策略与测试等模块结构完整便于按模块查阅和二次开发。已有 928 人学习关注。借助这套源码读者可对照 configure 与自动化构建体系完成环境适配理解 IPP 打印作业处理、过滤器驱动模型、Web 管理接口与 SSL/TLS 传输安全等实现思路并基于示例策略和测试用例开展本地验证适合需要深入掌握 CUPS 架构、定制打印方案或参与社区贡献的中高级技术人员。1. 从一台 cupsd 起来了但纸出不来的机器说起某公司内网有一台打印服务器发行版自带的那套打印组件版本偏旧接某台网络打印机时队列能建、作业能提交纸就是不出来。折腾半天决定上源码锁 CUPS 2.3.3。CUPS 2.3.3 源码安装这件事麻烦的从来不是 make 那几分钟而是 configure 时少装了一个开发包、cups-files.conf 里 User 写错、装完发现和系统自带的老 cupsd 抢 631 端口。这类问题编译期一声不吭全在运行期以「队列停住」「Forbidden」「Filter failed」的形式冒出来。下面这份记录从依赖清单一路写到一张纸真的从机器里出来第一次源码编 CUPS 的人可以照着走手里已经有 2.3.3 包、只想核对参数的人也能直接翻到 configure 那节对一遍。2. 装前把依赖对齐CUPS 2.3.3 编译要过哪几道关2.1 为什么很多环境还锁在 2.3.3CUPS 2.3.3 属于 2.3 系列构建方式还是 autotools 那一套./configure探一遍环境make编译make install落地。这个系列在配置文件的划分上已经定型——cupsd.conf管监听、访问控制和日志级别cups-files.conf管运行用户、目录、日志文件路径。网上流传的很多老教程还停留在「把 User 写进 cupsd.conf」的年代照着抄到 2.3.3 上cupsd 重启后直接起不来日志里只丢一句配置文件解析失败这是最常见的版本坑。选源码而不是直接用系统包通常有三个理由系统仓库里的版本太老缺 IPP Everywhere 或者缺 avahi 支持需要自己指定 TLS 后端让证书链路和现有环境对齐需要把 CUPS 装到/usr下和系统里其它依赖 libcups 的组件共用一套库。三种理由里任何一种成立源码编译就是唯一路径。反过来如果只是想要一个能打本地 USB 打印机的环境系统包通常更省事不必折腾编译。还要提醒一句2.3.3 是一个源码包不是二进制包tar.gz 解出来是完整源码树没有预编译产物也没有安装脚本所有路径和开关都得自己在 configure 阶段定下来。2.2 依赖清单分 apt 系和 dnf 系列一遍CUPS 的依赖分两类必需的和「有就编进去、没有就静默跳过」的。后者是翻车重灾区configure 不会因为缺 avahi 就停下它只是把 Bonjour 发现功能关掉你以为装好了实际网络打印机在客户端列表里根本看不见。所以依赖要一次性列全。组件作用apt 系包名dnf/yum 系包名gcc / make编译器和构建工具build-essentialgcc gcc-c makezlibPDF 与位图数据压缩zlib1g-devzlib-devellibpngPNG 图像 filterlibpng-devlibpng-devellibjpegJPEG 图像 filterlibjpeg-devlibjpeg-turbo-devellibtiffTIFF 图像 filterlibtiff-devlibtiff-develfreetype / fontconfig字体渲染文字类 filter 依赖libfreetype6-dev libfontconfig1-devfreetype-devel fontconfig-devellibusb-1.0USB backend本地 USB 打印机必需libusb-1.0-0-devlibusb1-develavahi-clientBonjour / DNS-SD 设备发现libavahi-client-devavahi-develgnutls 或 opensslTLS加密 IPP 连接libgnutls28-dev 或 libssl-devgnutls-devel 或 openssl-develPAM管理认证libpam0g-devpam-devellibpaper默认纸张尺寸libpaper-devlibpaper-develgettext本地化消息gettextgettext安装命令按包管理器分两条先更新索引再装不要图快直接上。# apt 系一次装齐缺一个都可能让某个 filter 静默失效 apt-get update apt-get install -y build-essential pkg-config \ zlib1g-dev libpng-dev libjpeg-dev libtiff-dev \ libfreetype6-dev libfontconfig1-dev libusb-1.0-0-dev \ libavahi-client-dev libgnutls28-dev libpam0g-dev \ libpaper-dev gettext# dnf/yum 系注意 libjpeg 在这里叫 libjpeg-turbo-devel dnf install -y gcc gcc-c make pkgconfig \ zlib-devel libpng-devel libjpeg-turbo-devel libtiff-devel \ freetype-devel fontconfig-devel libusb1-devel \ avahi-devel gnutls-devel pam-devel \ libpaper-devel gettext这里的取舍点在于 TLS 后端gnutls 和 openssl 装哪个configure 就优先用哪个两个都装的时候结果取决于探测顺序。我一般只装一个让链接目标确定下来省得后面排查证书问题时还要先确认 cupsd 到底链的哪套库。2.3 编译前自检pkg-config 名字和包名不是一回事装完包别急着 configure先拿 pkg-config 过一遍。库的 pkg-config 名字和包管理器里的包名经常对不上比如libtiff-dev对应的探测名是libtiff-4libusb-1.0-0-dev对应libusb-1.0。名字写错pkg-config 返回非零configure 就当这个库不存在。# 逐个探测 CUPS 会用到的库MISSING 的那行回去补包 for p in zlib libpng libjpeg libtiff-4 freetype2 fontconfig \ libusb-1.0 avahi-client gnutls; do printf %-14s $p pkg-config --modversion $p 2/dev/null || echo MISSING done输出里出现 MISSING 就去补对应的开发包全部有版本号再往下走。这一步看着啰嗦但比 configure 完事之后发现「怎么 avahi 没编进去」再重来一遍省时间。3. 编译与安装configure 开关怎么取、文件最终落在哪3.1 解包与看帮助拿到 cups-2.3.3-source.tar.gz 之后先确认顶层目录名再解压。# 先看一眼包的顶层目录正常应该是 cups-2.3.3/ tar -tzf cups-2.3.3-source.tar.gz | head -5 tar -xzf cups-2.3.3-source.tar.gz cd cups-2.3.3进目录后不要直接 configure先看一遍帮助里跟目录和功能相关的开关把实际支持的选项名记下来因为有些第三方重新打包过的源码包会改掉个别开关名。# 只看目录类、功能类开关输出不长值得逐条读 ./configure --help | grep -E ^ --(with|enable|disable) | head -40我习惯直接在源码目录里 configure不走 out-of-tree 构建。CUPS 的 Makefile 对 VPATH 的支持不算好out-of-tree 编完再 install偶尔会出现路径拼接对不上的情况为省这点磁盘空间不值得。源码目录留在/usr/local/src或者/opt/src下编完不急着删后面排查时要回来看编译日志。3.2 configure 关键开关逐条过下面是 2.3.3 上我常用的一套参数前缀定在/usr和系统里其它组件共用一套路径。./configure \ --prefix/usr \ --sysconfdir/etc \ --localstatedir/var \ --with-cups-userlp \ --with-cups-grouplp \ --with-dnssdavahi \ --with-tlsopenssl \ --disable-debug \ --disable-static逐条说清楚每个参数改了什么--prefix/usr程序本体装到/usr/sbin、/usr/lib/cups、/usr/share/cups。如果不想覆盖系统包把前缀改成/opt/cups代价是后面所有路径、systemd 单元、客户端默认 socket 位置都得跟着改。--sysconfdir/etc配置文件进/etc/cups。这是 CUPS 约定俗成的路径改到别处会出现 cupsd 找不到cups-files.conf的情况除非同步改启动参数。--localstatedir/var队列暂存、日志、状态文件落在/var/spool/cups、/var/log/cups、/var/cache/cups。--with-cups-user/--with-cups-groupcupsd 运行身份默认就是lp。系统里已有别的打印服务占用这个用户时这里改成专用账户后面cups-files.conf里也要同步。--with-dnssdavahi启用 Bonjour 发现。不需要局域网自动发现就写--with-dnssdno能少一个运行期依赖。--with-tlsopenssl显式指定 TLS 后端。你手上这份包如果不认这个开关--help里搜 tls 就能看到它实际认什么写法别硬套。--disable-debug关掉调试符号二进制小一圈。要抓 cupsd 的详细日志时LogLevel debug就够用不需要重新编译。--disable-static只生成共享库libcups.so不生成.a。除非有老程序必须静态链接否则没必要。configure 跑完会输出一屏检测结果逐行扫一遍yes/no。重点看 avahi、openssl/gnutls、usb、pam 这几项期望是 yes 的项显示 no就回去补开发包再重新 configure不要带着残缺的探测结果继续 make。3.3 make 与 make install以及装完之后的目录对照编译按 CPU 核数并行装的时候必须 root。# 并行编译nproc 拿到核数编译失败时先看最后 30 行 make -j$(nproc) # 安装已经装过旧版的话这一步会覆盖二进制但一般不动已有配置 make install # 装到 /usr/lib 下的共享库刷新一下缓存否则 cupsd 启动时报找不到 libcups.so.2 ldconfig装完之后对照下面这张表确认落地位置后面配置和排错全靠这些路径。路径内容备注/usr/sbin/cupsd调度器主程序-f前台运行-t只测配置/usr/lib/cups/backend/后端usb://、ipp://、socket://都靠它必须是可执行权限/usr/lib/cups/filter/格式转换 filter缺 cups-filters 时这里会很少/etc/cups/cupsd.conf监听、访问控制、日志级别常用改这里/etc/cups/cups-files.conf运行用户、组、目录、日志路径User/Group 在这/etc/cups/printers.conf队列定义由 lpadmin 自动写别手改/var/spool/cups/作业暂存属主必须是运行用户/var/log/cups/error_log主要排错入口tail -f常驻/run/cups/cups.sock本地域套接字客户端默认走这里4. 启动与最小配置cups-files.conf、cupsd.conf 和 systemd4.1 运行用户与 lpadmin 组cupsd 以什么身份跑、谁能做管理操作这两件事都在cups-files.conf里定不在cupsd.conf。这是 2.x 和更早版本最大的差别。# /etc/cups/cups-files.conf User lp Group lp # 管理组组内成员能通过认证执行增删队列等操作 SystemGroup lpadmin # 日志文件位置 AccessLog /var/log/cups/access_log ErrorLog /var/log/cups/error_log PageLog /var/log/cups/page_log把日常运维账号加进管理组让它不用 root 也能 lpadmin# 组不存在时先建再把人加进去 getent group lpadmin || groupadd -r lpadmin usermod -aG lpadmin deploy # deploy 换成你自己的账号 # 加组后必须重新登录或 newgrp lpadmin才生效 idid输出里没看到 lpadmin 就别急着测 lpadmin那是没生效不是权限配错。另外/var/spool/cups的属主要和这里的 User 一致装过旧版 CUPS 的机器上这个目录可能属于别的用户启动时会报目录不可写。4.2 cupsd.conf 里必须动的地方默认生成的cupsd.conf是监听所有地址的内网打印服务器这样配问题不大但如果是台有公网口的机器631 端口敞开意味着任何人都能提交作业。最小改动是只监听需要的地址。# /etc/cups/cupsd.conf # 只监听本机回环和内网地址需要别的机器直连就换成对应 IP Listen 127.0.0.1:631 Listen 192.168.10.20:631 Listen /run/cups/cups.sock # Web 管理界面方便看队列状态不需要就改 No WebInterface Yes DefaultAuthType Basic LogLevel warn MaxLogSize 1m PreserveJobHistory Yes # 访问控制Order 决定先看 Allow 还是先看 Deny Location / Order allow,deny Allow LOCAL /Location # 管理接口只放开本地子网别用 Allow all Location /admin Order allow,deny Allow LOCAL /Location Location /admin/conf Order allow,deny Allow LOCAL /LocationAllow LOCAL表示同网段来源放行比Allow all安全得多。Order allow,deny的判定顺序是先匹配 Allow 再匹配 Deny写反了会出现「明明在同网段却一直 403」。改完先别重启用cupsd -t做语法检查它会明确告诉你哪一行有问题。# 只检查配置不启动 /usr/sbin/cupsd -t4.3 systemd 托管与开机自启源码安装不会自动生成服务单元自己写一个。关键是Type如果 configure 时没开 systemd 相关支持cupsd 不会发 sd_notify 通知Typenotify会让 systemd 一直等到超时然后判失败。# /etc/systemd/system/cups.service [Unit] DescriptionCUPS Scheduler Afternetwork.target [Service] # 没编进 systemd 支持就用 simple别用 notify Typesimple ExecStart/usr/sbin/cupsd -f ExecReload/bin/kill -HUP $MAINPID Restarton-failure RestartSec3 [Install] WantedBymulti-user.target-f是前台运行交给 systemd 托管时必须加否则 cupsd 自己 daemon 化systemd 会以为进程退了然后反复重启。systemctl daemon-reload systemctl enable --now cups systemctl status cups --no-pager4.4 加第一个队列lpinfo 找设备lpadmin 建队列设备用lpinfo -v列驱动用lpinfo -m列。前者输出里direct usb://...是本地 USBnetwork ipp://...是网络打印机。# 列出 cupsd 当前能看到的设备 lpinfo -v # 列可用 PPD/驱动输出很长按关键字过滤 lpinfo -m | grep -i -E postscript|pcl|everywhere | head建队列分两种情形。打印机支持 IPP Everywhere 就直接用-m everywhere不依赖厂商 PPD老机器只能走 PPD。# 支持 IPP Everywhere 的网络打印机 lpadmin -p office-a -E \ -v ipp://192.168.10.50/ipp/print \ -m everywhere \ -o printer-is-sharedtrue # 只有 PPD 的老机器-E 表示启用并接受作业 lpadmin -p lab-b -E \ -v usb://Vendor/Model%20Name \ -P /usr/share/cups/model/vendor-model.ppd # 设默认打印机并放行 lpadmin -d office-a lpstat -p -d-E不能省它同时做两件事启用队列、接受作业。少了它队列建出来是停用状态lpstat -p显示 disabled提交的作业全堆在那不动。5. 常见问题排查源码装 CUPS 最容易翻车的五处5.1 编译期报找不到 zlib 或 libpng现象configure 输出里zlib一行是 no或者 make 阶段报cannot find -lpng但包管理器明明显示已安装。原因装的是运行库不是开发包头文件没落地。另一种情况是库装在非标准前缀下pkg-config 搜不到.pc文件。解决确认装的是-dev/-devel结尾的包再回 2.3 节那段 pkg-config 循环过一遍。库在自定义路径时补环境变量export PKG_CONFIG_PATH/opt/lib/pkgconfig:$PKG_CONFIG_PATHconfigure 前设好。还有一种罕见情况系统里同时存在两个版本的 zlib链接时取到了老的ldconfig -p | grep libz看一眼实际指向。5.2 cupsd 启动即退出日志里是 Address already in use现象systemctl start cups立刻 failed/var/log/cups/error_log里是Unable to bind socket for address 0.0.0.0:631。原因系统自带的老 cupsd 还在跑端口被占或者上一次 cupsd 异常退出留下了 socket 文件没清。解决先看谁占着端口停掉旧服务再启新的。ss -lntp | grep 631 systemctl stop cups # 老服务名可能相同源码安装后会被覆盖先停再启 rm -f /run/cups/cups.sock systemctl start cups如果是源码装到了/opt/cups而系统服务还在两个服务同名会互相覆盖这种情况建议直接卸掉系统包或者禁用它别让两套共存。5.3 lpadmin 报 Forbidden 或 Unauthorized现象执行lpadmin -p ...返回lpadmin: Forbidden或者 Web 界面进/admin一直弹认证框。原因当前账号不在cups-files.conf的SystemGroup里加进组后没有重新登录会话里还是旧的组信息或者cupsd.conf里/admin的访问控制没放开LOCAL。解决id看一眼有没有 lpadmin没有就newgrp lpadmin或者重新登录。确认SystemGroup lpadmin这行没写错改完systemctl reload cups。认证方式如果是DefaultAuthType Basic密码走的是系统 PAM账号本身要能登系统。5.4 作业一直 pendingerror_log 里是 Filter failed现象lpstat -o能看到作业状态停在 pending 或者 processing纸一动不动error_log里反复出现Filter failed。原因多半是 filter 缺依赖。CUPS 本体只带基础 filterPDF 转光栅要靠 cups-filters 和 ghostscript这两样源码包里没有得单独装。另一种是/usr/lib/cups/filter/下的脚本丢了执行权限。解决补装 cups-filters 和 ghostscript然后检查 filter 权限。# 看某台打印机最近一次作业的详细日志 grep -A 20 $(lpstat -W completed -o | tail -1 | awk {print $1}) /var/log/cups/error_log # filter 目录下所有文件都该有可执行位 ls -l /usr/lib/cups/filter/ | grep -v ^-rwx权限修复用chmod 755批量补一遍。如果是 PPD 引用了不存在的 filter那只能换驱动日志里会写出具体缺哪个二进制。5.5 打印出来是空白页或者乱码现象作业状态显示 completedpage_log也有记录纸出来是白的或者一堆乱码字符。原因PPD 和实际机型不匹配最常见的是拿 PostScript 驱动去驱动只支持 PCL 的机器或者页面尺寸配错内容被推到纸外。解决先确认机型支持什么页面描述语言再换对应 PPD。临时验证可以用-o覆盖页面尺寸发一个测试作业看是不是尺寸问题。# 发一个纯文本测试页绕开 PPD 的格式转换 lp -d lab-b -o mediaA4 /etc/cups/cupsd.conf # 查作业实际用了什么参数 lpstat -l -o纯文本能打、PDF 打不出来问题就在 PDF 到光栅的那段 filter 上回 5.4 处理。两种都空白基本可以断定是驱动选错。6. 验证跑通从 lpstat 到一张真正出来的纸配置改完、服务起来别急着提交作业按下面这条链路一层层验出问题时能立刻定位到哪一段断了。顺序命令期望结果不对时看哪1cups-config --version输出 2.3.3装的还是系统旧版查which cups-config2cupsd -t无输出退出码 0报行号就是配置语法错3systemctl is-active cupsactivejournalctl -u cups -n 504lpstat -rscheduler is runningcupsd 没起或 socket 路径不对5lpinfo -v至少列出一个设备backend 目录权限或设备没插好6lpstat -p -d队列 idle默认打印机有标记队列 disabled重跑 lpadmin -E7发作业纸出来tail -f /var/log/cups/error_log真正提交作业的时候建议同时开两个终端一个tail -f /var/log/cups/error_log一个跑命令。# 终端 A盯着日志作业进来会立刻打印处理链路 tail -f /var/log/cups/error_log # 终端 B发一个测试作业然后看队列和页计数 lp -d office-a /etc/cups/cupsd.conf lpstat -o tail -3 /var/log/cups/page_logpage_log里出现一行记录说明作业走完了整个 filter 链、被 backend 送出去了。这时候纸还没出来问题就已经不在 CUPS 这一层了去查打印机本身、网络连通性和队列名对不对。日志里如果卡在[Job xx] Started filter之后不动那就是 filter 环节回 5.4卡在Started backend之后就是设备侧先lpinfo -v确认设备还在不在。队列卡死清理用cancel -a把待处理作业全清掉再重来比一个个 cancel 快。验证阶段还有一个容易忽略的点preserve job history开着的时候历史作业会一直占着/var/spool/cups测试阶段无所谓长期跑建议定期cancel -a或者关掉历史保留。从那以后我每次源码装完 CUPS都会强制走一遍这七步验证哪怕只是给测试机搭个环境——因为「服务起来了」和「能打纸」之间隔着 filter、backend、权限三道门肉眼是看不出来的只有日志和 page_log 会说实话。这份 cups-2.3.3-source.tar.gz 拿到手先对一下顶层目录名是不是cups-2.3.3再按第 3 章那套 configure 参数走一遍剩下的就是耐心看日志。希望帮到你。本文还有配套的精品资源点击获取
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
