umputun/reproxy

Reproxy

镜像概述

Reproxy 是一款轻量级边缘HTTP(s)服务器/反向代理，支持多种提供者（Docker、静态规则、文件），通过灵活的路由规则将请求代理到目标地址。它可作为单个二进制文件或Docker容器部署，适用于边缘计算场景下的请求转发、SSL终止、静态文件服务等需求。

Reproxy 至少需要配置一个提供者，其余参数为可选且具有合理默认值。支持HTTP与HTTPS（静态证书或ACME自动证书），可通过正则表达式定义路由规则，并提供健康检查、日志记录等功能。

核心功能与特性

• 多提供者支持：同时配置多个提供者（静态规则、文件、Docker），动态获取路由信息
• 灵活路由规则：基于服务器名（FQDN或通配符*）和URL正则表达式匹配，支持分组捕获与替换
• HTTP/HTTPS支持：原生支持HTTP，HTTPS可使用静态证书或Let's Encrypt自动证书（ACME）
• 静态文件服务：内置资产服务器，可独立作为静态Web服务器使用
• 健康检查：提供/ping（服务存活）和/health（目标服务健康状态）端点
• 日志记录：支持Apache组合日志格式，自动轮转
• 额外功能：Gzip压缩、请求大小限制、自定义请求头添加

安装与部署

二进制文件

从https://github.com/umputun/reproxy/releases%E4%B8%8B%E8%BD%BD%E5%AF%B9%E5%BA%94%E5%B9%B3%E5%8F%B0%E7%9A%84%E4%BA%8C%E8%BF%9B%E5%88%B6%E6%96%87%E4%BB%B6%EF%BC%8C%E7%9B%B4%E6%8E%A5%E6%89%A7%E8%A1%8C%E5%8D%B3%E5%8F%AF%E3%80%82

Docker容器

Docker镜像可通过Docker Hub（umputun/reproxy）或GitHub容器 registry（ghcr.io/umputun/reproxy）获取。标签说明：

• :vX.Y.Z：稳定版本（latest为最新稳定版别名）
• :master：开发分支版本

使用方法

基本运行示例

Static提供者示例（Docker运行）

bash
docker run -d --name reproxy -p 8080:8080 umputun/reproxy \
  --static.enabled \
  --static.rule="example.com/api/(.*),https://api.example.com/$1" \
  --static.rule="*,/static/(.*),http://assets.example.com/$1,http://assets.example.com/ping"

File提供者示例

创建配置文件config.yml：

yaml
default:  # 匹配所有服务器（相当于通配符`*`）
  - {route: "^/api/svc1/(.*)", dest: "http://127.0.0.1:8080/blah1/$1"}
  - {route: "/api/svc3/xyz", dest: "http://127.0.0.3:8080/blah3/xyz", ping: "http://127.0.0.3:8080/ping"}
srv.example.com:  # 仅匹配服务器`srv.example.com`
  - {route: "^/api/svc2/(.*)", dest: "http://127.0.0.2:8080/blah2/$1/abc"}

运行Docker容器：

bash
docker run -d --name reproxy -p 8080:8080 -v $(pwd)/config.yml:/config.yml umputun/reproxy \
  --file.enabled \
  --file.name=/config.yml

Docker提供者示例

启动Docker容器并配置标签：

bash
# 目标服务容器（添加reproxy标签）
docker run -d --name api-service \
  --label "reproxy.server=api.example.com" \
  --label "reproxy.route=^/v1/(.*)" \
  --label "reproxy.dest=/api/v1/$1" \
  --label "reproxy.ping=/health" \
  my-api-image

# Reproxy容器（连接Docker守护进程）
docker run -d --name reproxy -p 80:8080 -v /var/run/docker.sock:/var/run/docker.sock umputun/reproxy \
  --docker.enabled \
  --docker.network=my-network \
  --docker.exclude=reproxy  # 排除自身容器

详细配置

提供者（Providers）

Reproxy支持同时配置多个提供者，动态获取路由规则。

Static提供者

通过命令行或环境变量直接定义路由规则，格式为server,sourceurl,destination,[ping-url]（逗号分隔，共3或4个元素）：

• server：服务器名（FQDN或*匹配所有）
• sourceurl：请求URL正则表达式（如^/api/(.*)）
• destination：目标URL（可引用正则分组，如http://dest/$1）
• ping-url（可选）：健康检查URL

示例规则：

• *,^/api/(.*),https://api.example.com/$1：所有服务器的/api/*请求代理到https://api.example.com/*
• example.com,/foo,https://dest.example.com/bar,https://dest.example.com/ping：example.com/foo请求代理到https://dest.example.com/bar，使用https://dest.example.com/ping健康检查

File提供者

通过YAML配置文件定义规则，支持动态更新（文件变更自动生效）。配置文件格式：

yaml
<server>:  # 服务器名（FQDN或`default`对应`*`）
  - route: <sourceurl正则>
    dest: <目标URL>
    ping: <可选健康检查URL>

启用命令：--file.enabled --file.name=<配置文件路径>

Docker提供者

自动发现Docker容器并生成路由规则，通过容器标签自定义路由：

• reproxy.server：匹配的服务器名
• reproxy.route：请求URL正则表达式
• reproxy.dest：目标路径（拼接容器IP:端口）
• reproxy.ping：健康检查路径
• reproxy.enabled=false：排除该容器

限制容器范围：

• --docker.exclude=<容器名>：排除指定容器（可多次使用）
• --docker.network=<网络名>：仅包含指定网络的容器

SSL配置

通过--ssl.type指定SSL类型：

• none（默认）：禁用HTTPS
• static：使用静态证书，需指定--ssl.cert（证书路径）和--ssl.key（私钥路径）
• auto：ACME自动证书（Let's Encrypt），需指定--ssl.acme-email（管理员***）和--ssl.acme-location（证书存储目录）

示例（ACME）：

bash
docker run -d --name reproxy -p 80:80 -p 443:443 -v ./acme:/acme umputun/reproxy \
  --ssl.type=auto \
  --ssl.acme-email=admin@example.com \
  --ssl.acme-location=/acme \
  --ssl.fqdn=example.com \
  --ssl.fqdn=www.example.com \
  --static.enabled \
  --static.rule="example.com,/,http://webserver:80"

静态文件服务（Assets Server）

启用后处理非代理请求，作为静态Web服务器：

• --assets.location=<静态文件目录>：启用资产服务器并指定文件路径
• --assets.root=<URL根路径>：静态文件访问根URL（默认/）

示例：

bash
docker run -d --name reproxy -p 8080:8080 -v ./static:/static umputun/reproxy \
  --assets.location=/static \
  --assets.root=/public

此时http://localhost:8080/public/file.txt会访问/static/file.txt

日志配置

启用访问日志：--logger.enabled，日志格式为Apache组合日志格式，自动轮转。可配置：

• --logger.file=<日志文件路径>（默认access.log）
• --logger.max-size=<最大大小MB>（默认100）
• --logger.max-backups=<保留文件数>（默认10）

其他选项

健康检查

Reproxy提供两个健康检查端点：

• /ping：返回pong，表示服务运行中
• /health：返回200 OK（所有目标服务健康）或417 Expectation Failed（存在不健康服务），响应体为JSON格式的健康状态详情

应用状态

项目处于活跃开发中，v1版本前可能存在不兼容变更。