大网数据广告活动
数据库部署与 SQL 参考

Apache Doris 中文参考:S3 | Storages

· 52CE 我爱测

默认情况下,如果未配置 ,Doris 会使用操作系统默认的 CA 证书。在大多数环境中,不需要手动设置该参数。建议在以下场景中显式配置:

S3

本文档用于介绍访问 AWS S3 时所需的参数。这些参数适用于:

  • Catalog 属性。
  • Table Valued Function 属性。
  • Broker Load 属性。
  • Export 属性。
  • Outfile 属性。

配置 BE 端 HTTPS CA 证书

自 Doris 2.1 起,当 Doris BE 通过 HTTPS 访问 S3 时,可以在 be.conf 中显式配置 ca_cert_file_paths。

默认情况下,如果未配置 ca_cert_file_paths,Doris 会使用操作系统默认的 CA 证书。在大多数环境中,不需要手动设置该参数。建议在以下场景中显式配置:

  • BE 节点未安装系统 CA 证书,或系统 CA 证书包版本过旧。
  • BE 节点运行在精简容器或镜像中,未包含 ca-certificates 包。
  • BE 节点上的默认 CA 文件路径无效,或 Doris 进程没有该 CA 文件的读取权限。
  • 环境中使用了自签名证书、私有 CA,或者会重签 TLS 流量的企业代理或网关。
  • 访问 S3 时出现 Problem with the SSL CA cert 或 curl 77: Problem with the SSL CA cert (path? access rights?) 等错误。

对于不支持 ca_cert_file_paths 的版本: ca_cert_file_paths 参数自 Doris 2.1 起可用。如果你使用的是 Doris 2.0.x 或更早版本并遇到 SSL CA 证书错误,需要确保系统 CA 证书已正确安装,并且 CA 证书包位于 /etc/ssl/certs/ca-certificates.crt:

  • RHEL / CentOS / RockyLinux:
    yum install -y ca-certificates
    update-ca-trust
    ln -s /etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt /etc/ssl/certs/ca-certificates.crt
    
  • Debian / Ubuntu: apt-get install -y ca-certificates

然后重启所有 BE 节点。更多证书相关问题,请参阅 数据湖 FAQ - 证书问题。

示例:

# be.conf
ca_cert_file_paths = /etc/ssl/certs/ca-certificates.crt

常见的系统 CA 文件路径包括:

  • Debian / Ubuntu:/etc/ssl/certs/ca-certificates.crt
  • CentOS / RockyLinux:/etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt

需要在所有可能访问 S3 的 BE 节点上配置该参数,并确保 Doris 进程对证书文件有读取权限。修改 be.conf 后,需要重启对应的 BE 节点使配置生效。

参数总览

属性名称 曾用名 描述 默认值 是否必须
s3.endpoint S3 服务访问地址,如 s3.us-east-1.amazonaws.com 无 否
s3.access_key AWS Access Key。用于身份验证 无 否
s3.secret_key AWS Secret Key。用于身份验证 无 否
s3.region S3 所在区域,例如:us-east-1。强烈建议配置 无 是
s3.use_path_style 是否使用 path-style(路径风格)访问 FALSE 否
s3.connection.maximum 最大连接数,适用于高并发场景 50 否
s3.connection.request.timeout 请求超时时间(毫秒),控制连接获取超时 3000 否
s3.connection.timeout 建立连接的超时时间(毫秒) 1000 否
s3.role_arn 使用 Assume Role 模式时指定的角色 ARN 无 否
s3.external_id 配合 s3.role_arn 使用的 external ID 无 否
s3.credentials_provider_type 指定 AWS 凭证提供器类型(无 AK/SK 时使用;在 IAM Role 场景用于 STS 源凭证) DEFAULT 否

版本说明:s3.credentials_provider_type 自 3.1.4 和 4.0.3 起支持。

认证配置

Doris 支持以下三种方式访问 S3:

1. 直接使用 Access Key 和 Secret Key(AK/SK)

"s3.access_key"="your-access-key",
"s3.secret_key"="your-secret-key",
"s3.endpoint"="https://s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

2. IAM Role(Assume Role)模式

适用于跨账号、临时授权访问。通过角色授权自动获取临时凭证。

"s3.role_arn"="arn:aws:iam::123456789012:role/demo-role",
"s3.external_id"="external-identifier",
"s3.endpoint"="https://s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

在 IAM Role 模式中配置 s3.credentials_provider_type

当配置了 s3.role_arn 时,s3.credentials_provider_type 用于指定 STS AssumeRole 调用所使用的源凭证 provider:

  1. 按 s3.credentials_provider_type 获取源凭证。
  2. 用源凭证调用 STS AssumeRole。
  3. 使用返回的临时凭证访问 S3。

IAM Role + s3.credentials_provider_type 配置示例

示例 1:EC2 Instance Profile 作为 STS 源凭证

"s3.role_arn"="arn:aws:iam::123456789012:role/demo-role",
"s3.external_id"="external-identifier",
"s3.credentials_provider_type"="INSTANCE_PROFILE",
"s3.endpoint"="https://s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

示例 2:Web Identity(如 IRSA)作为 STS 源凭证

