CloudZun
Go back

SearxNG Complete User Manual - Your Local Search Engine

编辑此文章

SearxNG 完整使用手册

版本： 3.0-enhanced
发布日期： 2026-02-12
状态： ✅ 生产环境可用

📌 核心原则

从现在起，互联网搜索优先使用本地 SearxNG 工具，而不是依赖外部搜索引擎。

本手册将所有使用方法和技巧固化下来，确保团队能够高效、一致地使用 SearxNG。

🎯 快速开始（5分钟）

1. 验证服务状态

# 检查 Wrapper 是否运行
curl http://127.0.0.1:8765/health

# 预期响应
{"status": "ok", "version": "3.0-enhanced"}

2. 获取 API Key

cat /home/chengzh/searxng/integrations/integrations_api_key.txt
# 输出: eCsZLy8b384nYvT4T4ydkO66gBg2_LCI3L0Q_ZcOV30

3. 执行第一次搜索

API_KEY="eCsZLy8b384nYvT4T4ydkO66gBg2_LCI3L0Q_ZcOV30"

curl "http://127.0.0.1:8765/search?q=python&api_key=$API_KEY" | jq .

完成！ 你现在已经可以使用 SearxNG 了。

📚 完整 API 参考

基础搜索

最简单的搜索：

curl "http://127.0.0.1:8765/search?q=QUERY&api_key=KEY"

参数说明：

参数必填说明示例
q✅搜索关键词python
api_key✅API 密钥eCsZLy8b...
sort❌排序方式relevance / date / domain
domains❌只搜索指定域名github.com,stackoverflow.com
exclude_domains❌排除指定域名pinterest.com,facebook.com
languages❌语言过滤en,zh,ja
days❌时间范围（天）7
remove_duplicates❌去重true / false
remove_spam❌去垃圾true / false

🔧 功能详解

1️⃣ 排序功能 (Sorting)

三种排序方式：

相关性排序（默认）

curl "http://127.0.0.1:8765/search?q=python&sort=relevance&api_key=KEY"

日期排序

curl "http://127.0.0.1:8765/search?q=AI+news&sort=date&api_key=KEY"

域名排序

curl "http://127.0.0.1:8765/search?q=python&sort=domain&api_key=KEY"

2️⃣ 过滤功能 (Filtering)

域名过滤 - 只搜索指定网站

# 只搜索 GitHub 和 Stack Overflow
curl "http://127.0.0.1:8765/search?q=python+async&\
  domains=github.com,stackoverflow.com&api_key=KEY"

常用域名组合：

# 技术文档
domains=github.com,stackoverflow.com,python.org,nodejs.org

# 学术资源
domains=arxiv.org,scholar.google.com,researchgate.net

# 新闻资讯
domains=techcrunch.com,arstechnica.com,theverge.com

# 中文资源
domains=csdn.net,cnblogs.com,zhihu.com

排除域名 - 隐藏指定网站

# 排除社交媒体和垃圾网站
curl "http://127.0.0.1:8765/search?q=python&\
  exclude_domains=pinterest.com,facebook.com,instagram.com&api_key=KEY"

语言过滤

# 只显示中文结果
curl "http://127.0.0.1:8765/search?q=python&languages=zh&api_key=KEY"

# 显示英文和日文
curl "http://127.0.0.1:8765/search?q=machine+learning&\
  languages=en,ja&api_key=KEY"

支持的语言代码：

代码语言用途
enEnglish英文文档
zhChinese中文文档
jaJapanese日文文档
koKorean韩文文档
esSpanish西班牙文文档
frFrench法文文档
deGerman德文文档
ruRussian俄文文档

时间范围过滤

# 只显示最近 7 天的结果
curl "http://127.0.0.1:8765/search?q=AI+news&days=7&api_key=KEY"

# 只显示最近 30 天的结果
curl "http://127.0.0.1:8765/search?q=python+release&days=30&api_key=KEY"

去重和去垃圾

# 移除重复的 URL 和垃圾内容
curl "http://127.0.0.1:8765/search?q=test&\
  remove_duplicates=true&remove_spam=true&api_key=KEY"

🎯 高级用法 - 组合搜索

场景 1：查找高质量技术文档

curl "http://127.0.0.1:8765/search?q=python+async&\
  sort=relevance&\
  domains=github.com,stackoverflow.com,python.org&\
  languages=en&\
  remove_spam=true&\
  remove_duplicates=true&\
  api_key=KEY"

