企业官网建设流程全解析

erlcloud 凭据配置终极指南：5 种 AWS 认证方式一次搞定

【免费下载链接】erlcloudAWS APIs library for Erlang (Amazon EC2, S3, SQS, DDB, ELB and etc)项目地址: https://gitcode.com/gh_mirrors/er/erlcloud

erlcloud是 Erlang 生态中最流行的 AWS 云服务 API 库，覆盖 EC2、S3、SQS、DDB、ELB 等数十项服务。不过很多新手在接入时，第一个卡住的地方就是erlcloud 凭据配置——AWS 认证方式太多，不知道该用哪一种。本文整理了 5 种实用的 AWS 认证方式，从最简单的环境变量到生产环境必备的自动发现认证，帮你一次搞定所有场景。

为什么凭据配置如此重要？🤔

AWS 的所有 API 调用都需要身份认证。erlcloud 将凭据统一封装在#aws_config{}记录中，该记录定义在 include/erlcloud_aws.hrl，包含access_key_id、secret_access_key、security_token等核心字段，以及各服务默认的 host、端口等参数。

配置错误最常见的表现是：函数调用成功，但返回{error, {http_error, 401, ...}}或签名不匹配的报错。下面这 5 种方式，总有一种适合你的项目。

方式一：环境变量认证——最快上手的 AWS 凭据配置方法 ⚡

如果只是本地快速测试，用环境变量最省事。erlcloud 会读取标准的 AWS 环境变量：

export AWS_ACCESS_KEY_ID=你的AccessKeyID export AWS_SECRET_ACCESS_KEY=你的SecretAccessKey export AWS_SESSION_TOKEN=你的SessionToken # 使用临时凭证时才需要 export AWS_REGION=us-east-1

之后直接调用 API 即可，不需要传任何配置参数：

erlcloud_s3:list_buckets(). erlcloud_ec2:describe_images().

原理说明：erlcloud_aws:default_config/0（见 src/erlcloud_aws.erl）会按「OS 环境变量 → erlcloud 应用环境」的顺序取值，构造默认的#aws_config{}。注意：环境变量优先级高于应用环境变量，且凭据必须成对出现（Key 和 Secret 都不能为空）才会被采用。

✅ 优点：零代码、跨语言通用 ❌ 缺点：全局生效，多账号切换麻烦

方式二：~/.aws/credentials 凭证文件——profile 配置文件认证 📄

如果你已经使用 AWS CLI，那么~/.aws/credentials文件早已存在。erlcloud 可以直接读取它，和 CLI 的行为完全一致：

[default] aws_access_key_id = XXXXXXXXXXXXXXXXXXXX aws_secret_access_key = yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy [dev] aws_access_key_id = XXXXXXXXXXXXXXXXXXXX aws_secret_access_key = yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

在 Erlang 代码中调用profile/0或profile/1指定命名 profile：

%% 读取 default profile {ok, Conf} = erlcloud_aws:profile(). %% 读取名为 dev 的 profile {ok, Conf2} = erlcloud_aws:profile(dev). erlcloud_s3:list_buckets(Conf).

进阶能力：profile/2还支持 CLI 同款的source_profile和role_arn间接引用。例如配置文件中[foo]段声明role_arn并从default继承基础凭据时，erlcloud 会自动调用 STS 完成角色切换，无需你手动处理。

✅ 优点：与 AWS CLI 共用一套配置、支持多账号 ❌ 缺点：服务器上需要预置文件

方式三：应用环境变量配置——app.config 中的 AWS 认证设置 🛠️

在 OTP 应用中，更规范的做法是把凭据写进应用环境。可以通过application:set_env/3动态设置，或写在 app.config 中随应用启动加载：

application:set_env(erlcloud, aws_access_key_id, "你的Key"), application:set_env(erlcloud, aws_secret_access_key, "你的Secret"), application:set_env(erlcloud, aws_security_token, "你的Token"), application:set_env(erlcloud, aws_region, "us-east-1"),

对应 app.config 写法：

[{erlcloud, [ {aws_access_key_id, "你的Key"}, {aws_secret_access_key, "你的Secret"}, {aws_region, "us-east-1"} ]}].

这种方式的好处是凭据集中管理、可随发布包分发，适合配置管理工具（如 Ansible、Chef）统一下发。

✅ 优点：集中管理、OTP 原生集成 ❌ 缺点：明文存储，需配合权限控制

方式四：进程字典配置——configure/new 函数硬编码凭据 🔑

