Apache Reqsign 0.20.7 配置参数详解

目标：系统讲解 Apache Reqsign 0.20.7 作为 Rust 请求签名库时的主要配置项。与常规服务不同，Reqsign 没有服务端配置文件，核心配置集中在三类对象上：凭据提供者（Credential Provider）、上下文（Context）与请求签名器（Request Signer），另有 Cargo.toml 的 feature 编译期配置。本文对每个参数给出含义、默认行为、设置方式与生产建议。所有参数均在 Ubuntu 22.04.5 + rustc 1.99.0 + reqsign 0.20.7 环境实测。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS
• Rust 工具链：rustc 1.99.0 / cargo 1.99.0
• Reqsign 版本：0.20.7（feature：aws-v4 + default-context）
• 配置载体：Cargo.toml（编译期）+ Rust 代码（运行期）
• 示例工程：/root/reqsign-demo/

二、前置条件

已安装 Rust 工具链与 reqsign 依赖，并能正常编译运行：

source "$HOME/.cargo/env"
cd /root/reqsign-demo
cargo build

三、参数查看与修改方式

Reqsign 的配置参数不是文本配置文件，而是通过 Cargo.toml 的 feature 声明与代码中的构造器/链式方法设置：

💡 feature 与版本信息可用 cargo info reqsign 实测查看（详见《安装指南》篇第三节）。

四、参数总览

五、核心参数详解

5.1 凭据（Credential）与凭据提供者参数

凭据数据本身是 Credential 结构，字段：access_key_id（String）、secret_access_key（String）、session_token（Option<String>）、expires_in（Option<Timestamp>）。提供者负责按需产出 Credential。

StaticCredentialProvider（静态凭据）：适合演示/固定凭据，构造参数直接给定：

use reqsign::aws::StaticCredentialProvider;

let cred = StaticCredentialProvider::new(
    "AKIDEXAMPLE",
    "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
);

EnvCredentialProvider（环境变量凭据）：读取以下环境变量（实测常量名）：AWS_ACCESS_KEY_ID（必填）、AWS_SECRET_ACCESS_KEY（必填）、AWS_SESSION_TOKEN（可选）。两个必填变量都存在时才返回凭据，否则返回 None 交给链中下一级。

export AWS_ACCESS_KEY_ID=AKIDEXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

DefaultCredentialProvider（默认凭据链，生产推荐）：DefaultCredentialProvider::new() 按固定顺序尝试各来源：环境变量 → profile 配置文件（~/.aws/credentials 与 ~/.aws/config，可被 AWS_SHARED_CREDENTIALS_FILE / AWS_CONFIG_FILE 覆盖，profile 选择用 AWS_PROFILE）→ SSO → Web Identity（AssumeRoleWithWebIdentity）→ process（外部进程）→ ECS 元数据 → IMDSv2（EC2 实例元数据）。可用 push_front(provider) 把自定义提供者插到链首：

use reqsign::aws::{DefaultCredentialProvider, StaticCredentialProvider};

let provider = DefaultCredentialProvider::new()
    .push_front(StaticCredentialProvider::new("AKIDEXAMPLE", "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"));

💡 说明：凭据会被签名器缓存并在过期前自动刷新；刷新失败不会回退旧凭据，而是返回错误，因此生产环境应保证凭据来源可用。

5.2 上下文（Context）参数

Context 提供签名器所需的四类基础设施，均可替换：

use reqsign::default_context;

let ctx = default_context();   // 全默认

// 或自定义：Context::new() + with_file_read / with_http_send / with_env / with_command_execute 逐项替换
use reqsign::{Context, OsEnv};
let ctx = Context::new()
    .with_env(OsEnv);

⚠️ 注意：开启 default-context feature 时可用 default_context() 一步到位；若不开启该 feature，则需手动 Context::new() 并注入所需组件，否则依赖这些组件的凭据来源（如 profile/IMDS）不可用。

5.3 AWS SigV4 请求签名器（RequestSigner）参数

RequestSigner::new(service, region) 指定签名服务与区域，二者都会进入 Credential 作用域与 authorization 头：

use reqsign::aws::RequestSigner;

let signer = RequestSigner::new("s3", "us-east-1");

• service：服务名，参与签名字符串与 Credential=AKIDEXAMPLE/20261012/us-east-1/s3/aws4_request 中的 s3 段。S3 用 s3，S3 Express 用 s3express。

• region：区域名（如 us-east-1、cn-north-1），必须与端点实际区域一致。

