Installeer, stel in en automatiseer Webship.

Productoverzicht

Één server tussen het netwerk en uw applicatie.

Webship is een zelfgehoste Rust edge- en statische webserver. Eén runtime beëindigt moderne protocollen, past edge-beleid toe, levert bestanden en proxyt applicatieverzoeken.

Snelle start

Van release-binaire naar gezonde listener.

Start op loopback, valideer alles voordat je bindt, en verifieer de ingebouwde health-respons voordat je publiek verkeer toevoegt.

1. 1

   Bereid bestanden voor

   Plaats het release-binary, het TOML-configuratiebestand, de statische root, en eventuele geconfigureerde TLS-certificaat- en sleutelbestanden op de host.

2. 2

   Valideer en inspecteer

   Voer beide configuratie-opdrachten uit. Los de eerste fout op en controleer het geanonimiseerde effectieve resultaat voordat je start.

3. 3

   Privé starten

   Start Webship met het geselecteerde TOML-bestand. Voeg een volledig certificaatpaar of automatische TLS toe wanneer de site klaar is voor veilig openbaar verkeer.

4. 4

   Verifieer de runtime

   Roep lokaal GET /health aan. Test daarna statische paden, TLS, proxyroutes, beveiligingsregels en geverifieerde monitoring.

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

Snelle startgids voor AI-agents

Verbind een AI-agent met Webship in vijf regels.

Verbind Claude Code, OpenAI, DeepSeek of een andere compatibele MCP-client via een privé SSH-tunnel. De agent ontvangt een geverifieerde operationele interface zonder de openbare luisteraar te delen of controlegegevens bloot te stellen aan internetverkeer.

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

Statische levering

Dien een directory met protocol-bewuste standaardinstellingen.

Stel een root globaal of per website in. TLS-sites standaard naar HTTP/3; niet-versleutelde sites standaard naar HTTP/1.1 en H2C. Overschrijf HTTP/1.1, HTTP/2 en HTTP/3 onafhankelijk voor elke site.

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

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

De ingebouwde router ondersteunt GET en HEAD, byte-ranges, voorwaardelijke verzoeken, validators en .br, .zst en .gz bijlagen. Paden naar dot-bestanden worden standaard geweigerd; .well-known blijft beschikbaar.

Applicatieverkeer

Routeer aanvragen naar een of meer upstreams.

Schakel reverse proxy in, stem een host en pad af, en definieer vervolgens een uiteindelijke onvoorwaardelijke policy. Webship ondersteunt begrensde pools, health checks, load balancing, circuit breakers, veilige bodyloze retries, WebSockets en 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

Webship 1.5.0 Laag 4

Proxy TCP- en UDP-verkeer zonder een HTTP-route.

Laag 4 is standaard uitgeschakeld. Definieer benoemde upstreams, onafhankelijke TCP- en UDP-beleidsregels, luisteraars en routes. TCP ondersteunt verbindingslimieten, health checks, load balancing, optioneel PROXY-protocol en TLS pass-through of terminatie. UDP gebruikt beperkte stromen en gebatchte ontvangstwerkers.

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

Per-route levering

Bouw een begrensde CDN-stijl cache zonder sitegrenzen te overschrijden.

Cache is geconfigureerd op elke reverse-proxy route, niet globaal. Kies veilige methoden en statussen, TTL-grenzen, CDN-Cache-Control gedrag en query-sleutel normalisatie voor die site en pad. Geauthenticeerde, gepersonaliseerde, privé en no-store reacties blijven standaard niet-cachebaar.

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

Lokale verkeerscontext

Pas GeoIP-regels toe zonder een gehoste opzoeksdienst.

Laad land-, stad- en ASN-gegevens vanuit lokale MaxMind-compatibele databases. GeoIP is standaard uitgeschakeld; houd de databasebestanden actueel en beslis of zoekfouten geo-afhankelijke regels moeten weigeren of overslaan voordat je het inschakelt.

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

Mailprotocollen

Router mail-sessies met protocolbewuste controles.

Gebruik het aparte mailgegevenskanaal voor SMTP-submissie, IMAP, POP3 en aanverwante protocolbewuste routering. Luisteraars kunnen pass-through, impliciete TLS of een begrensde STARTTLS-upgrade gebruiken. Houd nieuwe luisteraars op loopback totdat upstream-identiteit, certificaat, authenticatie en TLS-beleid zijn geverifieerd.

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

Gebruik handmatige certificaten of laat Webship ze beheren.

