保姆级教程|Ubuntu 手动安装 Meilisearch,新手也能一次成功

大家好～今天给大家带来一篇实用教程，教大家在 Ubuntu 系统中手动安装 Meilisearch 搜索引擎。

Meilisearch 是一款轻量、高效、易部署的开源搜索引擎，支持中文分词、模糊搜索、实时索引，不管是个人项目还是小型团队，都能快速集成使用。

本文适配 Ubuntu 20.04/22.04 及以上版本，全程命令行操作，步骤清晰可复现，新手也能跟着一步步完成，建议收藏备用！

一、安装前准备（必做）

在开始安装前，先确认你的系统满足以下条件，避免后续踩坑：

系统版本：Ubuntu 20.04 LTS 及以上（64位，amd64/arm64 架构）

权限要求：拥有 sudo 权限（能执行系统级命令）

网络要求：可访问外网（用于下载安装文件）

依赖工具：curl、unzip（用于下载和解压，未安装需提前安装）

快速安装依赖工具

打开 Ubuntu 终端（快捷键 Ctrl+Alt+T），复制粘贴以下命令，一键更新并安装依赖：

sudo apt-get update && sudo apt-get upgrade -ysudo apt-get install curl unzip -y

💡 提示：命令中 -y 表示自动确认安装，无需手动按回车，等待执行完成即可。

二、手动下载 Meilisearch 二进制文件

Meilisearch 官方提供了 Linux 二进制文件，我们直接从官方渠道下载最新稳定版（当前最新稳定版为 v1.42.1，无需手动替换版本号，脚本会自动匹配）。

步骤1：确认系统架构（可选，新手可跳过）

执行以下命令，查看你的 Ubuntu 系统架构，确保下载对应版本：

uname -m

输出结果对应关系：

x86_64 → amd64 架构（大部分 PC/服务器）

aarch64 → arm64 架构（树莓派、ARM 服务器）

步骤2：一键下载二进制文件

推荐使用官方安装脚本，自动匹配系统架构，下载并赋予执行权限，无需手动解压，终端输入以下命令：

curl -L https://install.meilisearch.com | sh

⚠️ 注意：若手动下载，可访问，选择对应架构的压缩包，下载后用 unzip 解压即可。

三、配置 Meilisearch（全局可执行+数据目录）

下载完成后，需要简单配置，让系统任意目录都能执行 Meilisearch 命令，同时创建专门的数据目录，方便后续管理。

1. 配置全局可执行

将下载的二进制文件移动到系统全局路径，终端输入：

sudo mv meilisearch /usr/local/bin/

执行以下命令，验证是否配置成功：

meilisearch --version

若输出类似「meilisearch 1.42.1」的信息，说明全局配置成功；若提示“command not found”，检查移动路径是否正确即可。

2. 创建数据目录（推荐，避免数据混乱）

Meilisearch 默认将数据存在当前命令执行目录，建议创建专门的数据目录，终端输入：

创建数据目录（推荐路径）

sudo mkdir -p /var/lib/meilisearch

赋予当前用户读写权限，避免启动报错

sudo chown -R $USER /var/lib/meilisearch

💡 提示：$USER 会自动替换为当前登录用户，无需手动修改；若需指定其他用户，替换为具体用户名即可（如 ubuntu）。

四、启动 Meilisearch（两种方式，按需选择）

Meilisearch 支持两种启动方式，新手建议先测试启动，确认无误后再配置后台启动（生产环境推荐）。

方式1：临时启动（测试用）

适合测试是否安装成功，关闭终端后服务会停止，终端输入：

meilisearch --data-dir /var/lib/meilisearch --master-key="your_custom_master_key"

参数说明（必看）：

--data-dir：指定数据存储目录（就是我们刚才创建的目录）

--master-key：自定义管理员密钥（建议16位以上复杂字符串，用于访问管理API）

默认端口：7700（可通过 --http-addr 0.0.0.0:新端口修改，如 8080）

启动成功后，终端会输出类似以下信息，说明启动正常：

Meilisearch has started on http://0.0.0.0:7700Master key: your_custom_master_keyData directory: /var/lib/meilisearchEnvironment: development

方式2：后台启动（生产用，推荐）

配置为系统服务，随系统开机自启，后台稳定运行，步骤如下（复制粘贴即可）：

步骤1：创建系统服务配置文件

sudo nano /etc/systemd/system/meilisearch.service

步骤2：编写配置内容

打开 nano 编辑器后，粘贴以下内容，替换「your_username」和「your_custom_master_key」为实际信息：

