SearXNG：自托管元搜索引擎（隐私优先、聚合多源）｜部署与使用全指南

本文基于 SearXNG 官方仓库（GitHub）与官方文档（docs.searxng.org）在 2026-10-26 的真实状态撰写。仓库最近一次提交为 54ca1d9（2026-10-25），文档版本标识 2026.10.25+54ca1d9cf，项目处于活跃维护状态。

一、项目简介与适用场景

SearXNG 是一个免费、开源的互联网元搜索引擎（Metasearch Engine）：它本身不建立自己的网页索引，而是把你的一次查询并发转发给多家上游搜索引擎与数据库（官方默认启用 81 个、共支持 261 个引擎），再把结果聚合、去重、排序后一并返回。

它的核心承诺是：不追踪用户、不为用户画像。SearXNG 在把请求发往上游引擎前，会剥离 Cookie、生成随机浏览器指纹；在结果页返回给用户前，会隐藏来源页与查询词。它也不需要 JavaScript 与 Cookie 即可正常工作（无 JS 的纯 HTML 界面是一等公民），并且可以运行在 Tor 之上以获得在线匿名性。

项目起源：SearXNG 于 2021 年中从经典的 searx 项目 fork 而来，并持续现代化。截至 2026 年，仓库累计 9,800+ 次提交、36,000+ Stars，过去 12 个月约 778 次提交、12/12 个月均有活跃提交，属活跃维护项目。

一句话定位：隐私友好、可自托管的元搜索引擎，聚合多家搜索结果且不追踪用户，适合自建私有搜索。

适用场景

二、核心功能逐条拆解

三、全套官方链接

关于在线 Demo：上表列出的 https://searx.be 为官方文档与社区公认、长期可用的公开实例之一，可直接访问体验搜索效果。公开实例由第三方运营，是否记录日志由运营者决定——对隐私敏感的日常使用仍建议自建私有实例。

四、硬件与环境前置要求

注意版本差异：源码方式默认 settings.yml 的 server.port 是 8888；而官方 Docker 容器内部监听 8080（由 Granian 提供）。两者不要混淆，改端口时分别对照处理（见第七章）。

五、多平台部署实战

5.1 Docker / Compose 部署（推荐，最省心）

官方提供 docker-compose.yml 与 .env.example 模板，包含 core（SearXNG 本体）与 valkey（限流数据库）两个服务。

第一步：准备目录并拉取模板

# 创建工作目录与配置目录
mkdir -p ./searxng/core-config/
cd ./searxng/

# 获取最新 compose 模板与 .env 模板
curl -fsSL \
    -O https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
    -O https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example

第二步：配置环境变量

cp -i .env.example .env
nano .env      # 按需修改，例如 SEARXNG_PORT、SEARXNG_BASE_URL、SEARXNG_SECRET 等

常用 .env 变量（均以 SEARXNG_ 前缀，覆盖 settings.yml 同名项）：

第三步：启动

docker compose up -d     # 后台启动
docker compose ps        # 查看状态，可见 searxng-core:0.0.0.0:8080->8080/tcp
docker compose logs -f core   # 跟踪日志

启动后访问 http://<服务器IP>:8080（若改了 SEARXNG_PORT 则用对应端口）。

第四步：个性化配置

编辑 ./searxng/core-config/settings.yml（容器挂载路径 /etc/searxng/settings.yml），按第六章说明修改。修改后重启：

docker compose down && docker compose up -d

手动 docker run（单容器，不含 valkey）

mkdir -p ./searxng/config/ ./searxng/data/
cd ./searxng/

docker run --name searxng -d \
    -p 8888:8080 \
    -v "./config/:/etc/searxng/" \
    -v "./data/:/var/cache/searxng/" \
    docker.io/searxng/searxng:latest

访问 http://localhost:8888。两个应挂载的卷：/etc/searxng（配置）、/var/cache/searxng（favicon 等缓存）。

DockerHub 若触发匿名拉取限流，可改用 GHCR 镜像：ghcr.io/searxng/searxng:latest。

5.2 源码部署（pip / venv，适合需要深度定制的场景）

以下为 Debian/Ubuntu 系命令（官方 step-by-step 精简版）。

第一步：安装系统依赖

sudo -H apt-get install -y \
    python3-dev python3-babel python3-venv python-is-python3 \
    uwsgi uwsgi-plugin-python3 \
    git build-essential libxslt-dev zlib1g-dev libffi-dev libssl-dev