Sinds Webship 1.4.0 kan elke site zijn certificaatmodus onafhankelijk kiezen. HTTP/3 gebruikt de bijbehorende UDP-listener; schakel HTTP/1.1 of HTTP/2 in wanneer dezelfde TLS 1.3-site ook TCP-compatibiliteit nodig heeft.

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

Per-site certificaatarchitectuur

Kies certificaatvertrouwen en schaal onafhankelijk voor elke site.

Webship 1.4.0 verplaatst certificate_mode naar elke [[sites]]-vermelding. Publieke per-site ACME, publieke DNS-01 fleet shards, de ingebouwde private CA, het legacy gedeelde certificaat en handmatige certificaatbestanden kunnen naast elkaar bestaan in één zelfstandig proces.

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

Edge-beleid

Houd de veilige basislijn intact.

Webship schakelt standaard zijn belangrijkste beschermingslagen in. Stel limieten af voor je workload en valideer na elke wijziging van regels of header-beleid.

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

Gebruik normale modus voor regulier verkeer, under_attack voor strengere actieve-aanvalsafhandeling, en lockdown wanneer alleen probes en expliciet toegestane paden beschikbaar moeten blijven.

Privédiagnostiek

Inspecteer de edge zonder het controlevlak bloot te stellen.

Statistieken en Prometheus-metrieken draaien op een aparte geverifieerde listener. Instrumentatie moet worden ingeschakeld wanneer een van de eindpunten actief is.

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

Veilige bewerkingen

Laad bewust opnieuw. Houd rollback dichtbij.

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

Profielgestuurde optimalisatie

Verzamel doel-native profielen zonder training en productie te verwarren.

Elke Webship 1.5.0 target heeft een aparte geïnstrumenteerde CLI voor het verzamelen van target native LLVM-profielgegevens onder je representatieve verkeer. Gebruik de exacte versie en target triple, oefen de routes en protocollen die ertoe doen, en stop het proces soepel zodat elk .profraw-bestand kan worden gecleard.

1. 1

   Selecteer het exacte target

   Download de PGO-trainings-CLI waarvan de releaseversie en Rust target triple exact overeenkomen met de runtime die je wilt optimaliseren. Verifieer eerst de gepubliceerde SHA-256.

2. 2

   Vang representatief verkeer op

   Stel LLVM_PROFILE_FILE in op een schrijfbare map, start het trainings-CLI met een gevalideerde kopie van de echte configuratie, speel representatief direct en reverse-proxy verkeer opnieuw af, en stop dan Webship netjes.

3. 3

   Ruwe profielen samenvoegen

   Gebruik llvm-profdata van de compiler generatie die is opgenomen voor de release. Voeg elk uitgegeven .profraw-bestand samen tot één sparce webship.profdata-bestand.

4. 4

   Herbouwen en gate

   Pas het samengevoegde profiel alleen toe op de exacte bron, compiler, crypto-provider, functieset en target die het heeft gegenereerd. Voer correctheids- en prestaties-gates uit voordat je promoot.

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

Commandoreferentie

Kleine oppervlakte, expliciete opstart.

webship [OPTIONS] | webship update [OPTIONS]

-c, --config PATH

Selecteer het TOML-bestand. Als het niet bestaat, maakt Webship het aan met een private localhost TLS-identiteit.

--check-config

Valideer de volledige configuratie en sluit af zonder listeners te starten.

--print-effective-config

Druk de samengevoegde effectieve configuratie af met verwijderde geheimen.

update

Verifieer het ondertekende communitymanifest, selecteer dit exacte platformdoel en installeer een nieuwere versie wanneer deze beschikbaar is.

--help / --version

Druk de hulp bij het commando af of de geïnstalleerde Webship-versie.

Veelvoorkomende foutmodi

Begin met de configuratie en werk dan naar buiten.

1. Voer --check-config uit en corrigeer de eerst gemelde fout; onbekende TOML-velden worden geweigerd.
2. Controleer of de geconfigureerde TCP- en UDP-poorten beschikbaar zijn en toegestaan door de firewall.
3. Bevestig dat het certificaat en de sleutel bestaan, door het serviceaccount leesbaar zijn, en een bij elkaar passend paar vormen.
4. Voor automatische TLS, bevestig dat elk geconfigureerd domein naar de Webship host resolveert.
5. Bel /health op de lokale applicatieluisteraar voordat je test via DNS of een externe laadroute.
6. Schakel tijdelijk geauthenticeerde observeerbaarheid in wanneer runtimebewijs vereist is.