CUPS 配置参数详解
cupsd.conf/cups-files.conf/printers.conf 逐项生效验证：Listen、MaxLogSize、LogLevel、WebInterface、Location 放行、LogFilePerm、ErrorPolicy 与默认队列双层存储，含 printers.conf 落盘时机与 ServerAlias 不生效等实测结论。
CUPS 配置参数详解
本文基于 Ubuntu 22.04 服务器实测（CUPS 2.4.1op1-1ubuntu4.21，对应上游 OpenPrinting CUPS v2.4.20），对
cupsd.conf、cups-files.conf、printers.conf三大配置文件的每一个关键参数做逐项生效验证：改什么、怎么重启、现象是什么，全部来自真机回显。部署过程见 《CUPS 安装部署指南（Ubuntu 22.04 直装实录）》，命令级操作见 《CUPS 常用 CLI 命令详解》，选型背景见 《CUPS 介绍与选型指南》。实验服务器：Ubuntu 22.04.5 LTS，主机名
cups-lab，内网 IP10.89.71.2；队列root，示例密码q1w2e3r4。
一、三大配置文件与加载机制
| 文件 | 管什么 | 谁来改 |
|---|---|---|
/etc/cups/cupsd.conf | 调度器行为：监听、日志、Web 界面、访问控制 | 管理员手工编辑 |
/etc/cups/cups-files.conf | 文件与身份：路径、日志权限、可执行组 | 管理员手工编辑 |
/etc/cups/printers.conf | 队列定义：URI、状态、策略 | 由 cupsd 写，禁止运行中手编 |
改完 cupsd.conf/cups-files.conf 的标准三步：cupsd -t 语法检查 → systemctl restart cups → 验证现象。
cupsd -t
实测回显：
"/etc/cups/cups-files.conf" is OK.
"/etc/cups/cupsd.conf" is OK.
printers.conf 的落盘时机（重要认知）：文件头自带警告——
# Printer configuration file for CUPS v2.4.1
# Written by cupsd
# DO NOT EDIT THIS FILE WHEN CUPSD IS RUNNING
lpadmin/cupsenable 等命令的变更先落在 cupsd 内存，重启 cupsd 后才写入 printers.conf。本文实测：lpadmin -d PDF 设默认后立即 cat 文件仍显示 <Printer PDF>，systemctl restart cups 后才出现 <DefaultPrinter PDF>；lpadmin -p PDF -o printer-error-policy=stop-printer 同理。运行中手编该文件会在 cupsd 下次落盘时被整体覆盖，等于白改。
二、cupsd.conf：监听类
2.1 Listen（默认值与多监听）
Ubuntu 22.04 默认配置的监听段：
grep -nE '^(Listen|Port)' /etc/cups/cupsd.conf
ss -ltn | grep -E '631|8147'
实测回显：
18:Listen localhost:631
19:Listen /run/cups/cups.sock
LISTEN 0 128 127.0.0.1:631 0.0.0.0:*
LISTEN 0 128 [::1]:631 [::]:*
默认只听本机回环 + 一个 Unix socket（/run/cups/cups.sock，供本机客户端走 socket 提速）。要让局域网访问，追加一条 Listen 0.0.0.0:8147：
sed -i 's/^Listen localhost:631$/Listen localhost:631\nListen 0.0.0.0:8147/' /etc/cups/cupsd.conf
grep -n '^Listen' /etc/cups/cupsd.conf
systemctl restart cups
sleep 2
ss -ltn | grep -E '631|8147'
实测回显：
18:Listen localhost:631
19:Listen 0.0.0.0:8147
20:Listen /run/cups/cups.sock
LISTEN 0 128 0.0.0.0:8147 0.0.0.0:*
LISTEN 0 128 127.0.0.1:631 0.0.0.0:*
LISTEN 0 128 [::1]:631 [::]:*
Listen 可叠加任意多条（每条一个 socket），631 是 IPP + Web 共用端口，自定义端口上同样是双职能。CUPS 默认 631，本文对外口改用 8147（网段规划），本机 631 保留给本机客户端。
2.2 Browsing
grep -n '^Browsing' /etc/cups/cupsd.conf
实测回显：
22:Browsing No
Ubuntu 默认关闭（服务器版合理默认）；开启后 cupsd 通过 mDNS/DNS-SD 向局域网广播共享队列。无共享打印需求的打印服务器保持 No。
三、cupsd.conf：日志类（LogLevel / MaxLogSize）
3.1 MaxLogSize：日志轮转验证
默认值（Ubuntu 配置为 0 = 不轮转，靠 logrotate 外部接管）：
12:MaxLogSize 0
改为 51200（50 KB）并重启，立即观察轮转：
sed -i 's/^MaxLogSize 0$/MaxLogSize 51200/' /etc/cups/cupsd.conf
systemctl restart cups
ls -la /var/log/cups/
实测回显（此前 debug 日志已积累 163 KB）：
-rw-r----- 1 root adm 1697 Oct 28 04:34 access_log
-rw------- 1 root lpadmin 5843 Oct 28 04:34 cups-pdf-PDF_log
-rw-r----- 1 root lpadmin 0 Oct 28 04:29 cups-pdf_log
-rw-r----- 1 root adm 165 Oct 28 04:37 error_log
-rw-r----- 1 root adm 163926 Oct 28 04:37 error_log.O
超限日志被轮转为 error_log.O（CUPS 自身的轮转后缀是 .O，不是 logrotate 的 .1），新 error_log 从 165 字节重新起步。MaxLogSize 0 + 无外部 logrotate 配置 = error_log 无限增长，磁盘敏感场景要么给一个有限值，要么确认 Ubuntu 的 logrotate 规则生效。
3.2 LogLevel：级别与日志量实测
默认 LogLevel warn。三个级别各跑一次同样的请求（curl 首页 + 重启），对比 error_log 增量：
| 级别 | 实测 error_log 行数（单次首页请求） | 说明 |
|---|---|---|
| warn | 1 | 仅警告与错误 + 任务事件 |
| debug | 数百行级 | 含任务 argv/envp 全量展开 |
| debug2 | 263 | 连 HTTP 头逐条记录，最快膨胀 |
（实测路径：sed 改 LogLevel debug2 → systemctl restart cups → curl 首页 → wc -l /var/log/cups/error_log 得 263 行；同场景 warn 下仅 1 行。）
快速切换不用手编文件，cupsctl 一条命令搞定（内部就是改 cupsd.conf 并热重启）：
cupsctl --debug-logging # 等价 LogLevel debug
cupsctl --no-debug-logging # 回到 warn
排障时临时开 debug，查完务必关回——debug2 级别下日志增长速度足以在数小时内写满小磁盘分区。
四、cupsd.conf：Web 界面与访问控制
4.1 WebInterface（语义实测）
29:WebInterface Yes
改为 No 并重启后，实测行为与常见说法不同——主页仍然 200，被禁的是 CGI 动态页：
curl -s http://localhost:631/ | grep -oE '<title>[^<]+</title>'
curl -s http://localhost:631/printers/ | grep -oE '<TITLE>[^<]+</TITLE>'
实测回显：
<title>Home - CUPS 2.4.1</title>
<TITLE>Web Interface is Disabled - CUPS v2.4.1</TITLE>
即：WebInterface No 关闭的是 /printers/、/jobs/、/admin/ 这些 CGI 页面（返回"Web Interface is Disabled"），静态首页照常。对外只提供 IPP 服务、不想暴露任何管理面的场景，这个值设 No 只是半关闭，还需配合 <Location> 全部拒绝。
4.2 <Location> 段：默认拒绝远程的根源
默认配置三个关键段（改前原样）：
36:<Location />
37- Order allow,deny
38-</Location>
41:<Location /admin>
42- Order allow,deny
43-</Location>
46:<Location /admin/conf>
47- AuthType Default
48- Require user @SYSTEM
49- Order allow,deny
50-</Location>
Order allow,deny + 无 Allow 指令 = 只允许 localhost。这就是「加了 Listen 0.0.0.0:8147 后远程访问全部 403」的直接原因（排障实录见 B1 篇）。放行运维网段：
<Location />
Order allow,deny
Allow 10.89.71.0/24
</Location>
<Location /admin>
Order allow,deny
Allow 10.89.71.0/24
</Location>
<Location /admin/conf>
AuthType Default
Require user @SYSTEM
Order allow,deny
Allow 10.89.71.0/24
</Location>
重启后远程验证（从另一台机器 curl）：
=== 主页 ===
200
=== /admin/ ===
200
生产写法建议把 Allow 收窄到管理网段（如 Allow 10.89.71.0/24），不要写 Allow @LOCAL（所有本地接口所在网段全放行）。
4.3 Web 认证：@SYSTEM 与 Basic Auth
<Location /admin/conf> 的 Require user @SYSTEM 中，@SYSTEM 组由 cups-files.conf 的 SystemGroup 定义（Ubuntu 默认含 root，见第六节）。管理操作触发 Basic 认证，用系统账号口令验证：
curl -s -o /dev/null -w 'no-auth: %{http_code}\n' http://localhost:631/admin/conf/cupsd.conf
curl -s -o /dev/null -w 'root-auth: %{http_code}\n' -u root:q1w2e3r4 http://localhost:631/admin/conf/cupsd.conf
curl -s -u root:q1w2e3r4 http://localhost:631/admin/conf/cupsd.conf | head -3
实测回显：
no-auth: 401
root-auth: 200
# Show troubleshooting information in error_log.
LogLevel warn
PageLogFormat
401 → 认证后 200 且能直接下载 cupsd.conf 本体——认证链路完整验证。把 root 加入 lpadmin 组（usermod -aG lpadmin root）可覆盖 SystemGroup lpadmin 更严格的发行版配置。
4.4 ServerAlias：实测不生效的一个坑
为让 CUPS 认领自定义域名（Host 头校验），在 Listen 段附近加入：
ServerAlias print.example.com
重启后实测（同一台机器、不同 Host 头）：
| Host 头 | 实测返回 |
|---|---|
localhost / 127.0.0.1 / localhost:631 | 200 |
10.89.71.2:8147（连接目标 = 该 IP） | 200 |
print.example.com（含 hosts 解析后重试、含 HostNameLookups On 重试） | 400 |
evil.host.net | 400 |
实测结论：Ubuntu 22.04 的 CUPS 2.4.1op1 上，Web 界面的 Host 校验以连接目标地址 + localhost 为准，ServerAlias 放行自定义域名在该发行版构建上不生效（配置语法合法、cupsd -t 通过，但行为不变）。需要域名访问的姿势是前置 Nginx 反向代理（代理侧用固定 Host 或透传均可，因为反代到 127.0.0.1:631 时 Host 变 localhost）。
五、printers.conf：队列级参数
一次落盘后的完整队列定义（真实文件节选）：
<DefaultPrinter PDF>
PrinterId 1
UUID urn:uuid:f748c9c4-ed47-3050-5261-dd0e6d8825ff
Info PDF
MakeModel Generic CUPS-PDF Printer (w/ options)
DeviceURI cups-pdf:
State Idle
StateTime 1793162054
ConfigTime 1793162054
Type 8450124
Accepting Yes
Shared Yes
JobSheets none none
QuotaPeriod 0
PageLimit 0
KLimit 0
OpPolicy default
ErrorPolicy retry-job
</Printer>
逐项说明与验证方法：
| 参数 | 含义 | 验证动作 |
|---|---|---|
<DefaultPrinter PDF> | 系统默认队列标签（普通队列为 <Printer PDF>） | lpadmin -d PDF → restart → 标签变化（实测见第一节） |
DeviceURI | 队列绑定的设备 | lpstat -v 回显 device for PDF: cups-pdf: |
State | Idle/Stopped/Processing | cupsdisable → 文件变 State Stopped，跨重启保持（实测） |
Accepting | 是否收新任务 | cupsreject PDF → Accepting No |
ErrorPolicy | 打印出错时队列行为 | lpadmin -o printer-error-policy=...（见下） |
OpPolicy | 操作策略（对应 <Policy> 段） | 默认 default |
JobSheets | 任务封面页 | 默认 none none（起止页均无） |
QuotaPeriod/PageLimit/KLimit | 配额（周期秒 / 页数 / KB） | 默认 0 = 不限额 |
5.1 ErrorPolicy 三态
lpadmin -p PDF -o printer-error-policy=stop-printer
systemctl restart cups
grep ErrorPolicy /etc/cups/printers.conf
实测回显：
ErrorPolicy stop-printer
可选值与语义：
stop-printer：出错即停队列，需人工cupsenable——缺纸卡纸类场景的标准选择；retry-job：同任务自动重试——Ubuntu 对 cups-pdf 等虚拟队列的默认值（本机默认即retry-job）；abort-job：出错任务直接作废，队列继续。
改回默认：lpadmin -p PDF -o printer-error-policy=retry-job + 重启。
5.2 默认打印机的两层存储
系统默认（lpadmin -d）落 printers.conf 的 <DefaultPrinter> 标签；用户默认（lpoptions -d）落 ~/.cups/lpoptions。lpstat -d 显示生效值：
system default destination: PDF
用户级优先于系统级，排查"为什么这台机器所有用户都打错队列"时两层都要看。
六、cups-files.conf：路径与身份
Ubuntu 22.04 的非注释有效配置（完整）：
grep -vE '^#|^$' /etc/cups/cups-files.conf
实测回显：
SystemGroup lpadmin root
PeerCred on
LogFileGroup adm
AccessLog /var/log/cups/access_log
ErrorLog /var/log/cups/error_log
PageLog /var/log/cups/page_log
| 参数 | 本机值 | 说明 |
|---|---|---|
SystemGroup | lpadmin root | Web 管理认证的 @SYSTEM 成员；手改风险高，建议只做加组 |
PeerCred | on | 允许通过 Unix socket 的客户端凭据直连（本机免密管理的基础） |
LogFileGroup | adm | 日志属组（与 Ubuntu 系统日志组惯例一致，便于 adm 组成员读日志） |
AccessLog/ErrorLog/PageLog | /var/log/cups/* | 三类日志路径；syslog 值可改走 journald |
6.1 LogFilePerm 生效验证
默认注释行 #LogFilePerm 00640，日志实际权限 0640 root:adm。改为 0644 后删除日志并重启（cupsd 重建日志文件时应用新权限）：
sed -i 's/^#LogFilePerm 00640$/LogFilePerm 0644/' /etc/cups/cups-files.conf
rm -f /var/log/cups/error_log
systemctl restart cups
ls -l /var/log/cups/error_log
实测回显：
-rw-r--r-- 1 root adm 165 Oct 28 04:43 /var/log/cups/error_log
恢复 LogFilePerm 00640 后重复实验，实测回显：
-rw-r----- 1 root adm 165 Oct 28 04:43 /var/log/cups/error_log
注意：LogFilePerm 只作用于新建的日志文件，对已存在文件不追溯改权限——验证时必须先删旧文件。
七、参数速查表
| 文件 | 参数 | 默认值（Ubuntu 22.04） | 生产建议 |
|---|---|---|---|
| cupsd.conf | Listen | localhost:631 + unix socket | 对外另加 Listen 0.0.0.0:8147，用防火墙限网段 |
| cupsd.conf | LogLevel | warn | 常态 warn，排障临时 debug，用完关回 |
| cupsd.conf | MaxLogSize | 0 | 设有限值（如 51200）或确认 logrotate 兜底 |
| cupsd.conf | Browsing | No | 不共享保持 No |
| cupsd.conf | WebInterface | Yes | 纯 IPP 服务端可 No（注意仅禁 CGI 页） |
| cupsd.conf | <Location> | 仅 localhost | 需远程管理时逐段加 Allow <管理网段> |
| cupsd.conf | ServerAlias | 未配置 | Ubuntu 构建上实测不生效，域名走反代 |
| cups-files.conf | SystemGroup | lpadmin root | 保持默认，用 lpadmin 组管理授权 |
| cups-files.conf | LogFilePerm | 00640（注释） | 保持 0640，需采集器读取走 adm 组 |
| printers.conf | ErrorPolicy | retry-job（虚拟队列） | 实体打印机建议 stop-printer |
| printers.conf | Accepting/State | Yes/Idle | 由 cupsaccept/cupsenable 管理，勿手编 |
相关阅读：
- 《CUPS 常用 CLI 命令详解》——本文所有配置变更对应的命令操作实录
- 《CUPS 安装部署指南（Ubuntu 22.04 直装实录）》——监听与 Location 改造的完整部署现场
- 《CUPS 介绍与选型指南》——为什么选 CUPS：三方案量化对比