"s3.role_arn"="arn:aws:iam::123456789012:role/demo-role",
"s3.credentials_provider_type"="WEB_IDENTITY",
"s3.endpoint"="https://s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

示例 3:容器元数据作为 STS 源凭证

"s3.role_arn"="arn:aws:iam::123456789012:role/demo-role",
"s3.credentials_provider_type"="CONTAINER",
"s3.endpoint"="https://s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

示例 4:使用默认 provider chain 作为 STS 源凭证

"s3.role_arn"="arn:aws:iam::123456789012:role/demo-role",
"s3.credentials_provider_type"="DEFAULT",
"s3.endpoint"="https://s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

3. 通过 s3.credentials_provider_type 指定凭证来源

适用于不显式填写 AK/SK 的场景,例如 EC2 Instance Profile、容器元数据、Web Identity 等。

"s3.credentials_provider_type"="INSTANCE_PROFILE",
"s3.endpoint"="https://s3.us-east-1.amazonaws.com",
"s3.region"="us-east-1"

s3.credentials_provider_type 可选值

值 说明
DEFAULT 使用默认 provider chain
ENV 从环境变量读取凭证
SYSTEM_PROPERTIES 从系统属性读取凭证
WEB_IDENTITY 使用 Web Identity Token 凭证
CONTAINER 使用容器元数据凭证
INSTANCE_PROFILE 使用 EC2 Instance Profile 凭证
ANONYMOUS 匿名访问(适用于公开桶)

同时配置时的生效规则

  1. 同时配置 s3.access_key 和 s3.secret_key 时,优先使用 AK/SK。
  2. 未配置 AK/SK 且配置了 s3.role_arn 时,使用 IAM Role;此时 s3.credentials_provider_type 用于 STS 源凭证选择。
  3. 未配置 AK/SK 且未配置 s3.role_arn 时,s3.credentials_provider_type 直接决定 S3 客户端使用的 provider。

注意:s3.access_key 和 s3.secret_key 必须成对出现,仅配置其中一个会报错。

AWS 认证鉴权配置说明请参阅文档aws-authentication-and-authorization

EKS Pod Identity(4.1.5 起)

自 4.1.5 版本起,BE 及相关 C++ 存储访问路径支持 EKS Pod Identity 的容器凭证端点和授权令牌文件。Pod 应已由 EKS 注入 AWS_CONTAINER_CREDENTIALS_FULL_URI 与 AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE,Doris 进程需能访问端点并读取令牌文件。使用容器凭证 Provider(s3.credentials_provider_type=CONTAINER,或会选中该 Provider 的默认凭证链)时,不要同时配置优先级更高的 AK/SK。

获取凭证时会重新读取令牌文件,以适应令牌轮换。与 ECS 兼容的 AWS_CONTAINER_CREDENTIALS_RELATIVE_URI、AWS_CONTAINER_AUTHORIZATION_TOKEN 仍受支持;同时存在相对和完整 URI 时,相对 URI 优先。该变化不替代 FE 端独立的 Java 凭证获取配置,需分别确认 FE 和 BE 的访问权限。

访问 S3 Directory Bucket

该功能自 3.1.0 起支持。

Amazon S3 Express One Zone(又名 Directory Bucket)提供更高性能,但 endpoint 格式不同。

  • 普通 bucket:s3.us-east-1.amazonaws.com
  • Directory Bucket:s3express-usw2-az1.us-west-2.amazonaws.com

更多可用区域参考:AWS 官方文档

示例:

"s3.access_key"="ak",
"s3.secret_key"="sk",
"s3.endpoint"="https://s3express-usw2-az1.us-west-2.amazonaws.com",
"s3.region"="us-west-2"

权限策略

根据使用场景不同,可以分为 只读 和 读写 两类策略。

1. 只读权限

只允许读取 S3 中的对象。适用于 LOAD、TVF、查询 EXTERNAL CATALOG 等场景。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
              "s3:GetObject",
              "s3:GetObjectVersion",
            ],
            "Resource": "arn:aws:s3:::<your-bucket>/your-prefix/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": "arn:aws:s3:::<your-bucket>"
        }    
    ]
}

2. 读写权限

在只读的基础上,允许删除、创建、修改对象。适用于 EXPORT、OUTFILE 以及 EXTERNAL CATALOG 回写等场景。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
              "s3:PutObject",
              "s3:GetObject",
              "s3:GetObjectVersion",
              "s3:DeleteObject",
              "s3:DeleteObjectVersion",
              "s3:AbortMultipartUpload",      
              "s3:ListMultipartUploadParts"
            ],
            "Resource": "arn:aws:s3:::<your-bucket>/<your-prefix>/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation",
                "s3:GetBucketVersioning",
                "s3:GetLifecycleConfiguration"
            ],
            "Resource": "arn:aws:s3:::<your-bucket>"
        }    
    ]
}

注意事项

  1. 占位符替换

    • <bucket> → 你的 S3 Bucket 名称。
    • <account-id> → 你的 AWS 账号 ID(12 位数字)。
  2. 最小权限原则

    • 如果只做查询,不要授予写权限。

本文来自 Apache Doris 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
Apache Doris 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。