特点：

场景 2：查找最新新闻

curl "http://127.0.0.1:8765/search?q=AI+news&\
  sort=date&\
  days=7&\
  exclude_domains=pinterest.com,facebook.com&\
  remove_duplicates=true&\
  api_key=KEY"

特点：

场景 3：多语言学术搜索

curl "http://127.0.0.1:8765/search?q=machine+learning&\
  sort=relevance&\
  domains=arxiv.org,github.com&\
  languages=en,zh&\
  remove_spam=true&\
  api_key=KEY"

特点：

场景 4：排除垃圾，获得纯净结果

curl "http://127.0.0.1:8765/search?q=python&\
  exclude_domains=pinterest.com,facebook.com,instagram.com,quora.com&\
  remove_spam=true&\
  remove_duplicates=true&\
  api_key=KEY"

🛠️ 实用工具和脚本

快速搜索脚本

创建文件： /home/chengzh/bin/searxng-search.sh

#!/bin/bash

API_KEY="eCsZLy8b384nYvT4T4ydkO66gBg2_LCI3L0Q_ZcOV30"
QUERY="$1"
SORT="${2:-relevance}"
DOMAINS="${3:-}"

# 构建 URL
URL="http://127.0.0.1:8765/search?q=$(echo "$QUERY" | sed 's/ /+/g')&sort=$SORT&api_key=$API_KEY"

if [ -n "$DOMAINS" ]; then
  URL="$URL&domains=$DOMAINS"
fi

# 执行搜索
curl -s "$URL" | jq '.results[] | {title, url, domain, snippet}'

使用方法：

# 基本搜索
./searxng-search.sh "python async"

# 指定排序
./searxng-search.sh "python async" "date"

# 指定域名
./searxng-search.sh "python async" "relevance" "github.com,stackoverflow.com"

Python 集成脚本

#!/usr/bin/env python3

import requests
import json
import sys

class SearxNG:
    def __init__(self, api_key="eCsZLy8b384nYvT4T4ydkO66gBg2_LCI3L0Q_ZcOV30"):
        self.base_url = "http://127.0.0.1:8765/search"
        self.api_key = api_key
    
    def search(self, query, sort="relevance", domains=None, 
               exclude_domains=None, languages=None, days=None,
               remove_spam=True, remove_duplicates=True):
        """执行搜索"""
        params = {
            'q': query,
            'sort': sort,
            'api_key': self.api_key,
            'remove_spam': 'true' if remove_spam else 'false',
            'remove_duplicates': 'true' if remove_duplicates else 'false'
        }
        
        if domains:
            params['domains'] = domains
        if exclude_domains:
            params['exclude_domains'] = exclude_domains
        if languages:
            params['languages'] = languages
        if days:
            params['days'] = days
        
        response = requests.get(self.base_url, params=params)
        return response.json()
    
    def print_results(self, results, limit=10):
        """打印搜索结果"""
        for i, result in enumerate(results['results'][:limit], 1):
            print(f"\n{i}. {result['title']}")
            print(f"   URL: {result['url']}")
            print(f"   Domain: {result['domain']}")
            print(f"   Language: {result['language_name']}")
            print(f"   Snippet: {result['snippet'][:100]}...")

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: searxng.py <query> [sort] [domains] [languages]")
        sys.exit(1)
    
    query = sys.argv[1]
    sort = sys.argv[2] if len(sys.argv) > 2 else "relevance"
    domains = sys.argv[3] if len(sys.argv) > 3 else None
    languages = sys.argv[4] if len(sys.argv) > 4 else None
    
    searxng = SearxNG()
    results = searxng.search(query, sort=sort, domains=domains, languages=languages)
    searxng.print_results(results)

📊 JSON 响应格式

完整响应示例

{
  "query": "python",
  "results": [
    {
      "title": "Python Official Website",
      "url": "https://python.org",
      "domain": "python.org",
      "snippet": "The official Python website with documentation, downloads, and community resources.",
      "language": "en",
      "language_name": "English"
    }
  ],
  "number_of_results": 42,
  "timestamp": "2026-02-12T14:35:00.000000",
  "cached": false,
  "enhancements": {
    "sort_by": "relevance",
    "languages_filter": ["en"],
    "domains_filter": ["github.com"],
    "remove_spam": true,
    "remove_duplicates": true
  }
}

