xunsearch在Linux上安装不复杂，只需下载官方tar包、解压后运行sh setup.sh，默认路径回车即可；注意依赖检测、权限统一、端口未被占用，并通过curl和ps验证服务真实启动，demo.ini位于sdk/php/app/目录，索引与搜索命令需严格匹配project.name。
xunsearch 在 Linux 上安装其实不复杂，但容易卡在依赖或路径配置上。只要步骤对、权限清、端口通，10 分钟内就能跑起来。
用官方 tar 包安装最稳妥
别从 Git 源码编译起步——新手容易缺 autoconf、automake 或 libtool，报错一堆还不好定位。直接下载官方预编译包最省事：
- 执行
wget http://www.xunsearch.com/download/xunsearch-full-latest.tar.bz2 - 解压：
tar -xjf xunsearch-full-*.tar.bz2 - 进目录后运行
sh setup.sh，提示输入安装路径时，默认/usr/local/xunsearch直接回车就行 - 安装过程会自动检测
gcc、make、zlib等依赖，缺哪个它会明确告诉你，比如zlib1g-dev（Ubuntu/Debian）或zlib-devel（CentOS/RHEL）
注意：setup.sh 是纯脚本安装，不走 ./configure && make && make install 流程，所以不用装 g++——除非你后续要自己改 C++ 模块。
xs-ctl.sh start 启动失败常见原因
安装完执行 /usr/local/xunsearch/bin/xs-ctl.sh start 却没反应？大概率是以下三类问题：
- 端口被占：
8383（索引服务）和8384（搜索服务）默认绑定127.0.0.1。如果本地已有服务占了这两个端口，启动会静默失败。用netstat -tuln | grep -E '8383|8384'查一下 - 权限不足：
setup.sh默认把文件属主设为当前用户，但如果你用root安装、再用普通用户启动，会因无法写data/目录而失败。统一用root执行启动命令，或chown -R youruser:yourgroup /usr/local/xunsearch/data - 防火墙拦截：即使服务起来了，外部机器也连不上
8384。确认ufw或firewalld放行了这两个端口，或者启动时加-b inet绑定到0.0.0.0（仅测试环境用）
验证服务是否真跑起来了
光看终端没报错不等于服务可用。最简单的验证方式是：
- 执行
curl http://127.0.0.1:8384—— 返回空白页或 404 是正常的，说明 HTTP 服务已监听 - 执行
ps aux | grep xs，应看到至少两个进程：xs_indexd和xs_searchd - 检查日志：
tail -f /usr/local/xunsearch/log/xs_indexd.log和xs_searchd.log，启动成功末尾会有类似daemon started, pid=12345的记录
别跳过日志——很多“启动成功”其实是假象，真正错误全藏在 log 文件里。
配置文件位置和 demo 测试必须知道的细节
demo.ini 不在 /etc 下，而是在 SDK 目录里：/usr/local/xunsearch/sdk/php/app/demo.ini。这个文件定义了字段名、编码、端口等，但关键一点是：
- 它默认连接本地
8383/8384，如果你改过服务绑定地址（比如用了-b inet），必须同步修改server.index和server.search字段，否则Indexer.php会连不上 - 执行索引导入时，命令是
php util/Indexer.php --source=csv --clean demo，不是php Indexer.php—— 少写util/路径会报“找不到文件” - 手动输入 CSV 时，最后一行输完必须先按
Enter换行，再按Ctrl+D（Linux/macOS）或Ctrl+Z（Windows WSL），否则数据不会提交
真正麻烦的不是安装，而是配置和路径之间的隐式耦合——demo.ini 里的 project.name 决定了索引库名，也决定了 Indexer.php 和 Quest.php 后面跟的参数名，拼错一个字母就查不到数据。
