# Docker 一键部署 SearXNG 私有搜索引擎 (含故障排查)

## 背景

在隐私泄露和广告追踪泛滥的今天，使用一个不记录搜索历史、不追踪用户行为的私有搜索引擎变得尤为重要。SearXNG 是一个开源、免费、注重隐私的元搜索引擎，它聚合了来自多个搜索引擎的结果，同时保护用户隐私。本文将介绍如何在远程服务器上通过 Docker 快速部署 SearXNG。

## 环境信息

- **服务器**: Ubuntu/CentOS (Root 权限)

- **IP 地址**: 43.x.x.115

- **端口**: 8888 (已开放)

- **依赖**: Docker & Docker Compose

- **SSH 密钥**: `~/.ssh/id_rsa`

## 部署步骤

### 1. 目录规划

在服务器上创建专用目录：

```bash

mkdir -p /root/SearXNG

cd /root/SearXNG

```

### 2. 编写 Docker Compose 配置

创建 `docker-compose.yml`，包含 SearXNG 主程序和 Redis 缓存服务：

```yaml

version: '3.8'

services:

  searxng:

    image: searxng/searxng:latest

    container_name: searxng

    ports:

      - 8888:8080

    volumes:

      - ./settings.yml:/etc/searxng/settings.yml

    environment:

      - SEARXNG_BASE_URL=http://43.x.x.115:8888/

      - INSTANCE_NAME=SearXNG

    depends_on:

      - redis

    restart: unless-stopped

  redis:

    image: redis:alpine

    container_name: searxng-redis

    restart: unless-stopped

```

### 3. 编写 Settings 配置

创建 `settings.yml`，配置基本参数（中文界面、关闭限流）：

```yaml

use_default_settings: true

general:

  instance_name: SearXNG

  enable_metrics: true

search:

  safe_search: 0

  autocomplete: google

  default_lang: zh-CN

server:

  secret_key: searxng-secret-key-change-me

  limiter: false

  image_proxy: true

ui:

  default_theme: simple

```

### 4. 启动服务

执行以下命令启动容器：

```bash

docker compose up -d

```

## 故障排查 (Troubleshooting)

### 问题一：`Invalid settings.yml` 报错

**现象**: 容器启动失败，日志显示 `ValueError: Invalid settings.yml`。

**原因**: SearXNG 对配置文件结构有严格要求，旧版本格式可能不兼容。

**解决**: 使用 `use_default_settings: true` 继承默认配置，仅覆盖必要字段。简化后的配置如下：

```yaml

use_default_settings: true

general:

  instance_name: SearXNG

search:

  safe_search: 0

  default_lang: zh-CN

server:

  secret_key: your-secret-key

  limiter: false

```

### 问题二：API 返回 403 Forbidden

**现象**: 使用 `curl` 直接访问 `/search?q=test&format=json` 返回 403 错误。

**原因**: SearXNG 默认启用 bot 检测机制，非浏览器环境（缺少正常 User-Agent 或请求头）可能被拦截。此外，直接访问 API 接口可能需要特定的 Cookie 或 CSRF Token。

**验证**: 通过浏览器访问 `http://IP:8888` 可正常使用，说明服务运行正常。

**结论**: 生产环境建议通过 Nginx 反向代理并配置 HTTPS，或仅通过浏览器访问使用。

## 验证部署

1. 打开浏览器访问：`http://43.x.x.115:8888/`

2. 页面显示 "SearXNG" 且搜索框可用即为成功。

3. 尝试搜索关键词，确认能返回结果。

## 回滚方案

若需卸载或重新部署，执行以下命令清理环境：

```bash

cd /root/SearXNG

docker compose down -v

cd /

rm -rf /root/SearXNG

```

## 总结

通过 Docker 部署 SearXNG 非常便捷，主要挑战在于配置文件的格式兼容性和安全策略（如限流、Bot 检测）。生产环境建议配置 HTTPS 和反向代理以获得更好的体验。

---

**生成时间**: 2026-03-03

**作者**: Magic (via DirectorMaster)