导读：在日常开发与网络检索中，主流商业搜索引擎普遍存在广告竞价泛滥、行为指纹画像深度追踪、信息茧房严重以及跨引擎比对繁琐等痛点。此外，在搭建 AI Agent 或自动化知识检索管线时，商业搜索 API（如 SerpAPI、Google Custom Search）价格高昂且调用额度极受限制。
本文将带你使用 Docker 搭建开源纯净的 SearXNG 私有元搜索引擎，聚合 Google、Bing、DuckDuckGo、GitHub、Wikipedia 等数十个主流数据源，攻克 secret_key 启动死锁、settings.yml 精细化分流调优、JSON API 格式解禁与防上游 403 封禁四大核心问题，不仅打造属于你自己的无广告搜索神器，更能直接白嫖无限次的专属 AI 搜索 API！

🎯 核心目标与收益

完成本教程后，你将获得以下物理级提升：

  1. 绝对隐私与零追踪：不记录 IP、不写跟踪 Cookie、不生成搜索画像，向所有上游引擎发起匿名代理查询；
  2. 多源智能聚合比对：一条搜索词同时向 Google、Bing、GitHub、DuckDuckGo 发送并发查询，去重清洗并按权重综合呈现最优结果；
  3. 彻底消灭竞价广告：所有商业竞价广告、推广软文与跳转链接在后端清洗层直接被物理抹除；
  4. 免费 AI Agent 搜索 API：一键开启原生 JSON 接口，无缝接入各类开源 Agent（如 Hermes Agent、Dify、FastGPT、LangChain），告别按次计费的商业搜索 Key。

🖥️ 基础环境与全局变量定义

在开始配置前，先明确操作涉及的核心变量。请根据你的服务器域名和实际规划替换对应值：

BASH 
# ================= 全局参数定义 =================
DOMAIN="search.0000996.xyz"     # 访问 SearXNG 的专属公网域名
DATA_DIR="/opt/searxng"         # 持久化配置与数据根目录
PORT="8080"                     # SearXNG 容器绑定的本地回环端口
# ================================================

💻 第一步：目录规划与 Secret Key 生成（关键避坑）

SearXNG 依赖一个用于会话加密和 CSRF 防护的 secret_key。如果在启动前没有正确生成并填入 settings.yml，容器会在启动时输出以下错误并直接崩溃退出：

TEXT 
CRITICAL:searx.configuration: secret_key is not set in settings.yml
Error: Exiting due to missing secret_key configuration.

1. 创建规范目录结构

🖥️ 【服务器窗口】

BASH 
sudo mkdir -p /opt/searxng/searxng
cd /opt/searxng

2. 生成 32 位随机密钥并保存

🖥️ 【服务器窗口】

BASH 
# 生成高强度随机密钥
openssl rand -hex 32

(例如输出：9f8a3c2b1e4d5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b)

💻 第二步：精细化 settings.yml 调优（解禁 API + 优化体验）

SearXNG 的默认配置为了防御爬虫，默认禁用了 JSON 接口，且语言和自动补全并未针对中文环境深度调优。我们需要编写一份兼顾个人日常使用与 AI API 调用的生产级配置文件。

请在 /opt/searxng/searxng/settings.yml 中写入以下配置，记得将 secret_key 替换为你刚才生成的真实随机值：

🖥️ 【服务器窗口】

BASH 
sudo tee /opt/searxng/searxng/settings.yml << 'EOF'
# --- SearXNG 核心基础设置 ---
use_default_settings: true

general:
  debug: false
  instance_name: "Private Metasearch"
  donation_url: false
  contact_url: false
  privacypolicy_url: false
  enable_metrics: false

# --- Web 前端与主题配置 ---
ui:
  static_use_hash: true
  default_locale: "zh-CN"
  query_in_title: true
  infinite_scroll: true          # 开启无缝瀑布流翻页
  center_alignment: true         # 搜索框与结果居中排版 (极客美学)
  default_theme: "simple"
  theme_args:
    simple_style: "dark"         # 默认开启护眼暗黑极客主题
  search_on_category_select: true
  hotkeys: "vim"                 # 支持 Vim 快捷键导航 (j/k 翻选)

# --- 搜索行为与请求调优 ---
search:
  safe_search: 0                 # 0: 关闭安全过滤, 1: 中度, 2: 严格
  autocomplete: "google"         # 搜索词自动补全源 (支持 google, bing, duckduckgo)
  ban_time_on_fail: 5
  max_ban_time_on_fail: 120
  formats:
    - html
    - json                       # 核心：必须解禁 json 格式，否则 AI Agent 调用报 403

