Kiwix 3.8.2 常用 CLI 命令与工具详解

目标：把 Kiwix 命令行三件套（kiwix-serve / kiwix-manage / kiwix-search）的常用命令整理成一本可直接照抄的运维手册——每条命令给出真实执行回显，覆盖伺服启停、库文件增删查、损坏 ZIM 校验与命令行全文检索，并汇总退出码语义与易错点。旗标级语义的逐项讲解见本专栏《Kiwix 3.8.2 启动旗标与库管理参数详解》，本文专注「怎么用」。

一、环境信息

本文实测环境与依据（实测日期 2026-11-01）：

操作系统：Ubuntu 26.04.1 LTS（x86_64），Docker 29.9.2 / Docker Compose v5.6.1
软件版本：kiwix-tools 3.8.2（2026-03-02 发布），镜像 ghcr.io/kiwix/kiwix-serve:3.8.2——三个 CLI 工具同属该套件、随镜像分发，无需单独安装
实测载体：Compose 常驻栈（容器 kiwix-3-8-2-web，部署见本专栏《Kiwix 3.8.2 Docker Compose 部署指南》）与探针容器 kiwix-3-8-2-probe（临时实例）
测试内容：wikibooks_zh_all_nopic_2026-10.zim（8510 条目，内嵌中文全文索引）与 wikibooks_ur_all_nopic_2026-10.zim（568 条目）
版本确认（kiwix-serve --version，三工具共享 kiwix-tools 版本号）：

$ kiwix-serve --version
kiwix-tools 3.8.2

libkiwix 14.2.0
+ libzim 9.5.0
+ libxapian 1.4.23
+ libcurl 8.4.0
+ libmicrohttpd 0.9.76
+ libz 1.3.1
+ libicu 73.2.0
+ libpugixml 1.15.0

二、工具概览

工具	定位	典型场景
`kiwix-serve`	HTTP 伺服器：把 ZIM（单文件或库）以网页形式对外提供	起/调服务，日常以容器形态运行
`kiwix-manage`	库文件管理器：维护 library.xml（添加/查看/删除条目）	增删书目的唯一正规入口
`kiwix-search`	命令行全文检索：直接对 ZIM 内嵌索引做查询/联想/纠错	不开网页时的快速查证、脚本化取标题

三者协作关系：kiwix-manage 把 ZIM 登记进 library.xml → kiwix-serve 以 --library 伺服库 → kiwix-search 直接对单个 ZIM 做检索（与伺服进程无关）。

三、前置条件

执行方式：工具都在镜像内 /usr/local/bin/，容器外用 docker exec <容器名> <工具> ...；compose 栈内用 docker compose exec kiwix-serve <工具> ...。本文回显均在容器内直接执行（等价于 exec 形态）。
路径约定：ZIM 与库文件都在挂载目录 /data 下；容器外路径与容器内路径通过 bind mount 对应（宿主 ./zim/ → 容器 /data/），命令里写容器内路径。
一个可直接练手的库：按部署篇 4.2 节执行过 kiwix-manage /data/library.xml add ... 即有现成库；本文另用临时库文件演示，避免动常驻栈。

四、各工具详解

4.1 kiwix-serve：伺服常用命令

起单书服务（容器形态 + 探针实测日志）：

$ docker run -d --name kiwix-3-8-2-web -p 8137:8080 -v /opt/kiwix/zim:/data \
    ghcr.io/kiwix/kiwix-serve:3.8.2 /data/wikibooks_zh_all_nopic_2026-10.zim
$ docker logs kiwix-3-8-2-web 2>&1 | tail -5
/usr/local/bin/kiwix-serve --port=8080 /data/wikibooks_zh_all_nopic_2026-10.zim
No stemming for language 'zh'
The Kiwix server is running and can be accessed in the local network at: 
  - http://10.89.57.10:8080
  - http://[::1]:8080

起多书服务：直接并列多个 ZIM 路径（部署篇实测，此处回显同）：

