stagex/curl

url-retriever 镜像文档

一、镜像概述

1.1 简介

url-retriever 是一个轻量级的 URL 检索工具与开发库镜像，提供命令行工具与可编程接口，支持通过 HTTP/HTTPS 协议与网络资源交互，可用于发送请求、获取响应数据及集成到应用开发流程中。

1.2 主要用途

• 命令行快速发起 HTTP/HTTPS 请求（测试 API、下载资源、验证接口可用性）
• 自动化脚本中集成 URL 检索逻辑（如 CI/CD 流程、监控告警）
• 作为开发库嵌入应用，提供跨语言 URL 检索能力（支持多语言调用）
• 轻量级网络资源交互测试与调试

二、核心功能与特性

2.1 核心功能

• 多协议支持：完整支持 HTTP/HTTPS，兼容 HTTP/1.1 与 HTTP/2 协议
• HTTP 方法覆盖：支持 GET、POST、PUT、DELETE、HEAD 等标准 HTTP 方法
• 灵活请求配置：自定义请求头（Headers）、请求体（Body）、查询参数（Query Parameters）
• 响应处理：返回完整响应数据（状态码、响应头、响应体），支持 JSON/XML/文本格式解析
• 网络控制：支持代理服务器（HTTP/SOCKS）、超时控制（连接超时、响应超时）、重试机制

2.2 关键特性

• 轻量级：镜像体积 < 50MB，启动速度快，资源占用低
• 跨平台兼容：基于 Alpine Linux 构建，支持 x86_64/ARM 架构
• 多语言集成：提供 C/C++、Python、JavaScript 等语言的调用接口（动态库/SDK）
• 安全可靠：内置 SSL/TLS 加密（OpenSSL 支持），支持证书验证与自定义 CA 证书
• 可扩展性：支持通过配置文件或环境变量扩展功能（如自定义重试策略、日志级别）

三、使用场景与适用范围

3.1 典型使用场景

• 命令行工具：开发者/运维人员通过终端快速测试 API（如 docker run url-retriever --url https://api.example.com）
• 自动化脚本：CI/CD 流程中验证服务健康状态（如 Jenkins 任务中检查后端接口可用性）
• 应用集成：在微服务架构中作为网络请求组件，嵌入到 Python/Node.js 应用中处理 URL 检索
• 教学与调试：演示 HTTP 协议交互细节（如请求/响应头格式、状态码含义）

3.2 适用范围

• 个人开发者：轻量网络工具需求（替代 curl/wget 的容器化方案）
• 企业开发团队：标准化网络请求组件，避免环境依赖冲突
• 自动化运维：监控脚本、批量资源同步、日志采集等场景
• 教育场景：网络协议教学、API 开发入门实践

四、使用方法与配置说明

4.1 镜像获取

通过 Docker Hub 拉取最新版本镜像：

bash
docker pull docker.xuanyuan.run/url-retriever:latest

4.2 基本使用（命令行工具模式）

4.2.1 简单 GET 请求

执行 HTTP GET 请求并输出响应体：

bash
docker run --rm docker.xuanyuan.run/url-retriever \
  --url "https://httpbin.org/get" \
  --method "GET"

4.2.2 带请求头的 POST 请求

发送 JSON 格式请求体并指定自定义头：

bash
docker run --rm docker.xuanyuan.run/url-retriever \
  --url "https://httpbin.org/post" \
  --method "POST" \
  --headers '{"Content-Type": "application/json", "Authorization": "Bearer token123"}' \
  --body '{"key": "value"}'

4.3 高级配置（环境变量与挂载）

4.3.1 环境变量参数

通过环境变量配置默认行为（优先级低于命令行参数）：

示例：通过环境变量设置默认超时与代理

bash
docker run --rm \
  -e TIMEOUT=10 \
  -e PROXY="http://proxy:8080" \
  docker.xuanyuan.run/url-retriever \
  --url "https://httpbin.org/get"

4.3.2 挂载配置文件

通过挂载本地配置文件（JSON 格式）定义复杂请求规则：

json
# 本地配置文件 config.json
{
  "requests": [
    {
      "url": "https://httpbin.org/get",
      "method": "GET",
      "headers": {"User-Agent": "url-retriever/1.0"},
      "timeout": 15
    },
    {
      "url": "https://httpbin.org/post",
      "method": "POST",
      "body": {"data": "test"},
      "retry": 2
    }
  ]
}

挂载并执行配置文件中的请求：

bash
docker run --rm \
  -v $(pwd)/config.json:/app/config.json \
  docker.xuanyuan.run/url-retriever --config /app/config.json

4.4 作为开发库使用

镜像内置多语言 SDK，支持在应用中直接调用 URL 检索功能（以 Python 为例）：

4.4.1 安装 SDK（容器内）

bash
# 进入容器交互式环境
docker run -it --rm docker.xuanyuan.run/url-retriever sh

# 安装 Python SDK
pip install url-retriever-sdk

4.4.2 Python 代码示例

python
from docker.xuanyuan.run/url_retriever import Retriever

# 初始化检索器
retriever = Retriever(timeout=10, proxy="http://proxy:8080")

# 发送 GET 请求
response = retriever.get("https://httpbin.org/get")
print(f"Status: {response.status_code}")
print(f"Body: {response.body}")

# 发送 POST 请求
response = retriever.post(
  url="https://httpbin.org/post",
  body={"key": "value"},
  headers={"Content-Type": "application/json"}
)

五、Docker 部署方案示例

5.1 docker run 完整示例

场景：定时检查网站可用性并记录响应状态

bash
docker run --rm \
  -e LOG_LEVEL=debug \
  -e TIMEOUT=5 \
  docker.xuanyuan.run/url-retriever \
  --url "https://example.com" \
  --method "HEAD" \
  --output /dev/stdout  # 输出响应状态码到标准输出

5.2 docker-compose 配置

场景：集成到监控服务，定时发送请求并输出日志

yaml
# docker-compose.yml
version: "3"
services:
  url-retriever:
    image: docker.xuanyuan.run/url-retriever:latest
    environment:
      - DEFAULT_URL=https://api.example.com/health
      - METHOD=GET
      - TIMEOUT=5
      - LOG_LEVEL=info
    volumes:
      - ./logs:/app/logs  # 挂载日志目录
    command: --output /app/logs/healthcheck.log  # 日志输出到文件

启动服务：

bash
docker-compose up -d

六、注意事项

• 镜像不包含持久化存储，需通过挂载目录保存日志或配置文件
• HTTPS 证书验证默认开启，如需禁用（测试场景），可添加 --insecure 命令行参数
• 作为库使用时，需确保目标语言环境已安装对应依赖（如 Python 的 pip、Node.js 的 npm）
• 高并发场景下建议通过容器编排工具（Kubernetes）进行资源限制与扩展