# SearXNG 自建搜索引擎搭建指南

> 用途：给 AI 助手提供**联网搜索**能力（后端 `web_search` 工具的后端服务）
> 环境：Docker 29.7.2 / SearXNG `2026.9.23-3cd69d30e` / Ubuntu（腾讯云 231）
> 验证状态：**已上线运行**，实测 14–17 条结果、零异常、约 1.5 秒

---

## 0. 这套东西解决什么问题

大模型自己**不能上网**。你问它"今天的天气"或"Flutter 最新版有什么变化"，它只能靠训练数据里的旧信息编——这叫做幻觉。

正确做法是给它一个**工具**：

```
你提问  →  LLM 判断"我需要联网查一下"
        →  它让后端调用 web_search("Flutter 3.47 新特性")
        →  后端去搜索引擎拿结果
        →  把结果喂回给 LLM
        →  LLM 基于真实结果回答
```

问题在于**中间那个搜索引擎从哪来**：

| 方案 | 问题 |
|---|---|
| Google / Bing 官方 API | 要钱、要申请 key、按次计费 |
| 直接爬搜索引擎页面 | 很快被封 IP，还要处理反爬 |
| **SearXNG（本方案）** | 开源自托管、免费、有现成的 JSON 接口 |

---

## 1. 先理解原理（不然后面调优会瞎猜）★

**这是全文最重要的一节。**

SearXNG 自己**不会搜索**，它是**元搜索引擎**（聚合器）：

```
                 ┌─→ Google      ─┐
你的查询 ─→ SearXNG ─→ DuckDuckGo  ─┼─→ 汇总 / 去重 / 排序 ─→ 返回
                 ├─→ Brave       ─┤
                 └─→ 百度        ─┘
```

**推论（记住这一条，能省你一小时）：**

> SearXNG 的可用性 = 它底下那些引擎在你服务器上**通不通**。

所以：
- 装在**国外**服务器上 → 默认配置开箱即用（Google/Bing 都通）
- 装在**国内**服务器上 → **默认配置返回 0 条结果**，因为默认开的全是墙外的

这不是 SearXNG 装坏了，是它的引擎连不上。第 4 节专门讲怎么解决。

---

## 2. 安装

### 2.1 前置

```bash
docker --version        # 需要 Docker
```

### 2.2 建配置目录

SearXNG 容器里以 **uid 977** 的用户运行，目录权限必须给对，否则它写不了配置：

```bash
mkdir -p /home/nzy/searxng
chown -R 977:977 /home/nzy/searxng
```

> 第一次启动时 SearXNG 会自动生成 `settings.yml`（含随机 secret_key）。预先把目录 chown 好，避免它因为没权限而静默失败。

### 2.3 启动容器

```bash
docker run -d --name searxng --restart unless-stopped \
  -p 127.0.0.1:8888:8080 \
  -v /home/nzy/searxng:/etc/searxng:rw \
  -e BASE_URL=http://127.0.0.1:8888/ \
  -e INSTANCE_NAME=qiangbao-search \
  searxng/searxng
```

逐项说明：

| 参数 | 作用 |
|---|---|
| `-p 127.0.0.1:8888:8080` | **只绑本机**。外面访问不到，降低攻击面和运维负担 |
| `-v .../searxng:/etc/searxng:rw` | 配置持久化，容器删了配置还在 |
| `--restart unless-stopped` | 开机自启 / 挂了自动拉起来 |
| `BASE_URL` | 影响 SearXNG 生成的链接，即使本机用也建议设对 |

### 2.4 为什么只绑 127.0.0.1

后端和 SearXNG 在**同一台机器**上，走 localhost 就够了。不对外暴露的好处：

- 不用管 `limiter`（防爬限流）—— 本项目就是关掉的
- 不用担心被当成公开实例滥用、被扫
- 不用配 HTTPS、不用备案

> 如果哪天你需要从别的机器访问它，**不要**直接把端口开到公网。至少加上 `limiter: true` + 反代 + 鉴权。

### 2.5 验证起来了

```bash
docker ps --filter name=searxng --format "  {{.Names}}  {{.Status}}  {{.Ports}}"
# 期望：searxng  Up xx seconds  127.0.0.1:8888->8080/tcp

ls -la /home/nzy/searxng/
# 期望：看到自动生成的 settings.yml
```

---

## 3. 两个必踩的坑 ★

