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

製品概要

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

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

クイックスタート

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

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

1. 1

   ファイルを準備する

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

2. 2

   検証および確認

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

3. 3

   非公開で起動する

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

4. 4

   ランタイムを確認します

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

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トンネル経由で接続します。エージェントは、パブリックリスナーを共有したり、制御資格情報をインターネットトラフィックにさらすことなく、認証された操作サーフェスを受け取ります。

{
  "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、およびキャッシュをサポートします。

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

エッジポリシー

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

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

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

安全な操作

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

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 [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. ランタイム証拠が必要な場合に、一時的に認証付きオブザーバビリティを有効にします。