🎯 最佳实践

搜索策略三步法

第一步：确定搜索目标

第二步：选择语言

第三步：过滤垃圾

性能优化

缓存利用

查询优化

📋 快速参考卡

常用命令

# 基本搜索
curl "http://127.0.0.1:8765/search?q=QUERY&api_key=KEY"

# 技术文档搜索
curl "http://127.0.0.1:8765/search?q=QUERY&sort=relevance&domains=github.com,stackoverflow.com&api_key=KEY"

# 最新新闻搜索
curl "http://127.0.0.1:8765/search?q=QUERY&sort=date&days=7&api_key=KEY"

# 多语言搜索
curl "http://127.0.0.1:8765/search?q=QUERY&languages=en,zh&api_key=KEY"

# 高质量搜索
curl "http://127.0.0.1:8765/search?q=QUERY&remove_spam=true&remove_duplicates=true&api_key=KEY"

常用域名

# 技术
github.com,stackoverflow.com,python.org,nodejs.org

# 学术
arxiv.org,scholar.google.com,researchgate.net

# 新闻
techcrunch.com,arstechnica.com,theverge.com

# 中文
csdn.net,cnblogs.com,zhihu.com

常用排除列表

# 社交媒体
pinterest.com,facebook.com,instagram.com,tiktok.com

# 垃圾网站
quora.com,medium.com,linkedin.com

# 中文垃圾
sohu.com,sina.com.cn,qq.com

🔍 故障排查

问题 1：返回 401 Unauthorized

原因： API Key 错误或过期

解决：

# 检查 API Key
cat /home/chengzh/searxng/integrations/integrations_api_key.txt

# 确认 Key 正确后重试
curl "http://127.0.0.1:8765/search?q=test&api_key=YOUR_KEY"

问题 2：返回 502 Bad Gateway

原因： SearxNG 后端服务未运行

解决：

# 检查容器状态
docker ps | grep searxng

# 重启容器
docker compose -f /home/chengzh/searxng/docker-compose.yml restart searxng

# 检查日志
docker logs -f searxng

问题 3：结果为空

原因： 过度过滤或查询词过于具体

解决：

# 移除过滤条件，重新尝试
curl "http://127.0.0.1:8765/search?q=QUERY&api_key=KEY"

# 简化查询词
curl "http://127.0.0.1:8765/search?q=python&api_key=KEY"

🚀 下一步

立即可做

  1. ✅ 书签本手册
  2. ✅ 保存 API Key
  3. ✅ 测试基本搜索

本周计划

  1. 📌 集成到日常工作流
  2. 📌 创建团队搜索预设
  3. 📌 建立搜索习惯

本月计划

  1. 🎯 监控使用统计
  2. 🎯 收集反馈改进
  3. 🎯 优化搜索策略

📝 总结

SearxNG v3.0 已完全部署！

✅ 所有 15 个测试通过 (100% 成功率)
✅ 所有核心功能已实现
✅ 性能指标达到预期
✅ 向后兼容 v2.0
✅ 可用于生产环境

关键成就：

记住：从现在起，互联网搜索优先使用本地 SearxNG，而不是依赖外部搜索引擎。

这是你的搜索工具。用好它。

最后更新：2026-02-12

编辑此文章
Share this post on:
Share this post via WhatsApp Share this post on Facebook Share this post on X Share this post via Telegram Share this post on Pinterest Share this post via email

📚 相关文章推荐

Building a Self-Hosted SearxNG Search Engine with JSON API Wrapper
2月9日 • 2 个共同标签
SearxNG Deployment and Using the Local Wrapper
2月9日 • 2 个共同标签
Hugo博客标准部署手册
2月5日 • 2 个共同标签
OpenClaw Memory Embedding 系统修复实录：从 Ollama 到 Gemini 的完整踩坑指南
3月3日 • 1 个共同标签
M7 Stock Analysis Skill - Installation and Usage Guide
2月13日 • 1 个共同标签
OpenClaw与Discord集成完整指南
2月4日 • 1 个共同标签
Previous Post
Multi-Agent Orchestration: A Comprehensive Survey of Recent Advances
Next Post
SearxNG Wrapper v3.0: Advanced Sorting, Filtering, and Multilingual Support