Webship ドキュメント

Webship をインストール、構成、および自動化する。

簡潔なTOML例とバージョン固定の運用ガイドに従って、AIネイティブWebshipエッジサーバーを構成、検証、デプロイ、および自動化します。

ドキュメントバージョン

Webship 1.4.0現在

2026-09-13 をリリース済み。このURLは選択したリリースに固定されています。

デフォルトリスナー
127.0.0.1:4433
設定
TOML
TLS
TLS 1.3

製品概要

ネットワークとアプリケーションの間に1つのサーバー。

Webshipはセルフホスト型のRustエッジおよび静的ウェブサーバーです。1つのランタイムが、最新のプロトコルを終了し、エッジポリシーを適用し、ファイルを提供し、アプリケーションリクエストをプロキシします。

最新のトランスポート

HTTP/1.1、HTTP/2、HTTP/3を受け入れ、TLS 1.3およびオプションのWebTransportエンドポイントを使用します。

静的およびプロキシ配信

バリデーターと事前圧縮されたサイドカーで静的ファイルを提供するか、制限されたアップストリームプールを介してアプリケーショントラフィックをプロキシします。

安全なデフォルト設定

WAF、DDoS対策、ボットチャレンジ、レスポンスセキュリティヘッダー、APIシールド、ドットファイル保護を有効にして開始します。

可観測な操作

認証済み統計、Prometheusメトリクス、リクエストID、グレースフルリロード、およびオプションのMCPコントロールプレーンを使用します。

クイックスタート

リリースバイナリから正常に動作するリスナーへ。

ループバックで開始し、バインドする前にすべてを検証し、パブリックトラフィックを追加する前に組み込みのヘルスレスポンスを確認します。

  1. ファイルを準備する

    リリースバイナリ、そのTOML設定、静的ルート、および設定されたTLS証明書とキーのファイルをホストに配置します。

  2. 検証および確認

    両方の設定コマンドを実行します。最初のエラーを修正し、起動前にマスクされた有効な結果を確認します。

  3. 非公開で起動する

    選択したTOMLファイルでWebshipを起動します。サイトが安全な公開トラフィックに対応できるようになったら、完全な証明書ペアまたは自動TLSを追加します。

  4. ランタイムを確認します

    ローカルで GET /health を呼び出します。その後、静的パス、TLS、プロキシルート、セキュリティルール、認証済み監視をテストします。

最小限のconfig.toml
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

AIエージェントのクイックスタートガイド

AIエージェントを五行でWebshipに接続する

Claude Code、OpenAI、DeepSeek、または互換性のあるMCPクライアントをプライベートSSHトンネル経由で接続します。エージェントは、パブリックリスナーを共有したり、制御資格情報をインターネットトラフィックにさらすことなく、認証された操作サーフェスを受け取ります。

五行のMCPクライアント設定
{
  "mcpServers": {
    "webship": { "url": "https://localhost:19443/mcp",
      "headers": { "Authorization": "Bearer <token>" } }
  } }

静的配信

プロトコル対応のデフォルトでディレクトリを提供します。

グローバルまたはサイトごとにルートを設定してください。TLS サイトはデフォルトで HTTP/3 のみを使用し、平文サイトはデフォルトで HTTP/1.1 と H2C を使用します。HTTP/1.1、HTTP/2、HTTP/3 は各サイトごとに独立して上書き可能です。

ドメイン固有の静的サイト
[[sites]]
domain = "app.example.com"
root = "/srv/app"
listen = "0.0.0.0:443"

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

内蔵ルーターは GET および HEAD、バイトレンジ、条件付きリクエスト、バリデータ、そして .br、.zst、.gz のサイドカーをサポートしています。ドットファイルのパスはデフォルトで拒否されますが、.well-known は利用可能なままです。

アプリケーショントラフィック

リクエストを1つ以上のアップストリームにルーティングします。

リバースプロキシを有効にし、ホストとパスを一致させ、最終的に無条件のポリシーを定義します。Webship は、バウンデッドプール、ヘルスチェック、ロードバランシング、サーキットブレーカー、安全なボディなしリトライ、WebSocket、およびキャッシュをサポートします。

