MeiliSearch 1.55.0 Ubuntu 22.04 安装指南
在 Ubuntu 22.04 上从零安装 MeiliSearch 1.55.0：官方脚本与手动二进制两条路径、systemd 托管、启动验证、升级降级与卸载清理全流程
MeiliSearch 1.55.0 Ubuntu 22.04 安装指南
目标：在 Ubuntu 22.04 服务器上从零安装并托管 MeiliSearch 1.55.0 全文搜索引擎，覆盖官方脚本安装与手动下载二进制两条路径、systemd 服务托管、启动验证、升级降级与卸载清理。已在 Ubuntu 22.04.5 LTS（x86_64）环境逐条实测通过。
一、环境信息
本文所有命令与回显均在以下环境中实测：
- 操作系统：Ubuntu 22.04.5 LTS（x86_64）
- 内核架构：x86_64（amd64）
- MeiliSearch 版本：1.55.0（commitSha
420ff1362801adb58c938aec89700e8f7e32e566，commitDate2026-10-12） - 安装路径：
/usr/local/bin/meilisearch - 数据目录：
/var/lib/meilisearch/data - Dump 目录：
/var/lib/meilisearch/dumps - 服务用户：
meilisearch（系统用户，禁止登录） - 监听地址：
127.0.0.1:7700 - Master Key（演示用测试口令）：
q1w2e3r4t5y6u7i8o0p
⚠️ 注意：本文以
q1w2e3r4t5y6u7i8o0p作为演示 Master Key（生产环境必须用openssl rand -hex 32重新生成，方法见第七章）。
二、概览与前置条件
2.1 MeiliSearch 简介
MeiliSearch（官方品牌写作 Meilisearch）是一个用 Rust 编写的开源全文搜索引擎，单个二进制文件即可运行，开箱即用，默认提供 RESTful HTTP API。它主打「搜索即服务」的极简体验：不需要像 Elasticsearch 那样理解分片、副本与 JVM 调优，创建索引、写入文档、发出搜索请求三个步骤即可上线一个容错搜索服务。项目地址：https://github.com/meilisearch/meilisearch，官网：https://www.meilisearch.com。
💡 技术拓展：全文检索引擎的核心数据结构是「倒排索引」（Inverted Index）——把文档拆词后建立「词 → 文档列表」的映射，查询时先查词表再取文档，而不是逐篇扫文档。除 MeiliSearch 外，常见同类引擎横向对比：
引擎 语言/形态 部署复杂度 容错搜索 适用场景 MeiliSearch Rust 单二进制 极低（单进程单文件） 原生支持、开箱即用 中小规模站点搜索、应用内搜索 Elasticsearch Java 多进程集群 高（JVM、分片、集群拓扑） 需自行配置 fuzzy 大规模日志/全文检索、复杂聚合 Typesense C++ 单二进制 低 原生支持 与 MeiliSearch 定位接近，中小规模 Algolia SaaS 托管 无需部署（商用收费） 原生支持 不想自运维、预算充足的商业站点 本文选用 MeiliSearch 1.55.0：单二进制零依赖、默认容错与中文分词友好、REST API 学习成本低，适合中小规模自托管搜索场景。
2.2 前置条件
安装前确认服务器满足以下条件。逐条验证命令与实测回显如下：
- 操作系统为 Ubuntu 22.04（其他 Debian 系发行版流程相同，包管理命令一致）：
cat /etc/os-release | head -3
实测输出：
PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"
- 已安装 curl 与 wget（下载二进制用）。若缺失则先安装：
apt update && apt install -y curl wget ca-certificates
实测输出（节选）：
Running hooks in /etc/ca-certificates/update.d...
done.
- 服务器可访问 GitHub（下载 release 二进制）。测试命令与实测输出：
curl -fsSI https://github.com/meilisearch/meilisearch/releases/latest | grep -i location
实测输出：
location: https://github.com/meilisearch/meilisearch/releases/tag/v1.55.0
💡 说明：该命令同时返回了当前最新 stable 版本号（HTTP 302 跳转到 v1.55.0 的 tag 页面），第三章的版本选型就依赖这条命令。
- systemd 可用（Ubuntu 22.04 默认自带，用于服务托管）：
systemctl is-system-running
实测输出：
running
三、版本选型说明
3.1 版本获取方法
MeiliSearch 遵循语义化版本（v主.次.修），发行节奏较快。查询最新 stable 版本的方法（不要硬编码记忆版本号，以下命令随时可复查）：
curl -fsSI https://github.com/meilisearch/meilisearch/releases/latest | grep -i location
实测输出（2026-10-16 查询）：
location: https://github.com/meilisearch/meilisearch/releases/tag/v1.55.0
3.2 版本与发布件对照表
MeiliSearch 官方发布渠道只有 GitHub Release，每个版本提供以下平台二进制（以 v1.55.0 实际资产清单为准）：
| 发布件名称 | 平台 | 说明 |
|---|---|---|
| meilisearch-linux-amd64 | Linux x86_64 | 本文使用 |
| meilisearch-linux-aarch64 | Linux ARM64 | 树莓派/ARM 云主机 |
| meilisearch-linux-riscv64 | Linux RISC-V | 实验性平台 |
| meilisearch-macos-amd64 / -apple-silicon | macOS | 开发机使用 |
| meilisearch-windows-amd64.exe | Windows | 开发机使用 |
| meilisearch-enterprise-* | 各平台企业版 | 商业授权版本 |
关键差异与选型：普通 Linux 服务器选 meilisearch-linux-amd64（x86_64）或 meilisearch-linux-aarch64（ARM64）；企业版需单独购买授权，本文不涉及。
⚠️ 注意：与 MySQL、Redis 等软件不同，MeiliSearch 官方不提供 APT 仓库，也不提供 deb/rpm 安装包（v1.55.0 的 Release 资产清单已逐项核实，只有各平台二进制与 openapi/error-codes 附加文件）。因此 Ubuntu 上的安装路径是「下载官方二进制 + 手工配置 systemd 服务」，不存在
apt install meilisearch的官方方式。网上的第三方 APT 源非官方维护，不建议使用。
3.3 两条安装路径概述
| 方案 | 方式 | 是否需联网 | 适用场景 |
|---|---|---|---|
| 方案 A | 官方安装脚本（install.meilisearch.com） | 需访问 GitHub | 能正常访问 GitHub 的服务器，一条命令完成 |
| 方案 B | 手动下载 GitHub Release 二进制 | 需下载 release 文件 | 网络受限、需要离线分发、需要固定版本号的场景 |
关键差异：方案 A 本质是脚本自动调用 GitHub API 查询最新版本再下载二进制，版本不可控且依赖 GitHub API 配额；方案 B 直接下载固定版本二进制，版本可控、可预下载后离线安装。生产环境推荐方案 B。
四、方案 A：官方安装脚本（在线一键安装）
4.1 方案说明
官方提供一条命令安装：
curl -L https://install.meilisearch.com | sh
脚本逻辑（源自脚本源码，官方地址 https://install.meilisearch.com）：调用 GitHub API 查询最新 stable 版本 → 判断操作系统与架构 → 从 GitHub Release 下载对应二进制到当前目录并命名为 meilisearch、赋权 744。脚本支持 GITHUB_PAT 环境变量携带 GitHub Token 以提升 API 配额。
4.2 实测：脚本执行与失败排障实录
在本环境直接执行脚本，两次实测均失败，报错如下（这是国内服务器访问 GitHub API 的典型现象，完整保留供排障）：
第一次（GitHub API 匿名限流）：
cd /opt && curl -L https://install.meilisearch.com | sh
实测输出：
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 167 0 167 0 0 22 0 --:--:-- 0:00:07 --:--:-- 47
100 4492 100 4492 0 0 535 0 0:00:08 0:00:08 --:--:-- 4386k
ERROR: Impossible to get the latest stable version of Meilisearch.
Please let us know about this issue: https://github.com/meilisearch/meilisearch/issues/new/choose
In the meantime, you can manually download the appropriate binary from the GitHub release assets here: https://github.com/meilisearch/meilisearch/releases/latest
第二次（GitHub API 连接被重置）：
curl: (56) OpenSSL SSL_read: Connection reset by peer, errno 104
错误定位：脚本匿名调用 https://api.github.com/repos/meilisearch/meilisearch/releases/latest，GitHub 对匿名 API 请求限制 60 次/小时/IP，超限即返回 403，脚本解析不到 tag_name 就报上述错误；部分网络环境还会出现到 api.github.com 的 TLS 连接被重置。
解决方案二选一：
- 携带 GitHub Token 执行（脚本原生支持 GITHUB_PAT 变量）：
GITHUB_PAT=你的GitHub令牌 sh -c 'curl -L https://install.meilisearch.com | sh'
- 放弃脚本，改用方案 B 手动下载（推荐，见第五章）。
4.3 脚本安装成功后的落位与处理
脚本成功时会在当前工作目录生成 meilisearch 文件（脚本源码中 chmod 744 "$binary_name"）。此时二进制只对当前目录可用，需继续完成以下三步：移动到系统路径、创建专用用户与数据目录、配置 systemd 服务。这三步与方案 B 完全一致，统一在 4.4 ～ 4.5 与第五章 5.3 ～ 5.5 描述（4.4/4.5 与 5.4/5.5 内容相同，任选一个方案的后续步骤即可）。
mv ./meilisearch /usr/local/bin/meilisearch && chmod 755 /usr/local/bin/meilisearch
meilisearch --version
实测输出：
meilisearch 1.55.0
五、方案 B：手动下载官方二进制（生产推荐）
5.1 方案说明
直接从 GitHub Release 下载固定版本的官方二进制，放到 /usr/local/bin，再手工创建专用用户、数据目录与 systemd 服务。版本完全可控，二进制可预下载后在内网服务器之间分发，是最贴近生产的安装方式。
5.2 下载与校验
下载 v1.55.0 的 linux-amd64 二进制（约 341 MB）：
cd /opt
curl -fLO https://github.com/meilisearch/meilisearch/releases/download/v1.55.0/meilisearch-linux-amd64
实测输出（下载完成确认）：
HTTP 200, 357184032 bytes
ls -lh /opt/meilisearch-linux-amd64
实测输出：
-rw-r--r-- 1 root root 341M Oct 16 15:29 meilisearch-linux-amd64
官方 Release 不随附 sha256 校验文件（v1.55.0 资产清单核实无 .sha256 发布件，尝试下载 meilisearch-linux-amd64.sha256 返回 404），但应自行记录校验值用于分发比对：
sha256sum /opt/meilisearch-linux-amd64
实测输出：
7e33f5889235f14290074a19a6d3574bd9b10fb2ee8731eabb7dafd0714b0513 meilisearch-linux-amd64
💡 说明：若服务器访问 GitHub 缓慢或失败，可预先在能联网的机器上下载该文件，再通过
scp /opt/meilisearch-linux-amd64 root@目标服务器:/opt/传输到目标服务器，sha256 值比对一致即可放心使用。
5.3 安装二进制与创建运行用户
把二进制安装到系统路径并赋予执行权限：
chmod 755 /opt/meilisearch-linux-amd64
mv /opt/meilisearch-linux-amd64 /usr/local/bin/meilisearch
验证安装：
which meilisearch
meilisearch --version
实测输出：
/usr/local/bin/meilisearch
meilisearch 1.55.0
创建专用系统用户（不可登录，仅用于运行服务，避免以 root 运行）：
useradd -r -s /usr/sbin/nologin meilisearch
创建数据、dump、uploads 目录并移交属主：
mkdir -p /var/lib/meilisearch/data /var/lib/meilisearch/dumps /var/lib/meilisearch/uploads
chown -R meilisearch:meilisearch /var/lib/meilisearch
验证用户与目录：
id meilisearch
ls -ld /var/lib/meilisearch
实测输出：
uid=999(meilisearch) gid=999(meilisearch) groups=999(meilisearch)
drwxr-xr-x 5 meilisearch meilisearch 4096 Oct 16 15:29 /var/lib/meilisearch
5.4 配置 systemd 服务
创建服务单元文件 /etc/systemd/system/meilisearch.service：
cat > /etc/systemd/system/meilisearch.service <<'EOF'
[Unit]
Description=MeiliSearch full-text search engine
After=network.target
[Service]
Type=simple
User=meilisearch
Group=meilisearch
ExecStart=/usr/local/bin/meilisearch --http-addr 127.0.0.1:7700 --env production --master-key q1w2e3r4t5y6u7i8o0p --db-path /var/lib/meilisearch/data --dump-dir /var/lib/meilisearch/dumps
Restart=always
RestartSec=5
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
EOF
逐项说明：
User/Group=meilisearch：以专用低权限用户运行；--http-addr 127.0.0.1:7700：仅监听本机回环（生产若需外部访问建议置于 Nginx 反代之后，或改为0.0.0.0:7700并配好防火墙）；--env production：生产模式，强制要求 Master Key 且日志更严格；--master-key：实例主密钥，保护除GET /health外的所有 API 路由；--db-path/--dump-dir：数据与 dump 落盘目录，与 5.3 创建的目录对应；Restart=always+RestartSec=5：异常退出 5 秒后自动拉起；LimitNOFILE=65536：提高文件描述符上限，避免大索引时too many open files。
加载并启用服务（每条命令针对一个服务单元）：
systemctl daemon-reload
systemctl enable meilisearch
systemctl start meilisearch
实测输出（enable 时）：
Created symlink /etc/systemd/system/multi-user.target.wants/meilisearch.service → /etc/systemd/system/meilisearch.service.
5.5 启动状态与服务验证
确认服务运行状态：
systemctl is-active meilisearch
systemctl status meilisearch --no-pager -l
实测输出：
active
● meilisearch.service - MeiliSearch full-text search engine
Loaded: loaded (/etc/systemd/system/meilisearch.service; enabled; vendor preset: enabled)
Active: active (running) since Fri 2026-10-16 15:29:58 UTC; 4s ago
Main PID: 2935 (meilisearch)
Tasks: 22 (limit: 7196)
Memory: 28.9M
CPU: 45ms
CGroup: /system.slice/meilisearch.service
└─2935 /usr/local/bin/meilisearch --http-addr 127.0.0.1:7700 --env production --master-key q1w2e3r4t5y6u7i8o0p --db-path /var/lib/meilisearch/data --dump-dir /var/lib/meilisearch/dumps
Oct 16 15:29:59 c7db0bef431b meilisearch[2935]: Anonymous telemetry: "Enabled"
Oct 16 15:29:59 c7db0bef431b meilisearch[2935]: Instance UID: "16d031b3-e7c6-4fa8-aa31-653cca51b776"
HTTP 健康检查（GET /health 无需鉴权）：
curl -s http://127.0.0.1:7700/health
实测输出：
{"status":"available"}
版本端点（需 Master Key）：
curl -s http://127.0.0.1:7700/version -H 'Authorization: Bearer q1w2e3r4t5y6u7i8o0p'
实测输出：
{"commitSha":"420ff1362801adb58c938aec89700e8f7e32e566","commitDate":"2026-10-12T08:45:13.000000000Z","pkgVersion":"1.55.0"}
无凭据访问业务路由会被拒绝（401），说明鉴权已生效：
curl -s http://127.0.0.1:7700/indexes -w '\nHTTP %{http_code}\n'
实测输出：
{"message":"The Authorization header is missing. It must use the bearer authorization method.","code":"missing_authorization_header","type":"auth","link":"https://docs.meilisearch.com/errors#missing_authorization_header"}
HTTP 401
带凭据访问正常（200）：
curl -s http://127.0.0.1:7700/indexes -H 'Authorization: Bearer q1w2e3r4t5y6u7i8o0p' -w '\nHTTP %{http_code}\n'
实测输出：
{"results":[],"offset":0,"limit":20,"total":0}
HTTP 200
六、方案对比与选择建议
| 维度 | 方案 A（官方脚本） | 方案 B（手动二进制） |
|---|---|---|
| 版本控制 | 自动取最新版，不可指定 | 任意固定版本 |
| 网络依赖 | GitHub API + Release 双依赖，易被限流 | 仅 Release 下载，可离线分发 |
| 落位路径 | 当前工作目录，需手动归位 | 直接安装到 /usr/local/bin |
| systemd 服务 | 脚本不创建，需手工配置 | 手工配置（本文 5.4 模板） |
| 可重复性 | 每次结果可能不同 | sha256 可校验，结果一致 |
选择建议：生产环境一律选方案 B（版本可控、可离线、可校验）；方案 A 仅适合个人机器快速体验。两条路径的二进制完全相同，后续的 systemd 配置、升级、卸载操作完全一致。
七、配置说明
7.1 生成生产用 Master Key
演示值 q1w2e3r4t5y6u7i8o0p 仅用于本文流程演示，生产环境用以下命令生成随机密钥（至少 16 字节）：
openssl rand -hex 32
实测输出（示例，每次运行结果不同）：
1d542b1e3d34e3ae1ba247dbb41d1a1fa4798a5d1c46e2c9f75ff8f4c50b0f37
将生成值替换 5.4 单元文件中的 --master-key，然后重载并重启（每条命令针对一个服务单元）：
systemctl daemon-reload
systemctl restart meilisearch
7.2 防火墙与端口
MeiliSearch 默认端口 7700。若监听 0.0.0.0，用 ufw 只放行可信来源：
ufw allow from 192.168.1.0/24 to any port 7700 proto tcp
实测输出：
Rule added
💡 说明：生产部署更常见的做法是保持
--http-addr 127.0.0.1:7700，由 Nginx 反向代理对外提供 HTTPS，Master Key 只存在后端配置里，避免密钥直接暴露给前端。
7.3 配置方式的优先级
MeiliSearch 支持三种配置方式，优先级为 命令行参数 > 环境变量（MEILI_*）> TOML 配置文件（--config-file-path），同一参数在高层指定时覆盖低层。TOML 配置示例（参数含义与 CLI 一致，键名去掉了 -- 前缀、连字符改下划线）：
db_path = "/var/lib/meilisearch/data"
http_addr = "127.0.0.1:7700"
master_key = "q1w2e3r4t5y6u7i8o0p"
env = "production"
no_analytics = true
启动时指定：meilisearch --config-file-path /etc/meilisearch.toml。逐项实测效果见《MeiliSearch 1.55.0 配置参数详解》。
八、常见问题（FAQ）
Q1：运行官方安装脚本报 ERROR: Impossible to get the latest stable version of Meilisearch. 怎么办？
原因：脚本匿名调用 GitHub API 被限流（匿名 60 次/小时/IP）或网络到 api.github.com 被重置。解决：按 4.2 节携带 GITHUB_PAT 环境变量重试，或直接改用方案 B 手动下载二进制。
Q2：production 模式启动报 You must provide a master key to secure your instance in a production environment.
原因：--env production（或 MEILI_ENV=production）时必须提供至少 16 字节的 Master Key。实测报错与官方提示：
2026-10-16T15:36:23.198420Z ERROR meilisearch: error=You must provide a master key to secure your instance in a production environment. It can be specified via the MEILI_MASTER_KEY environment variable or the --master-key launch option.
We generated a new secure master key for you (you can safely use this token):
>> --master-key DwHpHBFMdRx9MjkJ9FH8Fo0NMqdCI-MMdpwjJfPDT2Y <<
按提示用生成的密钥即可；密钥不足 16 字节时会报 The master key must be at least 16 bytes in a production environment. The provided key is only 5 bytes.（实测：传入 short 触发）。
Q3：以普通用户手动启动报 Permission denied (os error 13)，但数据目录权限明明正确。
原因：MeiliSearch 启动时还要求当前工作目录可写。实测对比：以 meilisearch 用户 cd / 后启动（/ 目录对该用户不可写）→ 报 ERROR meilisearch: error=Permission denied (os error 13) 后退出；cd /var/lib/meilisearch 后再启动同一命令 → 正常监听。解决：手动运行前先 cd 到可写目录；systemd 托管时 WorkingDirectory 缺省为服务用户主目录（本例 /var/lib/meilisearch，可写）因此不受影响，如自定义了 WorkingDirectory 请确保该目录对运行用户可写。
Q4：启动时端口被占用怎么办？
用 ss -lntp | grep 7700 找出占用进程后停掉它，或修改 --http-addr 换端口（如 --http-addr 127.0.0.1:7701）。修改单元文件后需 systemctl daemon-reload 再 systemctl restart meilisearch。
Q5：访问 API 返回 401 missing_authorization_header。
这是正常安全行为：production 模式且配置了 Master Key 后，除 GET /health 外所有路由都需要 Authorization: Bearer <master-key> 请求头。curl 加 -H 'Authorization: Bearer q1w2e3r4t5y6u7i8o0p' 即可（实测见 5.5）。
Q6：systemctl start meilisearch 后服务反复重启。
排查顺序：journalctl -u meilisearch -n 50 --no-pager 看启动日志。常见原因：数据目录属主不是 meilisearch 用户（chown -R meilisearch:meilisearch /var/lib/meilisearch 修复）、master key 少于 16 字节（见 Q2）、二进制与 libc 不兼容（必须使用 GitHub Release 的 linux-amd64 版本，不要复用其他发行版包里的二进制）。
九、升级与降级
9.1 升级步骤
MeiliSearch 升级 = 替换二进制 + 重启。官方要求跨版本升级前先做数据备份（dump 方式见《MeiliSearch 1.55.0 进阶实战与运维》第五章）：
systemctl stop meilisearch
curl -fLo /usr/local/bin/meilisearch.new https://github.com/meilisearch/meilisearch/releases/download/<新版本号>/meilisearch-linux-amd64
⚠️ 注意：
<新版本号>需替换为 3.1 节命令查到的真实版本（如 v1.56.0），本环境升级当日的最新版即 1.55.0，无更高版本可实测升级后的版本回显，故此步只给方法。
chmod 755 /usr/local/bin/meilisearch.new
mv /usr/local/bin/meilisearch.new /usr/local/bin/meilisearch
systemctl start meilisearch
meilisearch --version
9.2 降级与多版本管理
MeiliSearch 不支持降级数据库格式：高版本引擎写入的数据文件低版本无法打开。降级前必须先用当前高版本导出 dump，再用低版本 --import-dump 导入（完整流程见《MeiliSearch 1.55.0 进阶实战与运维》第五章）。需要多版本并存验证时，将不同版本二进制分别命名存放（如 /opt/meilisearch-1.55.0、/opt/meilisearch-1.54.0），启动时用不同 --http-addr 与 --db-path 隔离端口与数据。
十、卸载与清理
完整卸载按以下顺序执行（每条命令针对一个服务单元或一个路径），全部实测：
systemctl stop meilisearch
systemctl disable meilisearch
实测输出：
inactive
Removed /etc/systemd/system/multi-user.target.wants/meilisearch.service.
删除服务单元并重载：
rm -f /etc/systemd/system/meilisearch.service
systemctl daemon-reload
systemctl reset-failed
删除二进制与数据：
rm -f /usr/local/bin/meilisearch
rm -rf /var/lib/meilisearch
验证卸载结果：
which meilisearch || echo 'meilisearch command not found (uninstalled)'
systemctl status meilisearch 2>&1 | head -2
实测输出：
meilisearch command not found (uninstalled)
Unit meilisearch.service could not be found.
⚠️ 注意：
rm -rf /var/lib/meilisearch会永久删除全部索引数据，执行前确认已有 dump 备份。
十一、参考链接
- 官方下载与安装文档：https://www.meilisearch.com/docs/learn/self_hosted/getting_started_with_self_hosted_meilisearch
- GitHub 仓库：https://github.com/meilisearch/meilisearch
- Release 下载页：https://github.com/meilisearch/meilisearch/releases
- 官方安装脚本：https://install.meilisearch.com
- systemd 单元手册：https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html
- 相关文档：《MeiliSearch 1.55.0 配置参数详解》《MeiliSearch 1.55.0 快速入门与集成示例》