joseluisq/static-web-server

Static Web Server

概述

Static Web Server（简称SWS）是一个小巧快速的生产级Web服务器，适用于提供静态Web文件或资源。它专注于轻量级和易用性原则，同时借助https://rust-lang.org提供https://blog.rust-lang.org/2015/04/10/Fearless-Concurrency.html。基于https://github.com/hyperium/hyper和https://github.com/tokio-rs/tokio运行时构建，提供并发和异步网络能力以及最新的HTTP/1 - HTTP/2实现。跨平台支持Linux、macOS、Windows、FreeBSD、NetBSD、Android、Docker和Wasm（通过Wasmer）。

核心功能和特性

• 使用Rust构建，专注于安全性、速度和并发性
• 内存安全，显著降低CPU和RAM开销
• 基于最新的Hyper、Tokio和一系列优秀crate，提供极速静态文件服务和异步能力
• 单个4MB（未压缩）完全静态二进制文件，无依赖（Musl libc），适用于任何Linux发行版或Docker容器
• 可选的GZip、Deflate、Brotli或Zstandard（zstd）压缩，仅支持文本类Web文件
• 通过Accept-Encoding头部实现按需压缩
• 支持大文件的部分内容传输（Byte Serving）
• 可选的Cache-Control头部配置，用于资源缓存控制
• 终止信号处理，支持https://cloud.google.com/blog/products/containers-kubernetes/kubernetes-best-practices-terminating-with-grace和宽限期
• HTTP/2和TLS支持
• 默认提供HTTP/2安全头部（符合https://web.dev/security-headers/规范）
• 支持HEAD和OPTIONS响应
• 通过https://github.com/tokio-rs/tracing crate提供轻量级可配置日志
• 可自定义阻塞线程和工作线程数量
• 可选的目录列表功能，支持排序和JSON输出格式
• 支持CORS（含预检请求）
• 基本HTTP认证
• 通过glob模式为特定文件请求自定义HTTP响应头部
• 404错误回退页面，适用于单页应用
• 支持作为Windows服务运行
• 通过CLI参数、环境变量或TOML文件配置
• 默认和自定义错误页面
• 内置HTTP到HTTPS重定向
• GET/HEAD健康检查端点
• 支持直接从磁盘提供预压缩（Gzip/Brotli/Zstd）文件
• 通过glob模式和替换实现自定义URL重写和重定向
• 虚拟主机支持
• 多索引文件支持
• 维护模式功能
• 可用作带可选功能的库crate
• 一流Docker支持，提供Scratch、最新Alpine Linux和Debian镜像
• 支持接受文件描述符形式的套接字监听器，适用于沙箱和按需应用（如systemd套接字激活）
• 跨平台，预编译二进制文件支持Linux、macOS、Windows、FreeBSD、NetBSD、Android（x86/x86_64、ARM/ARM64）和WebAssembly（通过Wasmer）

使用场景和适用范围

适用于需要高效提供静态资源的场景，包括但不限于：

• 静态网站托管（HTML、CSS、JavaScript、图片等）
• 单页应用（SPA）部署
• 前端资源服务器（如React、Vue、Angular构建产物）
• 文档站点（如API文档、产品手册）
• 轻量级文件共享服务
• 资源受限环境（低CPU/内存设备）的静态内容服务

使用方法和配置说明

Docker部署示例

基本使用

bash
docker run -p 8080:80 -v $(pwd)/public:/public docker.xuanyuan.run/joseluisq/static-web-server:2

自定义配置（环境变量）

bash
docker run -p 8080:8080 \
  -v $(pwd)/public:/public \
  -e SERVER_PORT=8080 \
  -e SERVER_ROOT=/public \
  -e LOG_LEVEL=info \
  -e COMPRESSION_GZIP=true \
  docker.xuanyuan.run/joseluisq/static-web-server:2

自定义配置（CLI参数）

bash
docker run -p 8080:80 \
  -v $(pwd)/public:/public \
  docker.xuanyuan.run/joseluisq/static-web-server:2 \
  --port 80 \
  --root /public \
  --gzip true \
  --log-level info \
  --directory-listing true

docker-compose配置

yaml
version: '3'
services:
  static-web-server:
    image: docker.xuanyuan.run/joseluisq/static-web-server:2
    ports:
      - "8080:80"
    volumes:
      - ./public:/public
    environment:
      - SERVER_ROOT=/public
      - SERVER_PORT=80
      - COMPRESSION_GZIP=true
      - COMPRESSION_BROTLI=true
      - LOG_LEVEL=info
      - DIRECTORY_LISTING=true
    restart: unless-stopped

核心配置参数说明

完整配置参数可通过docker run joseluisq/static-web-server:2 --help查看，或参考官方文档。

文档

更多API详情、高级配置和使用示例，请参考官方文档网站。

发布版本

• Docker镜像：https://hub.docker.com/r/joseluisq/static-web-server/
• 发布二进制文件：https://github.com/static-web-server/static-web-server/releases
• 支持的平台/架构：static-web-server.net/platforms-architectures

基准测试

详细基准测试数据请参见https://github.com/static-web-server/benchmarks。

注意事项

• 如需使用v1版本，请查看https://github.com/static-web-server/static-web-server/tree/1.x。
• 从v1迁移到v2，请参考从v1迁移到v2文档。

贡献

除非另有明确说明，任何有意提交的贡献（如代码、文档等）将默认采用下述许可协议，无额外条款。欢迎提交https://github.com/static-web-server/static-web-server/pulls或https://github.com/static-web-server/static-web-server/issues。

许可

本作品主要采用MIT许可和Apache许可（版本2.0）双重授权。

© 2019-present Jose Quintana