Kiwix 3.8.2 Docker Compose 部署指南

Kiwix 3.8.2 官方镜像的 Docker Compose 从零部署与验证实录：直接 ZIM 与 library.xml 库模式两阶段编排、端口映射与欢迎页/OPDS/阅读器/内容页/全文搜索逐层验证、持久化与库热重载实测，以及库文件缺失与挂载属主两类故障的完整排障记录。

KiwixKiwixDockerDocker Compose自托管2026/11/01

Kiwix 3.8.2 Docker Compose 部署指南

目标：在一台 Ubuntu 服务器上用 Docker Compose 从零部署 Kiwix 官方镜像 ghcr.io/kiwix/kiwix-serve:3.8.2，完成「直接 ZIM 模式 → library.xml 库模式」两阶段编排、端口映射、数据持久化与页面级验证，并沉淀库文件缺失、挂载目录属主两类故障的完整排障实录。全部命令与回显均在真实服务器上逐条执行采集。

一、环境信息

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

  • 操作系统：Ubuntu 26.04.1 LTS（x86_64）
  • Docker：29.9.2（docker --version → Docker version 29.9.2, build a82e528）
  • Docker Compose：v5.6.1（docker compose version → Docker Compose version v5.6.1）
  • 软件版本：kiwix-serve 3.8.2（kiwix-tools 套件最新稳定版，2026-03-02 发布；版本线结论与溯源见本专栏 《Kiwix 介绍与选型指南》）
  • 镜像：ghcr.io/kiwix/kiwix-serve:3.8.2（92.8MB，镜像 ID e478554a9920，实测与 latest 标签同 ID）
  • 部署目录：/opt/data/quzuo/tmp/kiwix/compose/（ZIM 与库文件同目录托管）
  • 端口规划：宿主机 8137 → 容器 8080（容器内默认监听端口）
  • 拉取加速：本环境 docker pull 走代理 http://192.168.1.62:7897；ghcr.io 镜像为公开匿名拉取，无代理环境可直接 docker pull

二、镜像选型说明

Kiwix 官方在 ghcr.io 发布多形态镜像，逐一说明选型依据：

镜像内容本文取舍
ghcr.io/kiwix/kiwix-serve:<tag>仅 kiwix-serve（及随包的 kiwix-manage / kiwix-search），单一服务采用：伺服 ZIM 是唯一诉求，单容器职责清晰
ghcr.io/kiwix/kiwix-desktop:<tag>桌面 GUI 版，面向个人电脑交互使用不采用：无头服务器用不上 GUI
ZIM 下载器类辅助镜像抓取/转换在线内容为 ZIM不采用：直接使用官方成品 ZIM

补充三点实测结论：

  1. 版本对齐关系：kiwix-serve 没有独立版本线，随 kiwix-tools 套件统一发版。选 3.8.2 是因为它是 2026-11-01 查询时官方 Releases 的最新稳定版（3.8.0 → 3.8.1 → 3.8.2，约 2~3 个月一版）。
  2. 镜像与二进制同源：容器内同时带齐三件套，docker compose exec 即可调用 kiwix-manage 维护库文件，无需另装工具：
$ docker exec kiwix-3-8-2-web sh -c 'ls /usr/local/bin/'
kiwix-manage
kiwix-search
kiwix-serve
start.sh
  1. 入口约定：镜像 Entrypoint 为 /usr/bin/dumb-init -- /usr/local/bin/start.sh，compose 的 command 会原样追加为 kiwix-serve 参数。这一点决定了后面所有编排写法（详见第七节）。

三、前置条件

3.1 端口确认

容器内固定监听 8080（由镜像 start.sh 的 PORT 环境变量控制，默认 8080），宿主侧选 8137 承接。部署前确认宿主端口空闲：

$ ss -tlnp | grep 8137 || echo "8137 空闲"
8137 空闲

3.2 下载 ZIM 内容包

kiwix-serve 本体不自带任何内容，需要从官方目录 download.kiwix.org 下载 ZIM 文件。本文选两本书：中文维基教科书全量无图版（89 MiB 级，可验证全文搜索）与乌尔都语维基教科书（3 MiB 级，用于快速链路验证）：

