rginx

rginx 是一个面向 Linux 的 Rust 边缘反向代理单二进制项目。

当前版本：0.1.6

能力概览

• HTTP/1.1、HTTPS、HTTP/2、HTTP/3 入口
• Host / Path 路由与 Return / 反向代理处理器
• 静态文件站点：root / alias / index、try_files、error_page、single-range、 大文件流式发送
• upstream round_robin、ip_hash、least_conn
• weight、backup、幂等请求 failover
• 下游 TLS、SNI、OCSP、mTLS、ALPN、TLS 版本控制
• 上游 TLS、mTLS、HTTP/2、HTTP/3、server_name_override
• cleartext h2c gRPC upstream、regex 路由、动态代理 header
• gRPC、grpc-web、trailers、grpc-timeout
• 压缩、限流、CIDR allow/deny、trusted_proxies、client_ip_header
• 热重载、优雅重启、平滑退出
• 本地只读运维命令：check、status、snapshot、snapshot-version、delta、wait、counters、traffic、peers、upstreams

平台与交付

• 仅支持 Linux
• 源码构建要求 Rust 1.94.1
• GitHub Release 提供 linux-amd64 和 linux-arm64 的 tar.gz、.deb、.rpm 资产
• 提供 Cloudsmith 公共软件仓库安装入口，用于 apt / dnf / yum
• deb / rpm 包安装后会像 nginx 一样默认启用并启动 rginx.service
• release archive 包含 rginx、README.md、CHANGELOG.md、configs/、scripts/ 以及 deploy/systemd / deploy/supervisor 示例

Package repository hosting is graciously provided by Cloudsmith.

Workspace 结构

路径	作用
crates/rginx-app	rginx 二进制、CLI、集成测试
crates/rginx-config	配置加载、校验、编译
crates/rginx-core	共享核心模型
crates/rginx-http	HTTP server、proxy、TLS、HTTP/3、限流、状态快照
crates/rginx-runtime	reload / restart / shutdown / health orchestration
crates/rginx-observability	tracing / logging 初始化
configs/	默认边缘代理配置
docs/	当前生效的仓库治理文档
deploy/	systemd / supervisor 示例
scripts/	安装、测试与验证脚本

快速开始

