GooseForum 配置 Meilisearch 搜索教程：从 503 到正常搜索
GooseForum 的搜索依赖 Meilisearch。服务器上安装了 Meilisearch，并不代表论坛已经启用搜索：还需要在 GooseForum 中配置可访问的服务地址和认证密钥，重启进程，并建立主题索引。
这篇教程来自一次实际排查：搜索接口一直返回 503 search_unavailable，最终修正连接地址、重启论坛并重建索引后，搜索恢复正常。
一、先弄清论坛和 Meilisearch 运行在哪里
本次环境是：
- GooseForum 直接运行在宿主机，由 Supervisor 管理。
- Meilisearch 运行在 Docker 容器中。
- 容器的 7700 端口发布到宿主机的
127.0.0.1:7700。
- 同一台服务器还有另一个项目使用 Meilisearch。
本次遇到的两个问题是：最初 [meilisearch] 配置为空；补上参数后，又把地址填成了 Docker 容器名。
宿主机上的 GooseForum 通常无法解析 Docker 网络内部的容器名。 容器名作为服务地址，适用于能够通过同一个 Docker 网络进行名称解析的容器之间通信。
| GooseForum 运行位置 |
Meilisearch 地址选择 |
| 宿主机，Meilisearch 已将端口发布到本机 |
本次使用 http://127.0.0.1:7700 |
| 与 Meilisearch 位于同一 Docker 网络的容器 |
可使用实际可解析的服务名或容器网络别名，例如 http://meilisearch:7700 |
| 另一台服务器 |
使用那台服务器可访问的地址，并确认网络和访问控制 |
如果 GooseForum 本身也在容器内，127.0.0.1 指向的是它自己的容器，不能照抄本次宿主机地址。
二、确认 Meilisearch 服务正常
在宿主机查看容器及端口映射：
docker ps --format '{{.Names}} {{.Image}} {{.Ports}}'
本次 Meilisearch 的端口映射为：
127.0.0.1:7700->7700/tcp
检查健康状态：
curl -sS --max-time 10 http://127.0.0.1:7700/health
正常结果是：
{"status":"available"}
健康接口正常只说明服务可达，还需要确认论坛使用的密钥具有对应索引的查询、写入和设置权限。密钥应保存在私密配置中，不要贴进帖子或公开日志。
三、填写 GooseForum 配置
进入实际部署目录，备份 config.toml 后再修改：
cd /path/to/gooseforum
cp -p config.toml "config.toml.bak-$(date +%Y%m%d-%H%M%S)"
找到已有的 [meilisearch] 配置段，不要重复添加同名段：
[meilisearch]
url = "http://127.0.0.1:7700"
masterkey = "替换为实际有效的密钥"
上面的地址仅适用于前面描述的宿主机部署。masterkey 是 GooseForum 的配置字段名；当前源码会把该值作为 Meilisearch API Key 使用。若用受限 API Key，应确保它能操作论坛索引及完成索引设置，而不只是搜索。
本次生产服务已有主密钥，论坛配置中的密钥与服务端匹配。对于多项目部署，更建议给每个项目使用只允许访问自己索引的独立 API Key。
四、修改参数后重启 GooseForum
当前检查的 GooseForum 源码在进程启动时初始化 Meilisearch 客户端，所以只保存配置还不够，需要重启。
如果用 Supervisor 管理，先确认服务名：
supervisorctl status
本次 Discose 的服务名为 discose:discose_00：
supervisorctl restart discose:discose_00
supervisorctl status discose:discose_00
其他站点应替换为自己的服务名。使用 systemd 或 Docker 部署的站点，应通过对应的进程管理方式重启，并确认进程正常运行。
五、重建主题搜索索引
先确认不会与其他项目共用索引，再从实际部署目录运行：
./GooseForum rebuild-search-index
本次成功输出的关键部分是：
成功索引: 6 个主题
失败数量: 0 个主题
索引名称: topics
当前版本会配置搜索、过滤和排序字段，然后提交主题文档。Meilisearch 的索引任务是异步处理的，因此命令成功后，还应通过实际查询确认内容已经可搜索。
如果提示：
meilisearch 服务不可用，请检查配置或连接状态
说明尚未通过服务可用性检查，索引重建还没有开始。应先排查配置和连接，不要反复执行重建命令。
本次失败地址类似：
http://Docker容器名:7700
宿主机请求时出现名称解析失败。改成已发布到宿主机的 http://127.0.0.1:7700 后，健康检查和重建均恢复正常。
六、验证搜索真的恢复
选择一篇已发布且公开可见的主题中的关键词，通过网页搜索，也可以使用 Agent API：
curl -sS --max-time 10 -w '\nHTTP %{http_code}\n' \
--get 'https://你的论坛域名/api/agent/v1/search' \
--data-urlencode 'q=Agent' \
--data-urlencode 'limit=10'
示例针对公开内容，且需要站点启用了 Agent API。本次搜索 Agent 返回 HTTP 200，并找到已经发布的 Agent 接入指南。验证时既要看状态码，也要看结果是否包含预期主题。
只看到网页“没有结果”，不能排除服务异常：当前检查的网页实现可能把搜索不可用或查询错误表现为空结果，而 Agent 搜索接口会返回 503 search_unavailable。
七、多个项目共用 Meilisearch，会不会冲突？
可以共用服务，但必须检查索引名称和权限。
本次服务器最终有两个索引：
| 项目 |
索引 |
| 现有论坛搜索项目 |
bbs1_content |
| GooseForum / Discose |
topics |
两者名称不同。本次重建后，原来的 bbs1_content 索引仍然存在。
当前检查的 GooseForum 版本将索引名固定为 topics。 如果部署两个 GooseForum 站点，并且都连接同一 Meilisearch 实例，就可能共用这个索引，相同主题 ID 的文档可能互相覆盖，索引设置也会互相影响。仅更换 API Key 不能让同名索引变成两份独立数据。
这种情况需要修改索引命名实现，分别使用 site_a_topics、site_b_topics 等名称，或使用独立 Meilisearch 实例；当前版本不能通过 [meilisearch] 中添加一个未经支持的字段来改变索引名。
另外，当前源码中的旧索引迁移会尝试删除 articles 索引。如果同一服务上的其他项目还在使用该名称，应先检查和处理迁移逻辑，再进行可能触发迁移的启动或升级操作。
八、快速排查顺序
- 确认
[meilisearch].url 不是空字符串，配置保存在实际使用的文件中。
- 从 GooseForum 所在的运行环境请求
/health，确认地址能解析、端口能连接。
- 检查密钥和索引权限；健康检查成功不等于查询权限正常。
- 修改配置后重启论坛，确认进程运行正常。
- 核实共用服务的索引名称，避免与其他项目重名。
- 重建索引，再通过已知主题的关键词验证结果。
本次修复的核心是让 GooseForum 的运行环境能够访问配置中的 Meilisearch 地址。服务器装好了服务之后，把地址、认证、索引和进程重启这几步做完整，搜索才能真正可用。
本文记录于 2026-10-14；配置和源码行为以你部署的 GooseForum 版本为准。