对于简单任务或脚本，erlcloud 各服务模块都提供了configure/2,3和new/2,3系列函数。configure将凭据存入当前进程字典，new则返回独立的配置对象：

%% 存入进程字典，之后所有调用自动生效（见 src/erlcloud_ec2.erl） erlcloud_ec2:configure(AccessKeyId, SecretAccessKey). %% 生成独立配置对象，适合多账号并行访问 EC2 = erlcloud_ec2:new(AccessKeyId, SecretAccessKey). erlcloud_ec2:describe_images(EC2).

更通用的方式是直接构造#aws_config{}记录并交给erlcloud_aws:configure/1：

Config = #aws_config{access_key_id = "Key", secret_access_key = "Secret", ec2_host = "ec2.cn-north-1.amazonaws.com.cn"}, erlcloud_aws:configure(Config), erlcloud_s3:list_buckets().

注意：erlcloud_ec2:new/3中 Hostname 默认是"ec2.amazonaws.com"，这是设计上为了避免与 us-east-1 混淆，中国区等场景请显式指定。

✅ 优点：灵活、支持跨账号 ❌ 缺点：凭据暴露在代码中，不适合生产

方式五：自动发现认证——auto_config 一键搞定 🤖

生产环境（尤其是 ECS/EKS 容器和 EC2 实例）推荐使用erlcloud_aws:auto_config/0，它会按优先级自动探测可用的凭据来源：

1. 环境变量：AWS_ACCESS_KEY_ID等
2. 用户 Profile：~/.aws/credentials文件
3. ECS Task Role：容器任务角色，通过容器凭证端点获取
4. Host Metadata：EC2 实例元数据服务（IMDS），即实例上绑定的 IAM Role

{ok, Conf} = erlcloud_aws:auto_config(), erlcloud_ddb2:list_tables(Conf).

如果所有来源都不可用，返回undefined，不会抛异常。实现细节可参考 src/erlcloud_aws.erl 中的auto_config/1与config_metadata/1。

临时凭证自动刷新：元数据方式拿到的都是临时凭证（有有效期）。erlcloud 在发起请求时会通过update_config/1检查过期时间，若剩余不足 5 分钟会自动重新获取，无需你手动刷新。

✅ 优点：零配置、安全（不落盘明文密钥）、凭证自动轮换 ❌ 缺点：仅适用于 AWS 内部环境

进阶：STS AssumeRole 角色切换与跨账号访问 🔐

当需要跨账号访问时，可以在#aws_config{}中设置assume_role字段，erlcloud 会自动完成 STS AssumeRole 流程并缓存临时凭证：

Config = #aws_config{ assume_role = #aws_assume_role{ role_arn = "arn:aws:iam::123456789012:role/CrossAccountRole", session_name = "my-session", duration_secs = 3600 } }, %% 调用时自动切换角色 erlcloud_s3:list_buckets(Config).

该逻辑见update_config/1：若检测到role_arn未定义且当前无 KeyId，会依次尝试 ECS 和实例元数据，实现多级回退，非常适合容器化部署。

5 种 AWS 认证方式对比总结 📊

常见问题排查清单 🔍

• 401 Unauthorized：检查 Key/Secret 是否成对、有无多余空格
• SignatureDoesNotMatch：确认服务器时间是否同步（误差超过 5 分钟会签名失败）
• InvalidToken：使用了临时凭证但缺少AWS_SESSION_TOKEN
• 连接超时：中国区用户注意 region 对应 endpoint，可在#aws_config{}中覆盖*_host
• profile 读不到：确认HOME环境变量已设置，文件权限为当前用户可读

结语 ✨

至此，5 种 AWS 认证方式已经全部覆盖：本地快速验证用环境变量，多账号切换用凭证文件 profile，OTP 应用用应用环境变量，简单脚本用configure/new，生产环境则直接交给auto_config 自动发现。配合 STS AssumeRole，基本能应对 erlcloud 全部使用场景。

建议优先掌握方式一（环境变量）和方式五（auto_config），前者帮你快速跑通，后者是你上生产环境的安全保障。如果遇到配置问题，也可以对照 README.md 中的 "Using Access Key" 章节和 include/erlcloud_aws.hrl 中的字段说明逐一排查。祝你的 Erlang + AWS 之旅顺利！🚀

【免费下载链接】erlcloudAWS APIs library for Erlang (Amazon EC2, S3, SQS, DDB, ELB and etc)项目地址: https://gitcode.com/gh_mirrors/er/erlcloud