Getting Started

快速启动

从启动 OpenReach 到完成第一次 Search / Image Search / Read / Safe Curl 调用。服务启动后，根地址就是内置官网，无需额外部署前端。

Core Design

核心设计思路

OpenReach 不做“单一搜索引擎代理”，而是把 Agent 联网能力收敛成 Search / Image Search / Read / Safe Curl 四个稳定原语。上层 Agent 只依赖统一接口，底层 Provider 可以按地区、可用性和能力持续替换或扩展。

Agent / Skill统一调用四大原语

→

OpenReach API参数校验 · 安全边界

→

Route & Provider ChainCN / GLOBAL · 自动降级

→

Public Web搜索页 · 图片源 · HTML

统一原语Agent 不感知各搜索渠道差异，降低接入和迁移成本。

双路由 + Fallbackregion 先解析为 CN / GLOBAL，再执行对应 Provider Chain；单路失败自动切换。

免费优先默认链无需 Search API Key，不绑定商业搜索服务，适合自托管和 Agent 基础设施。

安全默认拒绝仅开放四个核心 POST API；Read/Curl 与图片下载统一执行 SSRF、重定向和响应体安全校验，Curl 额外禁止请求 OpenReach 自身。

Provider Channels

已对接渠道

当前 Provider 按能力和地区组合成多路免费链。provider=auto 时由 OpenReach 自动选择并降级；显式指定 Provider 时不会偷偷切换到其他渠道。

能力	CN 路由	GLOBAL 路由	默认策略
Web Search	`Bing CN` → `Baidu` → `Sogou` → `360` → `DuckDuckGo`	`Brave` → `DuckDuckGo` → `Bing Global`	逐路 fallback，结果 URL 去重并统一重排
Image Search	`Bing Images` → `Baidu Images` → `Sogou Images` → `Openverse`	`Bing Images` → `Openverse` → `Wikimedia Commons`	候选图片必须通过即时下载与真实图片字节校验
Web Read	`JsoupPageReader` + `SafeHttpFetcher` 本地读取链		读取公开 HTML / SSR 页面，不依赖第三方 Reader Key
Safe Curl	`CurlService` + `CurlTargetGuard` 安全公网请求链		只读 GET/HEAD；适合 GitHub API/raw 与公开 JSON/text，禁止私网和 OpenReach 自请求

路由说明：CN / zh-CN / china 等进入国内链；US / SG / JP / GLOBAL 等显式非 CN 地区进入 GLOBAL 链；auto 当前默认走 CN。Bing 会根据 Route 自动切换中国站与全球站。

BingBaiduSogou360 SearchDuckDuckGoBraveOpenverseWikimedia Commons

1. Docker 一键启动（推荐）

最快的体验方式。不需要 Clone 项目，也不依赖 Compose 文件；只要本机已安装 Docker，准备日志目录后复制下面命令即可启动：

sudo mkdir -p /data/openreach/data /data/openreach/logs
sudo chown -R 10001:10001 /data/openreach

docker run -d \
  --name openreach \
  --restart unless-stopped \
  -p 8080:8080 \
  -e OPENREACH_LOG_PATH=/app/logs \
  -v /data/openreach/data:/app/data \
  -v /data/openreach/logs:/app/logs \
  --log-driver json-file \
  --log-opt max-size=20m \
  --log-opt max-file=3 \
  codercl/openreach:latest

启动完成后直接访问：

官网：http://localhost:8080/
文档：http://localhost:8080/docs/
API Base URL：http://localhost:8080/api/web

# 查看容器
docker ps --filter name=openreach

# 查看控制台日志
docker logs -f openreach

# 查看持久化日志
tail -f ./logs/openreach-upstream.log

# 停止并删除
docker rm -f openreach

端口冲突？ 把 -p 8080:8080 改成例如 -p 18080:8080，然后访问 http://localhost:18080。

2. Docker Compose（可选）

如果你已经 Clone 了工程，或者希望用配置文件管理容器，可以继续使用项目内置 Compose：

docker compose up -d

docker compose ps
docker compose logs -f openreach

3. 源码启动

适合开发、调试和二次开发。要求 JDK 17+、Maven 3.9+。

mvn clean test
mvn spring-boot:run

OpenReach 默认监听 8080 端口。启动后 Spring Boot 会直接托管官网和文档静态资源。

4. 第一次调用

搜索网页

curl -X POST 'http://localhost:8080/api/web/search' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Spring Boot AI Agent",
    "limit": 5,
    "region": "auto",
    "provider": "auto",
    "timeRange": "any"
  }'

文搜图

curl -X POST 'http://localhost:8080/api/web/image-search' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "杭州西湖夜景",
    "limit": 8,
    "region": "auto",
    "provider": "auto"
  }'