第二步：创建专用系统用户

sudo -H useradd --shell /bin/bash --system \
    --home-dir "/usr/local/searxng" \
    --comment 'Privacy-respecting metasearch engine' \
    searxng

sudo -H mkdir "/usr/local/searxng"
sudo -H chown -R "searxng:searxng" "/usr/local/searxng"

第三步：克隆并建虚拟环境

sudo -H -u searxng -i
(searxng)$ git clone "https://github.com/searxng/searxng" \
                   "/usr/local/searxng/searxng-src"
(searxng)$ python3 -m venv "/usr/local/searxng/searx-pyenv"
(searxng)$ echo ". /usr/local/searxng/searx-pyenv/bin/activate" \
                   >>  "/usr/local/searxng/.profile"

第四步：安装依赖与本体

sudo -H -u searxng -i
(searxng)$ pip install -U pip setuptools wheel
(searxng)$ pip install -U pyyaml msgspec typing-extensions pybind11
(searxng)$ cd "/usr/local/searxng/searxng-src"
(searxng)$ pip install --use-pep517 --no-build-isolation -e .

第五步：生成初始配置

sudo -H mkdir -p "/etc/searxng"
sudo -H cp "/usr/local/searxng/searxng-src/utils/templates/etc/searxng/settings.yml" \
             "/etc/searxng/settings.yml"
sudo -H chown -R searxng:searxng /etc/searxng

第六步：本地验证

sudo -H -u searxng -i
(searxng)$ cd /usr/local/searxng/searxng-src
(searxng)$ export SEARXNG_SETTINGS_PATH="/etc/searxng/settings.yml"
(searxng)$ python -m searx.webapp

浏览器访问 http://127.0.0.1:8888；容器内/脚本中可用 curl http://127.0.0.1:8888 验证。CTRL-C 停止。

5.3 安装脚本（一键，适合快速上手）

官方提供 DevOps 工具箱 utils/searxng.sh，可一键安装系统服务与 nginx 站点：

git clone https://github.com/searxng/searxng.git
cd searxng
sudo -H ./utils/searxng.sh install webapp   # 安装 SearXNG
sudo -H ./utils/searxng.sh install uwsgi    # 安装 uWSGI 服务
sudo -H ./utils/searxng.sh install nginx    # 安装 nginx 站点

六、配置文件参数全解（settings.yml）

SearXNG 配置位于 /etc/searxng/settings.yml（源码）/ 容器挂载的 /etc/searxng/settings.yml（Docker）。可用 use_default_settings: true 继承内置默认值，仅覆盖需要修改的段。下面逐段解释核心参数。

6.1 general:（常规）

6.2 search:（搜索）

6.3 server:（服务器）

6.4 engines:（引擎）

engines: 为引擎列表，每项形如：

  - name: google
    engine: google
    disabled: false
    timeout: 3.0
    weight: 1.0
    # shortcut: go   # !go 语法

默认启用约 81 个引擎；要关闭某引擎，将其 disabled 设为 true 即可。

6.5 valkey: / redis:（限流数据库）

启用 server.limiter: true 时必须提供可用的 Valkey/Redis，否则 limiter 无法工作并报错。

6.6 ui: / preferences: / plugins:（界面与插件）

• ui: 控制界面主题、默认分类标签等。

• preferences: 控制用户偏好默认值。

• plugins: 列出启用的插件（- name: ...），内置插件包括 OA Status、Hostname replace 等，也可加载外部插件。

完整参数见官方 Settings 文档：https://docs.searxng.org/admin/settings/index.html

七、启动 / 后台常驻 / 开机自启 / 改端口

7.1 Docker 方式

docker compose up -d            # 启动（已含 restart: always，进程退出会自动重启）
docker compose down             # 停止并移除
docker compose ps               # 查看运行状态
docker compose logs -f core     # 跟踪日志
docker compose exec -it --user root core /bin/sh -l   # 进入容器排错

Compose 模板中 restart: always，进程挂掉会被 Docker 自动拉起（相当于后台常驻）。

7.2 源码方式：systemd 开机自启（uwsgi）

官方 step-by-step 采用 uWSGI。典型 systemd 单元（/etc/systemd/system/searxng.service）：

[Unit]
Description=SearXNG -- Privacy-respecting metasearch engine
After=network.target