$ mkdir -p zim && cd zim
$ curl -x http://192.168.1.62:7897 -LO https://download.kiwix.org/zim/wikibooks/wikibooks_zh_all_nopic_2026-10.zim
$ curl -x http://192.168.1.62:7897 -LO https://download.kiwix.org/zim/wikibooks/wikibooks_ur_all_nopic_2026-10.zim
$ ls -l
total 94276
-rw-r--r-- 1 1001 1001  3175666 Nov  1 11:44 wikibooks_ur_all_nopic_2026-10.zim
-rw-r--r-- 1 1001 1001 93335710 Nov  1 11:44 wikibooks_zh_all_nopic_2026-10.zim

说明：_nopic 为无图精简版，_all 表示该语言全部分册合集；文件名中的 _2026-10 是快照月份。选包原则——先小包打通链路，再引入大包。全部可用书目见 download.kiwix.org/zim/ 按项目与语言浏览（查询日期 2026-11-01）。

3.3 目录结构

最终部署目录结构如下（ZIM 与库文件同一目录，一并挂载进容器）：

/opt/data/quzuo/tmp/kiwix/compose/
├── docker-compose.yml
└── zim/
    ├── library.xml                              # 库文件（阶段二生成）
    ├── wikibooks_ur_all_nopic_2026-10.zim
    └── wikibooks_zh_all_nopic_2026-10.zim

四、部署步骤

按「先跑通、再规范化」分两阶段：阶段一直接把 ZIM 文件路径写进启动命令，最小代价验证镜像与端口链路；阶段二切换为 library.xml 库模式，这是官方推荐的长期运行形态（增删书目不用改 compose）。

4.1 阶段一：直接 ZIM 模式

compose 文件中 command 直接列出 ZIM 文件（容器内挂载路径 /data/...）：

    command: ["/data/wikibooks_zh_all_nopic_2026-10.zim", "/data/wikibooks_ur_all_nopic_2026-10.zim"]

启动并查看日志：

$ docker compose up -d
[+] Running 2/2
 ⠿ Network kiwix-382-stack_kiwix-net  Created
 ⠿ Container kiwix-3-8-2-web          Started
$ docker logs kiwix-3-8-2-web 2>&1 | tail -6
/usr/local/bin/kiwix-serve --port=8080 /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.57.10:8080
  - http://[::1]:8080

日志解读：第一行是 start.sh 回显的实际执行命令；No stemming for language 'zh'/'ur' 表示服务端对这两种语言没有词干归并规则，只影响检索词形归一，不影响搜索可用性，可忽略。日志中的 10.89.57.10 是容器在自定义网络中的固定 IP（第七节说明）。

4.2 阶段二：切换 library.xml 库模式

第一步：修正挂载目录属主。 镜像内进程以 uid=1001(user) 运行（docker compose exec kiwix-serve id → uid=1001(user) gid=1001(user) groups=1001(user)），宿主目录需允许该 uid 写入，否则 kiwix-manage 无法生成 library.xml（踩坑实录见第十一节）：

$ chown -R 1001:1001 zim

第二步：用 kiwix-manage 建库（两本书登记进库文件，条目数/媒体数/大小等元数据自动从 ZIM 内嵌信息读取）：

$ docker compose exec kiwix-serve kiwix-manage /data/library.xml add /data/wikibooks_zh_all_nopic_2026-10.zim
No stemming for language 'zh'
$ docker compose exec kiwix-serve kiwix-manage /data/library.xml add /data/wikibooks_ur_all_nopic_2026-10.zim
No stemming for language 'ur'

第三步：核对库内容（kiwix-manage 库文件 show，favicon 为 Base64 内嵌图标，此处省略显示）：

$ docker compose exec kiwix-serve 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
url:		
title:		ویکی کتب
name:		wikibooks_ur_all
tags:		wikibooks;_category:wikibooks;_pictures:no;_videos:no;_details:yes;_ftindex:yes
description:	اردو زبان میں ویکی بکس
creator:	Wikibooks
date:		2026-10-16
articleCount:	568
mediaCount:	167
size:		3175424 KB

口径注意：show 输出的 size 实际是字节数（93335552 ≈ 93 MB），但标签写作 KB；library.xml 内 size 属性则是 KiB 口径（91148，91148 × 1024 = 93335552）。两处数值同源、单位标注不一致，按字节理解即可。

第四步：改写 command 为库模式（完整 compose 全文见下）：

    command: ["--library", "/data/library.xml", "--monitorLibrary"]

最终版 docker-compose.yml 全文：

