十分钟跑通第一次本地云调用:最小可用路径

原创2026-11-04 14:28:162,188 阅读
文章标签:云原生测试开发工具本地部署

十分钟跑通第一次本地云调用:最小可用路径

对一个本地云模拟器来说,"第一次调用成功"是最难也最重要的十分钟。它会同时验证四件事:进程是否真的监听在预期端口、客户端是否真的把请求发到了本机、凭据是否被接受、以及这条链路上的错误信息是否可读。Floci 的项目定位正好压在这条线上——无需账号、无需 auth token、没有功能闸门,docker compose up 之后所有 AWS 服务都在 http://localhost:4566 上(见 README.md)。本文不谈全量服务覆盖,只把这条最小路径拆到可复制的程度,并用仓库源码解释每一个成功或失败信号从哪来。

十分钟的前提:三条启动路径里选最短的一条

仓库给出了三种启动方式(docs/getting-started/installation.md):Docker 镜像、预编译原生二进制、源码构建。第一次跑通建议直接用镜像,latest 是原生镜像,官方对比表给出的启动时间约 24 ms、空闲内存约 13 MiB、镜像约 90 MB(README.md 的能力对比表)。如果你只是想知道"能不能通",这是成本最低的选择。

最小 compose 文件只有六行,出处是 docs/getting-started/quick-start.md:

services:
  floci:
    image: floci/floci:latest
    ports:
      - "127.0.0.1:4566:4566"
    volumes:
      - ./data:/app/data

把发布端口显式绑在回环地址上是刻意的:仓库自己的环境变量文档写明,镜像内部监听 0.0.0.0,谁能访问 4566 完全取决于你如何发布端口,"Publish it on loopback unless other machines need it"(docs/configuration/environment-variables.md)。只有当你确实让 Lambda、ECS 这类容器化服务回连宿主时才需要放开,并且还要额外设置 FLOCI_SECURITY_ALLOW_UNSAFE_NETWORK_EXPOSURE。

启动之后不要凭感觉等待,用仓库自己的两个探针确认:

docker compose up -d

# 存活 + 服务清单
curl -s http://localhost:4566/_floci/health

# 初始化钩子的分阶段完成状态
curl -s http://localhost:4566/_floci/init

/_floci/health 由 HealthController.java 提供,返回 services、edition、original_edition、version 四个字段;/_floci/init 由 EmulatorInfoController.java 提供,返回 completed 里 boot / start / ready / shutdown 四个阶段的布尔值和每个脚本的 state、return_code。这个区别很实用:HTTP 端口通了不等于 ready 阶段跑完了。如果你挂了初始化钩子去预置资源,/_floci/init 才是应该等待的信号。镜像自带的健康检查脚本 docker/healthcheck.sh 正是轮询 /_floci/init 并匹配 "ready":true。

另外,日志里会出现一行 === AWS Local Emulator Ready ===,以及一行兼容用的 Ready.。后者的存在理由写在 EmulatorLifecycle.java 的注释里:Testcontainers 的 LocalStackContainer 默认等待策略是用正则 .*Ready\. 扫日志,只发自己的横幅会让它超时。这类细节决定了"看起来能跑"和"工具链真的能接上"之间的差别。

端点重定向:四行环境变量就能接管 SDK

Floci 复用 4566 端口和标准 AWS 环境变量,所以重定向本质上不是改代码,而是改环境(docs/getting-started/aws-setup.md):

export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_DEFAULT_REGION=us-east-1
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test

AWS_ENDPOINT_URL 是 AWS CLI v2 与 SDK v2+ 识别的标准变量,因此逐条命令不用再带 --endpoint-url(docs/services/index.md)。先在命令行确认连通性,再动代码:

aws sts get-caller-identity
aws s3 mb s3://my-bucket
echo "hello floci" | aws s3 cp - s3://my-bucket/hello.txt
aws s3 ls s3://my-bucket

get-caller-identity 应该立刻返回账号 000000000000。这个值不是硬编码的假数据,而是账号解析的默认落点:StsQueryHandler.java 里,当调用者凭据解析不出具体 IAM 身份时,ARN 回退为 arn:aws:iam::<account>:root,UserId 回退为账号 ID 本身。

