Instalar, configurar y automatizar Webship.

Resumen del producto

Un servidor entre la red y su aplicación.

Webship es un Rust de borde y servidor web estático autohospedado. Un runtime termina protocolos modernos, aplica políticas de borde, sirve archivos y realiza proxy de solicitudes de aplicaciones.

Inicio rápido

Desde el binario de lanzamiento hasta un oyente saludable.

Inicia en loopback, valida todo antes de enlazar y verifica la respuesta de salud incorporada antes de agregar tráfico público.

1. 1

   Preparar archivos

   Coloque el binario de la versión, su configuración TOML, la raíz estática y cualquier archivo de certificado y clave TLS configurados en el host.

2. 2

   Validar e inspeccionar

   Ejecute ambos comandos de configuración. Corrija el primer error e inspeccione el resultado efectivo redactado antes del inicio.

3. 3

   Iniciar de forma privada

   Inicie Webship con el archivo TOML seleccionado. Agregue un par completo de certificados o TLS automático cuando el sitio esté listo para tráfico público seguro.

4. 4

   Verifica el tiempo de ejecución

   Llama a GET /health localmente. Luego prueba rutas estáticas, TLS, rutas de proxy, reglas de seguridad y monitoreo autenticado.

listen = "127.0.0.1:4433"
workers = 4
root = "./public"

/usr/local/bin/webship --check-config --config /etc/webship/production.toml
/usr/local/bin/webship --print-effective-config --config /etc/webship/production.toml

/usr/local/bin/webship --config /etc/webship/production.toml
curl --http3-only --insecure https://127.0.0.1:4433/health

Guía de inicio rápido para agentes de IA

Conecta un agente de IA a Webship en cinco líneas.

Conecta Claude Code, OpenAI, DeepSeek o cualquier cliente compatible con MCP a través de un túnel SSH privado. El agente recibe una superficie de operaciones autenticada sin compartir el listener público ni exponer credenciales de control al tráfico de Internet.

{
  "mcpServers": {
    "webship": { "url": "https://localhost:19443/mcp",
      "headers": { "Authorization": "Bearer <token>" } }
  } }

Entrega estática

Servir un directorio con valores predeterminados conscientes del protocolo.

Establece una raíz de manera global o por sitio. Los sitios TLS por defecto usan HTTP/3 solamente; los sitios en texto claro usan por defecto HTTP/1.1 y H2C. Sobrescribe HTTP/1.1, HTTP/2 y HTTP/3 de manera independiente para cada sitio.

[[sites]]
domain = "app.example.com"
root = "/srv/app"
listen = "0.0.0.0:443"

[sites.protocols]
h1 = true
h2 = true
h3 = true

El router incorporado soporta GET y HEAD, rangos de bytes, solicitudes condicionales, validadores y archivos auxiliares .br, .zst y .gz. Por defecto se rechazan las rutas de archivos con punto (dot-files); .well-known permanece disponible.

Tráfico de la aplicación

Enrutar solicitudes a uno o más upstreams.

Habilita el proxy inverso, coincide con un host y ruta, y luego define una política final incondicional. Webship admite grupos limitados, comprobaciones de salud, balanceo de carga, disyuntores, reintentos seguros sin cuerpo, WebSockets y almacenamiento en caché.

[reverse_proxy]
enabled = true

[[reverse_proxy.routes]]
domain = "app.example.com"
path_prefix = "/api"
strip_path_prefix = true
upstreams = ["127.0.0.1:8080", "127.0.0.1:8081"]

[[reverse_proxy.policies]]
name = "default"
hosts = []
path_prefixes = ["/"]
methods = []
max_body_bytes = 1048576
total_timeout_ms = 30000

Webship 1.5.0 Capa 4

Hacer proxy del tráfico TCP y UDP sin una ruta HTTP.

La capa 4 está deshabilitada por defecto. Defina upstreams con nombre, políticas TCP y UDP independientes, listeners y rutas. TCP admite límites de conexión, comprobaciones de estado, balanceo de carga, protocolo PROXY opcional y paso o terminación de TLS. UDP utiliza flujos acotados y trabajadores de recepción por lotes.

[layer4]
enabled = true

[[layer4.tcp_policies]]
name = "edge-tcp"
max_connections = 10000
idle_timeout_ms = 300000

[[layer4.udp_policies]]
name = "edge-udp"
max_flows = 20000
receive_batch_size = 32

[[layer4.upstreams]]
name = "origin-a"
address = "127.0.0.1:9443"
weight = 100

[[layer4.tcp]]
name = "tls-tunnel"
listen = "127.0.0.1:10443"
policy = "edge-tcp"
tls_mode = "passthrough"

[[layer4.tcp.routes]]
name = "default"
default = true
upstreams = ["origin-a"]
load_balancing = "weighted-peak-ewma"

[[layer4.udp]]
name = "datagrams"
listen = "127.0.0.1:10443"
policy = "edge-udp"

