🦀 Rust Axum 框架中可信代理 IP 处理的最佳实践

🦀 Rust Axum 框架中可信代理 IP 处理的最佳实践

Photos provided by Unsplash OR Pexels

引言背景

在 Web 开发中，当应用程序运行在反向代理（如 Nginx 或 Cloudflare）后面时，直接从 TCP 连接获取的客户端 IP 往往是代理服务器的 IP，而不是真实用户的 IP。这会导致日志记录、安全审计和 IP 限制等功能失效。可信代理 IP 处理（Trusted Proxies）是一种机制，用于安全地从 HTTP 头部（如 X-Forwarded-For）中提取真实客户端 IP，但仅当请求来自预配置的可信代理 IP 时才信任这些头部。

基于 Rust 的 Axum 框架（版本 0.8），结合 Tokio（1.48.0）、Tower-HTTP（0.6.8）和 Rustls（假设 rustfs 为 rustls 的笔误，版本 0.23.35，用于 TLS 支持），我们可以实现自定义中间件来处理可信代理 IP。该实践强调高可读性、高可维护性和可扩展性，确保代码符合工业级标准。

本文将从基础概念入手，逐步深入到配置和使用，最后提供完整实例代码。

理论基础

基本原理

  • 直接连接 vs. 代理连接：在无代理场景下，Axum 通过 axum::extract::ConnectInfo 可以直接从 Socket 获取客户端 IP。但在代理场景下，Socket IP 是代理的 IP。
  • HTTP 头部的作用：代理服务器通常添加头部如：
    • X-Forwarded-For：记录客户端 IP 和代理链（如 “client-ip, proxy1-ip, proxy2-ip”）。
    • X-Real-IP：有时用于单一代理的真实 IP。
    • Forwarded：RFC 7239 标准头部，更安全和灵活。
  • 安全风险：如果无条件信任这些头部，攻击者可以伪造 IP（如通过发送假的 X-Forwarded-For）。因此，需要“可信代理”机制：仅当请求的直接来源 IP（Socket IP）属于预配置的可信列表时，才解析头部获取真实 IP。
  • 处理流程：
    1. 检查 Socket IP 是否在可信代理列表中。
    2. 如果是，从头部解析真实 IP（通常取 X-Forwarded-For 的第一个非代理 IP）。
    3. 如果不是，直接使用 Socket IP。
  • 边缘情况：
    • 多级代理：需递归检查代理链。
    • 私有 IP：可信列表可包括 CIDR 如 10.0.0.0/8。
    • 错误处理：无效 IP 时回退到 Socket IP，并记录日志。

为什么自定义中间件？

Axum 基于 Tower，支持层叠中间件。Tower-HTTP 提供基础中间件，但没有内置 Trusted Proxies。我们自定义中间件以：

  • 集成到 Axum 的 Handler 链中。
  • 使用 Tokio 的异步特性确保高效。
  • 支持 Rustls 的 TLS 终止（如果启用 HTTPS）。
  • 提高可维护性：通过配置结构体和 trait 扩展。

优势与最佳实践

  • 高效性：使用 ipnet crate 处理 CIDR，避免字符串解析开销。
  • 可读性：使用枚举和结构体清晰定义配置。
  • 可扩展性：支持多种头部（X-Forwarded-For、Forwarded），易添加日志或 Metrics。
  • 工业级：错误处理、测试友好、零拷贝解析。

如何使用与配置

步骤 1：依赖准备

在 Cargo.toml 中添加必要依赖。使用指定版本确保兼容性。

步骤 2：配置可信代理

  • 定义一个 TrustedProxies 结构体，包含 IP 列表（支持单个 IP 或 CIDR）。
  • 在应用启动时加载配置（从环境变量、配置文件或硬编码）。

步骤 3：实现中间件

  • 使用 Tower 的 Layer 和 Service trait 自定义中间件。
  • 在中间件中：
    • 从 extensions 获取 ConnectInfo 的 Socket IP。
    • 检查是否可信。
    • 如果可信，解析头部并插入自定义扩展（如 ClientIp）。
  • 在 Handler 中提取 ClientIp 使用。

