Webship 文档

安装、配置并自动化 Webship。

使用简明的 TOML 示例和版本固定的操作指南，配置、验证、部署并自动化 AI 原生 Webship 边缘服务器。

文档版本

Webship 1.2.0现状

2026-09-04年发布。该网址被置顶到所选版本。

默认监听器
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 盾牌和点文件保护开始。

可观测操作

使用经过身份验证的统计数据、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 支持有界池、健康检查、负载均衡、断路器、安全的无正文重试、WebSockets 和缓存。

双上游 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'"

使用 normal 模式处理常规流量，使用 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 目标都有一个单独的工具化 CLI，用于在您的代表性流量下收集目标本地 LLVM 配置文件数据。使用确切的版本和目标三元组，执行重要的路由和协议，并优雅地停止进程，以便它能刷新每个 .profraw 文件。

  1. 选择准确的目标

    下载 PGO 训练 CLI，其发布版本和 Rust 目标三元组必须与您打算优化的运行时完全匹配。首先验证其发布的 SHA-256。

  2. 捕获代表性流量

    将 LLVM_PROFILE_FILE 设置为可写目录，使用经过验证的真实配置启动训练 CLI，重放代表性的直接和反向代理流量，然后优雅地停止 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 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. 当需要运行时证据时，暂时启用认证可观测性。