[[layer4.udp.routes]]
name = "default"
default = true
upstreams = ["origin-a"]

Entrega por ruta

Construya una caché estilo CDN limitada sin cruzar los límites del sitio.

La caché se configura en cada ruta de proxy inverso, no de manera global. Elija métodos y estados seguros, límites de TTL, comportamiento de CDN-Cache-Control y normalización de clave de consulta para ese sitio y ruta. Las respuestas autenticadas, personalizadas, privadas y de no-almacenamiento permanecen no almacenables en caché por defecto.

[[reverse_proxy.routes]]
domain = "assets.example.com"
path_prefix = "/assets"
upstreams = ["127.0.0.1:8080"]

[reverse_proxy.routes.cache]
enabled = true
cacheable_methods = ["GET", "HEAD", "QUERY"]
cacheable_statuses = [200, 203, 204, 206, 301, 404, 410]
default_ttl_ms = 60000
max_ttl_ms = 86400000
honor_cdn_cache_control = true
query_mode = "ignore-listed"
ignored_query_parameters = ["utm_*", "fbclid"]

Contexto de tráfico local

Aplicar reglas GeoIP sin un servicio de búsqueda alojado.

Cargar datos de país, ciudad y ASN desde bases de datos locales compatibles con MaxMind. GeoIP está desactivado por defecto; mantén los archivos de la base de datos actualizados y decide si los fallos de búsqueda deben denegar o ignorar la política dependiente de la geolocalización antes de habilitarlo.

[geoip]
enabled = true
country_db = "/var/lib/webship/geo/country.mmdb"
city_db = "/var/lib/webship/geo/city.mmdb"
asn_db = "/var/lib/webship/geo/asn.mmdb"
failure_mode = "deny"

Protocolos de correo

Enrute las sesiones de correo con controles conscientes del protocolo.

Utilice el plano de datos de correo separado para el envío SMTP, IMAP, POP3 y el enrutamiento consciente de protocolos relacionado. Los escuchas pueden usar paso a través, TLS implícito o una actualización STARTTLS acotada. Mantenga los nuevos escuchas en loopback hasta que se verifiquen la identidad ascendente, el certificado, la autenticación y la política de TLS.

[mail]
enabled = true

[[mail.upstreams]]
name = "submission-a"
address = "127.0.0.1:2465"
protocol = "smtp-submission"
security = "plain"

[[mail.listeners]]
name = "submissions"
listen = "127.0.0.1:1465"
protocol = "smtp-submission"
client_security = "passthrough"
upstreams = ["submission-a"]
load_balancing = "weighted-least-requests"

TLS y HTTP/3

Utilice certificados manuales o deje que Webship los gestione.

Desde Webship 1.4.0, cada sitio puede seleccionar su modo de certificado de manera independiente. HTTP/3 utiliza el listener UDP correspondiente; habilite HTTP/1.1 o HTTP/2 cuando el mismo sitio TLS 1.3 también necesite compatibilidad con TCP.

listen = "0.0.0.0:443"

[automatic_tls]
enabled = true
directory_url = "https://acme-v02.api.letsencrypt.org/directory"
cache_dir = "/var/lib/webship/acme"
contacts = ["mailto:ops@example.com"]
accept_terms_of_service = true

[[sites]]
domain = "app.example.com"
root = "/srv/app"
certificate_mode = "per_site" # default public ACME certificate

[[sites]]
domain = "legacy.example.com"
root = "/srv/legacy"
certificate_mode = "shared" # legacy public multi-SAN certificate

Arquitectura de certificados por sitio

Elija la confianza y la escala del certificado de manera independiente para cada sitio.

Webship 1.4.0 mueve certificate_mode a cada entrada [[sites]]. ACME público por sitio, fragmentos de flota DNS-01 pública, la CA privada integrada, el certificado compartido heredado y los archivos de certificado manuales pueden coexistir en un solo proceso autónomo.

[automatic_tls]
enabled = true
directory_url = "https://acme-v02.api.letsencrypt.org/directory"
cache_dir = "/var/lib/webship/acme"
contacts = ["mailto:ops@example.com"]
accept_terms_of_service = true

[automatic_tls.fleet]
shard_size = 64
batch_window_ms = 300000
weekly_certificate_limit = 50
emergency_certificate_reserve = 5
registered_domains = ["example.com"]

[automatic_tls.fleet.dns]
listen = "0.0.0.0:53"
nameservers = ["ns1.example.net"]
addresses = ["192.0.2.10"]
propagation_timeout_ms = 120000
resolver_url = "https://dns.google/resolve"
challenge_ttl_seconds = 900

[[sites]]
domain = "app.example.com"
root = "/srv/app"
certificate_mode = "fleet"

[[sites]]
domain = "media.app.example.com"
root = "/srv/media"
certificate_mode = "fleet"

[automatic_tls]
enabled = true
cache_dir = "/var/lib/webship/acme"

[acme_ca]
state_dir = "/var/lib/webship/acme-ca"
leaf_validity_days = 90