$ docker compose exec kiwix-serve kiwix-serve --port=8090 \
    /data/wikibooks_zh_all_nopic_2026-10.zim /data/wikibooks_ur_all_nopic_2026-10.zim
No stemming for language 'zh'
No stemming for language 'ur'
The Kiwix server is running and can be accessed in the local network at: 
  - http://10.89.65.2:8090
  - http://[::1]:8090

库模式启动（生产推荐）：

$ docker compose exec kiwix-serve kiwix-serve --port=8092 --library /data/library.xml
Loading the library from the following files:
	/data/library.xml
The library was successfully loaded.
The Kiwix server is running and can be accessed in the local network at: 
  - http://10.89.65.2:8092
  - http://[::1]:8092

前台调试：加 -v 打印请求级调试日志，配合 docker logs -f 观察每个 HTTP 请求的处理过程。

版本与帮助：kiwix-serve --version（回显见第一节）；--help 在容器内直达二进制执行（docker exec <容器> kiwix-serve --help）。若经镜像入口 docker run <镜像> --help 会先报 Unexpected argument: --port=8080, --help（start.sh 预拼参数所致，详见参数详解篇第三节）。

生命周期：--attachToProcess=<pid> 绑定外部守护进程（实测被绑定进程死亡后服务随之退出）、--daemon 后台化——容器编排场景两者均不需要，容器本身就是守护单元。

4.2 kiwix-manage：库管理常用命令

无参数运行打印用法（逐字回显）：

$ kiwix-manage
Arguments did not match expected patterns
Manipulates the Kiwix library XML file

Usage:
 kiwix-manage LIBRARYPATH add [--zimPathToSave=<custom_zim_path>] [--url=<http_zim_url>] ZIMPATH ...
 kiwix-manage LIBRARYPATH (delete|remove) ZIMID ...
 kiwix-manage LIBRARYPATH show [ZIMID ...]
 kiwix-manage -v | --version
 kiwix-manage -h | --help

添加（add）——把 ZIM 登记入库，元数据（标题/语言/条目数/大小等）自动读取：

$ kiwix-manage /data/library.xml add /data/wikibooks_zh_all_nopic_2026-10.zim
No stemming for language 'zh'

带 --url 附加在线来源（实测库内 url 属性被写入）：

$ kiwix-manage /tmp/lib-url.xml add --url=https://download.kiwix.org/zim/wikibooks/wikibooks_ur_all_nopic_2026-10.zim /data/zims/wikibooks_ur_all_nopic_2026-10.zim
No stemming for language 'ur'
$ grep -oE "url=\"[^\"]*\"" /tmp/lib-url.xml
url="https://download.kiwix.org/zim/wikibooks/wikibooks_ur_all_nopic_2026-10.zim"

校验（add 即校验）——kiwix-manage 没有独立的 check 动作，add 过程会解析 ZIM 并做校验：损坏文件被拒绝、退出码 1、且库文件不会生成（实测：预先不存在的目标库在 add 失败后依旧不存在）：

$ echo "not-a-zim" > /data/broken.zim
$ kiwix-manage /tmp/lib-chk.xml add /data/broken.zim
Cannot add ZIM /data/broken.zim to the library.
$ echo "exit=$?"
exit=1
$ cat /tmp/lib-chk.xml
cat: can't open '/tmp/lib-chk.xml': No such file or directory

目录不能作为 add 参数（3.8.2 实测）：add /data/zims 报 Unable to add the ZIM file '/data/zims' to the internal library.，必须逐个列 ZIM 文件。

列表（show）——全量或按 ID 过滤（全字段样例；favicon Base64 略）：

$ kiwix-manage /data/library.xml show
id:		5c3cd871-8b19-8cc7-76ec-c02a1180d221
path:		/data/wikibooks_zh_all_nopic_2026-10.zim
url:		
title:		Wikibooks
name:		wikibooks_zh_all
tags:		wikibooks;_category:wikibooks;_pictures:no;_videos:no;_details:yes;_ftindex:yes
description:	An Offline Version of Wikibook in Chinese Language
creator:	Wikibooks
date:		2026-10-15
articleCount:	8510
mediaCount:	132
size:		93335552 KB

