SANE 1.2.1 常用 CLI 命令与工具详解

目标：逐一详解 SANE 在 Ubuntu 24.04 上随包分发的全部命令行工具——scanimage、saned、sane-find-scanner、scanadf、xcam、airscan-discover、gamma4scanimage、sane-config，覆盖参数语义与真实回显。已在 Ubuntu 24.04.5 LTS 裸机服务器实测通过。

一、环境信息

本文所有命令与回显均来自以下实验环境（与《Ubuntu 24.04 安装 SANE 1.2.1 指南》《SANE 1.2.1 配置参数详解》同一套两台服务器组成的最小扫描网络）：

操作系统：Ubuntu 24.04.5 LTS（PRETTY_NAME="Ubuntu 24.04.5 LTS"），内核 Linux 7.0.0-38-generic x86_64，systemd 255（255.4-1ubuntu8.18）
实验拓扑：扫描服务端 scan-server（10.89.68.10，运行 saned，systemd socket 托管），客户端 scan-client（10.89.68.20，net 后端远程访问）
前端版本（scanimage -V 实测）：scanimage (sane-backends) 1.2.1-debian; backend version 1.2.1

实验形态说明：实验服务器未接入 USB/SCSI 物理扫描仪，扫描数据全部来自 SANE 官方 test 虚拟后端（test:0/test:1 两个虚拟设备，出图内容可控）与 net 网络后端（设备名 net:10.89.68.10:test:0 形态）。test 后端模拟的是标准 SANE 设备行为，与真实硬件的差异主要在：无硬件专属选项（如灯管控制）、不出真实图像内容、无 USB 热插拔事件。文中已逐处注明。

二、工具概览

Ubuntu 24.04 安装 sane-utils / libsane1 / sane / sane-airscan 后可用的 CLI 工具全景（dpkg -l 与 dpkg -L 实测归属）：

工具	所属包	定位	man 页	本文实测
`scanimage`	sane-utils	核心命令行扫描前端	scanimage(1)	✅ 全参数实测
`saned`	sane-utils	网络扫描守护进程（服务端）	saned(8)	✅ 帮助与调试实测
`sane-find-scanner`	sane-utils	USB/SCSI 总线层找扫描仪	sane-find-scanner(1)	✅ 实测
`scanadf`	sane	面向 ADF 连续进纸的扫描前端	scanadf(1)	✅ 实测（含已知缺陷）
`xcam`	sane	摄像头图形采集前端	xcam(1)	⚠️ 仅验证启动依赖
`airscan-discover`	sane-airscan	eSCL/WSD 网络扫描仪发现	airscan-discover(1)	✅ 实测
`gamma4scanimage`	sane-utils	生成 SANE gamma 表的辅助工具	—（无独立 man 页，见 sane-utils 文件清单）	✅ 实测
`sane-config`	libsane-dev（未装）	查询编译期库路径的开发辅助	—	✅ 实测确认缺失

调用约定：所有扫描类工具都通过 SANE API（libsane）→ dll 加载器 → 后端这条链路工作，设备名语法与 /etc/sane.d/dll.conf 中启用的后端直接相关。

三、前置条件

已按《Ubuntu 24.04 安装 SANE 1.2.1 指南》完成安装；服务端 saned 已上线（systemd socket 托管）；
客户端 /etc/sane.d/net.conf 已登记服务端 IP，dll.conf 已启用 net 与 test 后端（配置细节见《SANE 1.2.1 配置参数详解》）；
scanadf、xcam 需要 sane 包（图形/工具前端打包，1.0.14-18）；airscan-discover 需要 sane-airscan 包；
本文示例均以 root 执行；文件输出路径统一使用 /tmp。

四、各工具详解

4.1 scanimage —— 核心扫描命令

scanimage 是 SANE 的事实标准 CLI：设备发现、自检、单页/批量扫描、格式转换一应俱全。帮助全文实测（scanimage --help，通用参数部分）：

Output format is not set, using pnm as a default.
Usage: scanimage [OPTION]...