### 坑一：JSON 接口默认是**关**的

**现象**：请求 `?format=json` 返回 **403**，而且报错信息完全看不出原因。

**原因**：SearXNG 官方镜像默认只开启 `html` 格式，JSON 需要显式打开。

**修法**：在 `settings.yml` 里加

```yaml
search:
  formats:
    - html
    - json          # ← 没有这行，你的程序永远拿不到数据
```

改完**必须重启**容器：

```bash
docker restart searxng
```

> 排查技巧：如果你看到 403 但浏览器打开首页是正常的，**先怀疑这一条**。

### 坑二：国内服务器上默认引擎**全军覆没**

**现象**：接口返回 200，但 `results` 是**空数组**。

**原因**：默认启用的通用引擎是 `google cse` / `duckduckgo` / `brave` / `wikipedia` / `wikidata` —— 在国内服务器上**全部连不上**。

**实测数据**（2026-09-24，腾讯云国内机器）：

```
结果数: 0
无响应引擎: [['brave','timeout'], ['duckduckgo','timeout'], ['google cse','timeout'],
            ['wikidata','timeout'], ['wikipedia','timeout']]
```

**更糟的是**：这些引擎不是立刻失败，而是**各等 3 秒超时**。所以你还会觉得"搜索怎么这么慢"。

**修法**：见下一节。

---

## 4. 引擎调优（国内服务器重点）

### 4.1 第一步：学会看诊断信息

SearXNG 的 JSON 返回里有个**关键字段** `unresponsive_engines`，它会告诉你哪些引擎挂了、为什么挂。这是排错的第一入口：

```bash
curl -s --get --data-urlencode "q=Flutter 状态管理" --data "format=json" \
  http://127.0.0.1:8888/search | python3 -c "
import json, sys
d = json.load(sys.stdin)
print('结果数:', len(d.get('results', [])))
print('异常引擎:', d.get('unresponsive_engines', []))
eng = {}
for r in d.get('results', []):
    eng[r.get('engine')] = eng.get(r.get('engine'), 0) + 1
print('各引擎贡献:', eng)
"
```

**三个指标都要看**：

| 指标 | 含义 |
|---|---|
| 结果数 | 0 就是没搜到，说明引擎全挂 |
| 异常引擎 | 谁挂了、挂的原因（timeout / CAPTCHA / crash） |
| 各引擎贡献 | 谁真的在干活。**贡献 0 的引擎可以直接关掉**，省它的等待时间 |

### 4.2 第二步：拿到引擎的**准确名字**

**这一步千万别跳过。** SearXNG 是按 `name` 覆盖配置的，**名字写错不会报错，只会静默失效**——你会以为改了，其实没生效。

```bash
# 看镜像里装了哪些引擎模块
docker exec searxng ls /usr/local/searxng/searx/engines/

# 用 /config 接口拿准确名字和当前启用状态（推荐）
curl -s http://127.0.0.1:8888/config | python3 -c "
import json, sys
keys = ['baidu', '360', 'quark', 'sogou', 'bing']
for e in json.load(sys.stdin).get('engines', []):
    if any(k in e['name'].lower() for k in keys):
        print(f\"{e['name']:<20} enabled={e['enabled']}\")
"
```

### 4.3 第三步：实测结论（本项目）

逐个开关测出来的结果：

| 引擎 | 分类 | 实测 | 处置 |
|---|---|---|---|
| **360search** | general | ✅ 可用 | **开启** |
| **quark**（夸克） | general | ✅ 可用 | **开启** |
| bing | general,web | ⚠️ 没报错但贡献 0 条 | 保留（无害） |
| baidu | general | ❌ `CAPTCHA`（被风控拦） | 关闭 |
| sogou | general | ❌ `unexpected crash` | 关闭 |
| google cse | general,web | ❌ `timeout` | 关闭 |
| duckduckgo | general | ❌ `timeout` | 关闭 |
| brave | general | ❌ `timeout` | 关闭 |
| wikipedia | general | ❌ `timeout` | 关闭 |
| wikidata | general | ❌ `timeout` | 关闭 |

> **注意**：这个结论**只对国内服务器成立**。如果你的服务器在香港/海外，Google 系反而应该开着。**别抄结论，抄方法**。