# --- 生产服务监听与安全密钥 ---
server:
  port: 8080
  bind_address: "0.0.0.0"
  secret_key: "9f8a3c2b1e4d5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b" # 替换为你自己的密钥
  base_url: "https://search.0000996.xyz/" # 你的实际公网反代根地址
  limiter: false                 # 私有实例建议关闭限流器，避免 AI Agent 频繁请求被关小黑屋
  image_proxy: true              # 开启图片代理，防止加载外部图片泄露本地真实 IP
  method: "POST"                 # 优先使用 POST 发送查询，增强私密性

# --- 常用主力引擎权重调优 ---
engines:
  - name: google
    engine: google
    shortcut: g
    weight: 2.0
    timeout: 3.0

  - name: bing
    engine: bing
    shortcut: b
    weight: 1.5
    timeout: 3.0

  - name: duckduckgo
    engine: duckduckgo
    shortcut: d
    weight: 1.2
    timeout: 3.0

  - name: github
    engine: github
    shortcut: gh
    weight: 1.0
    categories: it

  - name: wikidata
    engine: wikidata
    shortcut: w
    weight: 1.0
EOF

💻 第三步：Docker Compose 生产级编排

SearXNG 官方推荐搭配 Redis 作为热点搜索结果缓存与限流状态存储。通过组合容器，相同的搜索词在 24 小时内直接从本地缓存秒级返回，彻底杜绝上游引擎对服务器 IP 的速率限制。

1. 编写 docker-compose.yml

在 /opt/searxng/docker-compose.yml 中编排服务：

🖥️ 【服务器窗口】

BASH 
sudo tee /opt/searxng/docker-compose.yml << 'EOF'
version: '3.8'

services:
  # --- 本地高速缓存服务 (Redis) ---
  redis:
    image: redis:alpine
    container_name: searxng-redis
    restart: always
    command: redis-server --save "" --appendonly no  # 仅作为瞬态内存缓存，关闭持久化保护硬盘
    tmpfs:
      - /var/run/redis:rw,noexec,nosuid,size=64m
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "2"

  # --- SearXNG 主引擎容器 ---
  searxng:
    image: searxng/searxng:latest
    container_name: searxng
    restart: always
    depends_on:
      - redis
    ports:
      - "127.0.0.1:8080:8080"  # 仅绑定本地回环，安全交由反向代理转发
    volumes:
      - ./searxng:/etc/searxng:rw
    environment:
      - SEARXNG_BASE_URL=https://search.0000996.xyz/
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETGID
      - SETUID
    logging:
      driver: "json-file"
      options:
        max-size: "20m"
        max-file: "3"
EOF

2. 点火启动容器

🖥️ 【服务器窗口】

BASH 
cd /opt/searxng
sudo docker compose up -d

3. 现场核验容器状态

🖥️ 【服务器窗口】

BASH 
sudo docker compose ps

核验输出：searxng 与 searxng-redis 状态必须显示为 Up，且端口正常绑定。

💻 第四步：Nginx 反向代理与 HTTPS 加密

为了实现公网极速访问并隐藏内部端口，配置 Nginx / 1Panel 进行反向代理。注意传递必要的真实 Host 与 Scheme 标头。

1. Nginx 生产反代块配置

🖥️ 【服务器窗口】

NGINX 
server {
    listen 80;
    server_name search.0000996.xyz;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name search.0000996.xyz;

    # SSL 证书配置路径
    ssl_certificate     /etc/nginx/ssl/search.0000996.xyz.crt;
    ssl_certificate_key /etc/nginx/ssl/search.0000996.xyz.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    # 隐私防泄露：强制不缓存任何搜索请求结果
    proxy_buffering off;
    proxy_cache off;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 提高连接与读取超时，防止上游多源聚合慢响应导致 504 Gateway Timeout
        proxy_connect_timeout 15s;
        proxy_read_timeout 60s;
        proxy_send_timeout 60s;
    }
}

重新加载 Nginx：

BASH 
sudo nginx -t && sudo systemctl reload nginx

🌐 第五步：设为浏览器全平台默认搜索引擎

部署完成后，将属于你的私有搜索引擎无缝注入到日常主力浏览器中！

1. 获取 OpenSearch 快速集成

  • 使用 Chrome / Edge / Firefox 访问你的域名 https://search.0000996.xyz；
  • 现代浏览器会自动识别底部的 OpenSearch 规范；
  • 在浏览器地址栏输入任意字符并按下 Tab 键，即可直接触发 SearXNG 搜索。

2. 手动设定为默认搜索引擎