Start image acquisition on a scanner device and write image data to
standard output.

Parameters are separated by a blank from single-character options (e.g.
-d epson) and by a "=" from multi-character options (e.g. --device-name=epson).
-d, --device-name=DEVICE   use a given scanner device (e.g. hp:/dev/scanner)
    --format=pnm|tiff|png|jpeg|pdf  file format of output file
-i, --icc-profile=PROFILE  include this ICC profile into TIFF file
-L, --list-devices         show available scanner devices
-f, --formatted-device-list=FORMAT similar to -L, but the FORMAT of the output
                           can be specified: %d (device name), %v (vendor),
                           %m (model), %t (type), %i (index number), and
                           %n (newline)
-b, --batch[=FORMAT]       working in batch mode, FORMAT is `out%d.pnm' `out%d.tif'
                           `out%d.png' or `out%d.jpg' by default depending on --format
                           This option is incompatible with --output-file.    --batch-start=#        page number to start naming files with
    --batch-count=#        how many pages to scan in batch mode
    --batch-increment=#    increase page number in filename by #
    --batch-double         increment page number by two, same as
                           --batch-increment=2
    --batch-print          print image filenames to stdout
    --batch-prompt         ask for pressing a key before scanning a page
    --accept-md5-only      only accept authorization requests using md5
-p, --progress             print progress messages
-o, --output-file=PATH     save output to the given file instead of stdout.
                           This option is incompatible with --batch.
-n, --dont-scan            only set options, don't actually scan
-T, --test                 test backend thoroughly
-A, --all-options          list all available backend options
-h, --help                 display this help message and exit
-v, --verbose              give even more status messages
-B, --buffer-size=#        change input buffer size (in kB, default 32)
-V, --version              print version information

首行 Output format is not set, using pnm as a default. 是 scanimage 在未指定 --format 时的固定提示，后续所有扫描示例回显中均可能出现，不再重复标注。

4.1.1 设备发现：-L

客户端实测（scanimage -L，远程设备经 net 后端呈现）：

device `net:10.89.68.10:test:0' is a Noname frontend-tester virtual device
device `net:10.89.68.10:test:1' is a Noname frontend-tester virtual device

-f 可自定义输出格式，便于脚本取设备名（如 scanimage -f "%d%n" 每行一个设备名，语义见帮助原文 %d (device name) … %n (newline)）。

4.1.2 后端自检：-T

-T 对指定设备做彻底自检（读整行、读单字节、阶梯式读），服务端本地 test 设备实测（scanimage -d test:0 -T）：

scanimage: scanning image of size 157x196 pixels at 8 bits/pixel
scanimage: acquiring gray frame, 8 bits/sample
scanimage: reading one scanline, 157 bytes...	PASS
scanimage: reading one byte...		PASS
scanimage: stepped read, 2 bytes... 	PASS
scanimage: stepped read, 4 bytes... 	PASS
scanimage: stepped read, 8 bytes... 	PASS
scanimage: stepped read, 16 bytes... 	PASS
scanimage: stepped read, 32 bytes... 	PASS
scanimage: stepped read, 64 bytes... 	PASS
scanimage: stepped read, 128 bytes... 	PASS
scanimage: stepped read, 256 bytes... 	PASS
scanimage: stepped read, 255 bytes... 	PASS
scanimage: stepped read, 127 bytes... 	PASS
scanimage: stepped read, 63 bytes... 	PASS
scanimage: stepped read, 31 bytes... 	PASS
scanimage: stepped read, 15 bytes... 	PASS
scanimage: stepped read, 7 bytes... 	PASS
scanimage: stepped read, 3 bytes... 	PASS

全部 PASS、退出码 0，即链路（后端读取/参数/传输）完好。装上真实扫描仪后第一件事建议就是跑一遍 -T。

4.1.3 选项探测：-A 与 --help -d DEVICE