**为什么百度也不行？** 搜狗、百度这类国内引擎的反爬很激进，SearXNG 的对应实现经常被拦（返回验证码页）。所以"国内引擎"不等于"国内服务器上能用"——必须实测。

### 4.4 最终配置

`/home/nzy/searxng/settings.yml` 完整内容：

```yaml
# SearXNG —— 给强宝小助手用
#
# 关键一条：search.formats 必须包含 json。官方镜像默认只开 html，
# 不开的话 /search?format=json 直接返回 403，且报错信息看不出原因。
use_default_settings: true

server:
  secret_key: "<首次启动自动生成的随机串，保持原样别改>"
  image_proxy: true
  limiter: false          # 本机自用，限流会让 JSON 接口返回 429
  public_instance: false

search:
  formats:
    - html
    - json

# 引擎取舍：SearXNG 自己不会搜索，它只是聚合各家引擎。
# 这台机器在国内，google/duckduckgo/brave/wikipedia 全部连不上，
# 而且每个都要白等 3 秒超时 —— 必须关掉，否则搜索又慢又空。
engines:
  # 国内能通的
  - name: 360search
    disabled: false
  - name: quark
    disabled: false
  - name: bing
    disabled: false

  # 实测不行的：baidu 被 CAPTCHA 拦、sogou 报 unexpected crash
  - name: baidu
    disabled: true
  - name: sogou
    disabled: true

  # 实测 timeout 的（2026-09-24 测出来 5 个全挂）
  - name: google cse
    disabled: true
  - name: duckduckgo
    disabled: true
  - name: brave
    disabled: true
  - name: wikipedia
    disabled: true
  - name: wikidata
    disabled: true
```

**改完必做**：

```bash
chown 977:977 /home/nzy/searxng/settings.yml    # 权限别丢
docker restart searxng
sleep 7                                          # 给它点启动时间
docker logs searxng 2>&1 | grep -iE "error|invalid|unknown" | tail -5
```

> 日志里如果有 `can't register engine` 说明**引擎名写错了**，配置那行会静默失效——这就是 4.2 要你先拿准确名字的原因。

### 4.5 调优后的效果

```
查询「Flutter 状态管理」  → 12 条结果，1.5 秒，异常 []
查询「MySQL 主从复制 搭建」→ 14 条结果，异常 []
查询「深度求索 DeepSeek」  → 17 条结果，异常 []
各引擎贡献: {'360search': 6, 'quark': 8}
```

---

## 5. 验证清单

装完之后按顺序验三件事：

```bash
# ① 服务活着 + JSON 格式已开（这一步只验格式，不验引擎）
curl -s -o /dev/null -w "HTTP %{http_code}\n" \
  "http://127.0.0.1:8888/search?format=json&q=test"
# 200 = 格式开了；403 = 回去看 3.1

# ② 引擎真的能搜到东西
curl -s --get --data-urlencode "q=测试" --data "format=json" \
  http://127.0.0.1:8888/search | python3 -c "
import json,sys; d=json.load(sys.stdin)
print('结果数:', len(d.get('results',[])), '异常:', d.get('unresponsive_engines',[]))
"
# 结果数 >0 且 异常=[] 才算通

# ③ 中文查询也正常（很多引擎对中文支持差）
curl -s --get --data-urlencode "q=今天有什么新闻" --data "format=json" \
  http://127.0.0.1:8888/search | python3 -c "
import json,sys; print(len(json.load(sys.stdin).get('results',[])))
"
```

---

## 6. 接入后端（本项目）

### 6.1 配置

后端通过环境变量读地址（见 `application.yml` 的 `ai.search.base-url`）：

```bash
# /home/nzy/.env
SEARCH_BASE_URL=http://127.0.0.1:8888
```

`manage.sh` 会在启动 java 之前自动 source 这个文件。改完重启：

```bash
cd /home/nzy && ./manage.sh restart
# 确认变量真的进到进程里了
tr '\0' '\n' < /proc/$(cat app.pid)/environ | grep SEARCH_
```

**不配这个变量会怎样**：后端**不注册** `web_search` 工具——模型不知道自己能联网，也就不会瞎编"我查到了"。这是刻意的设计。

### 6.2 后端怎么用它

```
LLM 决定联网
   ↓ tool_calls: web_search({"query": "..."})
SearxngApiClient.search(query, maxResults=5)
   ↓ GET {SEARCH_BASE_URL}/search?format=json&q=<urlencoded>
取前 5 条 → 拼成 JSON（title/url/snippet）→ 回填给模型
   ↓
模型基于真实结果回答，并标注来源
```

