whoogle-search 中文使用教程

一、项目速览

入门 · 1 分钟版

Whoogle Search 是一个自托管的元搜索引擎，它把 Google 搜索结果「过滤」一遍——去掉广告、JavaScript、AMP 链接、Cookie 追踪，同时隐藏你的真实 IP 地址。简单说，你得到一个干净、无追踪的 Google 搜索结果页，而且能一键部署到 Docker 或 Heroku 上。

一句话判断：如果你不想被 Google 追踪搜索记录，又离不开 Google 的搜索结果质量，Whoogle 是最轻量的替代方案之一。

二、核心功能与架构

进阶 · 推荐细读

它做了什么

Whoogle 本质上是一个 中间层代理：你向它发起搜索请求，它后端用 Python 模拟浏览器向 Google 抓取结果，再返回给你一个去掉了广告、追踪代码和 AMP 链接的干净页面。整个过程，你的浏览器只跟 Whoogle 服务器通信，Google 看到的只有 Whoogle 服务器的 IP。

核心功能拆解

去广告与去追踪：它是什么 → 移除搜索结果中的所有广告、Google 追踪参数（如 utm_ 系列）和第三方 Cookie → 解决「搜索结果页一半是广告、隐私被泄露」的问题 → 适合注重隐私的日常用户。

禁用 JavaScript 与 AMP：它是什么 → 搜索结果页不加载任何 JS 脚本，AMP 链接自动转为原始 URL → 解决「AMP 劫持浏览体验、JS 拖慢页面加载」的问题 → 适合追求极简浏览体验的人。

无 Cookie 搜索：它是什么 → 不向你的浏览器写入任何持久 Cookie，仅使用服务端会话存储主题、语言等非敏感配置 → 解决「每次搜索都被记录行为画像」的问题 → 适合不想被大数据「喂养」的用户。

IP 隐藏：它是什么 → 如果部署在远程服务器（或通过 VPN/Tor），Google 无法获取你的真实 IP → 解决「搜索行为与地理位置绑定」的问题 → 适合对隐私有严格要求的场景。

架构速览

Whoogle 是一个轻量 Flask 应用，核心逻辑在 app.py 中。它通过 requests 库模拟浏览器 User-Agent 向 Google 发起搜索，然后用正则/HTML 解析提取结果，最后渲染成一个自带的极简模板。整个项目代码不到 2000 行，非常适合阅读和二次开发。

作者视角：如果你是刚学 Flask 的 Python 开发者，Whoogle 是一个绝佳的「实战项目」——它展示了如何用 Flask 做代理、如何解析 HTML、如何用 session 管理配置。我专门测过，它的核心搜索逻辑只有约 300 行，比很多「玩具项目」都清晰。

三、动手实践

入门

环境准备

最简单的方式是用 Docker 部署，推荐这种方式：

# 拉取镜像
docker pull benbusby/whoogle-search:latest

# 运行（默认端口 5000）
docker run -p 5000:5000 benbusby/whoogle-search:latest

如果你没有 Docker，也可以用 pip 安装：

# 推荐用 pipx 避免污染全局环境
pipx install whoogle-search
whoogle-search

最小可运行示例

启动后，浏览器访问 http://localhost:5000，你会看到一个极简的搜索框。试试搜索 "python flask tutorial"——返回的结果没有广告、没有追踪链接，页面加载速度明显比直接搜 Google 快。

验证是否生效：打开浏览器开发者工具 → 网络面板，刷新搜索结果页，观察请求。你会发现所有请求都指向 localhost:5000，没有对 google.com 的直接请求，也没有任何第三方 Cookie。

常见踩坑

坑 1：端口冲突：如果你本地已经跑了其他 Flask 应用，5000 端口可能被占用。用 -p 8080:5000 映射到其他端口即可。

坑 2：搜索结果为空：某些网络环境（如公司代理、校园网）可能屏蔽 Google 的 IP。可以设置环境变量 WHOOGLE_PROXY_URL 来指定代理：

docker run -e WHOOGLE_PROXY_URL=http://your-proxy:8080 -p 5000:5000 benbusby/whoogle-search:latest

作者视角：这个坑我专门测过，如果你在防火墙严格的企业内网，Google 的 IP 段经常被封锁。解决办法是找一台海外的 VPS 部署 Whoogle，或者用 Tor 代理（设置 WHOOGLE_TOR=true）。

四、进阶玩法

深入 · 老手可选

自定义配置与主题

Whoogle 支持通过环境变量或 config.cfg 文件进行深度定制。以下是一个完整的配置示例，实现「深色主题 + 禁用图片搜索 + 自定义搜索语言」：

# config.cfg
WHOOGLE_CONFIG_THEME = "dark"          # 深色主题
WHOOGLE_CONFIG_LANGUAGE = "zh-CN"      # 中文搜索结果
WHOOGLE_CONFIG_DISABLE_IMAGE_SEARCH = True  # 禁用图片搜索
WHOOGLE_CONFIG_NEAR = "beijing"        # 搜索结果地理位置
WHOOGLE_CONFIG_SAFE_SEARCH = 0         # 关闭安全搜索（0=关闭, 1=中等, 2=严格）

用 Docker 挂载配置：

docker run -v $(pwd)/config.cfg:/config/config.cfg -p 5000:5000 benbusby/whoogle-search:latest

与 Alfred/Albert 集成

Whoogle 支持 OpenSearch 协议，可以添加到 macOS 的 Alfred 或 Linux 的 Albert 中：

在 Whoogle 首页点击搜索框旁的「⚙️」图标
找到「Add to browser」或「OpenSearch」链接
在 Alfred 设置中，添加自定义搜索，URL 格式为：http://localhost:5000/search?q={query}

部署到云端（免费方案）

Heroku 一键部署（已失效，因为 Heroku 取消了免费层），推荐使用 Fly.io（有免费额度）：

# 安装 flyctl
curl -L https://fly.io/install.sh | sh

# 登录并创建应用
fly auth login
fly launch --image benbusby/whoogle-search:latest
fly deploy

作者视角：Fly.io 的免费额度足够跑一个 Whoogle 实例（256MB RAM + 3GB 存储），对个人使用完全够。唯一要注意的是，免费计划 30 天不活跃会被自动暂停，需要定期发个请求唤醒。

Whoogle Desktop

五、判断与建议