在代码里,SDK 需要显式指定 endpoint,其中 S3 有一个容易踩的坑——先给 boto3 版本:

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="http://localhost:4566",
    region_name="us-east-1",
    aws_access_key_id="test",
    aws_secret_access_key="test",
)
s3.create_bucket(Bucket="my-bucket")
print(s3.list_buckets()["Buckets"])

Node.js 的 AWS SDK v3 必须加 forcePathStyle: true,否则默认的虚拟主机寻址会拼出 my-bucket.localhost:4566 这类主机名:

import { S3Client, CreateBucketCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "http://localhost:4566",
  region: "us-east-1",
  credentials: { accessKeyId: "test", secretAccessKey: "test" },
  forcePathStyle: true,
});
await s3.send(new CreateBucketCommand({ Bucket: "my-bucket" }));

仓库的 Node 兼容测试就是把这个配置收敛成一个共享常量(compatibility-tests/sdk-test-node/tests/setup.ts),Python 侧则是把四个环境变量整体注入 client 工厂(compatibility-tests/sdk-test-python/conftest.py)。两处写法值得直接抄,因为它们是被上千个用例反复验证过的形态。

还有一个仓库内的小工具常被忽略:bin/awslocal。它先 export 四个变量,然后仍然显式传 --endpoint-url 再 exec aws。脚本里的注释解释了原因:少数服务(尤其旧版 botocore 的 SQS)会通过服务特定的 endpoint 解析器绕过 AWS_ENDPOINT_URL,把请求发到公网 AWS。所以如果你看到某条命令莫名其妙打到真实云上、或报 InvalidClientTokenId,第一反应应该是补上显式 --endpoint-url。

带身份校验的一次调用:从 test 到 IAM 用户

默认配置下,Floci 的"身份"是极简的:任何非空凭据都能通过,账号由 Access Key ID 推导。签名校验默认关闭,src/main/resources/application.yml 里写得很直白:

floci:
  auth:
    validate-signatures: false
    presign-secret: local-emulator-secret

这里有两层需要分清,混在一起是第一次配置最常见的困惑:

  1. 认证(authentication):请求是不是用它声称的那把 key 签的。由 FLOCI_AUTH_VALIDATE_SIGNATURES 控制,SigV4HeaderSignatureFilter.java 实现,开启后会重建规范请求并逐字节比对签名。
  2. 授权(authorization):这把 key 背后的身份,被策略允许做什么。由 FLOCI_SERVICES_IAM_ENFORCEMENT_ENABLED 控制,IamEnforcementFilter.java 实现。

两者都默认关闭,所以"跑通第一次调用"本来不需要它们。但如果你要验证业务代码里的 IAM 分支,就必须至少打开第二层。下面是完整可跑的一次带身份的调用,改编自 docs/services/iam.md 的最小强制示例:

# 1) 打开策略强制,用 test 凭据完成引导(test 永远绕过策略评估)
export FLOCI_SERVICES_IAM_ENFORCEMENT_ENABLED=true
docker compose up -d

# 2) 建用户、签发长期密钥
aws iam create-user --user-name alice
KEY=$(aws iam create-access-key --user-name alice \
  --query 'AccessKey.[AccessKeyId,SecretAccessKey]' --output text)
AKID=$(echo "$KEY" | awk '{print $1}')
SECRET=$(echo "$KEY" | awk '{print $2}')

# 3) 只给"列举桶"这一个动作
POLICY_ARN=$(aws iam create-policy \
  --policy-name allow-s3-list \
  --policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"s3:ListAllMyBuckets","Resource":"*"}]}' \
  --query 'Policy.Arn' --output text)
aws iam attach-user-policy --user-name alice --policy-arn "$POLICY_ARN"

# 4) 用 alice 的身份调用:允许的通过,越权的被拒
AWS_ACCESS_KEY_ID=$AKID AWS_SECRET_ACCESS_KEY=$SECRET aws s3 ls
AWS_ACCESS_KEY_ID=$AKID AWS_SECRET_ACCESS_KEY=$SECRET aws s3 mb s3://alice-bucket

第二条命令应当返回 AccessDeniedException,因为策略里只有 s3:ListAllMyBuckets。这不是"模拟器大概拒了",而是走了完整的策略评估:显式 Deny 优先、Allow 建立基础授权、无匹配则隐式拒绝,与 AWS 的优先级一致(docs/services/iam.md)。

如果你还想连带验证签名本身,再加一个开关,并把凭据换成上面签发的 IAM 密钥:

