Instale, configure e automatize Webship.

Visão geral do produto

Um servidor entre a rede e a sua aplicação.

Webship é um Rust de borda e servidor web estático auto-hospedado. Um runtime termina protocolos modernos, aplica políticas de borda, serve ficheiros e faz proxy de pedidos de aplicações.

Início rápido

Do binário de lançamento a um listener saudável.

Começa no loopback, valida tudo antes de ligar e verifica a resposta de saúde incorporada antes de adicionar tráfego público.

1. 1

   Preparar ficheiros

   Coloque o binário de lançamento, a sua configuração TOML, a raiz estática e quaisquer ficheiros de certificado e chave TLS configurados no host.

2. 2

   Validar e inspecionar

   Execute ambos os comandos de configuração. Corrija o primeiro erro e inspecione o resultado efectivo redigido antes da inicialização.

3. 3

   Inicie de forma privada

   Inicie Webship com o ficheiro TOML selecionado. Adicione um par de certificados completo ou TLS automático quando o site estiver pronto para tráfego público seguro.

4. 4

   Verifique o runtime

   Chame GET /health localmente. Depois teste caminhos estáticos, TLS, rotas proxy, regras de segurança e monitorização autenticada.

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

Guia de Início Rápido para Agentes de IA

Ligue um agente de IA ao Webship em cinco linhas.

Ligue o Claude Code, OpenAI, DeepSeek ou qualquer cliente MCP compatível através de um túnel SSH privado. O agente recebe uma superfície de operações autenticada sem partilhar o ouvinte público ou expor credenciais de controlo ao tráfego da internet.

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

Entrega estática

Servir um directório com predefinições conscientes do protocolo.

Defina uma raiz globalmente ou por site. Sites TLS usam HTTP/3 por defeito; sites em texto claro usam HTTP/1.1 e H2C por defeito. Pode substituir HTTP/1.1, HTTP/2 e HTTP/3 independentemente para cada site.

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

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

O router integrado suporta GET e HEAD, intervalos de bytes, pedidos condicionais, validadores e sidecars .br, .zst e .gz. Caminhos de ficheiros começando por ponto são recusados por defeito; .well-known permanece disponível.

Tráfego de aplicações

Encaminhe os pedidos para um ou mais a montante.

Ativar o reverse proxy, combinar um host e um caminho, e depois definir uma política final incondicional. Webship suporta pools limitados, verificações de saúde, balanceamento de carga, disjuntores, tentativas seguras sem corpo, WebSockets e cache.