代码在 `src/main/java/com/accounting/service/SearxngApiClient.java`。

### 6.3 ⚠️ 一个安全提醒

**脱敏层保护的是「发给 LLM 的内容」，不包含搜索词。**

搜索词会原样发给 360search / 夸克（以及它们的上游）。所以：

- ✅ 「帮我查一下 Flutter 3.47 有什么新特性」
- ❌ 「帮我查一下 155.103.159.109 这台机器」

第二句会把你的服务器 IP 送到第三方搜索引擎。**别在联网搜索里带敏感信息。**

---

## 7. 日常维护与排错

### 7.1 常用命令

```bash
docker logs searxng 2>&1 | tail -30        # 看日志
docker restart searxng                     # 改配置后重启
docker stats searxng --no-stream           # 资源占用
```

### 7.2 排错对照表

| 现象 | 原因 | 处置 |
|---|---|---|
| `?format=json` 返回 **403** | `search.formats` 没加 json | 见 3.1 |
| 返回 200 但**结果数为 0** | 引擎全连不上 | 见 3.2 / 4.3 |
| 结果里有 **`CAPTCHA`** | 该引擎被风控拦 | 关掉它 |
| 结果里有 **`unexpected crash`** | 该引擎实现有 bug | 关掉它 |
| 结果里有 **`timeout`** | 网络不通 | 关掉它（别留着白等） |
| 返回 **429** | `limiter` 开着 | 设 `limiter: false` 并重启 |
| 日志报 `can't register engine` | **引擎名写错** | 用 `/config` 拿准确名字（4.2） |
| 容器反复重启 | 配置目录权限不对 | `chown -R 977:977 /home/nzy/searxng` |
| 本机 curl 不通 | 端口没发布 / 绑错地址 | 检查 `-p 127.0.0.1:8888:8080` |
| 搜索很慢（3 秒以上） | 有引擎在等超时 | 用 `unresponsive_engines` 找出并关掉 |

### 7.3 升级 SearXNG

```bash
docker pull searxng/searxng
docker stop searxng && docker rm searxng
# 重新执行 2.3 的 docker run（配置在挂载目录里，不会丢）
```

> 升级后**重新跑一遍第 5 节的验证**——新版本可能改了默认引擎列表。

---

## 8. 附录

### 8.1 命令速查

```bash
# 启动
docker start searxng

# 看哪些引擎启用中
curl -s http://127.0.0.1:8888/config | python3 -c "
import json,sys
for e in json.load(sys.stdin)['engines']:
    if e['enabled']: print(e['name'], '|', ','.join(e.get('categories',[])))
"

# 完整搜索测试（三个指标一起看）
curl -s --get --data-urlencode "q=关键词" --data "format=json" \
  http://127.0.0.1:8888/search | python3 -c "
import json,sys; d=json.load(sys.stdin)
print('结果数:', len(d.get('results',[])))
print('异常引擎:', d.get('unresponsive_engines',[]))
eng={}
for r in d.get('results',[]): eng[r['engine']]=eng.get(r['engine'],0)+1
print('各引擎贡献:', eng)
"

# 浏览器里直接用（图形界面，方便手工试）
# 把 8888 端口临时转发出来，或直接在服务器上用 lynx/curl 看 html
```

### 8.2 本项目的部署信息

| 项 | 值 |
|---|---|
| 服务器 | 腾讯云 231（国内） |
| 容器名 | `searxng` |
| 监听 | `127.0.0.1:8888`（不对外） |
| 配置目录 | `/home/nzy/searxng/` |
| 版本 | SearXNG `2026.9.23-3cd69d30e` |
| 后端配置项 | `SEARCH_BASE_URL`（在 `/home/nzy/.env`） |
| 可用引擎 | 360search、quark（bing 保留） |
| 停用方式 | `docker stop searxng`（后端会自动不给模型 web_search 工具） |

### 8.3 一句话总结

> **SearXNG 装起来只要三行命令，难的是「它在你的服务器上能不能真的搜到东西」——而那 100% 取决于底层引擎的网络可达性。先测、再配，别抄别人的引擎清单。**

---

*文档创建：2026-09-24 · 所有数据均为在本项目服务器上实测*