-A 列出指定设备的全部可调选项（含取值范围、默认值、约束），是写扫描脚本前的必备侦察。实测（scanimage -d 'net:10.89.68.10:test:0' -A，节选首尾）：

Output format is not set, using pnm as a default.

All options specific to device `net:10.89.68.10:test:0':
  Scan Mode:
    --mode Gray|Color [Gray]
        Selects the scan mode (e.g., lineart, monochrome, or color).
    --depth 1|8|16 [8]
        Number of bits per sample, typical values are 1 for "line-art" and 8
        for multibit scans.
...
    --resolution 1..1200dpi (in steps of 1) [50]
        Sets the resolution of the scanned image.
    --source Flatbed|Automatic Document Feeder [Flatbed]
        If Automatic Document Feeder is selected, the feeder will be 'empty'
        after 10 scans.
...
  Geometry:
    -l 0..200mm (in steps of 1) [0]
        Top-left x position of scan area.
    -t 0..200mm (in steps of 1) [0]
        Top-left y position of scan area.
    -x 0..200mm (in steps of 1) [80]
        Width of scan-area.
    -y 0..200mm (in steps of 1) [100]
        Height of scan-area.

方括号内为当前默认值，| 分隔的是合法取值（字符串列表约束），N..M (in steps of Q) 为数值范围约束。test 设备还暴露一组特殊的 Special Options（--test-picture、--read-return-value 等），完整清单见帮助输出或《SANE 1.2.1 配置参数详解》5.2 节。

4.1.4 单页扫描：-o 与 --format

默认输出到 stdout，-o 落盘，--format 指定格式（pnm|tiff|png|jpeg|pdf）。实测一：Grid 测试图出 PNG（服务端本地设备）：

scanimage -d test:0 --test-picture=Grid --format=png -o /tmp/grid.png

EXIT=0
-rw-r--r-- 1 root root 334 Oct 29 13:23 /tmp/grid.png

用 od 校验文件头（实测）：

000000 89 50 4e 47 0d 0a 1a 0a 00 00 00 0d 49 48 44 52  >.PNG........IHDR<
000010 00 00 00 9d 00 00 00 c4 08 00 00 00 00 a0 cc 7c  >...............|<

PNG 魔数（89 50 4e 47）与 IHDR 尺寸段（0x9d=157、0xc4=196，与 -T 自检报告的 157x196 一致）均正确，出图真实有效。

实测二：-v 冗长模式（客户端，远程设备，--test-picture='Color pattern'）：

scanimage -v -d 'net:10.89.68.10:test:0' --test-picture='Color pattern' -o /tmp/verbose.pnm

scanimage: scanning image of size 157x196 pixels at 8 bits/pixel
scanimage: acquiring gray frame
scanimage: min/max graylevel value = 0/255
scanimage: read 30772 bytes in total

产物（实测）：-rw-r--r-- 1 root root 30807 Oct 29 13:24 /tmp/verbose.pnm。min/max graylevel 行可快速判断出图是否正常（纯黑图 0/0、正常图案 0/255）。

4.1.5 批量扫描：--batch（ADF 场景）

--batch 面向自动进纸器连续扫描。实测（客户端，远程设备，ADF 进纸 3 页）：

scanimage -d 'net:10.89.68.10:test:0' --source 'Automatic Document Feeder' --batch='b%d.pnm' --batch-count=3 --batch-print

Scanning 3 pages, incrementing by 1, numbering from 1
Scanning page 1
Scanned page 1. (scanner status = 5)
b1.pnm
Scanning page 2
Scanned page 2. (scanner status = 5)
b2.pnm
Scanning page 3
Scanned page 3. (scanner status = 5)
b3.pnm
Batch terminated, 3 pages scanned

产物（实测）：

-rw-r--r-- 1 root root 30807 Oct 29 13:24 /tmp/b1.pnm
-rw-r--r-- 1 root root 30807 Oct 29 13:24 /tmp/b2.pnm
-rw-r--r-- 1 root root 30807 Oct 29 13:24 /tmp/b3.pnm

要点：--source 'Automatic Document Feeder' 切换进纸器（取值来自 -A 探测）；scanner status = 5 为 test 后端 ADF 模式的固定状态值；test 后端的 ADF "10 页后空"的模拟行为由后端内置（见 -A 中 --source 描述）。--batch-print 在扫描时把文件名打到 stdout，--batch-prompt/--batch-start/--batch-increment 等组合语义见 4.1 帮助原文。

4.2 saned —— 网络扫描守护进程

saned 是把本机扫描设备共享给网络的服务端守护进程。帮助全文实测（saned -h）：

Usage: saned [OPTIONS]

 Options:

  -a, --alone[=user]	equal to `-l -D -u user'
  -l, --listen		run in standalone mode (listen for connection)
  -u, --user=user	run as `user'
  -D, --daemonize	run in background
  -o, --once		exit after first client disconnects
  -d, --debug=level	set debug level `level' (default is 2)
  -e, --stderr		output to stderr
  -b, --bind=addr	bind address `addr' (default all interfaces)
  -p, --port=port	bind port `port` (default sane-port or 6566)
  -h, --help		show this help message and exit

参数速查：

参数	说明
`-l`	standalone 监听模式（自己 listen 6566），与 inetd/systemd socket 托管相对
`-a[=user]`	等价 `-l -D -u user` 三合一：监听 + 后台化 + 降权，standalone 生产形态
`-u user`	以指定用户运行（systemd 托管形态由 `saned@.service` 的 `User=saned` 承担）
`-D`	daemonize 后台运行
`-o`	服务完第一个客户端连接后退出（配合调试）
`-d level`	调试级别（默认 2，最大 128）；注意：不带 `-l` 时 `-d` 是 inetd 模式，从 stdin 读协议，直接在终端跑会"无输出秒退"
`-e`	日志输出到 stderr（配合 `-d` 在前台看日志）
`-b addr`	绑定地址（默认全部网卡）
`-p port`	绑定端口（默认 `/etc/services` 注册的 sane-port/6566）

调试实战（实测结论）：前台调试必须 saned -l -d128 -e 三参数齐全——-l 进入监听模式、-d128 全量调试、-e 日志到 stderr。完整调试日志（含 check_host 白名单判定、init: access by host ... denied 拒绝记录）见《Ubuntu 24.04 安装 SANE 1.2.1 指南》FAQ Q1。生产部署推荐 systemd socket 托管（每连接一进程、配置热生效），形态对比与完整配置见同篇第九、十章。

4.3 sane-find-scanner —— 总线层找扫描仪

在 USB/SCSI 总线层直接探测扫描仪硬件，不经过任何 SANE 后端，用于区分"硬件没枚举到"还是"后端不认"。帮助全文实测（sane-find-scanner -h）：

Usage: sane-find-scanner [-hvqf] [devname ...]
	-h: print this help message
	-v: be more verbose (can be used multiple times)
	-q: be quiet (print only devices, no comments)
	-f: force opening devname as SCSI even if it looks like USB
	-p: enable scanning for parallel port devices

无扫描仪硬件的服务器实测（sane-find-scanner -q）：

could not fetch string descriptor: Pipe error
could not fetch string descriptor: Pipe error
could not fetch string descriptor: Pipe error
could not fetch string descriptor: Pipe error

退出码 0。无硬件时仅出现 USB 字符串描述符读取告警，不列出任何设备——这正是"总线层无扫描仪"的证据；接上硬件后此处会列出 found USB scanner (vendor=..., product=...) 形态的行，随后再由 scanimage -L 验证后端是否支持该型号。-v 可叠加（-vv）获取更详细的探测过程。

4.4 scanadf —— ADF 连续进纸扫描前端

scanadf 属 sane 包（1.0.14-18），面向 ADF 多页扫描与扫描后脚本处理（-S 指定每页后处理脚本）。通用帮助实测（scanadf -h 通用参数部分）：

Usage: scanadf [OPTION]...

Start image acquisition on a scanner device and write image data to
output files.

   [ -d | --device-name <device> ]   use a given scanner device.
   [ -h | --help ]                   display this help message and exit.
   [ -L | --list-devices ]           show available scanner devices.
   [ -v | --verbose ]                give even more status messages.
   [ -V | --version ]                print version information.
   [ -N | --no-overwrite ]           don't overwrite existing files.

   [ -o | --output-file <name> ]     name of file to write image data
                                     (%d replacement in output file name).
   [ -S | --scan-script <name> ]     name of script to run after every scan.
   [ --script-wait ]                 wait for scripts to finish before exit
   [ -s | --start-count <num> ]      page count of first scanned image.
   [ -e | --end-count <num> ]        last page number to scan.
   [ -r | --raw ]                    write raw image data to file.

已知缺陷实录（可稳定复现）：scanadf -h 在随后打印设备选项时，于 --string-constraint-long-string-list 描述中途崩溃（实测回显尾部）：

    --string-constraint-long-string-list First entry|Second entry|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45|46 [inactive]
        (3/3) String test option with string liSegmentation fault (core dumped)

这是 sane 前端 1.0.14 处理 test 后端超长字符串约束选项时的老 bug，与扫描功能无关。规避：看设备选项用 scanimage -d <设备> -A（4.1.3 节），不要依赖 scanadf -h 的设备选项段。

扫描功能实测（服务端，本地设备，Grid 图 2 页）：

cd /tmp && scanadf -d test:0 -o 'adf%d.pnm' --start-count 1 --end-count 2 --test-picture=Grid

Scanned document adf1.pnm
Scanned document adf2.pnm
Scanned 2 pages

产物（实测）：adf1.pnm、adf2.pnm 各 30807 字节。%d 页号替换、-s/-e 页码区间、-N 防覆盖等组合即可覆盖"编号连续、可断点续扫"的批量场景。

4.5 xcam —— 摄像头图形采集前端

xcam 属 sane 包，是针对摄像头类设备（v4l 后端等）的交互式图形采集前端。服务器实测（无 X11 显示环境）：

(xcam:3281): Gtk-WARNING **: 13:22:19.984: cannot open display:

实验约束说明：xcam 依赖 GTK 图形会话，本实验服务器无 X11，仅能验证到"启动即因无显示环境失败"这一层；其完整功能（窗口化取景、多帧采集）需在桌面环境验证，本文不作进一步描述。无头服务器上的摄像头采集应走 scanimage -d <v4l设备> 脚本化路径。

4.6 airscan-discover —— eSCL/WSD 网络扫描仪发现

sane-airscan 附带的发现工具，扫描局域网内支持 eSCL/AirPrint 或 WSD 协议的网络扫描仪（多数现代一体机的"免驱"通道），输出的 [devices] 段可直接粘进 /etc/sane.d/airscan.conf。无此类设备的实验网络实测（airscan-discover）：

[devices]

输出为空的 [devices] 段——未发现任何 eSCL/WSD 设备。发现到设备时该段会出现 "名称" = http://<ip>:<port>/eSCL 形式的登记行；本实验网络的后续排查可结合 avahi-browse 交叉验证。

4.7 gamma4scanimage —— gamma 表生成辅助

gamma4scanimage（sane-utils 包）把一个 gamma 值展开成 SANE --gamma-table 需要的 256 项灰度映射表字符串。不认识 --help（实测把 --help 当参数解析报错）：

gamma4scanimage error: gamma=0.000000 out of range [0.1;5]

有效输入实测（gamma4scanimage 1.8）：

[0]0-[64]11-[96]14-[144]18-[216]23-[325]28-[487]36-[731]45-[1097]56-[1646]71-[2469]89-[3704]111-[5557]139-[8335]175-[12503]219-[16383]255-[16383]255

取值范围 0.1~5.0（报错信息原文给出边界）。产物为 [源值]目标值 序列，可作为 --gamma-table 的实参喂给 scanimage（-A 输出中 --gamma-table 0..255,... 即该表的目标位置）。

4.8 sane-config —— 开发辅助（默认未安装）

scanimage -V 与 -h 输出中提到的库信息查询工具 sane-config 在 Ubuntu 24.04 默认安装中不存在（实测）：

sh: 1: sane-config: not found

它随开发包 libsane-dev 分发（查询头文件/库路径用，编译第三方 SANE 前端时才需要）。服务器仅做扫描用途时无需安装。

五、注意事项

设备名形态决定路径：本地设备 test:0（后端名:编号）；远程设备 net:10.89.68.10:test:0（net 后端:服务器:远端设备名）；真实 USB 设备形如 epson2:libusb:001:003。先 scanimage -L 拿到精确字符串再复制使用，-d 传错是新手最常见报错来源。
服务端全量枚举可能显著变慢（实测现象）：本实验中客户端 scanimage -L 秒级返回，而服务端上不带 -d 的 scanimage -L / scanimage --help 曾长时间等待才返回（两台服务器同为 1.2.1、同装 sane-airscan，差异原因未定论）。排查此类问题时用 SANE_DEBUG_DLL=5 scanimage -L 观察卡在哪个后端；日常脚本化扫描建议显式 -d <设备>，跳过全量枚举。
test 后端是有效的链路测试手段，不替代硬件验收：-T 自检、出图、ADF 批量行为均可模拟；真实硬件的专属选项、色彩校正、热插拔（60-libsane1.rules 授权）仍需实机验证。
scanadf -h 的段错误是前端老 bug（1.0.14），不要据此怀疑环境；看选项一律用 scanimage -A。
saned 前台调试三件套：saned -l -d128 -e；单 -d 是 inetd 模式会"无输出秒退"，属常见误用。
Output format is not set, using pnm as a default. 是提示不是报错：未指定 --format 时默认 pnm 输出；需要图片文件时显式 --format=png + -o。

六、常见问题

Q1：scanimage -L 返回为空但设备明明接着？ 分三层定位：① sane-find-scanner -v 确认总线层枚举（硬件/线缆/供电）；② SANE_DEBUG_DLL=5 scanimage -L 确认 dll.conf 加载了对应品牌后端；③ 对照后端 conf（/etc/sane.d/<品牌>.conf）确认寻址方式（USB vendor/product 或网络地址）。三层的实测方法与回显样例见 4.3、4.1.3 及《SANE 1.2.1 配置参数详解》。

Q2：怎么把扫描集成到无人值守脚本？ scanimage -d <设备> --format=png -o /path/out.png 单页最简；多页用 --batch（4.1.5 节实测）；需要每页触发后续处理时用 scanadf -S <脚本>（4.4 节）。错误注入验证可用 test 后端 --read-return-value（如 SANE_STATUS_JAMMED 模拟卡纸），让脚本分支真正被走到。

Q3：xcam / xscanimage 这类图形前端在服务器上能跑吗？ 不能直接跑，二者都依赖 X11/GTK 会话（xcam 实测 cannot open display，4.5 节）。服务器场景一律用 scanimage/scanadf 脚本化；确需 GUI 时在桌面终端里通过 net 后端连接 saned 服务器扫描即可。

Q4：--source 'Automatic Document Feeder' 报不支持的选项？ --source 的合法值因设备而异，必须先 scanimage -d <设备> -A 照抄原文（test 后端为 Flatbed|Automatic Document Feeder）。直接从网上抄别的机型参数是这类报错的主因。

七、参考链接

SANE 官方文档索引：http://www.sane-project.org/docs.html
man 手册（本机实测存在）：scanimage(1)、saned(8)、sane-find-scanner(1)（sane-utils 包）
test 后端参数权威说明：man 5 sane-test（libsane-common 包）
sane-airscan 与 airscan-discover：https://github.com/alexpevzner/sane-airscan
同系列文档：《SANE 介绍与选型指南》《Ubuntu 24.04 安装 SANE 1.2.1 指南》《SANE 1.2.1 配置参数详解》