步骤 4：集成到 Axum

  • 在 Router 中添加中间件层。
  • 可选：结合 Rustls 启用 HTTPS。

步骤 5：测试与部署

  • 测试：模拟代理请求，验证 IP 提取。
  • 部署：确保代理正确设置头部，并配置 TLS。

由浅入深：

  • 初级：理解头部作用，直接使用 Socket IP。
  • 中级：添加简单 IP 检查。
  • 高级：支持多头部、CIDR、错误日志。

完整实例代码

Cargo.toml

[package]
name = "axum-trusted-proxies"
version = "0.1.0"
edition = "2021"

[dependencies]
axum = "0.8"
tokio = { version = "1.48.0", features = ["full"] }
tower-http = { version = "0.6.8", features = ["trace"] }
rustls = "0.23.35"  # 假设 rustfs 为 rustls 的笔误，用于 TLS
rustls-pemfile = "2.2.0"  # 用于加载 PEM 文件
ipnet = "2.10.1"  # 用于 CIDR 支持
hyper = { version = "1.5.0", features = ["server"] }  # Axum 依赖
tracing = "0.1.40"  # 日志
tracing-subscriber = "0.3.18"  # 日志订阅

src/main.rs

use axum::{
    extract::{ConnectInfo, Extension, Request},
    http::{HeaderMap, StatusCode},
    middleware::{self, Next},
    response::{IntoResponse, Response},
    routing::get,
    Router,
};
use ipnet::IpNet;
use std::collections::HashSet;
use std::net::{IpAddr, SocketAddr};
use std::str::FromStr;
use std::sync::Arc;
use tokio::net::TcpListener;
use tower_http::trace::TraceLayer;
use tracing::{error, info};
use rustls::{Certificate, PrivateKey, ServerConfig};
use rustls_pemfile::{certs, pkcs8_private_keys};
use std::fs::File;
use std::io::BufReader;

// 自定义扩展：客户端真实 IP
#[derive(Clone, Copy, Debug)]
pub struct ClientIp(pub IpAddr);

// 配置结构体：高可维护性
#[derive(Clone, Debug)]
pub struct TrustedProxies {
    proxies: HashSet<IpNet>,
}

impl TrustedProxies {
    pub fn new(proxies: Vec<String>) -> Self {
        let mut set = HashSet::new();
        for proxy in proxies {
            match IpNet::from_str(&proxy) {
                Ok(net) => { set.insert(net); }
                Err(e) => { error!("Invalid proxy CIDR: {}, error: {}", proxy, e); }
            }
        }
        Self { proxies: set }
    }

    pub fn is_trusted(&self, ip: IpAddr) -> bool {
        self.proxies.iter().any(|net| net.contains(&ip))
    }
}

// 中间件：高效解析 IP
async fn trusted_proxy_middleware(
    Extension(trusted_proxies): Extension<Arc<TrustedProxies>>,
    ConnectInfo(socket_addr): ConnectInfo<SocketAddr>,
    headers: HeaderMap,
    mut req: Request,
    next: Next,
) -> Result<Response, (StatusCode, String)> {
    let socket_ip = socket_addr.ip();
    info!("Socket IP: {}", socket_ip);

    let client_ip = if trusted_proxies.is_trusted(socket_ip) {
        // 解析 X-Forwarded-For（优先），取第一个非私有 IP
        if let Some(forwarded) = headers.get("x-forwarded-for") {
            let forwarded_str = forwarded.to_str().map_err(|_| (StatusCode::BAD_REQUEST, "Invalid header".to_string()))?;
            let ips: Vec<&str> = forwarded_str.split(',').map(str::trim).collect();
            if let Some(first_ip) = ips.first() {
                match IpAddr::from_str(first_ip) {
                    Ok(ip) => ip,
                    Err(e) => {
                        error!("Invalid IP in X-Forwarded-For: {}, error: {}", first_ip, e);
                        socket_ip
                    }
                }
            } else {
                socket_ip
            }
        } else {
            // 回退到 X-Real-IP
            if let Some(real_ip) = headers.get("x-real-ip") {
                let real_ip_str = real_ip.to_str().map_err(|_| (StatusCode::BAD_REQUEST, "Invalid header".to_string()))?;
                match IpAddr::from_str(real_ip_str) {
                    Ok(ip) => ip,
                    Err(e) => {
                        error!("Invalid IP in X-Real-IP: {}, error: {}", real_ip_str, e);
                        socket_ip
                    }
                }
            } else {
                socket_ip
            }
        }
    } else {
        socket_ip
    };

    info!("Client IP: {}", client_ip);
    req.extensions_mut().insert(ClientIp(client_ip));

    Ok(next.run(req).await)
}

