Instale, configure e automatize Webship.

Visão geral do produto

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

Webship é uma Rust de borda auto-hospedada e servidor web estático. Um runtime termina protocolos modernos, aplica políticas de borda, serve arquivos e faz proxy de solicitações de aplicativos.

Início rápido

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

Inicie no loopback, valide tudo antes de ligar, e verifique a resposta de saúde embutida antes de adicionar tráfego público.

1. 1

   Preparar arquivos

   Coloque o binário de lançamento, sua configuração TOML, a raiz estática e quaisquer arquivos 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 efetivo com informações ocultas antes da inicialização.

3. 3

   Iniciar de forma privada

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

4. 4

   Verifique o runtime

   Chame GET /health localmente. Em seguida, teste caminhos estáticos, TLS, rotas de proxy, regras de segurança e monitoramento 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

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

Conecte um agente de IA ao Webship em cinco linhas.

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

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

Entrega estática

Sirva um diretório com padrões conscientes do protocolo.

Defina uma raiz globalmente ou por site. Sites TLS padrão para HTTP/3 apenas; sites em texto claro padrão para HTTP/1.1 e H2C. Substitua HTTP/1.1, HTTP/2 e HTTP/3 de forma independente 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 roteador embutido suporta GET e HEAD, intervalos de bytes, solicitações condicionais, validadores e arquivos auxiliares .br, .zst e .gz. Caminhos de arquivos iniciados por ponto (dot-files) são recusados por padrão; .well-known permanece disponível.

Tráfego de aplicação

Encaminhe requisições para um ou mais upstreams.

Habilite o proxy reverso, combine um host e caminho, e então defina uma política final incondicional. Webship suporta pools limitados, verificações de integridade, balanceamento de carga, circuit breakers, retentativas seguras sem corpo, WebSockets e caching.

[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

TLS e HTTP/3

Use certificados manuais ou deixe Webship gerenciá-los.

Webship aceita TLS 1.3. HTTP/3 roda sobre o listener UDP correspondente; habilite HTTP/1.1 ou HTTP/2 explicitamente quando um site TLS também precisar de compatibilidade com 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"

Política de borda

Mantenha a linha de base segura intacta.

Webship habilita suas principais camadas de proteção por padrão. Ajuste os limites para sua carga 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 manuseio mais rigoroso de ataques ativos e lockdown quando apenas sondas e caminhos explicitamente permitidos devem permanecer disponíveis.

Diagnósticos privados

Inspecione a borda sem expor o plano de controle.

Estatísticas e métricas do Prometheus rodam em um listener autenticado separado. A instrumentação deve estar habilitada sempre que qualquer um dos endpoints estiver 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 a reversão próxima.

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 treinamento e produção.

Cada Webship alvo 1.1 possui um CLI instrumentado separado para coletar dados de perfil LLVM nativos do alvo sob seu tráfego representativo. Use a versão exata e o triplo de destino, exercite as rotas e protocolos que importam e pare o processo de forma adequada para que ele possa gravar todos os arquivos .profraw.

1. 1

   Selecione o alvo exato

   Baixe o CLI de treinamento PGO cuja versão de release e triplo de destino Rust correspondam exatamente ao runtime que você pretende otimizar. Verifique primeiro seu SHA-256 publicado.

2. 2

   Capturar tráfego representativo

   Defina LLVM_PROFILE_FILE para um diretório gravável, inicie o CLI de treinamento com uma cópia validada da configuração real, reproduza o tráfego representativo direto e via proxy reverso, e então pare o Webship de forma adequada.

3. 3

   Mesclar perfis brutos

   Use llvm-profdata da geração do compilador registrada para o release. Mescle cada arquivo .profraw emitido em um único arquivo sparse webship.profdata.

4. 4

   Reconstruir e verificar

   Aplique o perfil mesclado somente ao código-fonte exato, compilador, provedor de criptografia, conjunto de recursos e alvo que o geraram. Execute 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.2.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.2.0-<target>.exe --config .\webship.toml

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

Referência da linha de comando

Superfície pequena, inicialização explícita.

webship [OPTIONS] | webship update [OPTIONS]

-c, --config CAMINHO

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

--check-config

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

--print-effective-config

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

update

Verifique o manifesto da comunidade assinado, selecione este alvo de plataforma exato e instale uma versão mais recente quando existir.

--help / --version

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

Modos comuns de falha

Comece pela configuração e depois vá para fora.

1. Execute --check-config e corrija o primeiro erro relatado; campos TOML desconhecidos são rejeitados.
2. Confirme se as portas TCP e UDP configuradas estão disponíveis e permitidas pelo firewall.
3. Confirme se 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 se cada domínio configurado resolve para o host Webship.
5. Chame /health no ouvinte de aplicação local antes de testar através do DNS ou de um caminho de carga externo.
6. Habilite a observabilidade autenticada temporariamente quando evidências em tempo de execução forem necessárias.