[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 Camada 4

Faça proxy do tráfego TCP e UDP sem uma rota HTTP.

A camada 4 está desativada por defeito. Defina upstreams nomeados, políticas independentes de TCP e UDP, listeners e rotas. O TCP suporta limites de conexão, verificações de integridade, balanceamento de carga, protocolo PROXY opcional e passagem ou terminação TLS. O UDP utiliza fluxos limitados e workers de recepção agrupados.

[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 rota

Construa um cache em estilo CDN limitado sem cruzar os limites do site.

O cache é configurado em cada rota de proxy inverso, não globalmente. Escolha métodos e estados seguros, limites de TTL, comportamento do CDN-Cache-Control e normalização de chave de consulta para esse site e caminho. Respostas autenticadas, personalizadas, privadas e de não armazenamento permanecem não armazenáveis por padrão.

[[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áfego local

Aplicar regras GeoIP sem um serviço de pesquisa hospedado.

Carregar dados de país, cidade e ASN a partir de bases de dados locais compatíveis com MaxMind. O GeoIP está desativado por defeito; mantenha os ficheiros da base de dados atualizados e decida se falhas de pesquisa devem negar ou contornar políticas dependentes da geolocalização antes de o ativar.

[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 correio

Encaminhe sessões de correio com controlos conscientes de protocolo.

Utilize um plano de dados de correio separado para submissão SMTP, IMAP, POP3 e encaminhamento relacionado com conhecimento de protocolo. Os ouvintes podem usar pass-through, TLS implícito ou uma atualização STARTTLS limitada. Mantenha os novos ouvintes em loopback até que a identidade upstream, certificado, autenticação e política TLS sejam verificadas.

[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 e HTTP/3

Use certificados manuais ou deixe Webship geri-los.

Desde Webship 1.4.0, cada site pode selecionar o seu modo de certificado de forma independente. HTTP/3 utiliza o ouvinte UDP correspondente; ative HTTP/1.1 ou HTTP/2 quando o mesmo site TLS 1.3 também precisar de compatibilidade 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

Arquitetura de certificados por site

Escolha a confiança do certificado e a escala independentemente para cada site.

Webship 1.4.0 move certificate_mode para cada entrada [[sites]]. ACME público por site, shards de frota pública DNS-01, a CA privada incorporada, o certificado partilhado legado e ficheiros de certificado manuais podem coexistir num único processo 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 borda

Mantenha a linha de base segura intacta.

Webship ativa as suas principais camadas de proteção por defeito. Ajuste os limites para o seu fluxo de trabalho e valide após cada alteração de regra ou política de cabeçalho.

[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'"

Use o modo normal para tráfego regular, under_attack para um tratamento mais rigoroso de ataques ativos, e lockdown quando apenas sondagens e caminhos explicitamente permitidos devem permanecer disponíveis.

Diagnósticos privados

Inspecione a borda sem expor o plano de controlo.

Estatísticas e métricas do Prometheus correm num ouvinte autenticado separado. A instrumentação deve ser ativada sempre que qualquer um dos endpoints esteja ativo.

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

Operações seguras

Recarregue deliberadamente. Mantenha o rollback próximo.

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

Otimização guiada por perfil

Colete perfis nativos do alvo sem confundir treino e produção.

Cada alvo Webship 1.5.0 tem uma CLI instrumentada separada para recolher dados de perfil LLVM nativo do alvo sob o seu tráfego representativo. Use a versão exata e o triplo do alvo, exercite as rotas e protocolos que são importantes, e pare o processo de forma adequada para que ele possa descarregar cada ficheiro .profraw.

1. 1

   Selecione o alvo exato

   Transferir a CLI de treino PGO cuja versão de lançamento e triplo de alvo Rust correspondam exatamente ao runtime que pretende otimizar. Verificar primeiro o seu SHA-256 publicado.

2. 2

   Capturar tráfego representativo

   Defina LLVM_PROFILE_FILE para um diretório gravável, inicie a CLI de treino com uma cópia validada da configuração real, reproduza o tráfego representativo direto e através do proxy inverso, e depois pare o Webship de forma controlada.

3. 3

   Mesclar perfis brutos

   Usar llvm-profdata da compilação registrada para a versão final. Mesclar cada ficheiro .profraw emitido num único ficheiro sparse webship.profdata.

4. 4

   Reconstruir e verificar

   Aplicar o perfil mesclado apenas ao código-fonte, compilador, fornecedor de criptografia, conjunto de funcionalidades e alvo que o geraram. Executar verificações de correção e desempenho antes da promoção.

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

Referência de linha de comando

Superfície pequena, arranque explícito.

webship [OPTIONS] | webship update [OPTIONS]

-c, --config PATH

Selecione o ficheiro TOML. Se não existir, Webship cria-o com uma identidade TLS privada para localhost.

--check-config

Valide a configuração completa e saia sem iniciar ouvintes.

--print-effective-config

Imprimir a configuração efetiva mesclada com os segredos removidos.

atualizar

Verificar o manifesto da comunidade assinado, selecionar este alvo de plataforma exato e instalar uma versão mais recente quando existir.

--help / --version

Imprimir a ajuda do comando ou a versão instalada do Webship.

Modos de falha comuns

Comece pela configuração e depois avance para o exterior.

1. Execute --check-config e corrija o primeiro erro reportado; campos TOML desconhecidos são rejeitados.
2. Confirme que as portas TCP e UDP configuradas estão disponíveis e permitidas pelo firewall.
3. Confirme que o certificado e a chave existem, são legíveis pela conta de serviço e formam um par correspondente.
4. Para TLS automático, confirme que cada domínio configurado resolve para o host Webship.
5. Chame /health no ouvinte da aplicação local antes de testar via DNS ou através de um caminho de carga externo.
6. Ativar a observabilidade autenticada temporariamente quando forem necessárias evidências em tempo de execução.