进入浏览器 「设置」 ➔ 「搜索引擎」 ➔ 「管理搜索引擎和网站搜索」：

  • 搜索引擎名称：SearXNG
  • 快捷字词：@s 或 s
  • URL 格式（以 %s 代替查询）：
    TEXT 
    https://search.0000996.xyz/search?q=%s
  • 点击右侧三点菜单，选择 「设为默认搜索引擎」。

🤖 第六步：实战进阶——作为 AI Agent 的专属无限次搜索 API

在构建企业或个人知识库、AI Agent（如 AutoGPT、LangChain、Hermes Agent 或 Dify）时，最头疼的就是调用商业搜索 API 极其昂贵。

因为我们在 settings.yml 中解禁了 json 格式，现在你的 SearXNG 已经是一个全功能、免鉴权、零成本的搜索 API！

1. 终端命令行物理验证 API

💻 【你自己的电脑】

BASH 
# 查询 "Linux BBR 加速" 并输出前 3 条结构化 JSON
curl -s "https://search.0000996.xyz/search?q=Linux+BBR+加速&format=json" | jq '.results[0:3][] | {title: .title, url: .url, content: .content}'

验证输出范例：

JSON 
{
  "title": "VPS 开启 BBR 网络加速指南",
  "url": "https://blog.0000996.xyz/archives/vps-bbr-guide/",
  "content": "详解 Linux 内核原生 BBR 拥塞控制算法部署，彻底解决海外节点网络丢包与吞吐低下..."
}

2. 在 Python / AI Agent 中直接调用

只需简单几行代码，你的 AI 即可实时联网检索最新资讯：

PYTHON 
import requests

def private_web_search(query: str, max_results: int = 5):
    url = "https://search.0000996.xyz/search"
    params = {
        "q": query,
        "format": "json",
        "language": "zh-CN"
    }
    resp = requests.get(url, params=params, timeout=10)
    data = resp.json()
    
    # 提取聚合后的结果
    return [
        {"title": item.get("title"), "link": item.get("url"), "snippet": item.get("content")}
        for item in data.get("results", [])[:max_results]
    ]

# 实测调用
results = private_web_search("最新开源 AI 智能体框架")
for r in results:
    print(f"[{r['title']}] -> {r['link']}")

🔍 验证测试：阶梯核实验收

1. Web 页面与多引擎聚合验证

打开 https://search.0000996.xyz，搜索关键词 Docker：

  • 查看结果右侧是否同时标注了 google、bing、duckduckgo 等来源标签；
  • 查看页面加载耗时，通常在缓存命中后保持在 200~500ms 极速响应。

2. 隐私阻断验证

按 F12 打开开发者工具网络面板（Network）：

  • 检查所有返回的静态图片链接，是否通过 /image_proxy?url=... 代理中转；
  • 确认没有向任何第三方追踪域名（如 Google Analytics、DoubleClick）发起过额外请求。

🚨 翻车急救站（常见避坑 FAQ）

Q1：为什么调用 JSON API 报 403 Forbidden？

  • 根因：settings.yml 中缺少 formats: - json，或者 limiter: true 触发了内部速率风控。
  • 排错方案：
    1. 检查 settings.yml 中的 search.formats 必须包含 json；
    2. 将 server.limiter 设为 false；
    3. 执行 sudo docker compose restart searxng 重启生效。

Q2：Google 或 Bing 引擎频繁报 Error: CAPTCHA required 或超时？

  • 根因：VPS 所在数据中心机房 IP 被 Google 识别为机房爬虫风控。
  • 自愈方案：
    1. 开启 Redis 缓存：大部分常见词命中本地缓存后不再触发上游风控；
    2. 降低特定引擎权重：在 settings.yml 中临时将 google 的 weight 调低，提升 duckduckgo 和 bing 的权重；
    3. 配置上游出站代理：在 compose 中为 searxng 挂载 ALL_PROXY=socks5://proxy_ip:port 走家宽或优质代理出口。

Q3：修改了 settings.yml，但重启容器配置不生效？

  • 避坑要点：检查宿主机与容器的挂载映射路径。宿主机的 ./searxng 对应容器内的 /etc/searxng。修改后必须执行 docker compose restart 重启进程读取新配置。

📋 毕业打钩自检清单

  • secret_key 已正确生成并写入 settings.yml，容器无闪退
  • Redis 缓存容器联动运行正常，docker compose ps 双容器均处于 Up 状态
  • settings.yml 成功解禁 formats: - json，允许 API 调用
  • 开启暗黑极客主题（simple_style: dark）与居中排版
  • Nginx 443 SSL 生产反代就位，关闭缓存确保隐私隔离
  • 浏览器地址栏成功集成 SearXNG 默认快捷检索
  • 终端 curl 验证 JSON 格式输出完整，AI Agent 搜索中枢搭建完毕