API
Descripci贸n general
La API de BunkerWeb es el plano de control utilizado para gestionar las instancias de BunkerWeb de forma program谩tica: listar y gestionar instancias, recargar/detener, manejar baneos, plugins, trabajos, configuraciones y m谩s. Expone una aplicaci贸n FastAPI documentada con autenticaci贸n fuerte, autorizaci贸n y limitaci贸n de velocidad.
Abre la documentaci贸n interactiva en /docs
(o <root_path>/docs
si estableciste API_ROOT_PATH
). El esquema OpenAPI est谩 disponible en /openapi.json
.
Seguridad
La API es un plano de control privilegiado. No la expongas en la Internet p煤blica sin protecciones adicionales.
Como m铆nimo, restringe las IP de origen (API_WHITELIST_IPS
), habilita la autenticaci贸n (API_TOKEN
o usuarios de API + Biscuit), y considera ponerla detr谩s de BunkerWeb con una ruta dif铆cil de adivinar y controles de acceso adicionales.
Requisitos previos
El servicio de la API requiere acceso a la base de datos de BunkerWeb (DATABASE_URI
). Generalmente se despliega junto con el Programador y opcionalmente la Interfaz de Usuario Web. La configuraci贸n recomendada es ejecutar BunkerWeb al frente como un proxy inverso y aislar la API en una red interna.
Consulta el asistente de inicio r谩pido y la gu铆a de arquitectura en la gu铆a de inicio r谩pido.
Puntos destacados
- Consciente de las instancias: transmite acciones operativas a las instancias descubiertas.
- Autenticaci贸n fuerte: B谩sica para administradores, anulaci贸n de administrador con Bearer, o ACL de Biscuit para permisos detallados.
- Lista blanca de IP y limitaci贸n de velocidad flexible por ruta.
- Se帽ales est谩ndar de salud/disponibilidad y comprobaciones de seguridad al inicio.
Plantillas de Compose
Haz un proxy inverso de la API bajo /api
con BunkerWeb.
x-bw-env: &bw-env
# Lista blanca compartida del plano de control de instancias para BunkerWeb/Scheduler
API_WHITELIST_IP: "127.0.0.0/8 10.20.30.0/24"
services:
bunkerweb:
image: bunkerity/bunkerweb:testing
ports:
- "80:8080/tcp"
- "443:8443/tcp"
- "443:8443/udp" # QUIC
environment:
<<: *bw-env
restart: unless-stopped
networks:
- bw-universe
- bw-services
bw-scheduler:
image: bunkerity/bunkerweb-scheduler:testing
environment:
<<: *bw-env
BUNKERWEB_INSTANCES: "bunkerweb" # Coincide con el nombre del servicio de la instancia
SERVER_NAME: "www.example.com"
MULTISITE: "yes"
DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db"
DISABLE_DEFAULT_SERVER: "yes"
# Proxy inverso de la API en /api
www.example.com_USE_REVERSE_PROXY: "yes"
www.example.com_REVERSE_PROXY_URL: "/api"
www.example.com_REVERSE_PROXY_HOST: "http://bw-api:8888"
volumes:
- bw-storage:/data
restart: unless-stopped
networks:
- bw-universe
- bw-db
bw-api:
image: bunkerity/bunkerweb-api:testing
environment:
DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db" # Usa una contrase帽a fuerte
API_WHITELIST_IPS: "127.0.0.0/8 10.20.30.0/24" # Lista blanca de la API
API_TOKEN: "secret" # Token de anulaci贸n de administrador opcional
API_ROOT_PATH: "/api" # Coincide con la ruta del proxy inverso
restart: unless-stopped
networks:
- bw-universe
- bw-db
bw-db:
image: mariadb:11
# Evita problemas con consultas grandes
command: --max-allowed-packet=67108864
environment:
MYSQL_RANDOM_ROOT_PASSWORD: "yes"
MYSQL_DATABASE: "db"
MYSQL_USER: "bunkerweb"
MYSQL_PASSWORD: "changeme" # Usa una contrase帽a fuerte
volumes:
- bw-data:/var/lib/mysql
restart: unless-stopped
networks:
- bw-db
volumes:
bw-data:
bw-storage:
networks:
bw-universe:
name: bw-universe
ipam:
driver: default
config:
- subnet: 10.20.30.0/24
bw-services:
name: bw-services
bw-db:
name: bw-db
Lo mismo que arriba pero aprovechando el servicio Autoconf para descubrir y configurar servicios autom谩ticamente. La API se expone bajo /api
usando etiquetas en el contenedor de la API.
x-api-env: &api-env
AUTOCONF_MODE: "yes"
DATABASE_URI: "mariadb+pymysql://bunkerweb:changeme@bw-db:3306/db" # Usa una contrase帽a fuerte
services:
bunkerweb:
image: bunkerity/bunkerweb:testing
ports:
- "80:8080/tcp"
- "443:8443/tcp"
- "443:8443/udp" # QUIC
environment:
AUTOCONF_MODE: "yes"
API_WHITELIST_IP: "127.0.0.0/8 10.20.30.0/24"
restart: unless-stopped
networks:
- bw-universe
- bw-services
bw-scheduler:
image: bunkerity/bunkerweb-scheduler:testing
environment:
<<: *api-env
BUNKERWEB_INSTANCES: "" # Descubierto por Autoconf
SERVER_NAME: "" # Rellenado a trav茅s de etiquetas
MULTISITE: "yes" # Obligatorio con Autoconf
API_WHITELIST_IP: "127.0.0.0/8 10.20.30.0/24"
volumes:
- bw-storage:/data
restart: unless-stopped
networks:
- bw-universe
- bw-db
bw-autoconf:
image: bunkerity/bunkerweb-autoconf:testing
depends_on:
- bunkerweb
- bw-docker
environment:
<<: *api-env
DOCKER_HOST: "tcp://bw-docker:2375"
restart: unless-stopped
networks:
- bw-universe
- bw-docker
- bw-db
bw-api:
image: bunkerity/bunkerweb-api:testing
environment:
<<: *api-env
API_WHITELIST_IPS: "127.0.0.0/8 10.20.30.0/24"
API_TOKEN: "secret"
API_ROOT_PATH: "/api"
labels:
- "bunkerweb.SERVER_NAME=www.example.com"
- "bunkerweb.USE_REVERSE_PROXY=yes"
- "bunkerweb.REVERSE_PROXY_URL=/api"
- "bunkerweb.REVERSE_PROXY_HOST=http://bw-api:8888"
restart: unless-stopped
networks:
- bw-universe
- bw-db
bw-db:
image: mariadb:11
command: --max-allowed-packet=67108864
environment:
MYSQL_RANDOM_ROOT_PASSWORD: "yes"
MYSQL_DATABASE: "db"
MYSQL_USER: "bunkerweb"
MYSQL_PASSWORD: "changeme"
volumes:
- bw-data:/var/lib/mysql
restart: unless-stopped
networks:
- bw-db
bw-docker:
image: tecnativa/docker-socket-proxy:nightly
environment:
CONTAINERS: "1"
LOG_LEVEL: "warning"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
restart: unless-stopped
networks:
- bw-docker
volumes:
bw-data:
bw-storage:
networks:
bw-universe:
name: bw-universe
ipam:
driver: default
config:
- subnet: 10.20.30.0/24
bw-services:
name: bw-services
bw-db:
name: bw-db
bw-docker:
name: bw-docker
Ruta del proxy inverso
Mant茅n la ruta de la API dif铆cil de adivinar y comb铆nala con la lista blanca de la API y la autenticaci贸n.
Si ya expones otra aplicaci贸n en el mismo nombre de servidor con una plantilla (p. ej., USE_TEMPLATE
), prefiere un nombre de host separado para la API para evitar conflictos.
Todo en Uno
Si utilizas la imagen Todo en Uno, la API se puede habilitar estableciendo SERVICE_API=yes
:
docker run -d \
--name bunkerweb-aio \
-e SERVICE_API=yes \
-e API_WHITELIST_IPS="127.0.0.0/8" \
-p 80:8080/tcp -p 443:8443/tcp -p 443:8443/udp \
bunkerity/bunkerweb-all-in-one:testing
Autenticaci贸n
Formas admitidas para autenticar solicitudes:
- Administrador B谩sico: Cuando las credenciales pertenecen a un usuario de API administrador, los puntos finales protegidos aceptan
Authorization: Basic <base64(nombredeusuario:contrase帽a)>
. - Anulaci贸n de Administrador con Bearer: Si se configura
API_TOKEN
,Authorization: Bearer <API_TOKEN>
otorga acceso completo. - Token Biscuit (recomendado): Obt茅n un token desde
POST /auth
utilizando credenciales B谩sicas o un cuerpo JSON/formulario que contengausername
ypassword
. Utiliza el token devuelto comoAuthorization: Bearer <token>
en llamadas posteriores.
Ejemplo: obtener un Biscuit, listar instancias y luego recargar todas las instancias.
# 1) Obtener un token Biscuit con credenciales de administrador
TOKEN=$(curl -s -X POST -u admin:changeme http://api.example.com/auth | jq -r .token)
# 2) Listar instancias
curl -H "Authorization: Bearer $TOKEN" http://api.example.com/instances
# 3) Recargar la configuraci贸n en todas las instancias (sin prueba)
curl -X POST -H "Authorization: Bearer $TOKEN" \
"http://api.example.com/instances/reload?test=no"
Hechos y comprobaciones de Biscuit
Los tokens incorporan hechos como user(<username>)
, client_ip(<ip>)
, domain(<host>)
, y un rol general role("api_user", ["read", "write"])
derivado de los permisos de la base de datos. Los administradores incluyen admin(true)
mientras que los no administradores llevan hechos detallados como api_perm(<resource_type>, <resource_id|*>, <permission>)
.
La autorizaci贸n mapea la ruta/m茅todo a los permisos requeridos; admin(true)
siempre pasa. Cuando los hechos detallados est谩n ausentes, la guarda recurre al rol general: GET/HEAD/OPTIONS requieren read
; los verbos de escritura requieren write
.
Las claves se almacenan en /var/lib/bunkerweb/.api_biscuit_private_key
y /var/lib/bunkerweb/.api_biscuit_public_key
. Tambi茅n puedes proporcionar BISCUIT_PUBLIC_KEY
/BISCUIT_PRIVATE_KEY
a trav茅s de variables de entorno; si no se establecen ni archivos ni variables de entorno, la API genera un par de claves al inicio y lo persiste de forma segura.
Permisos (ACL)
Esta API soporta dos capas de autorizaci贸n:
- Rol general: Los tokens llevan
role("api_user", ["read"[, "write"]])
para los puntos finales sin un mapeo detallado. Lectura se mapea a GET/HEAD/OPTIONS; escritura se mapea a POST/PUT/PATCH/DELETE. - ACL detallada: Los tokens incorporan
api_perm(<resource_type>, <resource_id|*>, <permission>)
y las rutas declaran lo que requieren.admin(true)
omite todas las comprobaciones.
Tipos de recursos admitidos: instances
, global_config
, services
, configs
, plugins
, cache
, bans
, jobs
.
Nombres de permisos por tipo de recurso:
- instances:
instances_read
,instances_update
,instances_delete
,instances_create
,instances_execute
- global_config:
global_config_read
,global_config_update
- services:
service_read
,service_create
,service_update
,service_delete
,service_convert
,service_export
- configs:
configs_read
,config_read
,config_create
,config_update
,config_delete
- plugins:
plugin_read
,plugin_create
,plugin_delete
- cache:
cache_read
,cache_delete
- bans:
ban_read
,ban_update
,ban_delete
,ban_created
- jobs:
job_read
,job_run
ID de recursos: Para comprobaciones detalladas, el segundo segmento de la ruta se trata como resource_id
cuando tiene sentido. Ejemplos: /services/{service}
-> {service}
; /configs/{service}/...
-> {service}
. Usa "*"
(u omite) para otorgar globalmente para un tipo de recurso.
Configuraci贸n de usuario y ACL:
- Usuario administrador: Establece
API_USERNAME
yAPI_PASSWORD
para crear el primer administrador al inicio. Para rotar las credenciales m谩s tarde, estableceOVERRIDE_API_CREDS=yes
(o aseg煤rate de que el administrador fue creado con el m茅todomanual
). Solo existe un administrador; los intentos adicionales recurren a la creaci贸n de no administradores. - Usuarios no administradores y concesiones: Proporciona
API_ACL_BOOTSTRAP_FILE
apuntando a un archivo JSON, o monta/var/lib/bunkerweb/api_acl_bootstrap.json
. La API lo lee al inicio para crear/actualizar usuarios y permisos. - Archivo de cach茅 de ACL: Se escribe un resumen de solo lectura en
/var/lib/bunkerweb/api_acl.json
al inicio para introspecci贸n; la autorizaci贸n eval煤a las concesiones respaldadas por la base de datos incorporadas en el token Biscuit.
Ejemplos de JSON de arranque (se admiten ambas formas):
{
"users": {
"ci": {
"admin": false,
"password": "Str0ng&P@ss!",
"permissions": {
"services": {
"*": { "service_read": true },
"app-frontend": { "service_update": true, "service_delete": false }
},
"configs": {
"app-frontend": { "config_read": true, "config_update": true }
}
}
},
"ops": {
"admin": false,
"password_hash": "$2b$13$...bcrypt-hash...",
"permissions": {
"instances": { "*": { "instances_execute": true } },
"jobs": { "*": { "job_run": true } }
}
}
}
}
O en formato de lista:
{
"users": [
{
"username": "ci",
"password": "Str0ng&P@ss!",
"permissions": [
{ "resource_type": "services", "resource_id": "*", "permission": "service_read" },
{ "resource_type": "services", "resource_id": "app-frontend", "permission": "service_update" }
]
}
]
}
Notas:
- Las contrase帽as pueden ser texto plano (
password
) o bcrypt (password_hash
/password_bcrypt
). Las contrase帽as de texto plano d茅biles son rechazadas en compilaciones que no son de depuraci贸n; si faltan, se genera una aleatoria y se registra una advertencia. resource_id: "*"
(o nulo/vac铆o) otorga globalmente sobre ese tipo de recurso.- Las contrase帽as de los usuarios existentes pueden actualizarse y se pueden aplicar concesiones adicionales a trav茅s del arranque.
Referencia de caracter铆sticas
La API est谩 organizada por enrutadores centrados en recursos. Utiliza las secciones a continuaci贸n como un mapa de capacidades; el esquema interactivo en /docs
documenta los modelos de solicitud/respuesta en detalle.
N煤cleo y autenticaci贸n
GET /ping
,GET /health
: sondas de actividad ligeras para el propio servicio de la API.POST /auth
: intercambia credenciales B谩sicas (o el token de anulaci贸n de administrador) por un Biscuit. Acepta JSON, formulario o cabecerasAuthorization
. Los administradores tambi茅n pueden continuar usando HTTP Basic directamente en rutas protegidas cuando lo deseen.
Plano de control de instancias
GET /instances
: lista las instancias registradas, incluyendo marcas de tiempo de creaci贸n/煤ltima vez visto, m茅todo de registro y metadatos.POST /instances
: registra una nueva instancia gestionada por la API (nombre de host, puerto opcional, nombre de servidor, nombre amigable, m茅todo).GET /instances/{hostname}
/PATCH /instances/{hostname}
/DELETE /instances/{hostname}
: inspecciona, actualiza campos mutables o elimina instancias gestionadas por la API.DELETE /instances
: eliminaci贸n masiva; omite las instancias que no son de la API y las informa enskipped
.GET /instances/ping
yGET /instances/{hostname}/ping
: comprobaciones de salud en todas o en instancias individuales.POST /instances/reload?test=yes|no
,POST /instances/{hostname}/reload
: activa la recarga de la configuraci贸n (el modo de prueba realiza una validaci贸n de ejecuci贸n en seco).POST /instances/stop
,POST /instances/{hostname}/stop
: retransmite comandos de detenci贸n a las instancias.
Configuraci贸n global
GET /global_config
: obtiene configuraciones no predeterminadas (usafull=true
para la configuraci贸n completa,methods=true
para incluir la procedencia).PATCH /global_config
: actualiza o inserta configuraciones globales propiedad de la API (method="api"
); los errores de validaci贸n se帽alan claves desconocidas o de solo lectura.
Ciclo de vida del servicio
GET /services
: enumera los servicios con metadatos, incluido el estado de borrador y las marcas de tiempo.GET /services/{service}
: recupera las superposiciones no predeterminadas (full=false
) o la instant谩nea completa de la configuraci贸n (full=true
) para un servicio.POST /services
: crea servicios, opcionalmente como borrador, y siembra variables con prefijo ({service}_{KEY}
). Actualiza la listaSERVER_NAME
at贸micamente.PATCH /services/{service}
: renombra servicios, cambia los indicadores de borrador y actualiza las variables con prefijo. Ignora las ediciones directas aSERVER_NAME
dentro devariables
por seguridad.DELETE /services/{service}
: elimina un servicio y sus claves de configuraci贸n derivadas.POST /services/{service}/convert?convert_to=online|draft
: cambia r谩pidamente el estado borrador/en l铆nea sin alterar otras variables.
Fragmentos de configuraci贸n personalizados
GET /configs
: lista fragmentos de configuraci贸n personalizados (HTTP/servidor/stream/ModSecurity/ganchos CRS) para un servicio (service=global
por defecto).with_data=true
incrusta contenido UTF-8 cuando es imprimible.POST /configs
yPOST /configs/upload
: crea nuevos fragmentos a partir de cargas 煤tiles JSON o archivos subidos. Los tipos aceptados incluyenhttp
,server_http
,default_server_http
,modsec
,modsec_crs
,stream
,server_stream
, y ganchos de plugins CRS. Los nombres deben coincidir con^[\w_-]{1,64}$
.GET /configs/{service}/{type}/{name}
: recupera un fragmento con contenido opcional (with_data=true
).PATCH /configs/{service}/{type}/{name}
yPATCH .../upload
: actualiza o mueve fragmentos gestionados por la API; las entradas gestionadas por plantilla o archivo permanecen de solo lectura.DELETE /configs
yDELETE /configs/{service}/{type}/{name}
: elimina fragmentos gestionados por la API conservando los gestionados por plantilla, devolviendo una listaskipped
para las entradas ignoradas.
Orquestaci贸n de baneos
GET /bans
: agrega los baneos activos informados por todas las instancias.POST /bans
oPOST /bans/ban
: aplica uno o varios baneos. Las cargas 煤tiles pueden ser objetos JSON, matrices o JSON en formato de cadena.service
es opcional; cuando se omite, el baneo es global.POST /bans/unban
oDELETE /bans
: elimina baneos globalmente o por servicio utilizando las mismas cargas 煤tiles flexibles.
Gesti贸n de plugins
GET /plugins?type=all|external|ui|pro
: lista plugins con metadatos;with_data=true
incluye los bytes empaquetados cuando est谩n disponibles.POST /plugins/upload
: instala plugins de UI desde archivos.zip
,.tar.gz
o.tar.xz
. Los archivos pueden agrupar m煤ltiples plugins siempre que cada uno contenga unplugin.json
.DELETE /plugins/{id}
: elimina un plugin de UI por ID (^[\w.-]{4,64}$
).
Cach茅 y ejecuci贸n de trabajos
GET /cache
: lista los artefactos en cach茅 producidos por los trabajos del programador, filtrados por servicio, ID de plugin o nombre de trabajo.with_data=true
incluye contenido de archivo imprimible.GET /cache/{service}/{plugin}/{job}/{file}
: obtiene un archivo de cach茅 espec铆fico (download=true
transmite un archivo adjunto).DELETE /cache
oDELETE /cache/{service}/{plugin}/{job}/{file}
: elimina archivos de cach茅 y notifica al programador sobre los plugins afectados.GET /jobs
: inspecciona trabajos conocidos, sus metadatos de programaci贸n y res煤menes de cach茅.POST /jobs/run
: solicita la ejecuci贸n de un trabajo marcando el(los) plugin(s) asociado(s) como cambiado(s).
Notas operativas
- Los puntos finales de escritura persisten en la base de datos compartida; las instancias recogen los cambios a trav茅s de la sincronizaci贸n del programador o despu茅s de un
/instances/reload
. - Los errores se normalizan a
{ "status": "error", "message": "..." }
con los c贸digos de estado HTTP apropiados (422 validaci贸n, 404 no encontrado, 403 ACL, 5xx fallos de origen).
Limitaci贸n de velocidad
La limitaci贸n de velocidad por cliente es manejada por SlowAPI. Habil铆tala/deshabil铆tala y configura los l铆mites a trav茅s de variables de entorno o /etc/bunkerweb/api.yml
.
API_RATE_LIMIT_ENABLED
(predeterminado:yes
)- L铆mite predeterminado:
API_RATE_LIMIT_TIMES
porAPI_RATE_LIMIT_SECONDS
(p. ej.,100
por60
) API_RATE_LIMIT_RULES
: JSON/CSV en l铆nea, o una ruta a un archivo YAML/JSON con reglas por ruta- Backend de almacenamiento: en memoria o Redis/Valkey cuando
USE_REDIS=yes
y se proporcionan las variablesREDIS_*
(compatible con Sentinel) - Cabeceras:
API_RATE_LIMIT_HEADERS_ENABLED
(predeterminado:yes
)
Ejemplo de YAML (montado en /etc/bunkerweb/api.yml
):
yaml
API_RATE_LIMIT_ENABLED: yes
API_RATE_LIMIT_DEFAULTS: ["200/minute"]
API_RATE_LIMIT_RULES:
- path: "/auth"
methods: "POST"
times: 10
seconds: 60
- path: "/instances*"
methods: "GET|POST"
times: 100
seconds: 60
Configuraci贸n
Puedes configurar la API a trav茅s de variables de entorno, secretos de Docker y los archivos opcionales /etc/bunkerweb/api.yml
o /etc/bunkerweb/api.env
. Configuraciones clave:
- Documentaci贸n y esquema:
API_DOCS_URL
,API_REDOC_URL
,API_OPENAPI_URL
,API_ROOT_PATH
. - Autenticaci贸n b谩sica:
API_TOKEN
(Bearer de anulaci贸n de administrador),API_USERNAME
/API_PASSWORD
(crear/actualizar administrador),OVERRIDE_API_CREDS
. - ACL y usuarios:
API_ACL_BOOTSTRAP_FILE
(ruta JSON). - Pol铆tica de Biscuit:
API_BISCUIT_TTL_SECONDS
(0/desactivado deshabilita el TTL),CHECK_PRIVATE_IP
(vincula el token a la IP del cliente a menos que sea privada). - Lista blanca de IP:
API_WHITELIST_ENABLED
,API_WHITELIST_IPS
. - Limitaci贸n de velocidad (n煤cleo):
API_RATE_LIMIT_ENABLED
,API_RATE_LIMIT_TIMES
,API_RATE_LIMIT_SECONDS
,API_RATE_LIMIT_HEADERS_ENABLED
. - Limitaci贸n de velocidad (avanzado):
API_RATE_LIMIT_AUTH_TIMES
,API_RATE_LIMIT_AUTH_SECONDS
,API_RATE_LIMIT_RULES
,API_RATE_LIMIT_DEFAULTS
,API_RATE_LIMIT_APPLICATION_LIMITS
,API_RATE_LIMIT_STRATEGY
,API_RATE_LIMIT_KEY
,API_RATE_LIMIT_EXEMPT_IPS
,API_RATE_LIMIT_STORAGE_OPTIONS
. - Almacenamiento de limitaci贸n de velocidad: en memoria o Redis/Valkey cuando
USE_REDIS=yes
y se establecen configuraciones de Redis comoREDIS_HOST
,REDIS_PORT
,REDIS_PASSWORD
,REDIS_DATABASE
,REDIS_SSL
, o variables de Sentinel. Consulta la tabla de configuraciones de Redis endocs/features.md
. - Red/TLS:
API_LISTEN_ADDR
,API_LISTEN_PORT
,API_FORWARDED_ALLOW_IPS
,API_SSL_ENABLED
,API_SSL_CERTFILE
,API_SSL_KEYFILE
,API_SSL_CA_CERTS
.
C贸mo se carga la configuraci贸n
Precedencia de mayor a menor:
- Variables de entorno (p. ej.,
environment:
del contenedor o variables de shell exportadas) - Archivos de secretos en
/run/secrets
(secretos de Docker/K8s; los nombres de archivo coinciden con los nombres de las variables) - Archivo YAML en
/etc/bunkerweb/api.yml
- Archivo de entorno en
/etc/bunkerweb/api.env
(l铆neas clave=valor) - Valores predeterminados incorporados
Notas:
- YAML admite la inserci贸n de archivos de secretos con
<file:relative/path>
; la ruta se resuelve contra/run/secrets
. - Establece las URL de la documentaci贸n en
off
/disabled
/none
para deshabilitar los puntos finales (p. ej.,API_DOCS_URL=off
). - Si
API_SSL_ENABLED=yes
, tambi茅n debes establecerAPI_SSL_CERTFILE
yAPI_SSL_KEYFILE
. - Si Redis est谩 habilitado (
USE_REDIS=yes
), proporciona los detalles de Redis; consulta la secci贸n de Redis endocs/features.md
.
Autenticaci贸n y usuarios
- Arranque de administrador: establece
API_USERNAME
yAPI_PASSWORD
para crear el primer administrador. Para volver a aplicar m谩s tarde, estableceOVERRIDE_API_CREDS=yes
. - No administradores y permisos: proporciona
API_ACL_BOOTSTRAP_FILE
con una ruta JSON (o monta en/var/lib/bunkerweb/api_acl_bootstrap.json
). El archivo puede listar usuarios y concesiones detalladas. - Claves de Biscuit: establece
BISCUIT_PUBLIC_KEY
/BISCUIT_PRIVATE_KEY
o monta archivos en/var/lib/bunkerweb/.api_biscuit_public_key
y/var/lib/bunkerweb/.api_biscuit_private_key
. Si no se proporciona ninguno, la API genera y persiste un par de claves al inicio.
TLS y redes
- Direcci贸n/puerto de enlace:
API_LISTEN_ADDR
(predeterminado0.0.0.0
),API_LISTEN_PORT
(predeterminado8888
). - Proxies inversos: establece
API_FORWARDED_ALLOW_IPS
en las IP del proxy para que Gunicorn conf铆e en las cabecerasX-Forwarded-*
. - Terminaci贸n de TLS en la API:
API_SSL_ENABLED=yes
m谩sAPI_SSL_CERTFILE
yAPI_SSL_KEYFILE
; opcionalAPI_SSL_CA_CERTS
Recetas r谩pidas de limitaci贸n de velocidad
- Deshabilitar globalmente:
API_RATE_LIMIT_ENABLED=no
- Establecer un l铆mite global simple:
API_RATE_LIMIT_TIMES=100
,API_RATE_LIMIT_SECONDS=60
- Reglas por ruta: establece
API_RATE_LIMIT_RULES
en una ruta de archivo JSON/YAML o YAML en l铆nea en/etc/bunkerweb/api.yml
.
Seguridad de inicio
La API se cierra si no hay una ruta de autenticaci贸n configurada (sin claves Biscuit, sin usuario administrador y sin API_TOKEN
). Aseg煤rate de que al menos un m茅todo est茅 configurado antes de iniciar.
Seguridad de inicio: La API se cierra si no hay una ruta de autenticaci贸n disponible (sin claves Biscuit, sin usuario de API administrador y sin API_TOKEN
). Aseg煤rate de que al menos una est茅 configurada.
Ruta ra铆z y proxies
Si despliegas la API detr谩s de BunkerWeb en una subruta, establece API_ROOT_PATH
en esa ruta para que /docs
y las rutas relativas funcionen correctamente cuando se usan con un proxy.
Operaciones
- Salud:
GET /health
devuelve{"status":"ok"}
cuando el servicio est谩 activo. - Servicio de Linux: se empaqueta una unidad
systemd
llamadabunkerweb-api.service
. Personaliza a trav茅s de/etc/bunkerweb/api.env
y gestiona consystemctl
. - Seguridad de inicio: la API falla r谩pidamente cuando no hay una ruta de autenticaci贸n disponible (sin claves Biscuit, sin usuario administrador, sin
API_TOKEN
). Los errores se escriben en/var/tmp/bunkerweb/api.error
.