[Service]
Type=simple
User=searxng
Group=searxng
WorkingDirectory=/usr/local/searxng/searxng-src
Environment=SEARXNG_SETTINGS_PATH=/etc/searxng/settings.yml
ExecStart=/usr/local/searxng/searx-pyenv/bin/python -m searx.webapp
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

启用并开机自启：

sudo systemctl daemon-reload
sudo systemctl enable --now searxng
sudo systemctl status searxng
sudo journalctl -u searxng -f   # 查看日志

提示：官方更推荐用 utils/searxng.sh install uwsgi 生成标准 uWSGI + systemd 配置；上例为最简 python -m searx.webapp 常驻方案，便于理解。

7.3 改端口

Docker（推荐改 .env 或映射）

• 改对外映射端口：在 docker-compose.yml 的 ports 或 .env 的 SEARXNG_PORT 调整，例如 SEARXNG_PORT=9000 → 访问 http://IP:9000。

• 单容器 docker run 改 -p 9000:8080（宿主机 9000 → 容器 8080）。

源码方式

直接改 settings.yml 的 server.port 与 server.bind_address，然后重启服务：

server:
  port: 9000
  bind_address: "0.0.0.0"   # 如需对外暴露（建议仍走反向代理）

若经 nginx 反向代理，实例通常仍 bind 127.0.0.1，由 nginx 监听 80/443 并转发，端口对用户透明。

八、功能实操教程

8.1 首次访问与基础搜索

启动后浏览器打开 http://<IP>:<端口>（公开 Demo 见 https://searx.be ）。首页即搜索框，直接输入关键词回车即可看到来自多个引擎的聚合结果。公开实例的推荐部署架构（反向代理 + uWSGI + 多 SearXNG 实例 + Valkey）如下图所示。

8.2 配置默认搜索引擎 / 引擎偏好

点击右上角 Preferences（偏好） 进入设置页：

• Default categories（默认分类）：勾选默认启用的分类标签（general、images、videos…）。

• Engines（引擎）：逐项勾选/取消要参与搜索的引擎；可设默认语言、安全搜索级别。

• SafeSearch：0/1/2 对应无/中/严。

• Method：GET/POST。

• Autocomplete：选择补全后端或关闭。

• 保存后写入浏览器本地存储（本地保存，不依赖服务端 Cookie）。

8.3 启用 / 禁用引擎（服务端级）

要服务端全局增删引擎，编辑 settings.yml 的 engines: 列表，对目标项设 disabled: true，或整体移除某项；也可在 use_default_settings: true 基础上用 engines: 覆盖。修改后重启实例。示例关闭某引擎：

use_default_settings: true
engines:
  - name: google
    disabled: true

8.4 隐私设置

• server.image_proxy: true：结果图片经实例中转，上游拿不到用户 IP（公开实例建议开启）。

• search.safe_search：按需提高过滤等级。

• server.method: POST：查询不进浏览器历史。

• 反向代理层关闭访问日志（nginx 中 access_log /dev/null;），进一步减少留存。

• 启用 limiter（配合 Valkey）抵御自动化滥用。

8.5 反向代理与 HTTPS（以 nginx 为例）

官方提供 utils/searxng.sh install nginx 一键生成站点；手动则在 /etc/nginx/sites-available/searxng.conf 写：

location /searxng {
    uwsgi_pass unix:///usr/local/searxng/run/socket;
    include uwsgi_params;
    uwsgi_param HTTP_HOST            $host;
    uwsgi_param HTTP_X_FORWARDED_PROTO $scheme;   # 关键：告知 SearXNG 实际协议(https)
    uwsgi_param HTTP_X_SCRIPT_NAME   /searxng;
    uwsgi_param HTTP_X_REAL_IP       $remote_addr;
    uwsgi_param HTTP_X_FORWARDED_FOR $proxy_add_x_forwarded_for;
}

启用站点并重启：

sudo ln -s /etc/nginx/sites-available/searxng.conf /etc/nginx/sites-enabled/searxng.conf
sudo systemctl restart nginx

务必：在 settings.yml 设 server.base_url: "https://search.example.com"（或对应路径），并正确传递 X-Forwarded-Proto / X-Real-IP，否则会出现跳转错误、样式丢失或 limiter IP 判定错误。HTTPS 证书用 Let's Encrypt（certbot）签发。

