whoogle-search RESTful API 完全指南：从基础到高级应用

whoogle-search RESTful API 完全指南：从基础到高级应用

【免费下载链接】whoogle-search A self-hosted, ad-free, privacy-respecting metasearch engine 项目地址: https://gitcode.com/GitHub_Trending/wh/whoogle-search

引言：隐私搜索的 API 解决方案

你是否在寻找一个既能保护隐私又能灵活集成到现有系统的搜索引擎 API？作为一款自托管、无广告、尊重隐私的元搜索引擎，whoogle-search 不仅提供了网页界面，更通过 RESTful API 接口赋能开发者构建自定义搜索体验。本文将系统讲解 whoogle-search API 的所有端点用法，提供 15+ 实战示例，以及企业级部署最佳实践，帮助你在 30 分钟内实现隐私搜索功能集成。

读完本文你将掌握：

• 7 个核心 API 端点的参数与响应格式
• 基本认证与参数加密的实现方案
• 10 种常见错误的诊断与修复方法
• 分布式部署的负载均衡策略
• 生产环境监控与性能优化技巧

技术架构概览

whoogle-search API 基于 Flask 框架构建，采用分层架构设计，核心处理流程如下：

核心技术栈：

• 后端框架：Flask 2.0+
• 加密算法：Fernet (AES-128-CBC)
• 数据格式：JSON/HTML/表单数据
• 认证方式：HTTP Basic Auth
• 部署选项：Docker/Kubernetes/裸金属

快速开始

环境准备

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/wh/whoogle-search
cd whoogle-search

# 配置环境变量（可选认证）
export WHOOGLE_USER="admin"
export WHOOGLE_PASS="secure_password"

# 启动服务
docker-compose up -d

服务默认运行在 http://localhost:5000，健康检查端点：

curl -I http://localhost:5000/healthz
# 预期响应：HTTP/1.1 200 OK

API 测试工具

推荐使用 Postman 或 curl 进行 API 测试：

# 安装 httpie（可选）
pip install httpie

# 基本搜索测试
http GET "http://localhost:5000/search?q=example"

API 参考手册

端点总览

端点路径	HTTP 方法	功能描述	认证要求	响应格式
/search	GET/POST	执行搜索查询	可选	HTML/重定向
/autocomplete	GET/POST	获取搜索建议	可选	JSON
/config	GET/PUT	管理用户配置	必需	JSON/HTML
/healthz	GET	服务健康检查	否	文本
/element	GET	获取加密资源	必需	二进制流
/window	GET	匿名浏览页面	必需	HTML
/opensearch.xml	GET	获取搜索引擎配置	否	XML

搜索端点（/search）

功能描述

执行搜索查询并返回处理后的结果页面，支持网页、图片、新闻等多种搜索类型。

请求参数

参数名	类型	描述	示例值
q	字符串	搜索关键词（必填）	人工智能 最新进展
tbm	字符串	搜索类型	isch（图片）、nws（新闻）
lang_search	字符串	搜索语言	zh-CN、en-US
country	字符串	搜索地区	cn、us
tbs	字符串	时间范围	qdr:d（过去 24 小时）
safe	布尔值	安全搜索	1（开启）、0（关闭）

搜索类型（tbm）枚举值

{
  "web": "",
  "images": "isch",
  "news": "nws",
  "videos": "vid",
  "maps": "map",
  "shopping": "shop",
  "books": "bks",
  "scholar": "scholar"
}

请求示例

基础文本搜索：

curl -G "http://localhost:5000/search" \
  --data-urlencode "q=whoogle-search 用法" \
  --data-urlencode "lang_search=zh-CN" \
  --data-urlencode "country=cn"

图片搜索：

curl -G "http://localhost:5000/search" \
  --data-urlencode "q=风景摄影" \
  --data-urlencode "tbm=isch"

响应处理

• 成功：返回 HTML 页面（200 OK）
• 重定向：303 See Other（"I'm Feeling Lucky" 功能）
• 错误：503 Service Unavailable（验证码或限流）

自动补全端点（/autocomplete）

功能描述

提供实时搜索建议，支持搜索词补全和热门推荐。

请求参数

参数名	类型	描述	示例值
q	字符串	部分搜索词（必填）	whoog

请求示例

curl "http://localhost:5000/autocomplete?q=whoog"

响应示例

[
  "whoog",
  [
    "whoogle search",
    "whoogle github",
    "whoogle 自托管",
    "whoogle 替代",
    "whoogle 使用教程"
  ]
]

配置端点（/config）

功能描述

管理用户偏好设置，支持获取和更新配置。

认证要求

必须启用基本认证（设置 WHOOGLE_USER 和 WHOOGLE_PASS）

请求示例（获取配置）

curl -u admin:secure_password "http://localhost:5000/config"

响应示例

{
  "lang_search": "en",
  "lang_interface": "lang_en",
  "country": "us",
  "theme": "system",
  "alts": false,
  "new_tab": true,
  "view_image": true,
  "block": "",
  "safe": false,
  "nojs": false,
  "anon_view": true,
  "preferences_encrypted": false,
  "tbs": ""
}

更新配置（PUT）

curl -u admin:secure_password -X PUT "http://localhost:5000/config" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "theme=dark" \
  -d "safe=1" \
  -d "lang_search=zh-CN"

高级功能

参数加密

敏感参数（如搜索词）可通过 Fernet 加密传输：

from cryptography.fernet import Fernet

# 生成密钥（服务端需使用相同密钥）
key = Fernet.generate_key()
cipher_suite = Fernet(key)

# 加密查询词
query = "敏感搜索词"
encrypted_q = cipher_suite.encrypt(query.encode()).decode()

# API 请求
curl "http://localhost:5000/search?q=${encrypted_q}"

