证书、令牌、区域:本地模拟环境里最容易被忽略的三类配置
证书、令牌、区域:本地模拟环境里最容易被忽略的三类配置
本地 AWS 模拟器最容易给人一种错觉:只要把 endpoint 指向 http://localhost:4566、凭据填 test/test,一切就能跑通。事实也确实如此——直到你把测试搬进 Docker Compose、打开 HTTPS、开启 IAM 校验,或者让两个 SDK 客户端分别用 us-east-1 和 eu-west-1 签名。此时失败往往不是一句清晰的报错,而是“证书链断了”“AssumeRole 403”“资源凭空消失”这类需要翻日志才能定位的问题。
Floci 把这三件事都实现得相当“较真”:它有一条真实的本地根 CA,有一套会校验信任策略的 STS,还有一套按 SigV4 签名区域切分的存储命名空间。本文结合仓库源码与文档,把这三类配置讲清楚,并给出一份可以直接复用的初始化模板。
一、证书:一条本地根 CA,串起 HTTPS、ACM 与工作负载容器
Floci 的 TLS 不是“随便生成一个自签证书”。打开 FLOCI_TLS_ENABLED=true 后,它会维护一个本地根 CA,落在 {persistent-path}/tls/floci-root-ca.crt(私钥 floci-root-ca.key),并通过 GET /_floci/ca.pem 暴露出来。关键在于:HTTPS 服务端证书、每一个 ACM 证书、每一个 IoT 设备证书,都链到这一个 CA。
代码层面这条链路很明确。FlociCertificateAuthority 负责加载或创建 CA,类注释写得很直白:“Every certificate the emulator hands out that a client is expected to validate ... chains to it, so a developer trusts one file once”;EmulatorInfoController 的 /_floci/ca.pem 端点返回这个 PEM;如果你提供了自定义证书,返回的是“你的证书链 + 本地 CA”的 bundle,而不是只返回叶子证书。
所以客户端侧正确的接法是“信任一次、进程级生效”,而不是关掉校验:
curl -s http://localhost:4566/_floci/ca.pem -o floci-root-ca.pem
export AWS_CA_BUNDLE=$PWD/floci-root-ca.pem # AWS CLI / AWS SDK
export NODE_EXTRA_CA_CERTS=$PWD/floci-root-ca.pem # Node.js(追加)
export SSL_CERT_FILE=$PWD/floci-root-ca.pem # curl / Python / Go(替换)
这三个变量的语义不同:SSL_CERT_FILE 是替换默认根证书集合,NODE_EXTRA_CA_CERTS 是追加,AWS_CA_BUNDLE 只作用于 AWS SDK 与 CLI 流量。文档建议把它们限定在需要的 shell 或 compose 的 environment: 块里,而不是装进操作系统信任库——因为一旦装进系统,本机所有进程都会信任那个私钥签出的任何东西。
测试容器里最容易踩的两个坑
坑一:主机名不在 SAN 里。 服务端证书的 SAN 覆盖 localhost、127.0.0.1、*.localhost、*.localhost.floci.io、*.execute-api.localhost.floci.io、*.cloudfront.localhost.floci.io 以及每个已发布区域的 *.dkr.ecr.<region>.localhost.floci.io 等。如果你在 Compose 里用服务名访问,必须设 FLOCI_HOSTNAME=floci(或在 FLOCI_BASE_URL 里用该主机名),Floci 会把它加进 SAN,并在主机名配置变化时重新签发服务端证书。否则 app 容器连 https://floci:4566 时校验必然失败,而失败信息只会说“证书不匹配”。
坑二:Floci 自己启动的容器怎么办? 这一层其实已经自动化了。ContainerCaBundle 会写出 {persistent-path}/tls/floci-ca-bundle.pem——JVM 默认根证书 + Floci 的信任锚,然后由 ContainerLifecycleManager 拷进容器的 /etc/floci-ca-bundle.pem,并把 SSL_CERT_FILE、CURL_CA_BUNDLE、REQUESTS_CA_BUNDLE、NODE_EXTRA_CA_CERTS、AWS_CA_BUNDLE 全部指向它。因为 bundle 里带着公共根证书,用“替换型”变量也不会让容器失去访问公网 HTTPS 的能力。Lambda 的 Kubernetes 启动路径则通过 ConfigMap 挂载同一个文件。
两个例外值得记住:
- JVM 不读这些变量。Java 工作负载仍要自己构造 trust store,或用
ApacheHttpClient.builder().tlsTrustManagersProvider(...)显式加载 CA,文档里给了完整示例。 - 你在函数或任务定义里显式设置的变量优先,注入逻辑不会覆盖已有键。
ACM 与 TLS 的关系常被误解
ACM 的文档明确写着:本地 CA 在第一次签发证书时创建,即使 TLS 关闭、即使存储模式是 memory,所以 {persistent-path}/tls/ 必须可写。也就是说,“我没开 HTTPS,所以不需要关心证书目录”是错的。另一个细节是 DescribeCertificate 返回的 Issuer 是 CN=Floci Local CA,而 AWS 返回 Amazon——任何对 issuer 字符串做断言的测试都会在这里翻车。
最后一条安全实践:GET /_floci/ca.pem 走的是明文 HTTP,它不证明来源。跨主机使用时应该从卷里读 tls/floci-root-ca.crt 或用 docker cp 取出,并比对指纹(启动日志会打印 SHA256 fingerprint AB:CD:...):
openssl x509 -in floci-root-ca.pem -noout -fingerprint -sha256
二、令牌:角色信任与临时凭据到底在哪一步被校验
很多人对本地模拟器的 IAM 有一个模糊印象:“反正不校验”。Floci 的默认行为确实宽松,但宽松的边界是精确的,而且会随开关变化。
默认态:角色必须存在,信任策略默认可放行
AssumeRole 和 AssumeRoleWithWebIdentity 在任何模式下都要求目标角色在 IAM 中存在,否则返回 AccessDenied(403)。这已经能挡掉一类错误:只写了 role_arn 却没在本地创建角色。
当 FLOCI_SERVICES_IAM_ENFORCEMENT_ENABLED=true 时,AssumeRole 会真正求值目标角色的 AssumeRolePolicyDocument:支持 "*"、账号 ID、arn:aws:iam::<acct>:root 和精确 principal ARN,显式 Deny 永远优先,Action 与 NotAction 都会参与 sts:AssumeRole 的匹配;同时调用方自身的身份策略也必须允许对该角色 ARN 执行 sts:AssumeRole。这意味着“能扮演 A 角色、不能扮演 B 角色”在本地是可测的。
一个常被忽略的缺口写在文档里:session tags 与 source identity 没有建模,aws:RequestTag/*、aws:TagKeys、sts:TransitiveTagKeys、sts:SourceIdentity 不在请求上下文中,因此带这些条件的信任策略不会命中,sts:TagSession 也不会被检查。把线上依赖标签条件的策略直接搬到本地验证,会得到“看起来通过了”的假阳性。
临时凭据会改变“你属于哪个账号”
这是令牌与账号模型的交汇点,也是跨账号测试能否成立的关键。Floci 解析账号的顺序是:12 位纯数字 AKID 直接当账号 ID → 活跃的长期 IAM 密钥 → 活跃的 STS 临时凭据 → 兜底 FLOCI_DEFAULT_ACCOUNT_ID。
对于 STS 临时凭据,路由规则是:
AssumeRole/ WebIdentity / SAML / Federation → 落在角色 ARN 所属账号;GetSessionToken→ 落在调用者自己的账号(因为不携带角色)。
于是“账号 A 扮演账号 B 的角色,然后用返回的 ASIA... 凭据建资源”这件事,在本地会真实地写进账号 B 的命名空间。这是 CloudFormation 跨账号部署这类模式能在本地跑通的原因,也是 AssumeRole 之后资源“跑到别处去了”的原因——它不是 bug。
IRSA:本地也能验证 JWT 签名
EKS 场景下,每个集群都会得到 OIDC issuer 和一个 RSA-2048 签名密钥对。当 AssumeRoleWithWebIdentity 收到的令牌 iss 指向 Floci 托管的 issuer 时,它会校验:RS256 签名、iss 精确匹配、aud 包含 sts.amazonaws.com、exp/nbf(60 秒时钟偏移容忍),以及角色信任策略里的 Principal.Federated 和 sub/aud 条件(大小写敏感的精确比较,支持 StringEquals、StringLike、NotEquals、NotLike)。
在真实 k3s 模式下,密钥会被导出到 /etc/rancher/k3s/sa-signing-key.pem 供 API Server 签发投射令牌;在 mock 模式或集群外测试时,可以直接向 Floci 要一个令牌:
curl -sX POST http://localhost:4566/_floci/eks/clusters/my-cluster/oidc-token \
-H 'Content-Type: application/json' \
-d '{"namespace":"default","serviceAccount":"irsa-workload"}'
这里有一个与“令牌”直接相关的默认行为差异:当 IAM 强制关闭时,来自 Floci 不托管 issuer 的令牌(或根本不是可解析 JWT 的令牌)会被当成不透明凭据接受,只要角色存在;打开强制后,这类令牌统一返回 InvalidIdentityToken。所以同一份 IRSA 测试在两种模式下结论完全不同——这是排查“为什么开了 enforcement 之后 Web Identity 全挂”的第一嫌疑点。
一个能省很多事的开关
FLOCI_SERVICES_IAM_SEED_DEPLOYER_PRINCIPAL=true 会在启动时创建 floci-deployer 用户,挂上 arn:aws:iam::aws:policy/AdministratorAccess,并生成静态凭据 floci/floci(IamService 中的 DEFAULT_DEPLOYER_USER 与 postConstruct 的 seedDefaults())。开启 IAM 校验后,用一个有真实 ARN 的管理员身份去跑 Terraform、CDK 之类的工具,比用匿名 test 凭据稳定得多——GetCallerIdentity 会返回该用户 ARN,而不是账号 root 兜底。
还有一个容易被忽略的连带影响:FLOCI_AUTH_VALIDATE_SIGNATURES=true 之后,没有角色的工作负载拿到的占位凭据是校验不过的(例如没有执行角色的 Lambda)。文档对此说得很明确:给函数一个角色。签名的世界和“随便填”的世界不能混用。
三、区域:它不是标签,而是命名空间与分区选择器
Floci 决定请求区域的逻辑集中在 RegionResolver,规则可以概括为四条:
- 从 SigV4
Authorization头的凭据作用域里取Credential=AKID/date/region/service/aws4_request的第三段; - 预签名请求取查询参数
X-Amz-Credential里的同一段; - SigV4A(
AWS4-ECDSA-P256-SHA256)没有区域段,改看X-Amz-Region-Set——只有集合中恰好一个具体区域时才采用,通配符或多元素集合回落到默认区域; - 没有凭据(或请求不在请求上下文中,例如轮询器、启动钩子)一律用
FLOCI_DEFAULT_REGION。
<partition>-global 这类伪区域会被规范化成该分区的隐式全局区域(例如 aws-cn-global 按 cn-northwest-1 处理),不会变成独立的存储命名空间。
“数据串场”的真实机制
区域被拼进了存储键。SqsService 里:
private String regionKey(String region, String queueUrl) {
return region + "::" + extractQueuePath(normalizeQueueUrl(queueUrl));
}
SSM 同样是 region + "::" + name,ECR 更直接,内部把仓库命名为 <account>/<region>/<repoName>。而账号维度由 AccountAwareStorageBackend 在最外层再加上 account/ 前缀。所以一个键的实际形状是“账号前缀 / 区域前缀 / 资源名”的三段式。
仓库里的集成测试 RegionIsolationIntegrationTest 就是手工构造不同区域的 Authorization 头,验证同名 SSM 参数和 DynamoDB 表在两个区域互不可见,并且返回的 ARN 里带对应区域。
由此可以推出三类经典故障:
- CLI 与代码区域不一致。你在终端
export AWS_DEFAULT_REGION=us-east-1建了队列,代码里 SDK 客户端硬编码eu-west-1,于是ListQueues返回空。资源没丢,只是不在那个命名空间里。 - 初始化钩子的区域被镜像默认值覆盖。
latest-compat镜像在钩子脚本里预置了AWS_DEFAULT_REGION=us-east-1(以及AWS_ENDPOINT_URL、test/test)。如果你把FLOCI_DEFAULT_REGION改成了eu-west-1却没在 compose 的environment:里覆盖AWS_DEFAULT_REGION,ready.d里种下的种子数据会落在us-east-1,而你的应用在eu-west-1里找不到它们。这是“资源凭空消失”最常见的一种。 - 只测了单区域。很多服务确实是区域隔离的,但也有真实 AWS 语义上的例外:Cost Explorer 的监控项与订阅“在调用账号内是全局的,不同区域签名的请求看到同一批资源”;IoT 的 MQTT broker 本身没有区域和账号,订阅者会收到所有区域的 shadow 事件;S3 默认按账号隔离桶,但打开
FLOCI_SERVICES_S3_GLOBAL_BUCKET_NAMESPACE=true后桶解析会跨账号。把“所有服务都严格按区域隔离”当成前提写断言,同样会翻车。
区域还会决定分区,而分区决定 ARN 与域名
FLOCI_DEFAULT_REGION 不只是默认值,它还推导部署分区:cn-north-1 → aws-cn,us-gov-west-1 → aws-us-gov。而单个请求的分区来自它的签名区域,所以一个进程可以同时服务多个分区。这与“区域”直接相关,因为分区一旦选错,ARN 前缀(arn:aws-cn:...)、DNS 后缀(amazonaws.com.cn)、S3 CreateBucket 的 LocationConstraint 规则都会跟着变。
两条硬性拒绝规则值得写进团队 checklist:
- 作用域里出现任何分区都不认识的区域(例如
polygondwanaland-west-1),S3 请求返回AuthorizationHeaderMalformed,其他服务返回InvalidSignatureException(400)。想让它拥有独立命名空间,必须显式开FLOCI_PARTITIONS_ALLOW_UNKNOWN_REGIONS=true。 - 区域标签里含冒号一律拒绝,因为冒号是 ARN 字段和存储标识的分隔符;这条同样适用于
FLOCI_DEFAULT_REGION,带冒号时 Floci 直接拒绝启动。
版图再往回看一层:账号是另一根独立的轴。12 位数字 AKID 会被直接当作账号 ID,这是和 LocalStack 一致的约定;但文档也提醒,账号选择只依赖 AKID,不校验你是否持有对应 secret,所以账号命名空间不是互不信任客户端之间的安全边界。
四、一份可直接复用的初始化配置模板
下面这份 docker-compose.yml 把三类配置一次性钉死:TLS + 固定主机名、区域与账号、IAM 强制与管理员身份。注释标出了每个变量为什么在这里。
services:
floci:
image: floci/floci:latest-compat
ports:
- "4566:4566"
environment:
# —— 证书 ——
FLOCI_TLS_ENABLED: "true"
FLOCI_HOSTNAME: floci # 关键:让服务端证书的 SAN 覆盖服务名
FLOCI_BASE_URL: https://floci:4566
# —— 区域 / 分区 / 账号 ——
FLOCI_DEFAULT_REGION: eu-west-1 # 同时决定分区与无凭据请求的落点
FLOCI_DEFAULT_ACCOUNT_ID: "000000000000"
# —— 令牌 ——
FLOCI_SERVICES_IAM_ENFORCEMENT_ENABLED: "true"
FLOCI_SERVICES_IAM_SEED_DEPLOYER_PRINCIPAL: "true" # floci/floci + AdministratorAccess
# —— 持久化(CA 也在这里)——
FLOCI_STORAGE_MODE: persistent
FLOCI_STORAGE_PERSISTENT_PATH: /data
volumes:
- floci-data:/data
- ./init:/etc/floci/init:ro
healthcheck:
test: ["CMD-SHELL", "curl -fsS http://localhost:4566/_floci/health || exit 1"]
interval: 2s
retries: 30
app:
build: .
depends_on:
floci:
condition: service_healthy
environment:
AWS_ENDPOINT_URL: https://floci:4566
AWS_DEFAULT_REGION: eu-west-1 # 必须与默认区域一致,别依赖镜像默认的 us-east-1
AWS_ACCESS_KEY_ID: floci
AWS_SECRET_ACCESS_KEY: floci
AWS_CA_BUNDLE: /floci-ca/tls/floci-root-ca.crt
volumes:
- floci-data:/floci-ca:ro # 共享卷直接拿到 CA,不必依赖明文下载
volumes:
floci-data:
app 容器通过共享卷读到 {persistent-path}/tls/floci-root-ca.crt,这比 curl http://floci:4566/_floci/ca.pem 更可靠:不依赖启动顺序,也不依赖明文 HTTP。
接着在 ready.d 里种下角色与信任策略。注意脚本里显式再设一次 AWS_DEFAULT_REGION,避免被镜像预置值覆盖:
#!/bin/sh
set -eu
export AWS_DEFAULT_REGION="${AWS_DEFAULT_REGION:-eu-west-1}"
export AWS_ACCESS_KEY_ID=floci
export AWS_SECRET_ACCESS_KEY=floci
# 1) 工作负载角色:信任 lambda 服务
aws iam create-role --role-name app-exec \
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"Service": "lambda.amazonaws.com"},
"Action": "sts:AssumeRole"
}]
}' >/dev/null 2>&1 || true
aws iam attach-role-policy --role-name app-exec \
--policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
# 2) 可扮演角色:信任本账号,供 AssumeRole 测试
aws iam create-role --role-name deployer \
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"AWS": "arn:aws:iam::000000000000:root"},
"Action": "sts:AssumeRole"
}]
}' >/dev/null 2>&1 || true
# 3) 一张与这条 CA 同源的 ACM 证书
aws acm request-certificate --domain-name app.localhost.floci.io \
--validation-method DNS >/dev/null
# 4) 把“默认区域”这件事写在种子里,减少跨区域误判
aws ssm put-parameter --name /app/region --type String --value "$AWS_DEFAULT_REGION" --overwrite
最后用三条命令验收,分别对应三类配置:
# 证书:HTTPS 能通、身份能取到、issuer 与指纹一致
curl --cacert floci-root-ca.pem https://floci:4566/_floci/ca.pem | openssl x509 -noout -subject
aws --endpoint-url https://floci:4566 sts get-caller-identity
aws --endpoint-url https://floci:4566 acm describe-certificate --certificate-arn "$(aws acm list-certificates --query 'CertificateSummaryList[0].CertificateArn' --output text)" \
--query 'Certificate.Issuer'
# 令牌:临时凭据应落到角色所属账号,且被信任策略放行
aws --endpoint-url https://floci:4566 sts assume-role \
--role-arn arn:aws:iam::000000000000:role/deployer \
--role-session-name smoke --query 'Credentials.AccessKeyId' --output text
# 区域:同一参数名在两个区域互不可见
aws --endpoint-url https://floci:4566 ssm get-parameter --name /app/region
aws --endpoint-url https://floci:4566 --region us-east-1 ssm get-parameter --name /app/region # 期望 ParameterNotFound
如果第三条返回了 ParameterNotFound,说明区域隔离生效了;如果两条都返回同一个值,先检查是不是走了无凭据路径落到了默认区域,或者脚本里的 AWS_DEFAULT_REGION 被镜像默认值覆盖。
收尾:把“默认能跑”升级成“默认正确”
Floci 的默认配置刻意做得宽松:任意凭据、明文 HTTP、单一区域。这让第一次 docker compose up 极其顺畅,也让后续的迁移成本被推迟到最不该出现的时候——CI 里、预发前、或者某个只在 HTTPS 下才触发的路径上。
三类配置的处理原则其实是一致的:不要全局关闭校验,而是把信任精确地交给该信任的那一个进程。证书用一条本地 CA、一次进程级信任变量解决;令牌用“角色必须存在 + 显式开启强制 + 用有 ARN 的管理员身份”解决;区域则要意识到它是命名空间与分区选择器,凡是会发出请求的地方(应用、CLI、初始化钩子、Terraform provider)都必须对齐签名区域,而不是依赖服务端默认值兜底。
这三件事都在仓库里有据可查:CA 的创建与分发在 FlociCertificateAuthority 和 ContainerCaBundle,令牌与信任策略的求值规则在 STS 文档 与 IAM 文档,区域的解析与分区推导在 RegionResolver 与 分区文档。把它们读一遍,比在失败日志里猜要快得多。