SearXNG 官方推荐的容器化部署方式是 Compose 模板(docker-compose.yml + .env.example),核心配置统一放在 core-config/ 目录;本文还覆盖手动 instancing、持久化卷、环境变量、自定义证书以及从旧版 searxng-docker 项目迁移。

前置条件

  • 需要 Docker(推荐)或 Podman
  • Docker:把当前用户加入 docker 组并重新登录会话:
sudo usermod -aG docker $USER

镜像仓库

DockerHub 对未认证拉取有速率限制,受影响时改用 GHCR 镜像:

Compose 部署(推荐)

声明式部署,带合理默认值。

初始化

# 1. 创建环境与配置目录
mkdir -p ./searxng/core-config/
cd ./searxng/

# 2. 拉取最新 compose 模板
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

# 3. 复制并编辑 .env
cp -i .env.example .env
nano .env

# 4. 启动服务
docker compose up -d

# 5. 在 core-config/settings.yml 里配置各项设置

停止服务用 docker compose down。

日常管理命令

操作 命令
更新模板 docker compose down → 重新 curl 两个文件 → docker compose up -d
更新服务镜像 docker compose down → docker compose pull → docker compose up -d
查看服务列表 docker compose ps
查看日志 docker compose logs -f core
进容器 shell(排障) docker compose exec -it --user root core /bin/sh -l
停止并删除 docker compose down

注意:更新模板后要检查新模板对部署的影响,并同步更新 .env。

docker compose ps 典型输出:

NAME            IMAGE  ...  CREATED        STATUS        PORTS
searxng-core    ...    ...  3 minutes ago  Up 3 minutes  0.0.0.0:8080->8080/tcp
searxng-valkey  ...    ...  3 minutes ago  Up 3 minutes  6379/tcp

手动部署(高级用户)

仅用于自定义部署,官方推荐 Compose:

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。

管理命令:docker container list / docker container logs -f searxng / docker container exec -it --user root searxng /bin/sh -l(提示符变为 /usr/local/searxng #)/ docker container stop searxng 后 docker container rm searxng。

持久化卷

必须挂载两个卷:

卷 用途
/etc/searxng 配置文件(settings.yml 等)
/var/cache/searxng 持久化数据(faviconcache.db 等)

环境变量

  • $SEARXNG_* — 控制 SearXNG 配置项(对应 server:、general: 等设置,见 .env.example 模板)
  • $GRANIAN_* — 控制 Granian 服务器参数
  • $FORCE_OWNERSHIP — 确保挂载的卷/文件归 searxng:searxng 用户所有(默认:true)

自定义证书

  • 挂载 /usr/local/share/ca-certificates/ 目录来添加/移除证书
  • 容器(重新)启动时生效,或在容器内执行 update-ca-certificates
  • 要求容器以 root 权限运行

自定义镜像(非官方支持)

git clone https://github.com/searxng/searxng.git
cd ./searxng/
make container

从 searxng-docker 迁移

官方预期旧项目目录结构:

searxng-docker
├── searxng
│   ├── favicons.toml
│   ├── limiter.toml
│   ├── settings.yml
│   └── ...
├── .env
├── Caddyfile
├── docker-compose.yml
└── ...

迁移步骤:

  1. 在 searxng-docker 目录之外新建环境,按上方 Compose 部署流程初始化
  2. 新环境跑起来后,停掉服务,把旧配置从旧挂载点移到新目录:
mv ./searxng-docker/searxng/* ./searxng/core-config/
  1. 如果用到了 Valkey 特性(如 bot 防护 limiter),需要把 settings.yml 里的 URL hostname 改为 valkey 或 searxng-valkey
  2. 旧 .env 里如果有环境变量,记得同步到新 .env
  3. 如果实例要公网暴露,考虑配置反向代理
  4. 确认新环境一切正常后,删除旧 searxng-docker 目录

迁移完成后的目标结构:

.
├── searxng
│   ├── core-config
│   │   ├── favicons.toml
│   │   ├── limiter.toml
│   │   ├── settings.yml
│   │   └── ...
│   ├── .env.example
│   ├── .env
│   └── docker-compose.yml
└── searxng-docker
    └── ...

原文:https://docs.searxng.org/admin/installation-docker.html (SearXNG Documentation,版本 2026.8.1+8892414dc)