• use_standard_session_token（默认 false）：S3 Express 场景下，若使用 IAM/STS 临时凭据，需调用 with_standard_session_token() 让会话令牌以标准 x-amz-security-token（头认证）/ X-Amz-Security-Token（查询认证）表示；默认的 CreateSession 凭据表示使用 x-amz-s3session-token：

  let signer = RequestSigner::new("s3express", "us-west-2")
      .with_standard_session_token();
  

5.4 签名器组装（Signer）参数

Signer 把上下文、凭据提供者、请求签名器组装为最终签名入口：

use reqsign::{Context, Signer};
use reqsign::aws::{RequestSigner, StaticCredentialProvider};

let ctx = Context::new();
let cred = StaticCredentialProvider::new("AKIDEXAMPLE", "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY");
let signer = Signer::new(ctx, cred, RequestSigner::new("s3", "us-east-1"));

组装后即可对请求签名。三个组件也支持链式替换：with_context(ctx)、with_credential_provider(provider)、with_request_signer(signer)。

5.5 调用参数（Signer::sign 的 expires_in）

signer.sign(&mut parts, expires_in: Option<Duration>) 的第二个参数是服务相关的有效期输入，不是「头认证/查询认证」的统一切换开关（由服务签名器与凭据类型共同决定其解释方式，例如预签名 URL 场景要求凭据有效期覆盖 URL 生命周期）：

signer.sign(&mut parts, None).await?;                          // 默认：无额外有效期要求
// signer.sign(&mut parts, Some(Duration::from_secs(3600))).await?; // 预签名等场景

5.6 编译期参数（Cargo features）

按需开启云服务模块，减少编译时间与依赖体积：

[dependencies]
reqsign = { version = "0.20.7", default-features = false, features = ["aws-v4", "default-context"] }

常用 feature（cargo info reqsign 实测）：

六、生产配置模板

按不同场景给出可复用的代码配置范式。

💡 适用场景：4GB 内存、普通 SSD、生产环境对接 AWS S3（或对应云对象存储）的 Rust 服务。

use reqsign::{Context, Signer, default_context};
use reqsign::aws::{DefaultCredentialProvider, RequestSigner};

// 生产：默认凭据链（环境变量 → ~/.aws/credentials → SSO → Web Identity → ECS/IMDS）
let ctx = default_context();
let provider = DefaultCredentialProvider::new();
let signer = Signer::new(ctx, provider, RequestSigner::new("s3", "cn-north-1"));

// 对请求签名后由自己的 HTTP 客户端发送
// let (mut parts, _) = http::Request::get(target).body(()).unwrap().into_parts();
// signer.sign(&mut parts, None).await?;

七、常见问题

Q1：为什么签名后请求被云服务拒绝（403）？ 依次核对：1) 服务器时间偏差（x-amz-date 应为 UTC 当前时间）；2) RequestSigner::new(service, region) 与实际服务/区域一致；3) 凭据有权限且未过期；4) 请求 URI 已百分号编码规范（reqsign 不做通用 URI 编码）。

Q2：环境变量已设置但没生效？ EnvCredentialProvider 要求 AWS_ACCESS_KEY_ID 与 AWS_SECRET_ACCESS_KEY 两个变量都存在才返回凭据；确认导出后当前进程可见（echo $AWS_ACCESS_KEY_ID 非空）。也可直接用 StaticCredentialProvider::new(ak, sk) 排除变量问题。

Q3：default-context 与自定义 Context 怎么选？ 不依赖 IMDS/ECS 元数据、无 profile 文件时，default_context() 足够；需要替换 HTTP 客户端（如自建 reqwest 池）时用 Context::new().with_http_send(自定义实现) 逐项注入。

Q4：多区域/多服务需要多个签名器吗？ 需要。RequestSigner 的 service/region 是构造参数，每类服务（如同时用 s3 与 sts、或多个区域）各建一个签名器实例即可，凭据提供者可复用。

Q5：编译报 edition2024 / lock 文件版本错误？ 工具链过旧。用 rustup 安装 stable（实测 rustc 1.99.0）并 source "$HOME/.cargo/env" 切换后重编。

八、参考链接

• Reqsign 官方文档：https://docs.rs/reqsign
• crates.io：https://crates.io/crates/reqsign
• AWS SigV4 签名规范：https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html
• AWS S3 Express 会话令牌说明：https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateSession.html
• 源码仓库：https://github.com/apache/opendal-reqsign