8.6 公开实例 vs 私有实例

公开实例务必开启 limiter + Valkey，并配置 base_url、关闭不必要的访问日志；同时在页脚提供隐私政策（general.privacypolicy_url）。

九、全套报错故障排查

以下为高频问题。多数日志可通过 docker compose logs -f core（Docker）或 journalctl -u searxng -f（源码 systemd）查看。

十、升级 / 回滚 / 卸载

10.1 升级

Docker Compose（滚动更新）

docker compose down
docker compose pull          # 拉取新镜像
docker compose up -d
# 升级后建议比对模板变化：
docker compose down
curl -fsSLO \
  https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
  https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example
docker compose up -d

官方建议定期阅读 Migrate and stay tuned（升级指南）：https://docs.searxng.org/admin/update-searxng.html ，关注配置项变更。

源码方式

sudo -H -u searxng -i
(searxng)$ cd /usr/local/searxng/searxng-src
(searxng)$ git pull
(searxng)$ pip install --use-pep517 --no-build-isolation -e .
(searxng)$ exit
sudo systemctl restart searxng

10.2 回滚

• Docker：固定镜像版本标签而非 latest（如 searxng/searxng:2026.10.17-xxxx），回滚时改回旧标签 docker compose up -d；或 docker image ls 找到旧镜像重新运行。

• 源码：git pull 前先 git log --oneline -5 记录当前 commit；回滚用 git checkout <旧commit> 后重装。注意配置兼容性，必要时比对 settings.yml 模板差异。

10.3 卸载

Docker

docker compose down          # 停止并移除容器（保留 core-config/data 卷）
docker compose down --volumes   # 连同数据卷一并删除
docker image rm searxng/searxng:latest   # 清理镜像

源码

sudo systemctl disable --now searxng
sudo userdel -r searxng       # 删除系统用户及其家目录
sudo rm -rf /etc/searxng /usr/local/searxng

十一、商用许可与合规风险提示

11.1 AGPL-3.0 的“传染性/网络条款”

SearXNG 以 GNU Affero General Public License v3.0（AGPL-3.0） 发布。AGPL 是强 Copyleft 许可证，关键条款：

• 网络使用即分发（Network clause）：若你修改了 SearXNG，并让用户通过网络与之交互（即部署为在线服务），你必须向用户提供你修改后的完整对应源代码，且同样以 AGPL 提供。

• 这意味着：把修改后的 SearXNG 作为托管/SaaS 服务对外提供时，不能把改动闭源——必须公开改动。

• 单纯原样部署、不作代码修改、仅改配置（settings.yml），通常不构成“修改版”，但服务本身仍受 AGPL 约束，需保留许可证与版权声明、提供源码获取途径（官方镜像/仓库链接即可满足）。

• 合规建议：自建私有/内部使用最稳妥；若对外提供修改版，准备源码托管与下载入口；避免在未开源改动的情况下以“自有闭源搜索服务”商业化分发代码本身。

11.2 公开实例的合规与防滥用

运营公开实例（任何人可访问）时，除许可证外还需注意：

1. 隐私政策：在 general.privacypolicy_url 提供清晰隐私政策，说明是否记录日志、记录什么、保留多久。

2. 防滥用：务必开启 limiter + Valkey，防止被用作自动化查询跳板；配置 IP 黑白名单（limiter.toml 的 block_ip / pass_ip）。

3. 上游服务条款：SearXNG 把查询转发给 Google、Bing、DuckDuckGo 等上游。高频/大规模转发可能触发上游反爬或违反其服务条款，进而导致封禁。应控制请求频率、合理设置引擎与超时、必要时用代理/Tor 分散出口。

4. 法律与内容责任：运营者需对实例可被查询到的内容承担相应司法辖区责任；建议 safe_search 适度开启、image_proxy 开启以隐藏用户 IP，并保留必要的访问限制（如基础鉴权或仅限受信任网络）。

5. 资源与可用性：公开实例会被匿名流量消耗带宽与上游配额，建议配置资源限制与监控（如 uptime 监控），避免被拖垮。

小结：SearXNG 适合自建私有搜索与内部工具；对外提供修改版须遵守 AGPL 源码公开义务；运营公开实例须做好隐私声明、防滥用与上游合规。

本文档仅作技术部署参考，不构成法律意见。许可证与合规请以官方 LICENSE 文件及当地法律为准。