[[sites]]
domain = "internal.example.com"
root = "/srv/internal"
certificate_mode = "embedded"

Política de borde

Mantén la línea base de seguridad intacta.

Webship activa sus principales capas de protección por defecto. Ajuste los límites para su carga de trabajo y valide después de cada cambio de regla o política de encabezado.

[ddos]
enabled = true
mode = "normal"
requests_per_minute = 600
burst = 100
block_seconds = 300

[security.response_headers]
enabled = true
nosniff = true
frame_deny = true
referrer_no_referrer = true
hsts = "max-age=31536000; includeSubDomains"
content_security_policy = "default-src 'self'; frame-ancestors 'none'"

Usa el modo normal para el tráfico regular, bajo_ataque para un manejo más estricto de ataques activos, y bloqueo cuando solo deberían permanecer disponibles las sondas y las rutas explícitamente permitidas.

Diagnósticos privados

Inspeccione el borde sin exponer el plano de control.

Las estadísticas y métricas de Prometheus se ejecutan en un receptor autenticado separado. La instrumentación debe estar habilitada siempre que cualquiera de los endpoints esté activo.

[observability]
instrumentation = true
stats = true
metrics = true
listen = "127.0.0.1:9090"
token = "replace-with-at-least-32-random-printable-ascii-characters"

Operaciones seguras

Recargue deliberadamente. Mantenga cerca la reversión.

kill -HUP "$(pidof webship)"
/usr/local/bin/webship update --config /etc/webship/production.toml
sudo systemctl daemon-reload
sudo systemctl enable --now webship
sudo systemctl status webship

Optimización guiada por perfil

Recoge perfiles nativos del objetivo sin confundir entrenamiento y producción.

Cada objetivo Webship 1.5.0 tiene un CLI instrumentado separado para recopilar datos de perfil LLVM nativo del objetivo bajo su tráfico representativo. Use la versión exacta y el triple de objetivo, ejercite las rutas y protocolos que importan, y detenga el proceso de manera ordenada para que pueda volcar cada archivo .profraw.

1. 1

   Selecciona el objetivo exacto

   Descargar la CLI de entrenamiento PGO cuya versión de lanzamiento y triple de destino Rust coincidan exactamente con el tiempo de ejecución que deseas optimizar. Verificar primero su SHA-256 publicado.

2. 2

   Capturar tráfico representativo

   Establezca LLVM_PROFILE_FILE a un directorio escribible, inicie la CLI de entrenamiento con una copia validada de la configuración real, reproduzca tráfico representativo directo y de proxy inverso, luego detenga Webship de manera controlada.

3. 3

   Combinar perfiles en bruto

   Usar llvm-profdata del compilador generado grabado para la versión de lanzamiento. Combinar cada archivo .profraw emitido en un solo archivo sparse webship.profdata.

4. 4

   Reconstruir y controlar

   Aplicar el perfil combinado únicamente al código fuente, compilador, proveedor de criptografía, conjunto de funciones y objetivo exactos que lo generaron. Ejecutar controles de corrección y rendimiento antes de la promoción.

mkdir -p ./profiles
export LLVM_PROFILE_FILE="$PWD/profiles/webship-%p-%m.profraw"
./webship-pgo-training-1.5.0-<target> --config ./webship.toml

New-Item -ItemType Directory -Force ./profiles
$env:LLVM_PROFILE_FILE = "$PWD/profiles/webship-%p-%m.profraw"
.\webship-pgo-training-1.5.0-<target>.exe --config .\webship.toml

llvm-profdata merge -sparse ./profiles/*.profraw -o ./webship.profdata

Referencia de línea de comandos

Superficie pequeña, inicio explícito.

webship [OPTIONS] | webship update [OPTIONS]

-c, --config PATH

Seleccione el archivo TOML. Si no existe, Webship lo crea con una identidad TLS privada de localhost.

--check-config

Valida la configuración completa y finaliza sin iniciar los listeners.

--print-effective-config

Imprima la configuración efectiva combinada con los secretos eliminados.

actualizar

Verifique el manifiesto de la comunidad firmado, seleccione este objetivo de plataforma exacto e instale una versión más reciente cuando exista.

--help / --version

Imprima la ayuda del comando o la versión instalada de Webship.

Modos de falla comunes

Comience con la configuración, luego expándase hacia afuera.

1. Ejecute --check-config y corrija el primer error informado; los campos TOML desconocidos son rechazados.
2. Confirme que los puertos TCP y UDP configurados estén disponibles y permitidos por el firewall.
3. Confirme que el certificado y la clave existen, son legibles por la cuenta de servicio y forman un par coincidente.
4. Para TLS automático, confirme que cada dominio configurado se resuelve al host Webship.
5. Llame a /health en el oyente de la aplicación local antes de probar a través de DNS o una ruta de carga externa.
6. Habilitar la observabilidad autenticada temporalmente cuando se requiera evidencia en tiempo de ejecución.