name: kiwix-3.8.2-stack

services:
  kiwix-serve:
    image: ghcr.io/kiwix/kiwix-serve:3.8.2
    container_name: kiwix-3-8-2-web
    restart: unless-stopped
    ports:
      - "8137:8080"
    volumes:
      - ./zim:/data
    command: ["--library", "/data/library.xml", "--monitorLibrary"]
    networks:
      kiwix-net:
        ipv4_address: 10.89.57.10

networks:
  kiwix-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.57.0/24
          gateway: 10.89.57.1

重新生效并查看启动日志：

$ docker compose up -d
[+] Running 1/1
 ⠿ Container kiwix-3-8-2-web  Started
$ docker logs kiwix-3-8-2-web 2>&1 | tail -6
/usr/local/bin/kiwix-serve --port=8080 --library /data/library.xml --monitorLibrary
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.57.10:8080
  - http://[::1]:8080

The library was successfully loaded. 即库模式加载成功。两行启动日志的差异就是两种模式的分水岭：直接模式只回显执行命令，库模式多出 Loading the library ... successfully loaded 两段。

4.3 部署状态与端口映射验证

$ docker compose ps
NAME              IMAGE                             STATUS          PORTS
kiwix-3-8-2-web   ghcr.io/kiwix/kiwix-serve:3.8.2   Up 11 minutes   80/tcp, 0.0.0.0:8137->8080/tcp, [::]:8137->8080/tcp
$ docker port kiwix-3-8-2-web
8080/tcp -> 0.0.0.0:8137
8080/tcp -> [::]:8137

4.4 页面级验证（HTTP 逐层探测）

本环境为无头服务器，以 HTTP 层等效证据完成「浏览器访问 library 页与内容页」验证，逐层覆盖欢迎页、静态资源、阅读器、书目目录与内容页：

$ curl -s -o /dev/null -w "%{http_code} %{size_download}B\n" http://127.0.0.1:8137/
200 4999B
$ curl -s http://127.0.0.1:8137/ | grep -oE "<title>[^<]*</title>"
<title>Welcome to Kiwix Server</title>
$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8137/viewer#wikibooks_zh_all_nopic_2026-10
200
$ curl -s -o /dev/null -w "%{http_code} %{size_download}B\n" "http://127.0.0.1:8137/skin/kiwix.css?cacheid=b4e29e64"
200 2458B

OPDS 书目目录确认两本书均已注册（<title> 依次为feed 标题与两本书名）：

$ curl -s "http://127.0.0.1:8137/catalog/v2/entries?count=-1" | grep -oE "<title>[^<]*</title>"
<title>Filtered Entries (count=-1)</title>
<title>Wikibooks</title>
<title>ویکی کتب</title>

内容页与原始元数据直接可读：

$ curl -s -o /dev/null -w "%{http_code} %{size_download}B\n" http://127.0.0.1:8137/content/wikibooks_zh_all_nopic_2026-10/Python
200 25495B
$ curl -s http://127.0.0.1:8137/raw/wikibooks_zh_all_nopic_2026-10/meta/Title
Wikibooks

全文搜索走公开端点 /search（默认每页 25 条）：

$ curl -s -o /dev/null -w "%{http_code}\n" "http://127.0.0.1:8137/search?pattern=Python&books.name=wikibooks_zh_all_nopic_2026-10"
200
$ curl -s "http://127.0.0.1:8137/search?pattern=Python&books.name=wikibooks_zh_all_nopic_2026-10" | grep -oE "Results <b>[^<]*</b> of <b>[^<]*</b>"
Results <b>1-25</b> of <b>178</b>

至此部署链路全部打通：欢迎页（书目入口）→ OPDS 目录 → 阅读器 → 内容页 → 全文搜索五层全部 200。

五、数据持久化说明

  • 全部状态都在 ./zim/ 一个目录：ZIM 文件 + library.xml，经 bind mount 挂到容器 /data。容器本身无状态，销毁重建不丢数据；备份就是备份这个目录。
  • 重启不丢服务：restart: unless-stopped 保证宿主重启或容器异常退出后自动拉起。实测 docker compose restart 后服务恢复、书目与搜索数据完好（重启即重新加载同一 library.xml）。
  • 崩溃自愈实证：第十一节的库文件缺失故障中，容器曾进入重启循环（RestartCount=8）；把 library.xml 放回原位后，下一轮自动重启即恢复正常（无需任何人工干预），HTTP 回到 200——unless-stopped 策略在故障修复后具备自愈能力。
  • 写库落盘即时：kiwix-manage 的每次 add/delete 都直接写宿主侧 ./zim/library.xml（属主 1001:1001），持久化与热重载同时生效（见第八节实测）。