默认入口根配置文件是 configs/rginx.ron；网站配置必须放在 configs/conf.d/*.ron。

cargo run -p rginx -- -t
cargo run -p rginx -- check
cargo run -p rginx --

默认会加载：

• configs/rginx.ron
• configs/conf.d/default.ron

配置布局与 nginx 对齐：rginx.ron 只保留全局 runtime/server 默认值和 conf.d/*.ron include；每个 VirtualHostConfig 站点文件负责自己的 listen、 TLS 证书、局部 upstreams 和 locations。不要把网站配置重新内联回 rginx.ron。 加载器会强制拒绝 canonical rginx.ron 根文件中内联站点级 listen、 upstreams、locations 和 servers 内容。

配置兼容提示：proxy_set_headers 现在支持结构化动态值；旧的静态字符串 写法如 "X-Foo": "bar" 仍然有效，动态值需使用 RON enum 写法如 "X-Real-IP": ClientIp 或 "Origin": Template("https://{host}")。

静态文件能力当前已经可以直接承载常见站点、文档站和下载站主路径，稳定支持：

• root / alias / index
• default_type、cache_control、expires_secs、immutable
• download / content_disposition
• autoindex、hide_dotfiles、follow_symlinks
• HEAD、ETag、Last-Modified、If-Modified-Since、If-None-Match
• single-range、try_files、error_page、目录 slash canonical redirect
• 大文件全量下载与 range 下载的流式发送

当前仍保留的边界：

• 仅支持 single-range；multi-range 仍未实现
• 尚未引入 sendfile / 零拷贝优化
• 对高流量复杂站点，仍建议先补一条真实子进程回归再上线

静态站点 / 下载站示例：

VirtualHostConfig(
    listen: ["127.0.0.1:8080"],
    server_names: ["static.example.com"],
    locations: [
        LocationConfig(
            matcher: Prefix("/downloads"),
            handler: File(
                alias: Some("/srv/releases"),
                default_type: Some("application/octet-stream"),
                download: Some(true),
                cache_control: Some("public, max-age=300"),
                hide_dotfiles: Some(true),
                follow_symlinks: Some(false),
            ),
        ),
        LocationConfig(
            matcher: Prefix("/"),
            handler: File(
                root: Some("/srv/www/site"),
                index: Some(["index.html", "index.htm"]),
                expires_secs: Some(86400),
                immutable: Some(true),
                hide_dotfiles: Some(true),
                follow_symlinks: Some(false),
            ),
            try_files: [
                Path("$uri"),
                Path("/index.html"),
            ],
            error_pages: [
                ErrorPageConfig(
                    statuses: [404],
                    target: Uri("/404.html"),
                ),
            ],
        ),
    ],
)

更完整的静态文件迁移样例与当前能力边界见：

• docs/NGINX_TO_RON_MIGRATION_EXAMPLES.md
• docs/NGINX_HTTP_ALIGNMENT_MATRIX.md

常用命令：

rginx -t
rginx -s reload
rginx check
rginx status
rginx snapshot --include status --include traffic
rginx snapshot-version
rginx delta --since-version <version> --include status
rginx wait --since-version <version> --timeout-ms 5000
rginx counters
rginx invalidate-cache --zone <zone> --key <cache-key>
rginx invalidate-cache --zone <zone> --prefix <cache-key-prefix>
rginx invalidate-cache --zone <zone> --tag <cache-tag>
rginx clear-cache-invalidations --zone <zone>
rginx peers
rginx traffic --window-secs 60
rginx upstreams --window-secs 60

systemd / supervisor 示例：

• rginx.service
• rginx.conf

安装

从源码仓库安装：

./scripts/install.sh --mode source

直接安装最新稳定版 release：

curl -fsSL https://raw.githubusercontent.com/vansour/rginx/main/scripts/install.sh | \
  bash -s -- --mode release --version latest

通过 Cloudsmith 一键安装最新版本：

curl -fsSL https://dl.cloudsmith.io/public/rginx/rginx/cfg/setup/bash.deb.sh | sudo bash
sudo apt update
sudo apt install -y rginx

curl -fsSL https://dl.cloudsmith.io/public/rginx/rginx/cfg/setup/bash.rpm.sh | sudo bash
sudo dnf install -y rginx
# 或
sudo yum install -y rginx

系统包安装行为与 nginx 对齐：

• 安装后默认启用并启动 rginx.service
• 升级时若服务当前在运行，会自动重启
• /etc/rginx/rginx.ron 与 conf.d/*.ron 作为配置文件保留，升级不会覆盖本地修改
• Cloudsmith 官方 bash.deb.sh / bash.rpm.sh setup script 负责接入系统软件源

安全提示：Cloudsmith 软件源引导脚本会在本机上修改系统仓库配置。 建议优先下载到本地、审阅内容后再执行，而不是直接 curl | bash。

卸载入口：

./scripts/uninstall.sh

开发与验证

完整检查命令：

cargo check --workspace --all-targets --message-format short
cargo test --workspace --all-targets --no-fail-fast
cargo clippy --workspace --all-targets -- -D warnings

仓库内置脚本：

python3 scripts/run-modularization-gate.py
scripts/test-fast.sh
scripts/test-slow.sh
scripts/run-nginx-diff.sh
scripts/run-clippy-gate.sh
scripts/run-tls-gate.sh
scripts/run-http3-gate.sh
scripts/run-http3-release-gate.sh --soak-iterations 1

文档

• docs/README.md 汇总当前生效的仓库治理文档
• docs/CACHE_ARCHITECTURE_GAPS.md 记录缓存当前长期架构差距与演进方向

许可证

双许可证：

• LICENSE-MIT
• LICENSE-APACHE