读取网页

curl -X POST 'http://localhost:8080/api/web/read' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://spring.io/projects/spring-boot/",
    "maxChars": 20000
  }'

读取 GitHub API / raw 源码

curl -X POST 'http://localhost:8080/api/web/curl' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://raw.githubusercontent.com/changluya/openreach/main/README.md",
    "method": "GET",
    "maxChars": 100000
  }'

Safe Curl：只允许公网 HTTP(S) 80/443 的 GET/HEAD 文本请求；禁止 localhost/私网/Metadata、禁止敏感认证头，并强制禁止请求 OpenReach 自身及其本机网卡地址。若存在额外公网别名，通过 OPENREACH_CURL_BLOCKED_HOSTS 一并加入拒绝列表。

5. 使用 OpenReach Skill / Python CLI

项目根目录内置 skills/openreach/，官网也提供 ZIP 一键下载。CLI 只依赖 Python 标准库，不需要额外安装 requests。

export OPENREACH_BASE_URL=http://localhost:8080

python3 skills/openreach/scripts/openreach.py search "AI Agent" --region US --provider auto --time-range month --limit 5
python3 skills/openreach/scripts/openreach.py image-search "杭州西湖" --region auto --provider auto --limit 8
python3 skills/openreach/scripts/openreach.py read "https://spring.io/projects/spring-boot/" --max-chars 20000
python3 skills/openreach/scripts/openreach.py curl "https://raw.githubusercontent.com/changluya/openreach/main/README.md" --max-chars 100000

推荐 Agent 调用顺序：search(query) 发现可信来源 → 普通 HTML 页面使用 read(url)；GitHub REST API、raw 源码、公开 JSON/text API 使用 curl(url) → 再由模型总结、对比或引用。AgentHub/沙箱生成的私网附件 URL、图片二进制和非标准端口资源应由调用方自己的文件/图片能力处理，不应转交 OpenReach Read。

6. 当前边界

免费搜索 Provider 属于 best-effort，不承诺商业 SLA。
微信公众号仅支持公开可访问页面；搜索可发现性依赖搜索引擎是否已收录。
当前 Read 聚焦公网 HTML/XHTML/纯文本页面，只允许 HTTP/HTTPS 80/443；私网/本机/内部附件与图片二进制不属于 Read 能力边界。
强 JavaScript、登录、验证码、HTTP 403/412 等访问策略页面不保证可读；此类明确拒绝不应对同一 URL 机械重试，应换公开来源或退回搜索摘要。
v0.1.4 默认链无需 Search API Key；免费 SERP 不承诺商业级精确 Geo 或高 QPS SLA。

下载并初始化 OpenReach Skill

Agent 判断是否已经初始化时，只执行一次 check。它先检查 Skill 的 config.json；不存在则 0 次网络请求直接返回未初始化，并要求 Agent 向用户索要服务地址；存在则只做 1 次无副作用 API 探测。用户未提供地址前禁止猜测地址、扫描端口、自动创建配置或自行调用 init。

python3 scripts/openreach.py check

# 只有用户明确给出服务地址并要求初始化时才执行
python3 scripts/openreach.py init '<OPENREACH_BASE_URL>'

check 的唯一网络探测是 POST /api/web/search + 空 JSON，预期在本地参数校验阶段返回 400 / VALIDATION_ERROR，不会执行真实搜索或访问上游 Provider。check 成功后，本次任务直接使用 Search / Image Search / Read / Curl；doctor 只用于人工排障。

python3 scripts/openreach.py search "OpenReach AI Agent" \
  --region US \
  --provider auto \
  --time-range month \
  --limit 5

region：默认 auto，不传时等价于 auto 且默认走 CN。CN/zh-CN 等进入国内链，US/JP/SG/GLOBAL 等其他显式地区进入 GLOBAL 免费链；原始 region 继续作为 Provider locale Hint。

timeRange：Web Search 支持 any/day/week/month/year；指定后 auto 只选择真正实现时间过滤的 Provider。图片：image-search 只返回经过即时下载验证的 imageUrl。

Project & Community

项目与社区

OpenReach 是开源项目。源码、问题反馈和后续版本都以 GitHub 仓库为核心；如果你正在做 Provider 扩展、私有化部署或 Agent Search，也可以加入项目交流群。

GitHub 仓库

查看源码、提交 Issue、参与贡献或关注后续 Roadmap。

github.com/changluya/openreach ↗

OpenReach 微信交流群

扫码加入项目交流群，交流部署、搜索 Provider、Skill 和 Agent Search 使用实践。

点击二维码可放大查看；二维码如过期，以项目后续更新为准。

下一篇：官方接口文档 →