产品概览

网络与您的应用程序之间的一个服务器。

Webship 是一个自托管的 Rust 边缘和静态网页服务器。一个运行时终止现代协议，应用边缘策略，提供文件服务，并代理应用请求。

现代传输

接受 HTTP/1.1、HTTP/2 和 HTTP/3，并具备 TLS 1.3 和可选的 WebTransport 端点。

静态和代理传输

使用验证器和预压缩的辅助服务提供静态文件，或通过有限的上游池代理应用流量。

安全默认值

从启用 WAF、DDoS 控制、机器人挑战、响应安全头、API 盾牌和点文件保护开始。

可观测操作

使用经过身份验证的统计数据、Prometheus 指标、请求 ID、优雅重载以及可选的 MCP 控制平面。

快速开始

从发布的二进制文件到健康的监听器。

从回环地址开始，在绑定之前验证所有内容，并在添加公共流量之前验证内置健康响应。

准备文件
将发布的二进制文件、其 TOML 配置文件、静态根目录，以及任何已配置的 TLS 证书和密钥文件放到主机上。
验证并检查
运行两个配置命令。修复第一个错误，并在启动前检查已编辑的有效结果。
私下启动
使用选定的 TOML 文件启动 Webship。在网站准备好安全的公共流量时，添加完整的证书对或自动 TLS。
验证运行时
在本地调用 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

Webship 1.5.0 第4层

在没有HTTP路由的情况下代理TCP和UDP流量。

第4层默认情况下被禁用。定义命名的上游、独立的TCP和UDP策略、监听器和路由。TCP支持连接限制、健康检查、负载均衡、可选的PROXY协议，以及TLS透传或终止。UDP使用有界流和批处理接收工作线程。

TCP 和 UDP 代理监听器

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

按路由交付

构建有界的 CDN 风格缓存而不跨越站点边界。

缓存是在每个反向代理路由上配置的，而不是全局配置。为该网站和路径选择安全的方法和状态、TTL 范围、CDN-Cache-Control 行为以及查询键规范化。经过身份验证的、个性化的、私有的和 no-store 响应默认仍不可缓存。

每路由的 CDN 风格缓存策略

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

本地流量上下文

应用 GeoIP 规则而无需托管查询服务

从本地 MaxMind 兼容数据库加载国家、城市和 ASN 数据。GeoIP 默认禁用；在启用前，请保持数据库文件最新，并决定查询失败时是拒绝还是绕过依赖地理位置的策略。

本地 GeoIP 数据库配置

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

邮件协议

使用协议感知控制路由邮件会话。

对 SMTP 提交、IMAP、POP3 及相关协议感知的路由使用独立的邮件数据平面。监听器可以使用透传、隐式 TLS 或有限的 STARTTLS 升级。在上游的身份、证书、认证和 TLS 策略得到验证之前，将新监听器保持在回环地址上。

SMTP 提交透传

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

使用手动证书或让 Webship 管理它们。

自 Webship 1.4.0 起，每个站点都可以独立选择其证书模式。HTTP/3 使用匹配的 UDP 监听器；当同一个 TLS 1.3 站点还需要 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 将 certificate_mode 移到每个 [[sites]] 条目上。公共每站点 ACME、公共 DNS-01 群集分片、内置私有 CA、遗留共享证书和手动证书文件可以在一个独立的进程中共存。

per_site — 公共证书

默认选项。为网站的精确名称使用 TLS-ALPN-01 订购一个受浏览器信任的公共 ACME 证书。

机群 — 公共 DNS-01 分片

对于明确注册域下的多个三级和四级域名，使用公共 DNS-01 签发。域名保持在稳定的批量证书分片中。

嵌入式 — 私有 CA

从 Webship 的私有 CA 内部分发单独证书。无需公共 ACME 帐户、DNS 验证、注册商集成或入站 443 端口。

共享 — 遗留多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 模式处理常规流量，使用 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.5.0 目标都有一个单独的仪表化 CLI，用于在代表性流量下收集目标本地的 LLVM 配置文件数据。请使用完全相同的版本和目标三元组，执行重要的路由和协议，并优雅地停止进程，以便它可以刷新每个 .profraw 文件。

选择准确的目标
下载 PGO 训练 CLI，其发布版本和 Rust 目标三元组必须与您打算优化的运行时完全匹配。首先验证其发布的 SHA-256。
捕获代表性流量
将 LLVM_PROFILE_FILE 设置为可写目录，使用经过验证的真实配置启动训练 CLI，重放代表性的直接和反向代理流量，然后优雅地停止 Webship。
合并原始配置文件
使用为发布版本生成的编译器记录的 llvm-profdata。将每个生成的 .profraw 文件合并成一个稀疏的 webship.profdata 文件。
重建并进行检测
仅将合并的配置文件应用于生成它的确切源代码、编译器、加密提供程序、功能集和目标。在推广之前运行正确性和性能检测。

Linux、macOS 和 OpenHarmony

mkdir -p ./profiles
export LLVM_PROFILE_FILE="$PWD/profiles/webship-%p-%m.profraw"
./webship-pgo-training-1.5.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.5.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 版本。

常见失效模式

先从配置开始，然后向外扩展。

运行 --check-config 并纠正报告的第一个错误；未知的 TOML 字段将被拒绝。
确认配置好的TCP和UDP端口是否可用且防火墙允许。
确认证书和密钥存在，服务帐户可以读取，并且形成匹配的配对。
对于自动 TLS，确认每个配置的域名都解析到 Webship 主机。
在通过 DNS 或外部负载路径测试之前，调用本地应用程序监听器的 /health。
当需要运行时证据时，暂时启用认证可观测性。

安装、配置并自动化 Webship。

Webship 1.5.0现状