六、环境变量表

镜像内置启动脚本 start.sh（/usr/local/bin/start.sh）仅识别两个环境变量（脚本关键逻辑摘录，实测读自容器内文件）：

环境变量默认值作用本文用法
PORT8080拼接为 kiwix-serve --port=$PORT，容器内监听端口不设置，用默认 8080，端口转换全部交给宿主侧 ports 映射
DOWNLOAD空非空时启动前 wget $DOWNLOAD -O <文件名> 下载 ZIM 到当前目录；若 command 未给参数则自动把该文件作为伺服目标不设置：ZIM 已离线就位，避免启动期依赖外网

start.sh 原文关键段（cat /usr/local/bin/start.sh 摘录）：

if [ -z "$PORT" ]
then
    PORT=8080
fi
CMD="/usr/local/bin/kiwix-serve --port=$PORT $@"
echo $CMD
$CMD

两点工程提示：

  1. DOWNLOAD 下载前会检查 /data 可写性，不可写直接退出（'/data' directory is not writable by ...）——又是一个把目录属主配对（1001:1001）的理由。
  2. command 里的参数追加在 --port 之后，所以即使想改容器内端口也只能通过 PORT 环境变量，不要试图在 command 里再写一个 --port（会拼出两个 --port 参数，行为未定义）。

七、配置参数说明

compose 文件逐项拆解：

配置项取值说明
namekiwix-3.8.2-stack项目名。实测 Compose 会把点号剥离，实际生效项目名为 kiwix-382-stack（docker compose ls 可见），网络随之命名为 kiwix-382-stack_kiwix-net——项目名建议一开始就避开点号
imageghcr.io/kiwix/kiwix-serve:3.8.2显式版本标签，锁版本升级可控
container_namekiwix-3-8-2-web固定容器名，<产品>-<版本>-<用途> 命名法，便于日志与 exec 引用
restartunless-stopped故障自愈 + 开机自启（手工 stop 的除外），持久化一节的崩溃自愈实证依赖此策略
ports"8137:8080"宿主 8137 → 容器 8080；容器内端口由 PORT 默认值决定，两者必须对应
volumes./zim:/data官方镜像约定的内容目录；ZIM、library.xml、镜像 DOWNLOAD 下载目标都落在这里
command["--library", "/data/library.xml", "--monitorLibrary"]原样透传给 kiwix-serve：--library 指定库文件（XML 或 OPDS）；--monitorLibrary 监视库文件变化自动重载。kiwix-serve 全部启动旗标（端口/线程/界面裁剪/外链封锁等）在本专栏《Kiwix 启动旗标与库管理参数详解》篇逐项实测讲解
networks.ipv4_address10.89.57.10自定义网桥内固定 IP。显式声明 10.89.57.0/24 子网是为了与其他 compose 栈的 Docker 默认网段隔离，避免网段漂移导致的防火墙/路由规则失效；日志里打印的 http://10.89.57.10:8080 即此地址

八、配置文件挂载（library.xml）

8.1 文件结构

library.xml 是 kiwix-manage 维护的 XML 库文件，根元素与书目条目实测结构如下（favicon 为 Base64 书封图标，实际文件中完整保留，此处截断展示）：

<library version="20110515">
  <book id="5c3cd871-8b19-8cc7-76ec-c02a1180d221" path="wikibooks_zh_all_nopic_2026-10.zim" title="Wikibooks" description="An Offline Version of Wikibook in Chinese Language" language="zho" creator="Wikibooks" publisher="openZIM" name="wikibooks_zh_all" flavour="nopic" tags="wikibooks;_category:wikibooks;_pictures:no;_videos:no;_details:yes;_ftindex:yes" faviconMimeType="image/png" favicon="iVBORw0KGgoAAAANSU……（Base64 略）" date="2026-10-15" articleCount="8510" mediaCount="132" size="91148" />
  <book id="9165b265-394c-22bf-4e51-eec17f9639b3" path="wikibooks_ur_all_nopic_2026-10.zim" ……（结构与上一条相同） />