id:		9165b265-394c-22bf-4e51-eec17f9639b3
path:		/data/wikibooks_ur_all_nopic_2026-10.zim
……（第二本书字段结构相同）
$ kiwix-manage /data/library.xml show 5c3cd871-8b19-8cc7-76ec-c02a1180d221
id:		5c3cd871-8b19-8cc7-76ec-c02a1180d221
path:		/data/wikibooks_zh_all_nopic_2026-10.zim
url:		
title:		Wikibooks

删除（delete / remove，两动词等价）——按 show 拿到的 UUID 删除；非法 ID 报错并返回 1：

$ kiwix-manage /data/library.xml delete 9165b265-394c-22bf-4e51-eec17f9639b3
$ kiwix-manage /tmp/lib-hup2.xml delete deadbeef-dead-dead-dead-deadbeefdead
Invalid book id 'deadbeef-dead-dead-dead-deadbeefdead'.

典型工作流：新增一本书（全程不重启服务，依赖运行中实例的 --monitorLibrary 或向进程发 SIGHUP）：

# 1. ZIM 放入挂载目录（宿主侧）
$ curl -x http://192.168.1.62:7897 -LO https://download.kiwix.org/zim/wikibooks/<新书目>.zim && mv <新书目>.zim zim/
# 2. 容器内登记入库（add 即校验）
$ docker compose exec kiwix-serve kiwix-manage /data/library.xml add /data/<新书目>.zim
# 3. 确认条目数（2 → 3）
$ docker compose exec kiwix-serve kiwix-manage /data/library.xml show | grep -c "^id:"
# 4. 服务侧验证（数秒内热重载生效）
$ curl -s "http://127.0.0.1:8137/catalog/v2/entries?count=-1" | grep -c "<entry>"

4.3 kiwix-search：命令行全文检索

无参数运行打印用法（逐字回显）：

$ kiwix-search
Arguments did not match expected patterns
Find articles based on a fulltext search pattern.

Usage:
  kiwix-search [options] ZIM PATTERN
  kiwix-search -h | --help
  kiwix-search -V | --version

Arguments:
  ZIM       The full path of the ZIM file
  PATTERN   Word(s) - or part of - to search in the ZIM.

Options:
  -s --suggestion    Suggest article titles based on the few letters of the PATTERN instead of making a fulltext search. Work a bit like a completion solution
  --spelling         Suggest article titles based on the spelling corrected PATTERN instead of making a fulltext search.
  -v --verbose       Give details about the search process
  -V --version       Print software version
  -h --help          Print this help

全文检索（返回命中条目标题列表，实测中文维基教科书查 Python）：

$ kiwix-search /data/zims/wikibooks_zh_all_nopic_2026-10.zim Python
No stemming for language 'zh'
Python
Python/变量和字符串
Python/列表
Python/Standard Library
Python/条件语句
Python/提示与技巧
Python/TensorFlow
Python/Conda包管理
Python/创建
Python/反射

标题联想（-s / --suggestion）——按词条前缀联想标题，实测查「数学」：

$ kiwix-search -s /data/zims/wikibooks_zh_all_nopic_2026-10.zim 数学
No stemming for language 'zh'
No stemming for language 'zh'
小学数学
数学分析/函数
高中数学/复数
LaTeX/数学公式
Python/基础数学
基础数学
数学/求和表
数学分析

拼写纠错（--spelling）——实测输错一个字母 Pythn，纠正为 Python 并返回命中：

$ kiwix-search --spelling /data/zims/wikibooks_zh_all_nopic_2026-10.zim Pythn
No stemming for language 'zh'
Python

过程详情（-v / --verbose）——打印查询解析过程（乌尔都语书查 Pakistan）：

$ kiwix-search -v /data/zims/wikibooks_ur_all_nopic_2026-10.zim Pakistan
No stemming for language 'ur'
Parsed query 'Pakistan' to Query(pakistan@1)
ویکی کتب:اصولِ اخفائے راز
ویکی کتب:دیوان عام