export FLOCI_AUTH_VALIDATE_SIGNATURES=true

此时 test/test 仍然有效(它是内置的可验证凭据),但形如 12 位数字账号的 Access Key 会失效:这类 key 只是路由元数据,不代表持有任何 secret。docs/configuration/multi-account.md 把失败矩阵写得很清楚——S3 头部签名返回 403 InvalidAccessKeyId,S3 预签名 POST 返回 403 SignatureDoesNotMatch,其余服务返回 403 InvalidClientTokenId 或 403 UnrecognizedClientException。这意味着多账号隔离演示和签名校验是两个互斥的教学场景,别在同一个 shell 里同时演示。

成功与失败的信号对照

把上面每一步的失败形态列成表,比读十页文档都省时间。左列是你会看到的字符串,右列是它在源码里的出处和成因。

现象 成因与定位
Connection refused / Could not connect to the endpoint URL 容器没起、端口没发布,或 AWS_ENDPOINT_URL 指向了错误主机。先用 curl -s http://localhost:4566/_floci/health 排除服务侧
Unable to locate credentials 只设了 endpoint 和 region,漏了 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY。Floci 接受任意非空值,但 CLI 在发出请求前本地就会拦
403 InvalidClientTokenId / UnrecognizedClientException 开了 validate-signatures 或 IAM 强制后,用了一把 Floci 不认识的 key。错误码按协议分派,见 SigV4HeaderSignatureFilter.java
403 InvalidAccessKeyId 同上,但请求走的是 S3 头部签名路径
403 SignatureDoesNotMatch 认证层失败:secret 不对、方法或路径参与签名的形态不一致,或签名时间偏离服务器超过 15 分钟
Signature expired: … / Signature not yet current: … 预签名 URL 的 X-Amz-Expires(1–604800 秒)已过,或头部签名时间超前。消息里的 cutoff 就是服务器时间减去有效窗口
400 IncompleteSignature / IncompleteSignatureException / AuthorizationHeaderMalformed Authorization 头缺字段(如缺 Credential、Signature、aws4_request 终止符),按协议返回不同名字
Credential should be scoped to correct service: '<service>' SigV4 凭据作用域里的服务名与接收请求的服务不匹配,只在服务有唯一注册签名名时给出这条精确消息
AccessDeniedException / AccessDenied / AuthorizationError 授权层失败:key 合法但策略不允许。状态码随协议变化,JSON 1.0/1.1 是 400,REST-JSON 是 403,Query 与 S3 是 403 XML,SNS 用 AuthorizationError
403 MissingAuthenticationToken 开了 IAM 强制却发了不带 Authorization 头的 RPC 请求(JSON / CBOR / Query)
IllegalLocationConstraintException / InvalidLocationConstraint S3 建桶的地区规则:非 us-east-1 端点必须带同名 LocationConstraint;us-east-1 端点不接受 us-east-1 常量本身,见 docs/services/s3.md 与 S3Controller.java
NoSuchBucket 常见于虚拟主机寻址拼错,或跨账号看到了别的命名空间里的桶(S3 默认按账号隔离)
请求成功但资源"消失" 切了 AWS_ACCESS_KEY_ID。12 位数字 key 会被直接当作账号 ID,资源落在该账号的命名空间里,见 AccountContextFilter.java
Lambda 调用一直 Function.TimedOut 原生 Linux 宿主上 UFW 拦了 docker 网桥回连,需要放行 docker0。这类问题不属于"第一次调用",见 docs/getting-started/quick-start.md 的 UFW 小节

这张表里有两条最值得记住的经验。第一,错误码的差异往往不是 Floci 的随意设计,而是协议差异:同一个"凭据无效"在 S3、Query、JSON 三套协议下必须是三个不同的名字,因为各 SDK 只认识自己模型里存在的那个。第二,账号解析与身份认证是两件事:即使在完全关闭校验的默认配置下,改一个 12 位数字的 Access Key 就已经改变了资源的可见范围,这一点对写多账号测试用例的人尤其重要。

十分钟结束时,你手上应该有三样东西:一个能返回服务清单的 /_floci/health、一条能打印 000000000000 的 get-caller-identity、以及一张知道该看哪里的失败信号表。剩下的服务覆盖、容器化后端和 CI 集成,都可以在这条已经打通的路径上逐项加。

登录后查看全文
floci