</library>

关键字段解读：

字段含义工程要点
id书目唯一 ID（UUID）源自 ZIM 内嵌 UUID，删除重加不变；kiwix-manage delete 按它定位
pathZIM 路径add 传入 /data/... 绝对路径，XML 中存为相对库文件目录的形式；show 输出又带 /data/ 前缀，两种形态实测并存
name内容的 URL 名称决定 /content/<name>/...、/search?books.name=<name> 里的书名标识
tags分号分隔标签_ftindex:yes 表示内嵌全文索引（可被 /search 检索）；_pictures:no、_category:wikibooks 等 _ 前缀为机器用私有标签
articleCount / mediaCount条目数 / 媒体数由 add 时从 ZIM 元数据自动读取（8510 / 132）
size文件大小单位 KiB（91148 KiB），与 show 的字节口径相差一个 1024 因子

8.2 热重载实测（--monitorLibrary）

command 里的 --monitorLibrary 让运行中的 kiwix-serve 监视 library.xml。实测：不重启容器，删除乌尔都语书再重新加回，OPDS 目录条目数即时跟随变化（2 → 1 → 2）：

$ curl -s "http://127.0.0.1:8137/catalog/v2/entries?count=-1" | grep -c "<entry>"
2
$ docker compose exec kiwix-serve kiwix-manage /data/library.xml delete 9165b265-394c-22bf-4e51-eec17f9639b3
$ sleep 3 && curl -s "http://127.0.0.1:8137/catalog/v2/entries?count=-1" | grep -c "<entry>"
1
$ docker compose exec kiwix-serve kiwix-manage /data/library.xml add /data/wikibooks_ur_all_nopic_2026-10.zim
$ sleep 3 && curl -s "http://127.0.0.1:8137/catalog/v2/entries?count=-1" | grep -c "<entry>"
2

结论：日常增删书目完全不需要动 compose 或重启容器——下载 ZIM 进 ./zim/、kiwix-manage add、几秒内生效。另注意 monitorLibrary 重载默认不打印日志，验证生效与否看 OPDS/欢迎页条目数即可。

九、等价 docker run

库模式等价的一次性启动命令（与 compose 编排同效，适合临时验证）：

$ docker run -d --name kiwix-3-8-2-web \
    -p 8137:8080 \
    -v /opt/data/quzuo/tmp/kiwix/compose/zim:/data \
    --restart unless-stopped \
    ghcr.io/kiwix/kiwix-serve:3.8.2 \
    --library /data/library.xml --monitorLibrary

与 compose 版的差异：未建自定义网络（无固定容器 IP，用默认 bridge），其余语义一致。dumb-init 入口、start.sh 包装、参数透传行为与 compose 完全相同（都由镜像自身决定）。

十、常用运维命令

# 状态与日志
$ docker compose ps
$ docker compose logs -f --tail 100

# 重启 / 停止 / 销毁
$ docker compose restart          # 重启容器，数据不丢
$ docker compose stop             # 停止（保留容器与网络）
$ docker compose down             # 销毁容器与网络（./zim/ 数据保留）

# 变更后重新生效（改了 compose 文件）
$ docker compose up -d

# 版本升级：改 image 标签后
$ docker compose pull && docker compose up -d

# 书目管理（容器内自带 kiwix-manage）
$ docker compose exec kiwix-serve kiwix-manage /data/library.xml show
$ docker compose exec kiwix-serve kiwix-manage /data/library.xml add /data/<新ZIM文件>.zim
$ docker compose exec kiwix-serve kiwix-manage /data/library.xml delete <book-id>

升级提示：3.8.2 → 后续版本时，ZIM 与 library.xml 格式向后兼容（libzim 读取端承诺旧文件兼容），直接换镜像标签重建即可；升级后用第 4.4 节的 HTTP 探测链路快速回归。

十一、常见问题（排障实录）

以下三类故障均为本文实测复现的真实案例，回显逐字保留。

11.1 library.xml 缺失 → 容器反复重启（crash-loop）

现象：docker compose ps 里容器状态不断变为 Restarting，HTTP 不通。

复现：把 library.xml 移走后 docker compose down && docker compose up -d，日志出现服务端报错，start.sh 的兜底逻辑还会打印 /data 目录内容辅助定位：

