umputun/reproxyServidor HTTP(S) de borde ligero y proxy inverso con SSL automático, descubrimiento Docker/Consul, autenticación por ruta, limitación de velocidad y conmutación por error basada en comprobaciones de salud.
Reproxy es un servidor/proxy inverso simple de borde HTTP(s) que admite varios proveedores (docker, estático, archivo, catálogo consul). Uno o más proveedores suministran información sobre el servidor solicitado, la URL solicitada, la URL de destino y la URL de verificación de salud. Se distribuye como un solo binario o como un contenedor docker.
El servidor (host) puede configurarse como FQDN, ej. s.example.com, * (catch all) o una expresión regular. La coincidencia exacta tiene prioridad, por lo que si hay dos reglas con servidores example.com y example\.(com|org), la solicitud a example.com/some/url coincidirá con la primera. La URL solicitada puede ser una expresión regular, por ejemplo ^/api/(.*) y la URL de destino puede tener grupos coincidentes de la expresión regular, ej. http://d.example.com:8080/$1. Para el ejemplo anterior, http://s.example.com/api/something?foo=bar se proxyará a http://d.example.com:8080/something?foo=bar.
Por conveniencia, las solicitudes con / final y sin grupos de expresión regular se expanden a /(.*), y los destinos en esos casos se expanden a /$1. Es decir, /api/ -> http://127.0.0.1/service se traducirá a ^/api/(.*) -> http://127.0.0.1/service/$1.
La sustitución de host es compatible en la URL de destino. Por ejemplo, /files/${host} se reemplazará con el nombre del host coincidente. También se puede usar $host (sin llaves).
Se admiten tanto HTTP como HTTPS. Para HTTPS, se puede usar un certificado estático así como certificados ACME automatizados (Let's Encrypt). Se puede usar un servidor de activos opcional para servir archivos estáticos. Iniciar reproxy requiere al menos un proveedor definido. El resto de parámetros son estrictamente opcionales y tienen valores predeterminados razonables.
Ejemplos:
reproxy --static.enabled --static.rule="*,example.com/api/(.*),https://api.example.com/$1"reproxy --docker.enabled --docker.autodocker up -p 80:8080 umputun/reproxy --docker.enabled --docker.autodocker up -p 80:8080 -p 443:8443 umputun/reproxy --docker.enabled --docker.auto --ssl.type=auto --ssl.fqdn=example.comReproxy se distribuye como un pequeño binario autónomo, así como una imagen docker. Tanto el binario como la imagen admiten múltiples arquitecturas y múltiples sistemas operativos, incluyendo linux_x86_64, linux_arm64, linux_arm, macos_x86_64, macos_arm64, windows_x86_64 y windows_arm. También proporcionamos paquetes deb y rpm tanto para arm64 como para x86.
brew install umputun/apps/reproxydocker pull umputun/reproxy o docker pull ghcr.io/umputun/reproxy.La última versión estable tiene la etiqueta docker :vX.Y.Z (con el alias :latest) y la rama master actual tiene la etiqueta :master.
Las reglas de proxy son proporcionadas por varios proveedores. Actualmente incluidos - file, docker, static y consul-catalog. Cada proveedor puede definir múltiples reglas de enrutamiento tanto para solicitudes proxy como para activos estáticos. El usuario puede configurar múltiples proveedores al mismo tiempo.
Vea ejemplos de varios proveedores en examples
Este es el proveedor más simple que define todas las reglas de mapeo directamente en la línea de comandos (o entorno). Se admiten múltiples reglas. Cada regla tiene de 3 a 7 elementos separados por comas server,sourceurl,destination[,ping-url[,forward-health-checks[,timeout[,throttle]]]]. Por ejemplo:
*,^/api/(.*),https://api.example.com/$1 - proxy todas las solicitudes a cualquier host/servidor con prefijo /api a https://api.example.comexample.com,/foo/bar,https://api.example.com/zzz,https://api.example.com/ping - proxy todas las solicitudes a example.com y con url /foo/bar a https://api.example.com/zzz y usa https://api.example.com/ping para la verificación de salud.example.com,/foo/bar,https://api.example.com/zzz,https://api.example.com/ping,true - igual que el anterior pero también reenvía las solicitudes /ping y /health al backend.example.com,^/upload/(.*),https://api.example.com/$1,,,5m - tiempo de espera de solicitud por ruta de 5 minutos (4to y 5to campos vacíos para omitir ping-url y forward-health-checks).El 4º elemento define una url de ping opcional utilizada para informes de salud. El 5º elemento habilita opcionalmente el reenvío de solicitudes de verificación de salud al backend (true, yes, 1). Consulte la sección Verificación de salud para más detalles. El 6º elemento es un tiempo de espera de solicitud por ruta opcional (duración Go, ej. 5m, 30s); 0 o vacío hereda la configuración global --timeout.write. El 7º elemento es un límite opcional de req/seg por usuario por ruta; 0 o vacío hereda la configuración --throttle.user. Se permiten campos posicionales vacíos (ej. ,, para los campos intermedios no utilizados).
Este proveedor utiliza un archivo yaml con reglas de enrutamiento.
reproxy --file.enabled --file.name=config.yml
Ejemplo de config.yml:```yaml
default: # the same as * (catch-all) server
Este es un proveedor dinámico y el cambio de archivo se aplicará automáticamente.
**Múltiples sitios estáticos en diferentes dominios** se pueden servir utilizando nombres de servidor como claves con `assets: true`:```yaml
site-en.example.com:
- { route: "/", dest: "/var/www/en", "assets": true }
site-ru.example.com:
- { route: "/", dest: "/var/www/ru", "assets": true }
Importante: el campo route para las reglas de assets debe ser un prefijo de ruta (p.ej., /, /web/), no una expresión regular. Los patrones de regex como ^/(.*) no funcionarán con assets: true porque la coincidencia de assets estáticos utiliza comparación de prefijos de ruta, no regex.
El proveedor Docker admite un descubrimiento totalmente automático (con --docker.auto) sin necesidad de configuración adicional. Por defecto, redirige todas las solicitudes como http://<url>/<nombre del contenedor>/(.*) a la IP interna del contenedor dado y al puerto expuesto. Solo se detectarán los contenedores activos (en ejecución).
Este valor predeterminado se puede cambiar con etiquetas:
reproxy.server - servidor (hostname) a coincidir. También puede ser una lista de servidores separados por comas.reproxy.route - ruta de origen (ubicación)reproxy.dest - ruta de destino. Nota: no es una URL completa, solo la ruta que se añadirá a la ip:puerto del contenedor.reproxy.port - puerto de destino para el contenedor descubiertoreproxy.ping - ruta de ping para el contenedor de destino.reproxy.remote - restringir el acceso a la ruta con una lista de subredes o IPs separadas por comasreproxy.auth - requerir autenticación básica para la ruta con pares usuario:hash_bcrypt separados por comas (generados por htpasswd -nbB)reproxy.assets - establecer el mapeo de assets como raíz-web:ubicación, por ejemplo reproxy.assets=/web:/var/wwwNota: sin --docker.auto, el contenedor de destino debe tener al menos una de las etiquetas reproxy.* para ser considerado como destino potencial.
Con --docker.auto, todos los contenedores con puerto expuesto serán considerados como destinos de enrutamiento. Hay 3 formas de restringirlo:
--docker.exclude, es decir, --docker.exclude=c1 --docker.exclude=c2 ...--docker.networkreproxy.enabled=false o reproxy.enabled=no o reproxy.enabled=0Si no se define reproxy.route, la ruta predeterminada es ^/<nombre_del_contenedor>/(.*). En caso de que todas las rutas de origen proxy deban tener el mismo patrón de prefijo, por ejemplo /api/(.*), el usuario puede definir el prefijo común (en este caso /api) para todas las rutas basadas en contenedores. Esto se puede hacer con el parámetro --docker.prefix.
El proveedor Docker también permite definir múltiples conjuntos de etiquetas reproxy.N.something para coincidir con varias rutas distintas en el mismo contenedor. Esto es útil ya que, en algunos casos, un solo contenedor puede exponer múltiples endpoints, por ejemplo, una API pública y alguna API de administración. Todas las etiquetas anteriores se pueden usar con un "índice N", es decir, reproxy.1.server, reproxy.1.port y así sucesivamente. N debe estar en el rango de 0 a 9.
Este es un proveedor dinámico y cualquier cambio en el estado del contenedor se aplicará automáticamente.
Uso: reproxy --consul-catalog.enabled
El proveedor de Consul Catalog llama a la API de Consul periódicamente (cada segundo por defecto) para obtener servicios que tengan alguna etiqueta con el prefijo reproxy.. El usuario puede redefinir el intervalo de comprobación con la bandera de línea de comandos --consul-catalog.interval así como la dirección de consul con la opción de línea de comandos --consul-catalog.address. La dirección predeterminada es http://127.0.0.1:8500.
Por ejemplo:``` reproxy --consul-catalog.enabled --consul-catalog.address=http://192.168.1.100:8500 --consul-catalog.interval=10s
Por defecto, el proveedor establece valores para cada servicio:
- habilitado `false`
- servidor `*`
- ruta `^/(.*)`
- destino `http://<SERVICE_ADDRESS_FROM_CONSUL>/$1`
- ping `http://<SERVICE_ADDRESS_FROM_CONSUL>/ping`
Este valor predeterminado se puede cambiar con etiquetas:
- `reproxy.server` - servidor (nombre de host) a coincidir. También puede ser una lista de servidores separados por comas.
- `reproxy.route` - ruta de origen (ubicación)
- `reproxy.dest` - ruta de destino. Nota: esta no es una URL completa, solo la ruta que se agregará a la ip:puerto del servicio
- `reproxy.port` - puerto de destino para el servicio descubierto
- `reproxy.remote` - restringir acceso a la ruta con una lista de subredes o IPs separadas por comas
- `reproxy.auth` - requerir autenticación básica para la ruta con pares `usuario:bcrypt_hash` separados por comas (generados por `htpasswd -nbB`)
- `reproxy.ping` - ruta de ping para el servicio de destino.
- `reproxy.forward-health-checks` - reenviar solicitudes `/ping` y `/health` al backend (`true`, `yes`, `1`).
- `reproxy.timeout` - tiempo de espera por ruta como una duración de Go (ej. `5m`, `30s`). `0` o no establecido hereda el global `--timeout.write`. Los valores inválidos se ignoran con una advertencia.
- `reproxy.throttle` - límite de req/seg por ruta y usuario. `0` o no establecido hereda `--throttle.user`. Los valores inválidos o negativos se ignoran con una advertencia.
- `reproxy.enabled` - habilitar (`yes`, `true`, `1`) o deshabilitar (`cualquier otro valor`) el servicio de los destinos de reproxy.
### Detalles específicos de Compose
En caso de que las reglas se establezcan como parte de un entorno de docker compose, el destino con el grupo de expresión regular entrará en conflicto con la sintaxis de compose. Es decir, intentar usar `https://api.example.com/$1` en un entorno de compose fallará debido a un error de sintaxis. La solución estándar aquí es "escapar" el signo `$` reemplazándolo por `$$`, es decir, `https://api.example.com/$$1`. Esta sustitución es compatible con docker compose y no tiene nada que ver con reproxy en sí. Otra forma es usar `@` en lugar de `$`, lo cual es compatible a nivel de reproxy, es decir, `https://api.example.com/@1`_
## Soporte SSL
El modo SSL (por defecto ninguno) se puede establecer en `auto` (certificados ACME/LE), `static` (certificado existente) o `none`. Si se activa `auto`, el certificado SSL se emitirá automáticamente para todos los nombres de servidor descubiertos. El usuario puede sobrescribirlo estableciendo el/los valor(es) de `--ssl.fqdn`. En modo SSL `auto` y `static`, Reproxy agregará automáticamente las cabeceras `X-Forwarded-Proto` y `X-Forwarded-Port`. Estas cabeceras son útiles para los servicios detrás del proxy para conocer el protocolo original (http o https) y el número de puerto utilizados por el cliente.
Cuando se usa ACME con proveedores de descubrimiento (docker, file, consul), los certificados SSL se obtienen automáticamente para los servidores recién descubiertos sin necesidad de reiniciar reproxy.
### Desafíos ACME
Reproxy admite dos tipos de desafíos ACME para la validación de certificados SSL:
1. **Desafío HTTP-01** (predeterminado): Valida la propiedad del dominio sirviendo un token en una URL HTTP específica. Requiere que el puerto 80 sea accesible públicamente.
2. **Desafío DNS-01**: Valida la propiedad del dominio creando registros TXT de DNS. Este método:
- No requiere que el puerto 80 sea accesible
- Funciona con certificados comodín
- Requiere una configuración de proveedor de DNS compatible
#### Selección de desafío
Reproxy determina automáticamente qué método de desafío usar según su configuración:
- **HTTP-01** (predeterminado): Se usa cuando no hay un proveedor de DNS configurado
- **DNS-01**: Se usa cuando hay un proveedor de DNS configurado
No necesita seleccionar explícitamente un tipo de desafío: solo configure un proveedor de DNS si desea usar desafíos DNS-01.
#### Proveedores de DNS actualmente compatibles
Reproxy actualmente incluye soporte para los siguientes proveedores de DNS:
- **Cloudflare**: `--ssl.dns.type=cloudflare --ssl.dns.cloudflare.api-token=TOKEN`
- **Route53 (AWS)**: `--ssl.dns.type=route53 --ssl.dns.route53.region=REGION --ssl.dns.route53.hosted-zone-id=ID`
- **Gandi**: `--ssl.dns.type=gandi --ssl.dns.gandi.bearer-token=TOKEN`
- **DigitalOcean**: `--ssl.dns.type=digitalocean --ssl.dns.digitalocean.api-token=TOKEN`
- **Hetzner**: `--ssl.dns.type=hetzner --ssl.dns.hetzner.api-token=TOKEN`
- **Linode**: `--ssl.dns.type=linode --ssl.dns.linode.api-token=TOKEN`
- **GoDaddy**: `--ssl.dns.type=godaddy --ssl.dns.godaddy.api-token=TOKEN`
- **Namecheap**: `--ssl.dns.type=namecheap --ssl.dns.namecheap.api-key=KEY --ssl.dns.namecheap.user=USER`
- **Scaleway**: `--ssl.dns.type=scaleway --ssl.dns.scaleway.secret-key=KEY --ssl.dns.scaleway.organization-id=ID`
- **Porkbun**: `--ssl.dns.type=porkbun --ssl.dns.porkbun.api-key=KEY --ssl.dns.porkbun.api-secret-key=SECRET`
- **DNSimple**: `--ssl.dns.type=dnsimple --ssl.dns.dnsimple.api-access-token=TOKEN --ssl.dns.dnsimple.account-id=ID`
- **DuckDNS**: `--ssl.dns.type=duckdns --ssl.dns.duckdns.api-token=TOKEN`
Ejemplo con Cloudflare como proveedor DNS:```
export CLOUDFLARE_API_TOKEN=your_api_token
reproxy --ssl.type=auto [email protected] --ssl.fqdn=example.com
El desafío DNS-01 es especialmente útil cuando:
Reproxy permite sanitizar (eliminar) los encabezados entrantes pasando el parámetro --drop-header (se puede repetir). Este parámetro puede ser útil para asegurar que algunos de los encabezados, establecidos internamente por los servicios, no puedan ser establecidos/falsificados por el usuario final. Por ejemplo, si alguno de los servicios responsables de la autenticación establece X-Auth-User y X-Auth-Token, probablemente tenga sentido eliminar esos encabezados de las solicitudes entrantes pasando el parámetro --drop-header=X-Auth-User --drop-header=X-Auth-Token o mediante la variable de entorno DROP_HEADERS=X-Auth-User,X-Auth-Token
La función opuesta, establecer encabezados salientes, también es compatible. Puede ser útil en muchos casos, por ejemplo, aplicar reglas CORS personalizadas, encabezados relacionados con la seguridad, etc. Esto se puede hacer con el parámetro --header (se puede repetir) o la variable de entorno HEADER. Por ejemplo, así es como se puede hacer con docker compose:```yaml
environment:
- HEADER=
X-Frame-Options:SAMEORIGIN,
X-XSS-Protection:1; mode=block;,
Content-Security-Policy:default-src 'self'; style-src 'self' 'unsafe-inline';
## Logging
Por defecto no se genera ningún registro de solicitud. Esto se puede activar configurando `--logger.enabled`. El registro (con rotación automática) tiene [Formato de Registro Combinado de Apache](http://httpd.apache.org/docs/2.2/logs.html#combined)
El usuario también puede activar el registro en stdout con `--logger.stdout`. Esto no afectará al registro de archivos anterior, pero mostrará información mínima sobre las solicitudes procesadas, algo como esto:```
2021/04/16 01:17:25.601 [INFO] GET - /echo/image.png - xxx.xxx.xxx.xxx - 200 (155400) - 371.661251ms
2021/04/16 01:18:18.959 [INFO] GET - /api/v1/params - xxx.xxx.xxx.xxx - 200 (74) - 1.217669m
Los usuarios pueden activar el servidor de assets (desactivado por defecto) para servir archivos estáticos. Mientras --assets.location esté configurado, trata cada solicitud no proxy bajo assets.root como una solicitud de archivos estáticos. El servidor de assets puede utilizarse sin ningún proveedor de proxy; en este modo, reproxy actúa como un servidor web simple para el contenido estático. El servidor de assets también admite el "modo spa" con --assets.spa, donde todas las solicitudes no encontradas se redirigen a index.html.
Además del servidor de assets común, se admiten múltiples servidores de assets personalizados. Cada proveedor tiene una forma diferente de definir dicha regla estática, y algunos proveedores pueden no soportarlo en absoluto. Por ejemplo, múltiples servidores de assets tienen sentido en el proveedor estático (línea de comandos), el proveedor de archivos e incluso son útiles con proveedores de Docker, sin embargo, tiene muy poco sentido con el proveedor de catálogo de Consul.
assets: o spa:, se tratará como un servidor de archivos. Por ejemplo *,assets:/web,/var/www, servirá todas las solicitudes /web/* con un servidor de archivos sobre el directorio /var/www.assets: true o spa: true. Nota: el campo route debe ser un prefijo de ruta (ej., /, /web/), no un patrón regex.reproxy.assets=web-root:location, es decir, reproxy.assets=/web:/var/www. El cambio al modo spa se realiza configurando reproxy.spa a o El servidor de assets admite control de caché con el parámetro --assets.cache=<duration>. La duración 0s (por defecto) desactiva el control de caché. Una duración es una secuencia de números decimales, cada uno con fracción opcional y un sufijo de unidad, como "300ms", "1.5h" o "2h45m". Las unidades de tiempo válidas son "ns", "us" (o "µs"), "ms", "s", "m", "h" y "d".
Hay dos formas de configurar la duración de la caché:
--assets.cache=48h.--assets.cache, es decir, --assets.cache=48h --assets.cache=text/html:24h --assets.cache=image/png:2h. Los valores de entorno deben estar separados por comas, es decir, ASSETS_CACHE=48h,text/html:24h,image/png:2hLa página personalizada 404 (no encontrada) se puede configurar con el parámetro --assets.not-found=<path>. La ruta debe ser relativa a la raíz de assets.
Servir contenido puramente estático es uno de los casos de uso populares. Generalmente esto se utiliza para el contenedor frontend separado que solo proporciona UI. Con el servidor de assets, dicho contenedor es casi trivial de hacer. Este es un ejemplo del contenedor que sirve reproxy.io```docker FROM node:22-alpine as build
WORKDIR /build COPY site/ /build COPY README.md /build/src/index.md
RUN yarn --frozen-lockfile RUN yarn build RUN ls -la /build/public
FROM ghcr.io/umputun/reproxy COPY --from=build /build/public /srv/site EXPOSE 8080 USER app ENTRYPOINT ["/srv/reproxy", "--assets.location=/srv/site"]
Todo lo que necesita es copiar los activos estáticos a alguna ubicación y pasar esta ubicación como `"--assets.location` al punto de entrada de reproxy.
## Modo compatible con SPA
Algunas aplicaciones SPA dependen del proxy para manejar el 404 en activos estáticos de una manera especial, redirigiéndolos a "/index.html". Esto es similar a la directiva `try_files $uri $uri/ …` de nginx y, aparentemente, esta funcionalidad es algo importante para las aplicaciones web modernas.
Este modo está desactivado por defecto y se puede activar configurando `--assets.spa` o la variable de entorno `ASSETS_SPA=true`.
## Redirecciones
Por defecto, reproxy trata el destino como una ubicación de proxy, es decir, invoca una llamada http internamente y devuelve la respuesta al cliente. Sin embargo, al prefijar la URL de destino con `@code`, este comportamiento se puede cambiar a una redirección permanente (código de estado 301) o temporal (código de estado 302). Es decir, un destino configurado como `@301 https://example.com/something` provocará una redirección http permanente a `Location: https://example.com/something`
códigos soportados:
- `@301`, `@perm` - redirección permanente
- `@302`, `@temp`, `@tmp` - redirección temporal
## Más opciones
- `--gzip` habilita la compresión gzip para las respuestas.
- `--max=N` permite establecer el tamaño máximo de la solicitud (por defecto 64k). Configurarlo en `0` desactiva la verificación de tamaño.
- `--timeout.*` varios tiempos de espera tanto para el servidor como para el transporte del proxy. Consulte la sección `timeout` en [Todas las opciones de la aplicación](#all-application-options). Un valor cero o negativo significa que no habrá tiempo de espera.
- `--insecure` desactiva la verificación SSL en el host de destino. Esto es útil para certificados autofirmados.
## Puertos predeterminados
Para eliminar la necesidad de pasar parámetros/entorno personalizados, el `--listen` predeterminado es dinámico y trata de ser razonable y útil para los casos típicos:
- Si el usuario configura algo en `--listen`, toda la lógica siguiente se ignora y se utiliza directamente el host:puerto pasado.
- Si el usuario no configura nada en `--listen` y reproxy se ejecuta fuera del contenedor docker, el valor predeterminado es `127.0.0.1:80` para el modo http (`ssl.type=none`) y `127.0.0.1:443` para el modo ssl (`ssl.type=auto` o `ssl.type=static`).
- Si el usuario no configura nada en `--listen` y reproxy se ejecuta dentro de docker, el valor predeterminado es `0.0.0.0:8080` para el modo http, y `0.0.0.0:8443` para el modo ssl.
Otro valor predeterminado configurado de manera dinámica similar es `--ssl.http-port`. Para ejecución dentro del contenedor docker se establece en `8080` y fuera en `80`.
## Ping, comprobaciones de estado y fail-over
reproxy proporciona dos endpoints para este propósito:
- `/ping` responde con `pong` e indica que reproxy está en funcionamiento
- `/health` devuelve el estado `200 OK` si todos los servidores de destino respondieron a su solicitud de ping con `200` o `417 Expectation Failed` si algún servidor respondió con un código diferente a 200. También devuelve un cuerpo json con detalles sobre los servicios que pasaron/fallaron.
Además de los endpoints anteriores, reproxy admite comprobaciones de estado en vivo opcionales. En este caso (si está habilitado), cada destino se verifica periódicamente para obtener respuesta de ping y se excluyen las rutas de destino fallidas. Es posible devolver múltiples destinos idénticos del mismo o de varios proveedores, y solo se seleccionan los que pasan. Si se descubren y pasan numerosas coincidencias, se selecciona la final según la estrategia `lb-type` (por defecto, selección aleatoria).
Para activar la comprobación de estado en vivo, el usuario debe configurar `--health-check.enabled` (o la variable de entorno `HEALTH_CHECK_ENABLED=true`). Para personalizar el intervalo de verificación, se puede usar `--health-check.interval=`.
## API de gestión
Opcional, se puede activar con `--mgmt.enabled`. Expone 2 endpoints en `mgmt.listen` (dirección:puerto):
- `GET /routes` - lista de todas las rutas descubiertas
- `GET /metrics` - devuelve métricas de prometheus (`http_requests_total`, `response_status` y `http_response_time_seconds`)
Por defecto, `http_response_time_seconds` utiliza las rutas de solicitud sin procesar como etiquetas, lo que puede causar alta cardinalidad con URL dinámicas (por ejemplo, `/api/users/123`, `/api/users/456`). Use `--mgmt.low-cardinality` para cambiar a patrones de ruta (por ejemplo, `^/api/users/(.*)`) en su lugar, reduciendo significativamente la cardinalidad de las métricas.
_consulte también [examples/metrics](https://github.com/umputun/reproxy/tree/master/examples/metrics)_
## Informes de errores
Reproxy devuelve un error 502 (Bad Gateway) si la solicitud no coincide con ninguna ruta o activo proporcionado. En caso de que ocurra algún error interno inesperado, devuelve 500. Por defecto, reproxy renderiza la versión de texto más simple del error - "Server error". Configurar `--error.enabled` activa el mensaje de error html predeterminado y con `--error.template` el usuario puede establecer cualquier archivo de plantilla html personalizado para la representación del error. La plantilla tiene dos variables: `{{.ErrCode}}` y `{{.ErrMessage}}`. Por ejemplo, esta plantilla `oh my! {{.ErrCode}} - {{.ErrMessage}}` se renderizará como `oh my! 502 - Bad Gateway`
## Limitación de velocidad
Reproxy permite definir un valor máximo de req/seg a nivel de sistema para la actividad general del sistema, así como por usuario. Los valores 0 (predeterminados) se tratan como ilimitados.
La actividad del usuario está limitada tanto para rutas coincidentes como no coincidentes. Todas las rutas no coincidentes se consideran como un "grupo de destino único" y obtienen un limitador común que es `rate*3`. Esto significa que si se define 10 (req/seg) con `--throttle.user=10`, el usuario final podrá realizar hasta 30 solicitudes por segundo tanto para activos estáticos como para rutas no coincidentes. Para rutas coincidentes, este limitador se mantiene por destino (ruta), es decir, las solicitudes proxy a s1.example.com/api permitirán 10 r/s y las solicitudes proxy a s2.example.com permitirán otras 10 r/s.
### Tiempo de espera y limitación por ruta
Las rutas individuales pueden anular las configuraciones globales `--timeout.write` y `--throttle.user` a través de los campos `timeout` y `throttle` específicos del proveedor. Esto es útil para endpoints de larga duración (por ejemplo, cargas, generación de informes) que necesitan un plazo superior al tiempo de espera de escritura global, y para endurecer los límites de velocidad en rutas sensibles (por ejemplo, inicio de sesión) sin aumentar el límite global para todo lo demás.
La precedencia es "cero hereda global, positivo anula": una ruta con `timeout: 0` (o sin campo `timeout`) mantiene el `--timeout.write` global; una ruta con `timeout: 5m` lo anula solo para las solicitudes coincidentes. La misma regla se aplica a `throttle`.
El tiempo de espera por ruta anula los plazos de lectura y escritura de la conexión para las solicitudes coincidentes, por lo que puede extenderse más allá del `--timeout.write` global (por defecto 30s). Las rutas sin un tiempo de espera por ruta aún respetan la configuración global.
**Limitación — tiempo de espera del encabezado de respuesta a nivel de transporte:** el `timeout` por ruta NO anula `--timeout.resp-header` (por defecto 5s). Ese tiempo de espera se establece en el `http.Transport` compartido y se aplica antes de que el upstream comience a enviar los encabezados de respuesta. Si un upstream tarda más que `--timeout.resp-header` en comenzar su respuesta (por ejemplo, un endpoint de informe lento), la solicitud falla en ese límite independientemente del `timeout` por ruta. Para admitir dichas rutas, aumente `--timeout.resp-header` globalmente al máximo necesario para cualquier ruta de respuesta lenta. La anulación por ruta de los tiempos de espera a nivel de transporte está intencionalmente fuera del alcance.
Sintaxis del proveedor:
- **Proveedor de archivos** (YAML): `timeout: 5m`, `throttle: 2`
- **Proveedor estático** (CSV): campos posicionales 6.º y 7.º, p. ej. `*,^/upload/(.*),http://up:8080/$1,,,5m,2`
- **Proveedor Docker**: `reproxy.timeout=5m`, `reproxy.throttle=2` (o `reproxy.<n>.timeout` / `reproxy.<n>.throttle` para contenedores con múltiples rutas)
- **Proveedor Consul Catalog**: `reproxy.timeout=5m`, `reproxy.throttle=2`
## Límites de conexión upstream
Reproxy permite configurar los ajustes del grupo de conexiones upstream para controlar cuántas conexiones se mantienen con los servidores backend:
- `--upstream.max-idle-conns` - Número máximo de conexiones inactivas en todos los hosts upstream. Por defecto: 100.
- `--upstream.max-conns` - Número máximo de conexiones por host upstream (0 = ilimitado). Por defecto: 0.
Configurar `--upstream.max-conns` limita las conexiones concurrentes a cada backend, lo cual es útil cuando los servidores upstream tienen capacidad limitada o para evitar el agotamiento de conexiones.
## Autenticación básica
Reproxy admite autenticación básica en dos modos: global (todas las rutas) y por ruta.
### Autenticación básica global
La autenticación básica global protege todas las rutas. Esto es útil para proteger endpoints durante el desarrollo y las pruebas. Para habilitarla, configure el archivo htpasswd con `--basic-htpasswd=<ubicación del archivo>` o la variable de entorno `BASIC_HTPASSWD=<ubicación del archivo>`.
Reproxy espera que el archivo htpasswd tenga el siguiente formato:```
username1:bcrypt(password1)
username2:bcrypt(password2)
...
esto se puede generar con el comando htpasswd -nbB, es decir, htpasswd -nbB test passwd
La autenticación por ruta permite diferentes credenciales para diferentes rutas. Cuando una ruta tiene autenticación por ruta configurada, la autenticación global se omite para esa ruta. La autenticación por ruta se configura mediante ajustes específicos del proveedor:
auth en YAML, p. ej., auth: "user1:$2y$..., user2:$2y$..."reproxy.authreproxy.authEl formato es una lista separada por comas de pares user:bcrypt_hash (mismo formato htpasswd). Se pueden especificar múltiples usuarios para la misma ruta.
Ejemplo con docker-compose:```yaml services: admin-api: labels: - "reproxy.route=^/admin/(.*)" - "reproxy.dest=/$1" - "reproxy.auth=admin:$$2y$$05$$hashedpassword"
Nota: En docker-compose, `$` debe escaparse como `$$`.
## Control de acceso basado en IP
Reproxy permite restringir el acceso a las rutas con una lista de subredes o ips separadas por comas. Esto es útil para el desarrollo y las pruebas, antes de permitir el acceso sin restricciones a ellas. También se puede usar para restringir el acceso a los servicios internos. Por defecto, todas las rutas están abiertas para todos los clientes.
Para restringir el acceso a las rutas, el usuario debe establecer las claves adecuadas para las rutas, es decir, `reproxy.remote` para docker y consul, y `remote` para el proveedor de archivos. El valor debe ser una lista de subredes o ips separadas por comas o subredes. Por ejemplo `127.0.0.1, 192.168.1.0/24`. Para más detalles, consulte las secciones [proveedor docker](#docker-provider) y [proveedor catálogo consul](#consul-catalog-provider).
Por defecto, reproxy verificará la dirección remota de la solicitud del cliente. Sin embargo, en algunos casos, esto no funcionará como se espera, por ejemplo detrás de otro proxy, o con la red puente de docker. Esto se puede modificar con el parámetro `--remote-lookup-headers` que permite verificar el valor de la cabecera `X-Real-IP` o `X-Forwarded-For` (en ese orden) y usarlo para la verificación. Si la cabecera no está configurada, la verificación se realizará contra la dirección remota del cliente. Estas cabeceras son proporcionadas por el cliente y se pueden falsificar fácilmente, por lo que este parámetro solo debe activarse cuando reproxy se ejecuta detrás de un proxy frontal de confianza que siempre establece y sobrescribe estas cabeceras.
La verificación de cabeceras debe usarse con precaución, ya que es posible falsificarlas. Cuando `--remote-lookup-headers` está habilitado, la lista blanca de IP depende completamente de esta suposición de confianza: un cliente que envíe `X-Real-IP` o `X-Forwarded-For` con una dirección permitida puede eludir la restricción. Habilite esta opción solo si reproxy está detrás de un proxy de confianza que controla estas cabeceras y puede garantizar que no sean falsificadas.
## Soporte de plugins
La funcionalidad central de reproxy se puede extender con plugins externos. Cada plugin es un proceso/contenedor independiente que implementa un servidor rpc. Los plugins se registran con el conductor de reproxy y se agregan a la cadena de middlewares. Cada plugin recibe una solicitud con la url original, las cabeceras y toda la información de la ruta coincidente y responde con las cabeceras y el código de estado. Cualquier código de estado >= 400 se trata como una respuesta de error y finaliza el flujo inmediatamente con el error del proxy. Hay dos tipos de cabeceras que los plugins pueden establecer:
- `HeadersIn` - cabeceras entrantes. Se enviarán a la url destino
- `HeadersOut` - cabeceras salientes. Se enviarán de vuelta al cliente
Por defecto, las cabeceras establecidas por un plugin se mezclarán con las cabeceras originales. En caso de que el plugin necesite controlar todas las cabeceras, por ejemplo eliminar algunas, el campo `OverrideHeaders*` puede ser establecido por un plugin indicando al proceso central de reproxy la necesidad de sobrescribir todas las cabeceras en lugar de mezclarlas.
- `OverrideHeadersIn` - indica que el plugin es responsable de todas las cabeceras entrantes.
- `OverrideHeadersOut` - indica que el plugin es responsable de todas las cabeceras salientes
Para simplificar el proceso de desarrollo, se proporcionan todos los bloques de construcción. Incluye `lib.Plugin` que maneja el registro, la escucha y el envío de llamadas, así como `lib.Request` y `lib.Response` que definen la entrada y salida. Los autores de plugins deben implementar manejadores concretos que cumplan con la firma `func(req lib.Request, res *lib.HandlerResponse) (err error)`. Cada plugin puede contener múltiples manejadores de este tipo.
_Vea [examples/plugin](https://github.com/umputun/reproxy/tree/master/examples/plugin) para más información_
## Seguridad del contenedor
Por defecto, el contenedor de reproxy se ejecuta bajo el usuario root para simplificar la configuración inicial y acceder al socket de docker. Esto es necesario para permitir que el proveedor docker descubra los contenedores en ejecución. Sin embargo, si no se requiere dicho descubrimiento o no se utiliza el proveedor docker, se recomienda cambiar el usuario a uno con menos privilegios. Esto se puede hacer a nivel de docker-compose y a nivel de docker con la opción `user`, consulte la sección a continuación para más detalles.
A veces, incluso con el enrutamiento dentro de docker, tiene sentido deshabilitar el proveedor docker y configurar las reglas con el proveedor estático o de archivos. Todos los contenedores que se ejecutan dentro de un compose comparten la misma red y son accesibles a través de DNS local. El usuario puede tener una regla como esta para evitar el descubrimiento docker: `- STATIC_RULES=*,/api/email/(.*),http://email-sender:8080/$$1`. Esta regla espera que el contenedor `email-sender` esté definido dentro del mismo compose. Tenga en cuenta: los usuarios pueden lograr el mismo resultado usando la red docker incluso si el servicio de destino se definió en un archivo compose diferente. De esta manera, la configuración de reproxy puede mantenerse separada de los servicios reales.
No hay nada más que el binario de reproxy dentro del contenedor de reproxy, ya que se construye sobre una imagen vacía (scratch).
### Ejecución con un usuario no root
Un usuario con UID `1001` (perteneciente a los grupos `1001` y `999`) está precreado dentro del contenedor y se puede utilizar para ejecutar reproxy como un usuario no root:```yaml
services:
reproxy:
user: 1001
image: umputun/reproxy:latest
# <...>
# see examples/ssl/docker-compose.yml for the full file example
Si desea utilizar el proveedor Docker, deberá asegurarse de que este usuario tenga permiso para acceder al socket de Docker en el sistema anfitrión. Cómo configurar estos permisos depende de la configuración de su sistema anfitrión. Para más información sobre la configuración de permisos del socket de Docker, consulte la documentación de Docker sobre cómo proteger el socket del demonio Docker.
Cada opción se puede proporcionar de dos formas: línea de comandos o par clave:valor de entorno. Algunas opciones de línea de comandos tienen una forma corta, como -l localhost:8080 y todas tienen la forma larga, es decir --listen=localhost:8080. La clave de entorno (nombre) enumerada para cada opción como sufijo, es decir [$LISTEN].
Todas las opciones de tamaño admiten sufijos de unidad, p. ej., 10K (o 10k) para kilobytes, 16M (o 16m) para megabytes, 10G (o 10g) para gigabytes. La ausencia de cualquier sufijo (p. ej., 1024) significa bytes.
Algunas opciones son repetibles; en este caso, el usuario puede pasarlas múltiples veces en la línea de comandos, o separadas por comas en la variable de entorno. Por ejemplo, --ssl.fqdn es una de esas opciones y se puede pasar como --ssl.fqdn=a1.example.com --ssl.fqdn=a2.example.com o como variable de entorno SSL_ACME_FQDN=a1.example.com,a2.example.com
Esta es la lista de todas las opciones que admiten múltiples elementos:
ssl.fqdn (SSL_ACME_FQDN)assets.cache (ASSETS_CACHE)docker.exclude (DOCKER_EXCLUDE)static.rule ($STATIC_RULES)header ($HEADER)drop-header ($DROP_HEADERS)-l, --listen= listen on host:port (default: 0.0.0.0:8080/8443 under docker, 127.0.0.1:80/443 without) [$LISTEN]
-m, --max= max request size (default: 64K) [$MAX_SIZE]
-g, --gzip enable gz compression [$GZIP]
-x, --header= outgoing proxy headers to add [$HEADER]
--drop-header= incoming headers to drop [$DROP_HEADERS]
--basic-htpasswd= htpasswd file for basic auth [$BASIC_HTPASSWD]
--lb-type=[random|failover|roundrobin] load balancer type (default: random) [$LB_TYPE]
--signature enable reproxy signature headers [$SIGNATURE]
--remote-lookup-headers enable remote lookup headers, trust only behind a trusted proxy [$REMOTE_LOOKUP_HEADERS]
--keep-host keep original Host header as default when proxying [$KEEP_HOST]
--insecure skip SSL verification on destination host [$INSECURE]
--dbg debug mode [$DEBUG]
ssl: --ssl.type=[none|static|auto] ssl (auto) support (default: none) [$SSL_TYPE] --ssl.cert= path to cert.pem file [$SSL_CERT] --ssl.key= path to key.pem file [$SSL_KEY] --ssl.acme-location= dir where certificates will be stored by autocert manager (default: ./var/acme) [$SSL_ACME_LOCATION] --ssl.acme-email= admin email for certificate notifications [$SSL_ACME_EMAIL] --ssl.http-port= http port for redirect to https and acme challenge test (default: 8080 under docker, 80 without) [$SSL_HTTP_PORT] --ssl.fqdn= FQDN(s) for ACME certificates [$SSL_ACME_FQDN]
assets: -a, --assets.location= assets location [$ASSETS_LOCATION] --assets.root= assets web root (default: /) [$ASSETS_ROOT] --assets.spa spa treatment for assets [$ASSETS_SPA] --assets.cache= cache duration for assets [$ASSETS_CACHE] --assets.not-found= path to file to serve on 404, relative to location [$ASSETS_NOT_FOUND]
logger: --logger.stdout enable stdout logging [$LOGGER_STDOUT] --logger.enabled enable access and error rotated logs [$LOGGER_ENABLED] --logger.file= location of access log (default: access.log) [$LOGGER_FILE] --logger.max-size= maximum size before it gets rotated (default: 100M) [$LOGGER_MAX_SIZE] --logger.max-backups= maximum number of old log files to retain (default: 10) [$LOGGER_MAX_BACKUPS]
docker: --docker.enabled enable docker provider [$DOCKER_ENABLED] --docker.host= docker host (default: unix:///var/run/docker.sock) [$DOCKER_HOST] --docker.network= docker network [$DOCKER_NETWORK] --docker.exclude= excluded containers [$DOCKER_EXCLUDE] --docker.auto enable automatic routing (without labels) [$DOCKER_AUTO] --docker.prefix= prefix for docker source routes [$DOCKER_PREFIX] --docker.api-version= docker API version (default: 1.24) [$DOCKER_API_VERSION]
consul-catalog: --consul-catalog.enabled enable consul catalog provider [$CONSUL_CATALOG_ENABLED] --consul-catalog.address= consul address (default: http://127.0.0.1:8500) [$CONSUL_CATALOG_ADDRESS] --consul-catalog.interval= consul catalog check interval (default: 1s) [$CONSUL_CATALOG_INTERVAL]
file: --file.enabled enable file provider [$FILE_ENABLED] --file.name= file name (default: reproxy.yml) [$FILE_NAME] --file.interval= file check interval (default: 3s) [$FILE_INTERVAL] --file.delay= reload only after the file has been unchanged for this long (default: 500ms) [$FILE_DELAY]
static: --static.enabled enable static provider [$STATIC_ENABLED] --static.rule= routing rules [$STATIC_RULES]
timeout: --timeout.read-header= read header server timeout (default: 5s) [$TIMEOUT_READ_HEADER] --timeout.write= write server timeout (default: 30s) [$TIMEOUT_WRITE] --timeout.idle= idle server timeout (default: 30s) [$TIMEOUT_IDLE] --timeout.dial= dial transport timeout (default: 30s) [$TIMEOUT_DIAL] --timeout.keep-alive= keep-alive transport timeout (default: 30s) [$TIMEOUT_KEEP_ALIVE] --timeout.resp-header= response header transport timeout (default: 5s) [$TIMEOUT_RESP_HEADER] --timeout.idle-conn= idle connection transport timeout (default: 90s) [$TIMEOUT_IDLE_CONN] --timeout.tls= TLS hanshake transport timeout (default: 10s) [$TIMEOUT_TLS] --timeout.continue= expect continue transport timeout (default: 1s) [$TIMEOUT_CONTINUE]
mgmt: --mgmt.enabled enable management API [$MGMT_ENABLED] --mgmt.listen= listen on host:port (default: 0.0.0.0:8081) [$MGMT_LISTEN] --mgmt.low-cardinality use route patterns instead of raw paths for metrics labels [$MGMT_LOW_CARDINALITY]
error: --error.enabled enable html errors reporting [$ERROR_ENABLED] --error.template= error message template file [$ERROR_TEMPLATE]
health-check: --health-check.enabled enable automatic health-check [$HEALTH_CHECK_ENABLED] --health-check.interval= automatic health-check interval (default: 300s) [$HEALTH_CHECK_INTERVAL]
throttle: --throttle.system= throttle overall activity' (default: 0) [$THROTTLE_SYSTEM] --throttle.user= limit req/sec per user and per proxy destination (default: 0) [$THROTTLE_USER]
upstream: --upstream.max-idle-conns= max idle connections total (default: 100) [$UPSTREAM_MAX_IDLE_CONNS] --upstream.max-conns= max connections per upstream host (0=unlimited) (default: 0) [$UPSTREAM_MAX_CONNS]
plugin: --plugin.enabled enable plugin support [$PLUGIN_ENABLED] --plugin.listen= registration listen on host:port (default: 127.0.0.1:8081) [$PLUGIN_LISTEN]
Help Options: -h, --help Show this help message
## Estado
El proyecto está en desarrollo activo y puede tener cambios importantes hasta que se lance la versión `v1`. Sin embargo, estamos haciendo todo lo posible por no romper cosas a menos que haya una buena razón. A partir de la versión 0.4.x, reproxy se considera lo suficientemente bueno para uso real, y muchas configuraciones lo están utilizando en producción.
example.com,^/login,https://api.example.com/login,,,,2 - limitación por ruta de 2 req/seg por usuario (los campos posicionales anteriores están vacíos).reproxy.keep-host - mantener el header Host tal cual (yes, true, 1) o reemplazarlo con el host de destino (no, false, 0)reproxy.forward-health-checks - reenviar solicitudes /ping y /health al backend en lugar de que reproxy las maneje (yes, true, 1). Útil cuando el backend tiene sus propios endpoints de health check con respuestas específicas de la aplicación.reproxy.timeout - tiempo de espera por ruta como duración de Go (p.ej. 5m, 30s). 0 o no establecido hereda el valor global --timeout.write. Los valores inválidos se ignoran con una advertencia.reproxy.throttle - límite de solicitudes/segundo por usuario por ruta. 0 o no establecido hereda --throttle.user. Los valores inválidos o negativos se ignoran con una advertencia.reproxy.enabled - habilitar (yes, true, 1) o deshabilitar (no, false, 0) el contenedor de los destinos de reproxy.yestrue