Установите, настройте и автоматизируйте Webship.

Обзор продукта

Один сервер между сетью и вашим приложением.

Webship — это самоуправляемый Rust край и статический веб-сервер. Один среда выполнения завершает современные протоколы, применяет политику на краю, обслуживает файлы и проксирует запросы приложений.

Быстрый старт

От бинарного релиза до работающего слушателя.

Запускайте на loopback, проверяйте всё перед привязкой и проверяйте встроенный ответ состояния до добавления публичного трафика.

1. 1

   Подготовьте файлы

   Разместите бинарный файл релиза, его конфигурацию TOML, статический корень и любые настроенные файлы сертификата и ключа TLS на хосте.

2. 2

   Проверяйте и осматривайте

   Выполните обе команды конфигурации. Исправьте первую ошибку и проверьте скрытый фактический результат перед запуском.

3. 3

   Запуск в приватном режиме

   Запустите Webship с выбранным файлом TOML. Добавьте полный комплект сертификатов или автоматический 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>" } }
  } }

Статическая доставка

Обслуживайте каталог с настройками по умолчанию, которые учитывают протокол.

Установите root глобально или для каждого сайта. 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 остается доступным.

Трафик приложения

Маршрутизируйте запросы к одному или нескольким upstream'ам.

Включите обратное проксирование, сопоставьте хост и путь, затем определите итоговую безусловную политику. Webship поддерживает ограниченные пулы, проверки состояния, балансировку нагрузки, прерыватели цепи, безопасные повторные попытки без тела, WebSockets и кэширование.

[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

Проксировать TCP и UDP трафик без HTTP маршрута.

Слой 4 по умолчанию отключен. Определите именованные апстримы, независимые политики TCP и UDP, слушатели и маршруты. TCP поддерживает ограничения соединений, проверки состояния, балансировку нагрузки, необязательный протокол PROXY и TLS с пропуском или завершением. 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 по умолчанию остаются некэшируемыми.

[[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 без использования хостингового сервиса поиска.

Загружайте данные о стране, городе и ASN из локальных баз данных, совместимых с MaxMind. 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. Держите новые слушатели на loopback до тех пор, пока не будут проверены идентификатор источника, сертификат, аутентификация и политика TLS.

[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-листенер; включайте HTTP/1.1 или HTTP/2, когда такой же сайт TLS 1.3 также требует совместимости с TCP.

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, устаревший общий сертификат и ручные файлы сертификатов могут сосуществовать в одном автономном процессе.

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

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

Безопасные операции

Перезагружайте сознательно. Держите откат под рукой.

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 напрямую с цели под вашим представительным трафиком. Используйте точную версию и target triple, проверяйте маршруты и протоколы, которые имеют значение, и корректно завершайте процесс, чтобы были сброшены все файлы .profraw.

1. 1

   Выберите точную целевую платформу

   Скачайте PGO CLI для обучения, версия релиза и тройка целей Rust которого точно совпадает с временем выполнения, которое вы намерены оптимизировать. Сначала проверьте его опубликованный SHA-256.

2. 2

   Захватите репрезентативный трафик

   Установите LLVM_PROFILE_FILE в директорию с правами на запись, запустите тренировочный CLI с проверенной копией реальной конфигурации, воспроизведите репрезентативный прямой и обратный прокси-трафик, затем корректно остановите Webship.

3. 3

   Объедините сырые профили

   Используйте llvm-profdata из компиляции, созданной для релиза. Объедините каждый сгенерированный .profraw файл в один разреженный файл webship.profdata.

4. 4

   Пересборка и проверка

   Применяйте объединённый профиль только к точному исходному коду, компилятору, криптопровайдеру, набору функций и цели, которые его сгенерировали. Проведите проверки правильности и производительности перед публикацией.

mkdir -p ./profiles
export LLVM_PROFILE_FILE="$PWD/profiles/webship-%p-%m.profraw"
./webship-pgo-training-1.5.0-<target> --config ./webship.toml

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-profdata merge -sparse ./profiles/*.profraw -o ./webship.profdata

Справка по командной строке

Малый интерфейс, явный запуск.

webship [OPTIONS] | webship update [OPTIONS]

-c, --config PATH

Выберите файл TOML. Если он не существует, Webship создаст его с приватным удостоверением TLS для localhost.

--check-config

Проверьте полную конфигурацию и завершите работу без запуска прослушивателей.

--print-effective-config

Вывести объединённую эффективную конфигурацию без секретов.

update

Проверить подписанный манифест сообщества, выбрать эту точную целевую платформу и установить более новую версию, если она существует.

--help / --version

Вывести помощь по команде или установленную версию Webship.

Общие режимы отказа

Начните с конфигурации, затем двигайтесь наружу.

1. Запустите --check-config и исправьте первую выявленную ошибку; неизвестные поля TOML отклоняются.
2. Подтвердите, что настроенные TCP и UDP порты доступны и разрешены брандмауэром.
3. Подтвердите, что сертификат и ключ существуют, доступны для чтения учетной записи службы и образуют соответствующую пару.
4. Для автоматического TLS убедитесь, что каждый настроенный домен разрешается в хост Webship.
5. Вызовите /health на локальном слушателе приложения перед тестированием через DNS или внешнюю нагрузочную маршрутизацию.
6. Временно включите аутентифицированную наблюдаемость, когда требуется доказательство во время выполнения.