OmniFetch

OmniFetch 是一个用 Go + Fiber v3 实现的数据获取与流式传输服务。它的核心目标很简单：接收一个资源标识或 URL，找到真实数据源，然后把数据稳定地返回给客户端；必要时也可以把远端资源下载到服务器本地。

当前项目主要覆盖三类能力：

• 资源透传：通过 HTTP、HTTPS 或本地 file:// 资源直接返回数据流。
• DO 数据获取：根据 doid 查询注册表，再按配置规则提取真实下载地址并返回文件内容。
• 后台下载：把指定 URL 下载到服务器本地，支持普通阻塞下载和 SSE 进度推送。

项目结构

.
├── cmd/omnifetch/            # 服务入口
├── internal/api/             # HTTP 路由与请求处理
├── internal/pkg/i18n/        # 国际化文案
├── internal/pkg/ierr/        # 统一错误处理
├── pkg/adapter/              # HTTP/File 数据源适配器
├── pkg/config/               # 配置加载与 Expr 规则预编译
├── pkg/downloader/           # 下载管理
├── pkg/extractor/            # 动态提取规则
├── pkg/register/             # 注册表查询
├── docs/                     # 模块说明文档
├── paper_to_do_sync/         # paper 表同步到 DO 接口的辅助脚本
├── conf.toml                 # 服务配置
├── Dockerfile
├── docker-compose.yml
└── go.mod

环境要求

• Go 1.25.4 或兼容版本
• 可访问 conf.toml 中配置的注册表服务时，/data 接口才可正常完成 DO 查询

快速启动

安装依赖：

go mod download

准备本地配置：

cp conf.example.toml conf.toml

然后按实际环境修改 conf.toml 中的注册表地址、公钥和私钥。

启动服务：

go run ./cmd/omnifetch

默认监听端口来自本地 conf.toml，模板见 conf.example.toml，当前默认值为 3000。

健康检查：

curl http://localhost:3000/health

配置说明

主配置文件是本地 conf.toml，不要提交到仓库；配置模板是 conf.example.toml。配置包含：

• port：服务监听端口，默认 3000
• download_timeout：普通下载和阻塞请求的超时时间，默认 30m
• registry：DO 注册表与智能合约相关配置
• extraction_rules：基于 Expr 的数据提取规则，用于从注册表返回数据中提取真实 URL 和响应头

当前代码支持以下环境变量覆盖：

FILE_ADAPTER_PORT=3001
FILE_ADAPTER_TIMEOUT=10m

API 速览

GET /transfer

按 uri 打开资源并直接流式返回。

curl -OJ "http://localhost:3000/transfer?uri=https://example.com/file.pdf"

支持的资源类型由 pkg/adapter 决定，当前包括：

• http://
• https://
• file://

GET /data

根据 doid 查询注册表，使用 conf.toml 中的 extraction_rules 提取真实资源地址，然后把资源返回给客户端。

curl -OJ "http://localhost:3000/data?doid=100.iod/sci/example-id"

默认使用流式返回。需要阻塞读取完整响应时，可显式传入：

curl -OJ "http://localhost:3000/data?doid=100.iod/sci/example-id&stream=false"

POST /download

把 URL 下载到服务器本地路径。

curl -X POST "http://localhost:3000/download" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/file.pdf","dest":"./downloads/file.pdf"}'

成功响应：

{
  "dest": "./downloads/file.pdf",
  "status": "completed",
  "url": "https://example.com/file.pdf"
}

GET|POST /download/stream

通过 SSE 返回下载进度。

curl -N "http://localhost:3000/download/stream?url=https://example.com/file.pdf&dest=./downloads/file.pdf"

事件示例：

data: {"status": "downloading", "current": 1048576, "total": 5242880}

data: {"status": "completed"}

错误响应

API 错误统一返回 JSON：

{
  "code": 400,
  "message": "无效的参数",
  "details": "uri is required"
}

错误语言可通过 lang 参数或 Accept-Language 请求头控制，例如：

curl "http://localhost:3000/transfer?lang=en"

Docker

构建镜像：

docker build -t omnifetch:v1.0.0 .

运行容器：

docker run --rm -p 3000:3000 \
  -v "$PWD/conf.toml:/app/conf.toml" \
  -v "$PWD/downloads:/app/downloads" \
  omnifetch:v1.0.0

paper_to_do_sync

paper_to_do_sync 是独立的辅助脚本目录，用于把 PostgreSQL paper 表数据同步到 DO 接口。它不是主服务启动依赖。

常用入口：

• paper_to_do_sync/README.md：脚本使用说明
• paper_to_do_sync/sync_paper_to_do.py：同步脚本
• paper_to_do_sync/config.example.json：配置模板

更多文档

• docs/api.md：API 模块说明
• docs/config.md：配置模块说明
• docs/adapter.md：适配器说明
• docs/extractor.md：提取规则说明
• docs/downloader.md：下载模块说明

开发

运行测试：

go test ./...