[Unit]Description=Meilisearch ServiceAfter=network.target[Service]Type=simpleUser=your_username  替换为当前登录用户（如 ubuntu）ExecStart=/usr/local/bin/meilisearch --data-dir /var/lib/meilisearch --master-key="your_custom_master_key" --http-addr 0.0.0.0:7700Restart=on-failure  # 服务异常时自动重启[Install]WantedBy=multi-user.target

操作提示：粘贴完成后，按 Ctrl+O 保存，按 Ctrl+X 退出 nano 编辑器。

步骤3：启用并启动服务

重新加载系统配置

sudo systemctl daemon-reload

启用开机自启

sudo systemctl enable meilisearch

启动服务

sudo systemctl start meilisearch

步骤4：查看服务状态

执行以下命令，确认服务是否正常运行：

sudo systemctl status meilisearch

若输出包含「active (running)」，说明启动成功；若失败，执行「sudo journalctl -u meilisearch」查看错误日志，排查问题。

五、验证安装成功（关键一步）

启动 Meilisearch 后，通过以下两种方式验证，确保安装成功，避免后续无法使用。

方式1：本地终端验证（最稳妥）

在 Ubuntu 本地终端，输入以下命令，访问健康检查接口：

curl http://localhost:7700/health

若返回「{"status":"available"}」，说明 Meilisearch 运行正常。

方式2：网页访问验证（可选）

若 Ubuntu 有图形界面，或通过远程桌面访问，打开浏览器输入「http://localhost:7700」，会显示 Meilisearch 默认页面。

⚠️ 注意：若从其他电脑远程访问（如 http://192.168.1.100:7700），需先开放 7700 端口，终端输入：

sudo ufw allow 7700/tcpsudo ufw reload

提示：若访问时出现「URL拼写可能存在错误」，检查端口是否开放、服务是否启动，以及IP地址是否正确。

六、基础使用示例（快速上手）

安装成功后，教大家一个简单的测试方法，快速体验 Meilisearch 的搜索功能（替换「your_custom_master_key」为你设置的密钥）。

1. 创建索引并添加文档

curl -X POST 'http://localhost:7700/indexes/movies/documents' \-H 'Content-Type: application/json' \-H 'Authorization: Bearer your_custom_master_key' \--data-binary '[  {"id": 1, "title": "肖申克的救赎", "genres": ["剧情", "犯罪"]},  {"id": 2, "title": "霸王别姬", "genres": ["剧情", "爱情"]},  {"id": 3, "title": "阿甘正传", "genres": ["剧情", "励志"]}]'

2. 执行搜索

curl -X POST 'http://localhost:7700/indexes/movies/search' \-H 'Content-Type: application/json' \-H 'Authorization: Bearer your_custom_master_key' \--data-binary '{"q": "救赎"}'

执行后会返回包含「肖申克的救赎」的搜索结果，说明 Meilisearch 正常工作，而且它原生支持中文分词，无需额外配置！

七、常见问题排查（新手必看）

安装过程中遇到问题，不用慌，看看以下常见问题及解决方案，快速排查。

1. 启动失败，提示“Permission denied”

原因：数据目录权限不足，解决方案：

sudo chown -R $USER /var/lib/meilisearch

2. 端口被占用，提示“Address already in use”

原因：7700 端口被其他程序占用，解决方案：

临时启动：添加 --http-addr 0.0.0.0:新端口（如 8080）

后台启动：修改服务配置文件中的 ExecStart 一行，添加端口参数，重新加载配置并重启服务

3. 远程无法访问（提示URL错误）

原因：防火墙未开放端口，或 Meilisearch 仅监听本地地址，解决方案：

开放 7700 端口（参考本文第五部分）

启动命令中添加 --http-addr 0.0.0.0:7700（监听所有网卡地址）

八、卸载 Meilisearch（可选）

若后续不需要使用，执行以下命令，彻底卸载 Meilisearch：

停止并禁用服务

sudo systemctl stop meilisearchsudo systemctl disable meilisearch

删除服务配置文件

sudo rm /etc/systemd/system/meilisearch.service

删除二进制文件

sudo rm /usr/local/bin/meilisearch

删除数据目录（无需保留数据时执行）

sudo rm -rf /var/lib/meilisearch

最后总结

以上就是 Ubuntu 手动安装 Meilisearch 的完整流程，从依赖安装、下载配置，到启动验证、问题排查，全程保姆级指导。

Meilisearch 配置简单、性能优秀，支持中文分词，适合各类项目快速集成搜索功能，跟着步骤操作，新手也能一次成功～

如果觉得有用，欢迎点赞、收藏，转发给需要的朋友！