// 示例 Handler
async fn hello(Extension(client_ip): Extension<ClientIp>) -> impl IntoResponse {
    format!("Hello from IP: {}", client_ip.0)
}

// TLS 配置函数：使用 Rustls
fn load_tls_config() -> Arc<ServerConfig> {
    let cert_file = &mut BufReader::new(File::open("cert.pem").unwrap());
    let key_file = &mut BufReader::new(File::open("key.pem").unwrap());

    let cert_chain = certs(cert_file).unwrap().into_iter().map(Certificate).collect();
    let mut keys = pkcs8_private_keys(key_file).unwrap();

    let config = ServerConfig::builder()
        .with_safe_defaults()
        .with_no_client_auth()
        .with_single_cert(cert_chain, PrivateKey(keys.remove(0)))
        .unwrap();

    Arc::new(config)
}

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt::init();

    // 配置可信代理（从环境或硬编码）
    let trusted_proxies = Arc::new(TrustedProxies::new(vec![
        "127.0.0.1/32".to_string(),    // 本地
        "192.168.0.0/16".to_string(),  // 示例私有网
    ]));

    // 构建 Router
    let app = Router::new()
        .route("/", get(hello))
        .layer(middleware::from_fn(move |req, next| {
            trusted_proxy_middleware(Extension(trusted_proxies.clone()), req, next)
        }))
        .layer(TraceLayer::new_for_http());

    // TLS 配置（可选，如果需要 HTTPS）
    let tls_config = load_tls_config();

    // 监听（HTTPS 示例，端口 3000）
    let listener = TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum_server::from_tcp(listener)
        .tls(tls_config)
        .serve(app.into_make_service_with_connect_info::<SocketAddr>())
        .await
        .unwrap();
}

附属文件说明

  • cert.pem 和 key.pem：TLS 证书文件（自行生成，自签名或 CA 签发）。示例命令：openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out cert.pem。
  • 无其他附属文件；代码自包含。

参考资料

版权声明：自由转载-非商用-非衍生-保持署名（创意共享3.0许可证）

Similar Posts

Rustfs gRPC Panic 秒修：GetMetrics 反序列化加兜底，服务零崩溃

Rustfs gRPC Panic 秒修：GetMetrics 反序列化加兜底，服务零崩溃

🦀 Rust Axum 框架中支持 Forwarded 头部的可信代理 IP 处理最佳实践

🦀 Rust Axum 框架中支持 Forwarded 头部的可信代理 IP 处理最佳实践

疾风 Hyper：Rust 异步风暴中的优雅征服者——从入门翱翔，到高负载巅峰调御

疾风 Hyper：Rust 异步风暴中的优雅征服者——从入门翱翔，到高负载巅峰调御

Rust Axum + Hyper 流式代理秘籍：高效铸就 RustFS Console 转发神器

Rust Axum + Hyper 流式代理秘籍：高效铸就 RustFS Console 转发神器

条件依赖的星辰图景：Rust 目标配置的诗意解析

条件依赖的星辰图景：Rust 目标配置的诗意解析