证书、令牌、区域:本地模拟环境里最容易被忽略的三类配置

原创2026-11-04 19:45:271,381 阅读
文章标签:云原生测试开发工具本地部署

证书、令牌、区域:本地模拟环境里最容易被忽略的三类配置

本地 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,规则可以概括为四条:

  1. 从 SigV4 Authorization 头的凭据作用域里取 Credential=AKID/date/region/service/aws4_request 的第三段;
  2. 预签名请求取查询参数 X-Amz-Credential 里的同一段;
  3. SigV4A(AWS4-ECDSA-P256-SHA256)没有区域段,改看 X-Amz-Region-Set——只有集合中恰好一个具体区域时才采用,通配符或多元素集合回落到默认区域;
  4. 没有凭据(或请求不在请求上下文中,例如轮询器、启动钩子)一律用 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 与 分区文档。把它们读一遍,比在失败日志里猜要快得多。

登录后查看全文
floci