无结果形态——空输出、退出码 0（脚本里按输出判空即可）：

$ kiwix-search /data/zims/wikibooks_ur_all_nopic_2026-10.zim "qzxjq"
No stemming for language 'ur'
$ echo "exit=$?"
exit=0

边界：kiwix-search 一次只吃一个 ZIM 文件（不是库文件）；目标 ZIM 的 tags 需含 _ftindex:yes（内嵌全文索引）否则无结果可出。

五、注意事项

三个工具的参数顺序各不相同（易错 TOP1）：kiwix-serve 是 选项在 ZIM/库路径前；kiwix-manage 是 库文件在动作前（kiwix-manage 库文件 add/show/delete）；kiwix-search 是 选项 ZIM PATTERN。写反统一得到 Arguments did not match expected patterns。
退出码语义表（监控与脚本判断依据，全部实测）：

命令情形	退出码	回显要点
`kiwix-manage add` 损坏 ZIM	1	`Cannot add ZIM ... to the library.`，库文件不生成
`kiwix-manage delete` 非法 ID	1	`Invalid book id 'xxx'.`
`kiwix-serve` 库文件缺失	0	`ERROR: Failed to load the XML library file ...` + /data 清单，服务退出
`kiwix-serve` 端口被占	1	`ERROR: Unable to instantiate the HTTP daemon. The port N is maybe already occupied ...`
`kiwix-search` 无结果	0	空输出

特别警惕库文件缺失的 exit 0——监控不能依赖退出码，要用 HTTP 探活（完整案例见部署篇 11.1）。 3. 容器内外路径一致性：exec 执行时命令里写容器内路径（/data/...）；库文件里的相对 path 以库文件所在目录为基准解析，建议 add 时统一用绝对路径。 4. kiwix-manage 不触碰运行中的服务：它只改库文件；要让变更对运行中实例生效，实例需带 --monitorLibrary，或向进程发 SIGHUP（两者均已实测生效）。 5. No stemming for language 'xx' 是提示不是错误：该语言无词干归并规则，检索功能不受影响，无需处理。

六、常见问题

kiwix-search 没有结果：依次排查——目标 ZIM 的 tags 是否含 _ftindex:yes（kiwix-manage 库文件 show 看得到）；确认搜的是 ZIM 文件而不是库文件路径；尝试 --spelling 纠错（实测 Pythn → Python）或 -s 前缀联想。
kiwix-manage add 拒绝入库：先 file 或大小核对 ZIM 完整性（下载中断常见），损坏文件回显 Cannot add ZIM ... to the library.（exit 1）；add 通过即代表元数据可读、文件可用，可作为下载后的校验步骤。
docker run <镜像> --help 报 Unexpected argument: --port=8080, --help：镜像入口 start.sh 预拼了 --port=8080；改用 docker exec <容器> kiwix-serve --help。
show 输出的 size 为什么和文件大小对不上单位：show 显示字节数但标 KB（93335552 KB 实为约 93 MB）；库 XML 内 size 属性是 KiB（91148），两者同源差 1024 倍，按字节理解即可。
删除书目后欢迎页还在：删除后若实例未带 --monitorLibrary 也不会自动重载——向进程发 kill -HUP 或重启容器；带 -M 时数秒内自动生效（部署篇 8.2 实测）。

七、参考链接

本专栏系列：《Kiwix 介绍与选型指南》、《Kiwix 3.8.2 Docker Compose 部署指南》、《Kiwix 3.8.2 启动旗标与库管理参数详解》
kiwix-tools 官方文档（kiwix-serve / kiwix-manage 权威口径）：https://kiwix-tools.readthedocs.io/en/latest/kiwix-serve.html （查询日期 2026-11-01）
kiwix-tools 源码与发布仓库：https://github.com/kiwix/kiwix-tools （查询日期 2026-11-01）
ZIM 官方下载目录：https://download.kiwix.org/zim/ （查询日期 2026-11-01）