使用Docker运行Xunsearch是最省事易复现的方案，但需注意镜像版本（推荐ghcr.io/xunsearch/xunsearch:latest）、配置与数据目录挂载权限（宿主机目录需chown 1001:1001）、PHP客户端连接地址（容器内用服务名，宿主机用127.0.0.1）及显式启用拼音模块（enable_pinyin=1并调用setAutoSpell(true)）。
直接用 Docker 跑 Xunsearch 是目前最省事、最易复现的方案，尤其适合 PHP 项目快速接入中文全文检索。它绕过了源码编译、PHP 扩展手动安装、字符集/端口冲突等老问题，但要注意镜像版本、配置挂载和 PHP 客户端连接方式这三处关键。
确认 Docker 镜像是否支持新版 Xunsearch（1.4.16+）
官方 hightman/xunsearch 镜像长期未更新，最新 tag 仍停留在 1.4.11（2021 年），不包含 1.4.14+ 的拼音纠错增强和并发连接优化。实际可用方案有两个：
- 改用社区维护的镜像：
ghcr.io/xunsearch/xunsearch:latest（截至 2026 年 4 月已同步至1.4.16） - 或自己基于官方源码构建：克隆
https://github.com/hightman/xunsearch，在Dockerfile中指定git checkout v1.4.16后docker build - 验证方式：容器启动后执行
docker exec -it xunsearch /usr/local/xunsearch/bin/xs-ctl.sh status，输出中需含version: 1.4.16
挂载配置与数据目录时必须避开权限陷阱
Docker 内 Xunsearch 进程以 xs 用户（UID 1001）运行，若宿主机挂载目录属主不是 UID 1001，会导致索引写入失败、xs-dstart 启动静默退出，且日志无明确报错。
- 正确做法：创建专用目录并 chown：
mkdir -p /var/xunsearch/data /var/xunsearch/conf && sudo chown -R 1001:1001 /var/xunsearch -
conf/下必须有项目配置文件，如music.ini；Xunsearch 不会自动创建该文件，缺失时搜索请求返回空结果而非报错 - 避免挂载整个
/usr/local/xunsearch—— 容器内二进制路径固定，挂载会覆盖可执行文件
PHP 客户端连接 Docker 版 Xunsearch 的真实地址
别写 localhost:8383。Docker 容器内 localhost 指向自身，而 Xunsearch 服务在另一个容器里。PHP 应用若也在容器中（如 nginx+php-fpm），必须用 Docker 网络别名；若在宿主机，则用 127.0.0.1（不是 localhost）。
立即学习“PHP免费学习笔记（深入）”；
- Docker Compose 场景：在
php-fpm容器的XS初始化代码中写new XS('music', ['server' => 'xunsearch:8383'])，其中xunsearch是docker-compose.yml中的服务名 - 宿主机 PHP 场景：用
new XS('music', ['server' => '127.0.0.1:8383'])，同时确保docker run映射了-p 8383:8383 - 连接超时常见于防火墙拦截：检查
ufw status或iptables -L是否放行 8383 端口
中文分词与拼音模糊搜索必须显式启用
Xunsearch Docker 镜像默认关闭拼音扩展，即使配置了 tokenizer = builtin，输入“zjl”也匹配不到“周杰伦”。必须手动开启：
- 进入容器：
docker exec -it xunsearch bash - 编辑
/usr/local/xunsearch/etc/xunsearch.ini，取消注释并确认以下两行存在：enable_pinyin = 1和pinyin_dict = /usr/local/xunsearch/dict/pinyin.dict - 重启服务：
/usr/local/xunsearch/bin/xs-ctl.sh restart - PHP 端发起查询时，需调用
$search->setAutoSpell(true)，否则拼音容错不生效
真正卡住人的从来不是“能不能跑起来”，而是配置挂载权限、容器网络地址、拼音模块开关这三处——它们不报错，只沉默地返回空结果。动手前先 docker logs xunsearch 看一眼有没有 permission denied 或 dict not found 才是最省时间的做法。