$ docker logs kiwix-3-8-2-web 2>&1 | tail -9
/usr/local/bin/kiwix-serve --port=8080 --library /data/library.xml --monitorLibrary
Loading the library from the following files:
	/data/library.xml
ERROR: Failed to load the XML library file '/data/library.xml'.
Errors encountered while loading the library.
Here is the content of /data:
/data/wikibooks_ur_all_nopic_2026-10.zim
/data/wikibooks_zh_all_nopic_2026-10.zim
$ docker ps -a --filter name=kiwix-3-8-2-web --format '{{.Status}}'
Restarting (0) 2 seconds ago
$ docker inspect kiwix-3-8-2-web --format 'ExitCode={{.State.ExitCode}} RestartCount={{.RestartCount}}'
ExitCode=0 RestartCount=8

根因与两个细节：kiwix-serve 对 --library 指向的文件是强依赖，加载失败即退出；但退出码是 0 而不是非零（ExitCode=0），所以任何依赖退出码的监控告警都会漏报，只能靠 restart 次数或 HTTP 探活发现。restart: unless-stopped 让容器陷入「启动→失败→退避→再启动」循环（实测 RestartCount 涨到 8）。

修复：把 library.xml 放回原路径即可，无需人工重启——下一轮自动拉起即加载成功并恢复 HTTP 200（实测 Restarting (0) 8 seconds ago → Up，curl 回到 200）。预防：建库（kiwix-manage add）务必先于库模式启动；首次部署按 4.2 节顺序操作。

11.2 挂载目录属主为 root → kiwix-manage 写库失败

现象：kiwix-manage ... add 报错（回显含一行正常的词干提示与一行致命错误）：

$ chown -R root:root zim   # 错误配置：宿主目录归 root
$ docker compose exec kiwix-serve kiwix-manage /data/library.xml add /data/wikibooks_ur_all_nopic_2026-10.zim
No stemming for language 'ur'
Cannot write the library /data/library.xml

根因：容器内进程是 uid=1001(user)（docker compose exec kiwix-serve id → uid=1001(user) gid=1001(user) groups=1001(user)），宿主目录归 root 且未放开写权限时，bind mount 内的 library.xml 不可写。

修复与验证：

$ chown -R 1001:1001 zim
$ docker compose exec kiwix-serve kiwix-manage /data/library.xml add /data/wikibooks_ur_all_nopic_2026-10.zim
No stemming for language 'ur'
$ grep -c "<book " zim/library.xml
2

11.3 kiwix-manage 参数顺序写反 → 直接拒绝执行

kiwix-manage 的语法是 kiwix-manage 库文件 动作（库文件在前），写成 kiwix-manage show 库文件 会得到用法报错：

$ docker compose exec kiwix-serve kiwix-manage show /data/library.xml
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 /data/library.xml show（动作后还可跟可选的 book-id 过滤）。

11.4 症状速查

症状先查什么
容器 Restarting 循环、HTTP 000docker logs 看是否 Failed to load the XML library file（11.1）；确认 library.xml 存在且路径正确
add/写库报 Cannot write the library挂载目录属主是否 1001:1001（11.2）
Arguments did not match expected patternskiwix-manage 参数顺序（11.3）
欢迎页 200 但书目为空库模式是否漏带 --library（漏带时 library.xml 会被当成 ZIM 报 Unable to add the ZIM file '/data/library.xml' ...）；或 OPDS 端点 /catalog/v2/entries 直接核对
搜索无结果目标书 tags 里是否含 _ftindex:yes（无全文索引的 ZIM 不参与 /search）；多书联合检索需同语言且受 --searchLimit 约束

十二、参考链接

  1. 本专栏前置阅读：《Kiwix 介绍与选型指南》（ZIM 架构、版本线溯源与同类方案对比）
  2. kiwix-serve 官方文档（旗标与 HTTP API 权威口径）：https://kiwix-tools.readthedocs.io/en/latest/kiwix-serve.html （查询日期 2026-11-01）
  3. 官方 Docker 镜像：ghcr.io/kiwix/kiwix-serve（标签 3.8.2；查询日期 2026-11-01）
  4. ZIM 官方下载目录（wikibooks 分类）：https://download.kiwix.org/zim/wikibooks/ （查询日期 2026-11-01）
  5. kiwix-tools 源码与发布仓库：https://github.com/kiwix/kiwix-tools （查询日期 2026-11-01）