xixu-me/xread

0 Fork 0

Files

T

xixu-me e9dd414266 fix(docs): format repository links in README files

2026-03-31 07:11:11 +08:00

5.8 KiB

Raw Blame History

Xread

English

你的 LLM 值得更好的输入。

将杂乱网页转成干净的 Markdown，为 LLM 提供网页搜索能力，并将整套服务自行托管。

Xread 是一个面向 LLM 工作流的开源、自托管网页摄取服务，提供三个主要入口：

crawl：抓取 URL 并转换为可读的 Markdown
search：执行搜索并返回便于直接粘贴进提示词的文本结果
serp：执行搜索并返回结构化 JSON

它是公开 Jina AI Reader 存储库 jina-ai/reader 的一个独立分叉版本，移除了原始内部 thinapps-shared 依赖，并适配为自托管使用。

该存储库额外增加了什么

围绕上游 Reader 存储库完成自托管封装
本地优先的存储与缓存持久化
发布到 GHCR 的 OCI 镜像
面向 Docker、Podman 和 nerdctl 的统一镜像、Compose 栈与环境变量部署资产
已接好的 CI、CodeQL、依赖治理与容器发布流程

快速预览

下面这些示例直接使用已发布镜像的 HTTP/1 端口（8081）。部署文档会进一步说明 Compose 后端 loopback 端口（3001、3101、3201）以及公网反向代理域名入口。

抓取网页

curl "http://127.0.0.1:8081/http://example.com"

以文本形式搜索网页

curl "http://127.0.0.1:8081/search?q=example%20domain&num=5&provider=google"

以 JSON 形式搜索网页

curl "http://127.0.0.1:8081/?q=example%20domain&num=5&provider=google"

快速开始

本地运行

npm ci
npm run build
npm start

上面会启动 crawl 服务。独立入口包括：

build/stand-alone/crawl.js
build/stand-alone/search.js
build/stand-alone/serp.js

使用容器引擎运行

docker run --rm -p 8081:8081 ghcr.io/xixu-me/xread:latest

已发布镜像默认启动 crawl。任何兼容 OCI 的容器引擎都可以运行它。下面示例使用 Docker 语法；如果要运行其他入口：

docker run --rm -p 8081:8081 --entrypoint node ghcr.io/xixu-me/xread:latest build/stand-alone/search.js
docker run --rm -p 8081:8081 --entrypoint node ghcr.io/xixu-me/xread:latest build/stand-alone/serp.js

为自托管而构建

镜像内已包含用于页面渲染的 Chrome
内部支持 HTTP/2 cleartext（h2c）
在 PORT + 1 上提供 HTTP/1 回退端口
即使没有付费搜索提供方，search 和 serp 也仍可通过独立回退路径工作

已发布镜像：

ghcr.io/xixu-me/xread:latest

用于生产环境时，建议固定镜像 digest，而不是持续跟随 latest。

部署

存储库内已经提供完整的反向代理部署示例：

部署文档在 Docker、Podman 和 nerdctl/containerd 下使用同一镜像、同一 Compose 栈和同一套环境变量。

文档中使用的部署拓扑是：

r.your-domain.example -> crawl
s.your-domain.example/search -> search
s.your-domain.example/?q=... -> serp

配置

standalone 构建通过环境变量读取配置。

deploy/.env.example 中的部署模板包含了共享部署变量。完整的运行时配置面如下：

变量	用途
`PORT`	主服务端口。HTTP/1 回退端口监听在 `PORT + 1`。
`PUBLIC_HTTP_PORT`	Compose 部署中由反向代理暴露的公网 HTTP 端口。
`PUBLIC_HTTPS_PORT`	Compose 部署中由反向代理暴露的公网 HTTPS 端口。
`XREAD_LOOPBACK_HOST`	Compose 部署中后端 loopback 端口所绑定的宿主机 IP。
`XREAD_CRAWL_LOOPBACK_PORT`	`crawl` 后端对应的宿主机 loopback 端口。
`XREAD_SEARCH_LOOPBACK_PORT`	`search` 后端对应的宿主机 loopback 端口。
`XREAD_SERP_LOOPBACK_PORT`	`serp` 后端对应的宿主机 loopback 端口。
`STORAGE_ROOT`	快照和生成资产等存储内容的根目录。
`LOCAL_DB_ROOT`	本地元数据、缓存和轻量持久化的根目录。
`SERPER_SEARCH_API_KEY`	启用基于 Serper 的 Google/Bing 搜索。
`BRAVE_SEARCH_API_KEY`	在支持的场景下启用 Brave Search 集成。
`CLOUD_FLARE_API_KEY`	在已配置能力下启用 Cloudflare 相关集成。
`LOCAL_PROXY_URLS`	可选的出站代理池。
`OVERRIDE_CHROME_EXECUTABLE_PATH`	Chrome 可执行文件路径的可选覆盖值。

抓取相关的常用请求控制头包括：

x-no-cache
x-target-selector
x-wait-for-selector
x-respond-with
x-timeout

构建与验证

npm run lint
npm run security:audit
npm run test:ci
npm run build

镜像构建流程还会对三个 standalone 服务做启动演练。

存储库结构

src/api/           RPC 主机与对外 HTTP 方法
src/stand-alone/   standalone 服务入口
src/services/      抓取、格式化、搜索与运行时服务
src/shared/        存储、限流与配置等本地共享基础设施
public/            静态资源
deploy/            可直接使用的生产部署模板
docs/              运维文档
scripts/           构建、许可证与安全辅助脚本
tests/             构建、运行时与自动化回归测试

5.8 KiB Raw Blame History Unescape Escape