认证实现

所有受保护端点需要在请求头中包含认证信息：

# 生成 Basic Auth 凭证
echo -n "admin:secure_password" | base64
# 输出：YWRtaW46c2VjdXJlX3Bhc3N3b3Jk

# 带认证请求
curl -H "Authorization: Basic YWRtaW46c2VjdXJlX3Bhc3N3b3Jk" \
  "http://localhost:5000/config"

批量搜索接口

通过组合搜索端点和配置端点，实现批量查询：

import requests
from requests.auth import HTTPBasicAuth

config = {
    "lang_search": "fr",
    "country": "fr",
    "safe": True
}

# 更新配置
response = requests.put(
    "http://localhost:5000/config",
    auth=HTTPBasicAuth("admin", "secure_password"),
    data=config
)

# 执行批量搜索
queries = ["paris weather", "lyon events", "marseille news"]
results = []

for q in queries:
    search_response = requests.get(
        "http://localhost:5000/search",
        params={"q": q, "tbm": "nws"}
    )
    results.append({
        "query": q,
        "status": search_response.status_code,
        "content_length": len(search_response.text)
    })

print(json.dumps(results, indent=2))

错误处理与调试

常见错误码

状态码	含义	可能原因	解决方案
401	未授权	凭据错误或缺失	检查用户名密码
403	禁止访问	IP 被阻止	检查服务器防火墙
404	未找到	端点路径错误	验证 URL 拼写
500	服务器错误	代码异常	查看应用日志
503	服务不可用	验证码或限流	启用 Tor 或更换 IP

调试技巧

1. 启用详细日志：

export WHOOGLE_LOG_LEVEL="DEBUG"

2. 查看实时日志：

docker-compose logs -f whoogle-search

3. 验证码处理： 当遇到 503 错误时，可配置自动切换代理：

export WHOOGLE_FALLBACK_ENGINE_URL="https://farside.link/google/search?q="

部署与扩展

负载均衡

多实例部署架构：

Nginx 配置示例：

upstream whoogle {
    server 127.0.0.1:5000;
    server 127.0.0.1:5001;
    server 127.0.0.1:5002;
}

server {
    listen 80;
    server_name search.example.com;

    location / {
        proxy_pass http://whoogle;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

性能优化

1. 启用缓存：

export WHOOGLE_CACHE=true
export CACHE_TTL=3600  # 缓存 1 小时

2. 资源压缩：

export WHOOGLE_COMPRESS=true

3. 连接池配置：

# app/__init__.py 中调整
app.config['MAX_CONTENT_LENGTH'] = 16 * 1024 * 1024  # 16MB
app.config['JSON_SORT_KEYS'] = False

安全最佳实践

1. 启用 HTTPS：

export HTTPS_ONLY=true
export SSL_CERT_PATH=/path/to/cert.pem
export SSL_KEY_PATH=/path/to/key.pem

2. 配置内容安全策略：

export WHOOGLE_CSP="default-src 'self'; img-src 'self' data:;"

3. 定期轮换密钥：

# 生成新密钥
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

# 更新环境变量
export WHOOGLE_ENC_KEY="新密钥"

监控与维护

健康检查

集成 Prometheus 监控：

# 启用 metrics 端点
export WHOOGLE_METRICS=true

# metrics 地址
curl http://localhost:5000/metrics

关键指标：

• whoogle_search_requests_total: 总搜索请求数
• whoogle_config_updates_total: 配置更新次数
• whoogle_response_time_seconds: 平均响应时间
• whoogle_errors_total: 错误总数

备份策略

配置数据定期备份：

# 创建备份脚本 backup.sh
#!/bin/bash
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/var/backups/whoogle"
mkdir -p $BACKUP_DIR

# 备份用户配置
docker cp whoogle-search:/app/config $BACKUP_DIR/config_$TIMESTAMP

# 保留最近 30 天备份
find $BACKUP_DIR -type f -mtime +30 -delete

添加到 crontab：

0 2 * * * /path/to/backup.sh  # 每天凌晨 2 点执行

总结与展望

whoogle-search API 为构建隐私保护的搜索解决方案提供了灵活的接口，核心优势包括：

• 完全自托管，数据主权掌控
• 丰富的配置选项，适应不同场景
• 轻量级架构，易于部署和扩展
• 活跃的社区支持和持续开发

未来版本可能新增的功能：

• GraphQL 接口支持
• 高级搜索过滤器 API
• WebSocket 实时通知
• 多语言语音搜索

通过本文介绍的 API 使用方法和最佳实践，你可以快速集成 whoogle-search 到自己的应用中，为用户提供安全、私密的搜索体验。如需进一步帮助，可查阅官方文档或提交 Issue 反馈。

附录：配置参数参考

完整配置参数列表：

参数名	类型	默认值	描述
lang_search	字符串	""	搜索语言代码
lang_interface	字符串	"lang_en"	界面语言
country	字符串	""	搜索地区代码
theme	字符串	"system"	主题（light/dark/system）
safe	布尔值	false	安全搜索模式
dark	布尔值	false	暗色主题（已废弃）
alts	布尔值	false	显示替代结果
nojs	布尔值	false	禁用 JavaScript
tor	布尔值	false	通过 Tor 路由请求
near	字符串	""	地理位置 proximity 搜索
new_tab	布尔值	false	新标签页打开结果
view_image	布尔值	false	启用查看图片功能
get_only	布尔值	false	仅接受 GET 请求
anon_view	布尔值	false	启用匿名查看模式
preferences_encrypted	布尔值	false	加密偏好设置

【免费下载链接】whoogle-search A self-hosted, ad-free, privacy-respecting metasearch engine 项目地址: https://gitcode.com/GitHub_Trending/wh/whoogle-search