二重アップストリーム API ルート
[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 と HTTP/3

手動証明書を使用するか、Webship に管理させてください。

Webship 1.4.0 は TLS 1.3 を受け入れ、各サイトが独自に証明書モードを選択できるようにします。HTTP/3 は対応する UDP リスナーを使用します；同じ TLS サイトで TCP 互換性も必要な場合は HTTP/1.1 または HTTP/2 を有効にしてください。

レガシー共有サイトを持つサイトごとのデフォルトパブリック
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

Webship 1.4.0証明書アーキテクチャ

各サイトに対して証明書の信頼性とスケールを独立して選択してください。

Webship 1.4.0では、certificate_modeが各[[sites]]エントリに移動しました。パブリックのサイトごとのACME、パブリックDNS-01フリートシャード、組み込みのプライベートCA、レガシーの共有証明書、手動証明書ファイルは、1つの自己完結型プロセスで共存できます。

per_site — 公的証明書

デフォルト。TLS-ALPN-01でサイトの正確な名前に対して、ブラウザに信頼される公的ACME証明書を1つ注文します。

フリート — 公的DNS-01シャード

明示的に登録されたドメインの下の多数の三次および四次レベル名について、公的なDNS-01発行を使用します。名前は安定したバッチ化された証明書シャードのままです。

組み込み — プライベートCA

Webship のプライベートCAからプロセス内で別の証明書を発行します。公開ACMEアカウント、DNSチャレンジ、レジストラ統合、または着信ポート443は不要です。

shared — レガシー複数SAN

レガシーのパブリック複数SANグループは、必要なデプロイメントのために維持してください。これはデフォルトではなく、引き続きパブリックCAの識別子制限の対象となります。

自己完結型のパブリックDNS-01フリート
[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"
プライベート組み込みCAサイト
[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"

エッジポリシー

セキュアなベースラインを維持してください。

Webship はデフォルトで主要な保護レイヤーを有効にします。ワークロードに応じて制限を調整し、ルールやヘッダーポリシーを変更するたびに検証してください。

DDoS およびレスポンスヘッダーポリシー
[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'"

通常の通信には normal モードを使用し、strict なアクティブ攻撃対策には under_attack を使用、プローブや明示的に許可されたパスのみを残す場合は lockdown を使用します。

プライベート診断

コントロールプレーンを公開せずにエッジを検査してください。

統計および Prometheus メトリクスは別の認証済みリスナーで実行されます。どちらかのエンドポイントが有効な場合は、計測を有効にする必要があります。

認証済みローカルオブザーバビリティ
[observability]
instrumentation = true
stats = true
metrics = true
listen = "127.0.0.1:9090"
token = "replace-with-at-least-32-random-printable-ascii-characters"

安全な操作

意図的にリロードしてください。ロールバックを近くに保ってください。

設定のリロード

ファイルベースの設定を編集した後に SIGHUP を送信します。Webship はインストール前に置き換えを検証し、検証に失敗した場合は現在の設定を保持します。

アップグレードとロールバック

新しいバイナリを前のバージョンの横にインストールし、それで本番構成を検証してから、正常性、TLS、プロキシ、メトリクスを確認してください。すべてのゲートが通過するまで前のバイナリを保持します。

再読み込みと systemd コマンド
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

プロファイルガイド最適化

トレーニングと本番環境を混同せずに、ターゲットネイティブのプロファイルを収集します。

各Webship 1.4.0ターゲットには、代表的なトラフィック下でターゲットネイティブLLVMプロファイルデータを収集するための個別に計装されたCLIがあります。正確なバージョンとターゲットトリプルを使用し、重要なルートとプロトコルを実行し、すべての.profrawファイルをフラッシュできるようにプロセスを正常に停止してください。

  1. 正確なターゲットを選択してください

    最適化したいランタイムと正確に一致するリリースバージョンおよび Rust ターゲットトリプルを持つ PGO トレーニング CLI をダウンロードします。まず公開されている SHA-256 を確認します。

  2. 代表的なトラフィックをキャプチャする

    LLVM_PROFILE_FILE を書き込み可能なディレクトリに設定し、実際の構成の検証済みコピーでトレーニングCLIを起動し、代表的なダイレクトおよびリバースプロキシトラフィックをリプレイしてから、Webship を正常に停止してください。

  3. 生のプロファイルをマージする

    リリース用に生成されたコンパイラからの llvm-profdata を使用します。出力されたすべての .profraw ファイルを 1 つの sparse webship.profdata ファイルにマージします。

  4. 再構築してゲートを適用する

    マージされたプロファイルは、それを生成した正確なソース、コンパイラ、暗号プロバイダ、機能セット、およびターゲットにのみ適用します。昇格前に正確性とパフォーマンスのゲートを実行します。

Linux、macOS、および OpenHarmony
mkdir -p ./profiles
export LLVM_PROFILE_FILE="$PWD/profiles/webship-%p-%m.profraw"
./webship-pgo-training-1.4.0-<target> --config ./webship.toml
Windows PowerShell
New-Item -ItemType Directory -Force ./profiles
$env:LLVM_PROFILE_FILE = "$PWD/profiles/webship-%p-%m.profraw"
.\webship-pgo-training-1.4.0-<target>.exe --config .\webship.toml
対応するLLVMツールチェーンとマージ
llvm-profdata merge -sparse ./profiles/*.profraw -o ./webship.profdata

コマンドラインリファレンス

小さなサーフェス、明示的な起動。

webship [OPTIONS] | webship update [OPTIONS]

-c, --config PATH
TOMLファイルを選択します。存在しない場合、Webship がプライベートなローカルホストTLSアイデンティティで作成します。
--check-config
構成全体を検証し、リスナーを開始せずに終了します。
--print-effective-config
シークレットを除外した統合された有効な設定を表示します。
update
署名されたコミュニティマニフェストを検証し、この正確なプラットフォームターゲットを選択し、新しいバージョンが存在する場合はインストールします。
--help / --version
コマンドヘルプまたはインストールされている Webship のバージョンを表示します。

一般的な故障モード

まず構成から始め、次に外側に進みます。

  1. --check-config を実行し、最初に報告されたエラーを修正してください。未知の TOML フィールドは拒否されます。
  2. 設定されたTCPおよびUDPポートが利用可能であり、ファイアウォールで許可されていることを確認してください。
  3. 証明書とキーが存在し、サービスアカウントによって読み取れること、そして一致するペアであることを確認してください。
  4. 自動 TLS の場合、設定されたすべてのドメインが Webship ホストに解決されることを確認してください。
  5. DNS や外部ロードパスを通してテストする前に、ローカルアプリケーションリスナーで /health を呼び出してください。
  6. ランタイム証拠が必要な場合に、一時的に認証付きオブザーバビリティを有効にします。