Webship 文件

安裝、配置並自動化 Webship。

使用簡明的 TOML 範例和版本固定的操作指南，配置、驗證、部署並自動化 AI 原生 Webship 邊緣伺服器。

文件版本

Webship 1.2.0當前

已發佈 2026-09-04。此 URL 已固定到所選發布版本。

預設監聽器
127.0.0.1:4433
設定
TOML
TLS
TLS 1.3

產品概覽

網路和您的應用程式之間的一台伺服器。

Webship 是一個自托管的 Rust 邊緣和靜態網頁伺服器。一個運行時終止現代協議，應用邊緣策略，提供文件，並代理應用請求。

現代傳輸

接受 HTTP/1.1、HTTP/2 以及 HTTP/3，並使用 TLS 1.3 及可選的 WebTransport 端點。

靜態與代理傳遞

使用驗證器和預壓縮的輔助程式提供靜態文件服務，或通過受限的上游池代理應用流量。

安全預設值

啟用 WAF、DDoS 控制、機器人挑戰、回應安全標頭、API Shield 以及點文件保護。

可觀察的操作

使用驗證的統計資料、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。

透過私人 SSH 通道連接 Claude Code、OpenAI、DeepSeek 或任何相容的 MCP 客戶端。代理接收經認證的操作介面，而不需要分享公共監聽器或將控制憑證暴露給網際網路流量。

五行 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 路徑保持可用。

應用程式流量

將請求路由到一個或多個上游。

啟用反向代理，匹配主機和路徑，然後定義最終的無條件策略。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 接受 TLS 1.3。HTTP/3 在匹配的 UDP 監聽器上運行；當 TLS 網站也需 TCP 相容時，請明確啟用 HTTP/1.1 或 HTTP/2。

使用 TLS-ALPN-01 的自動 TLS
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 與回應標頭策略
[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'"

對於一般流量使用普通模式，對於嚴格的主動攻擊處理使用 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.1 目標都有一個獨立的指令列工具，用於在您的代表性流量下收集目標原生的 LLVM 分析資料。請使用完全相同的版本與目標三元組，執行重要的路由和協議，並優雅地停止進程，以便能夠刷新每個 .profraw 檔案。

  1. 選擇精確的目標

    下載 PGO 訓練 CLI，其發布版本和 Rust 目標三元組與您打算優化的運行時完全匹配。首先驗證其發布的 SHA-256。

  2. 捕捉代表性流量

    將 LLVM_PROFILE_FILE 設定為可寫入的目錄，使用經驗證的實際配置啟動訓練指令列，重放代表性的直接及反向代理流量，然後優雅地停止 Webship。

  3. 合併原始配置文件

    使用編譯器生成的 llvm-profdata，該生成已為發布版本記錄。將每個生成的 .profraw 文件合併成一個稀疏的 webship.profdata 文件。

  4. 重建並進行檢查

    僅對生成它的精確源代碼、編譯器、加密提供程序、功能集和目標應用合併後的配置文件。在推廣前運行正確性和性能檢查。

Linux、macOS 和 OpenHarmony
mkdir -p ./profiles
export LLVM_PROFILE_FILE="$PWD/profiles/webship-%p-%m.profraw"
./webship-pgo-training-1.2.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.2.0-<target>.exe --config .\webship.toml
與相符的 LLVM 工具鏈合併
llvm-profdata merge -sparse ./profiles/*.profraw -o ./webship.profdata

命令列參考

小面積，明確啟動。

webship [OPTIONS] | webship update [OPTIONS]

-c, --config 路徑
選擇 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. 在需要運行時證據時，臨時啟用已驗證的可觀察性。