【免费下载链接】flociLight, fluffy, and always free - The AWS Local Emulator alternative项目地址https://gitcode.com/gh_mirrors/fl/floci点击查看免费下载Floci 是一款以 Docker 镜像形式分发的 AWS 本地模拟器全部配置均通过FLOCI_*环境变量完成无需挂载任何 YAML 配置文件。本文以 docs/configuration/docker-compose.md 为骨架完整覆盖单容器快速启动、数据持久化、ElastiCache/RDS 等容器化服务的端口映射、多容器 DNS 互通、初始化钩子与 CI 管道配置并结合仓库源码如 docker-compose.yml、entrypoint.sh、Dockerfile给出源码级的原理说明帮助你在本地开发、集成测试与 CI 流水线中一次性把 Floci 跑起来。一、核心设计镜像分发 纯环境变量配置Floci 以 Docker 镜像形式发布其设计哲学是开箱即用、零配置文件所有配置项区域、账号、存储模式、代理端口、Docker 网络等都通过环境变量注入这与许多要求挂载application.yml的模拟器形成鲜明对比。仓库根目录的 docker-compose.yml 本身就是这套思路的官方示范——它不依赖任何外部配置文件仅靠environment块驱动。从 entrypoint.sh 可以看出这一设计在镜像层的落实入口脚本以 root 启动探测绑定的 Docker socket 属组并动态降权为 UID 1001 的floci用户随后直接exec用户传入的命令默认命令为java -Dquarkus.http.host0.0.0.0 -Dfloci.security.allow-unsafe-network-exposuretrue -jar ...。也就是说镜像默认监听0.0.0.0配合显式声明的允许不安全网络暴露确保发布端口后即可被宿主访问。二、Quick Start一条命令启动Floci 的默认配置即可支撑大多数常用服务的本地开发包括 SQS、SNS、S3、DynamoDB、SSM、Lambda、API Gateway、Cognito、KMS、Kinesis、Secrets Manager、CloudFormation、Step Functions、IAM、STS、EventBridge、Scheduler 和 CloudWatchdocker run --rm -p 4566:4566 floci/floci:latest启动后所有 AWS SDK / CLI 调用都指向http://localhost:4566例如aws s3 ls --endpoint-url http://localhost:4566 aws sqs list-queues --endpoint-url http://localhost:4566 aws lambda list-functions --endpoint-url http://localhost:4566Dockerfile 中定义了健康检查wget -q --spider http://localhost:4566/_floci/health间隔 5 秒、超时 3 秒、重试 5 次。编排工具可以依赖docker inspect的State.Health.Status等待就绪仓库的 compatibility.yml CI 工作流正是用这一机制轮询等待 Floci 变为healthy后才开始执行 SDK 兼容性测试套件。三、最小 Docker Compose 配置无状态对单测或一次性实验使用最小 Compose 文件即可services: floci: image: floci/floci:latest ports: - 4566:4566 environment: FLOCI_HOSTNAME: floci这里只映射了 AWS API 端口4566并设置FLOCI_HOSTNAME为服务名。默认存储模式为memory容器销毁后状态即消失非常适合 CI 管道详见下文存储模式。四、数据持久化两个变量 一个卷要在重启后保留状态只需要增加两个环境变量和一个命名卷依然不需要任何配置文件services: floci: image: floci/floci:latest ports: - 4566:4566 volumes: - floci-data:/app/data environment: FLOCI_HOSTNAME: floci FLOCI_STORAGE_MODE: persistent FLOCI_STORAGE_PERSISTENT_PATH: /app/data volumes: floci-data:FLOCI_STORAGE_PERSISTENT_PATH的镜像内默认路径就是/app/dataDockerfile 中ENV FLOCI_STORAGE_PERSISTENT_PATH/app/data并在末尾声明VOLUME /app/dataCompose 侧只需把命名卷挂到这个路径。存储模式深度说明FLOCI_STORAGE_MODE支持四种取值详见 docs/configuration/storage.md模式数据跨重启存活写入性能适用场景memory否最快单元测试、CI 管道persistent是每次变更同步写盘需要持久状态、看重即时落盘的开发hybrid是内存读 异步刷盘通用本地开发wal是追加式写前日志 压缩高写入负载一个值得注意的细节来自 storage.mdJava 代码注解中的默认值是hybrid但发布镜像自带的application.yml强制为memory因此直接运行官方镜像得到的默认行为是memory除非你显式设置FLOCI_STORAGE_MODE。存储模式还支持按服务覆盖例如全局内存、只持久化 DynamoDB 和 S3的混合方案FLOCI_STORAGE_MODEmemory FLOCI_STORAGE_SERVICES_DYNAMODB_MODEpersistent FLOCI_STORAGE_SERVICES_S3_MODEhybrid FLOCI_STORAGE_PERSISTENT_PATH/app/data可覆盖的服务包括SSM、SQS、S3、DYNAMODB、SNS、LAMBDA、CLOUDWATCHLOGS、CLOUDWATCHMETRICS、SECRETSMANAGER、ACM、OPENSEARCH、RDS、ELASTICACHE、APPCONFIG、BACKUP、FIS等模式用FLOCI_STORAGE_SERVICES_SERVICE_MODE指定异步刷盘间隔用FLOCI_STORAGE_SERVICES_SERVICE_FLUSH_INTERVAL_MS指定默认5000毫秒。对于 RDS、OpenSearch、MSK、ECR 这类由 Floci 拉起真实 Docker 容器的服务其数据存放在命名 Docker 卷中命名规则如floci-rds-{volumeId}、floci-opensearch-{volumeId}全部带flocitrue标签可用标准命令管理docker volume ls --filter labelflocitrue docker volume prune --filter labelflocitrue # 注意破坏性操作卷的生命周期与存储模式联动memory模式下资源删除时卷总是被移除其他模式下默认保留贴近真实 AWS 行为如需即时删除可设置FLOCI_STORAGE_PRUNE_VOLUMES_ON_DELETEtrue。五、带 ElastiCache 与 RDS 的完整配置ElastiCache 与 RDS 会把 TCP 连接代理到真实 Docker 容器这些容器端口必须从宿主可达因此需要额外暴露端口段同时 Floci 需要 Docker socket 来管理这些容器services: floci: image: floci/floci:latest ports: - 4566:4566 - 6379-6399:6379-6399 # ElastiCache proxy ports - 7001-7099:7001-7099 # RDS proxy ports volumes: - /var/run/docker.sock:/var/run/docker.sock - floci-data:/app/data environment: FLOCI_HOSTNAME: floci FLOCI_SERVICES_DOCKER_NETWORK: myproject_default FLOCI_STORAGE_MODE: persistent FLOCI_STORAGE_PERSISTENT_PATH: /app/data volumes: floci-data:⚠️Docker socket 警告Lambda、ElastiCache、RDS、OpenSearch、MSK 需要访问/var/run/docker.sock来拉起并管理容器。若你完全不用这些服务可以省略该卷挂载。ECR 数据面说明ECR 复用 Floci 的4566监听端口处理 Docker push/pullregistry:2侧车容器只占用一个 loopback 实现端口因此 Floci 服务的ports列表中不应包含任何 ECR 专用端口段。详见 Ports Reference: ECR。为什么是这两个端口段源码与端口参考印证docs/configuration/ports.md 明确区分了 Floci 暴露容器端口的两种模式这决定了你的ports:列表该写什么代理进程在 Floci 容器内ElastiCache6379–6399、MemoryDB6400–6419、RDS7001–7099、Neptune Gremlin8182–8282、MWAA8700–8799监听器在 Floci 容器内部docker-compose.yml的ports:映射是必须的宿主才能访问。容器直接绑定宿主端口Web 控制台4500、EKS k3s API6500–6599、OpenSearch 数据面9400–9499、Amazon MQ5672–5699与15672–15699端口由 Docker daemon 直接绑定在宿主上Floci 通过共享 Docker 网络与容器通信不需要在ports:中映射——强行加上反而可能与后端容器的绑定冲突。仓库根目录的 docker-compose.yml 完整实践了这一原则它映射了4566、6379-6399、7001-7099、9200-9299注9200–9299曾是 Lambda Runtime API 的旧端口段现已在 ports.md 中调整为12000–12499且无需映射并挂载了 Docker socket。各端口段的起止可用对应环境变量调整例如FLOCI_SERVICES_ELASTICACHE_PROXY_BASE_PORT/FLOCI_SERVICES_ELASTICACHE_PROXY_MAX_PORT默认6379/6399FLOCI_SERVICES_RDS_PROXY_BASE_PORT/FLOCI_SERVICES_RDS_PROXY_MAX_PORT默认7001/7099FLOCI_SERVICES_EKS_API_SERVER_BASE_PORT/_MAX_PORT默认6500/6599FLOCI_SERVICES_OPENSEARCH_PROXY_BASE_PORT/_MAX_PORT默认9400/9499创建资源后即可直连代理端口例如创建 ElastiCache 复制组后redis-cli -h localhost -p 6379直连创建 RDS 实例后psql -h localhost -p 7001 -U admin连接代理端口来自Describe*响应的Endpoint.Port。六、多容器网络FLOCI_HOSTNAME 与 DNS 互通Floci 默认会把localhost嵌入响应 URL——例如 SQS 队列 URL 形如http://localhost:4566/000000000000/my-queue。应用与本机同机运行时没问题但在 Docker Compose 中其他容器无法访问 Floci 容器的localhost需要设置FLOCI_HOSTNAME为 Compose 服务名services: floci: image: floci/floci:latest ports: - 4566:4566 environment: FLOCI_HOSTNAME: floci # (1) app: build: . environment: AWS_ENDPOINT_URL: http://floci:4566 depends_on: - floci必须与 Compose 服务名一致其他容器才能通过 DNS 解析到它。设置后Floci 返回的 URL 变成http://floci:4566/000000000000/my-queue其他容器即可访问。从 EmulatorConfig.java 的源码注释可以印证其实现FLOCI_HOSTNAME存在时会替换FLOCI_BASE_URL中的主机名部分从而影响所有响应中生成的 URL。受影响的关键字段包括SQS ——QueueUrlSNS —— topic ARN 回调 URL 与订阅端点任何由FLOCI_BASE_URL派生的预签名 URL 或回调地址与 Lambda 容器的网络互通当未显式配置 Docker 网络时Floci 会自动把其拉起的 Lambda 容器挂到同一个 Compose 网络上。设置FLOCI_HOSTNAME确保这些容器拿到可达的端点且响应字段如 SQSQueueUrl使用 Docker 服务名而非localhost。仓库根目录的 docker-compose.yml 展示了更进一步的做法把FLOCI_BASE_URL显式设为http://floci:4566并为服务添加网络别名localhost.floci.io配合FLOCI_SERVICES_ELASTICACHE_CLUSTER_ANNOUNCE_HOSTNAME: localhost.floci.io让集群模式节点通告的MOVED/ASK重定向地址能被所有客户端解析。其注释解释得很清楚localhost.floci.io在宿主上经公共 DNS 解析到127.0.0.1到达发布的代理端口在 Compose 网络内则解析为 Floci 容器别名。CI 提示在 GitHub Actions 或 GitLab CI 中当你的应用与 Floci 都作为services运行时把FLOCI_HOSTNAME设为服务名如floci并让 SDK 指向http://floci:4566。这与仓库 compatibility.yml 中真实 CI 的做法一致——它创建compat-net网络后以-e FLOCI_BASE_URLhttp://floci:4566 -e FLOCI_SERVICES_DOCKER_NETWORKcompat-net -e FLOCI_HOSTNAMEfloci启动 Floci再运行各语言 SDK 兼容性测试。网络自动检测与覆盖当 Floci 运行在容器内且未配置网络时它会自动探测当前容器的 Docker 网络并用于其拉起的容器仅在需要强制指定时才需手动设置FLOCI_SERVICES_DOCKER_NETWORK。注意 Compose 默认网络名是project-name_default例如 compose 文件位于myapp目录则网络名为myapp_default。各容器化服务还支持更细粒度的覆盖变量如FLOCI_SERVICES_LAMBDA_DOCKER_NETWORK、FLOCI_SERVICES_RDS_DOCKER_NETWORK、FLOCI_SERVICES_ELASTICACHE_DOCKER_NETWORK等。七、CI 管道示例在 GitHub Actions 中把 Floci 作为服务运行测试步骤通过AWS_ENDPOINT_URL指向它services: floci: image: floci/floci:latest ports: - 4566:4566 steps: - name: Run tests env: AWS_ENDPOINT_URL: http://localhost:4566 AWS_DEFAULT_REGION: us-east-1 AWS_ACCESS_KEY_ID: test AWS_SECRET_ACCESS_KEY: test run: mvn test这里test/test凭据与us-east-1区域正是镜像内预置的默认值Dockerfile 中ENV AWS_DEFAULT_REGIONus-east-1 AWS_ACCESS_KEY_IDtest AWS_SECRET_ACCESS_KEYtestSDK 与 CLI 无需额外配置即可通过鉴权。若测试应用也在同一网络内把AWS_ENDPOINT_URL改为http://floci:4566即可。仓库的 compatibility.yml 是更完整的生产级参考它会创建专用网络、注入FLOCI_SERVICES_DOCKER_NETWORK与FLOCI_HOSTNAME、启用 TLS 与 Lambda 热重载并通过 Docker 健康状态轮询等待就绪再对 Java、Go、Node、Python、awscli、Terraform/OpenToFu、CDK 等多套测试矩阵执行。你的 CI 可以直接借鉴这套参数组合。八、初始化钩子Initialization HooksFloci 支持按生命周期阶段执行 shell / Python 初始化脚本用于预置资源或收尾清理无需任何配置变量——Floci 按目录自动发现脚本services: floci: image: floci/floci:latest-compat ports: - 4566:4566 volumes: - ./init/boot.d:/etc/floci/init/boot.d:ro # before storage loads — no AWS APIs yet - ./init/start.d:/etc/floci/init/start.d:ro # after HTTP server is ready - ./init/ready.d:/etc/floci/init/ready.d:ro # after all start hooks complete - ./init/stop.d:/etc/floci/init/stop.d:ro # during shutdown, while HTTP is still up脚本调用aws或boto3时务必使用latest-compat镜像——它内置了 AWS CLI 与 boto3且已针对本地端点预配置脚本内无需--endpoint-url标志Dockerfile 中用一个aws.real包装脚本把默认--endpoint-urlhttp://localhost:4566注入所有 CLI 调用并写入/etc/floci/aws/config。已有 LocalStack init 脚本时挂载到 LocalStack 兼容路径即可原样运行volumes: - ./localstack-init/ready.d:/etc/localstack/init/ready.d:ro关于执行顺序、脚本类型与退出码行为的完整说明见 Initialization Hooks要点包括阶段执行时机AWS API 可用目录Floci / LocalStack 兼容boot存储加载前、服务启动前否boot.d/boot.dstartHTTP 服务器在 4566 就绪后是 ✅start.d/start.dready所有 start 钩子完成后是 ✅ready.d/ready.dstop关停期间、HTTP 仍在线时是 ✅stop.d或shutdown.d/shutdown.d同阶段脚本按字典序串行执行用01-、02-前缀控制顺序采用快速失败策略非零退出会跳过该阶段剩余脚本boot或start/ready钩子失败会导致 Floci 关停stop钩子失败仅记录日志。可通过FLOCI_INIT_HOOKS_TIMEOUT_SECONDS默认30秒与FLOCI_INIT_HOOKS_SHELL_EXECUTABLE默认/bin/sh调整行为。另需注意 stop 钩子的累计执行时间会计入 Floci 总关停时间编排器要相应调大宽限期如 Compose 的stop_grace_period。九、常用环境变量速查表以下是最常设置的变量完整清单见 Environment Variables Reference变量默认值用途FLOCI_HOSTNAME(无)嵌入响应 URL 的主机名多容器场景下设为 Compose 服务名FLOCI_BASE_URLhttp://localhost:4566响应字段SQSQueueUrl、预签名 URL 等中的基础 URLFLOCI_HOSTNAME只覆盖其中的主机名部分FLOCI_DEFAULT_REGIONus-east-1ARN 与响应中报告的 AWS 区域FLOCI_DEFAULT_ACCOUNT_ID000000000000ARN 中使用的 AWS 账号 IDFLOCI_STORAGE_MODEmemorymemory、persistent、hybrid或walFLOCI_STORAGE_PERSISTENT_PATH./data持久化存储目录镜像内默认/app/dataFLOCI_SERVICES_DOCKER_NETWORK(无)拉起容器Lambda、ElastiCache、RDS、OpenSearch、MSK 等所在的 Docker 网络FLOCI_AUTH_VALIDATE_SIGNATURESfalse是否校验 S3 预签名 URL 签名FLOCI_SERVICES_LAMBDA_EPHEMERALfalse每次调用后是否立即移除 Lambda 容器FLOCI_SERVICES_RDS_PROXY_BASE_PORT7001RDS 代理端口段起始FLOCI_SERVICES_ELASTICACHE_PROXY_BASE_PORT6379ElastiCache 代理端口段起始一个与 Docker Compose 部署强相关的安全细节镜像默认监听0.0.0.0但显式声明了允许不安全网络暴露因此谁能访问 Floci 完全取决于你如何发布端口。仅本机使用时建议绑定回环地址docker run --rm -p 127.0.0.1:4566:4566 floci/floci:latest十、Docker 配置进阶Floci 为 Lambda、RDS、ElastiCache、OpenSearch、MSK、ECS 等拉起真实容器全部共享同一套 Docker 客户端配置详见 docs/configuration/docker.md与 Compose 部署直接相关的几项Docker socket 与权限默认通过unix:///var/run/docker.sock连接。镜像入口脚本会自动探测 socket 属组并给 UID 1001 的floci用户附加该组无需手动--group-add原生 Linux Docker 的 socket 通常为root:dockerDocker Desktop 则通常是root:root运行时探测可透明适配两种宿主。若 socket 仅 root 可访问可用FLOCI_RUN_AS_ROOTtrue保持以 root 运行。私有镜像仓库认证可挂载宿主~/.dockerFLOCI_DOCKER_DOCKER_CONFIG_PATH复用docker login会话或使用按索引递增的显式凭据如FLOCI_DOCKER_REGISTRY_CREDENTIALS_0__SERVER/_USERNAME/_PASSWORD。注意 Docker Hub 镜像的主机名为空不会被显式凭据匹配需走配置挂载方式。日志轮转FLOCI_DOCKER_LOG_MAX_SIZE默认10m与FLOCI_DOCKER_LOG_MAX_FILE默认3控制拉起容器的日志轮转。容器标签Floci 创建的每个容器与卷都带flocitrue、floci_emulatorfloci-aws标签外加io.floci.*资源身份标签如io.floci.resource-idorders-db-primary可用docker ps --filter labelio.floci.resource-idorders-db-primary直接定位某个模拟资源对应的后端容器额外的自定义标签用FLOCI_DOCKER_EXTRA_LABELS_0__KEY/_VALUE注入。Podmanrootless官方文档提供了已知可行的配置关键点包括创建命名网络rootless 默认桥接不给容器间分配可达 IP、设置FLOCI_SERVICES_LAMBDA_DOCKER_NETWORK、FLOCI_HOSTNAMEflocisocket 挂载需带:zSELinux 重标记若 Lambda Runtime API 地址仍不可达可显式设置FLOCI_SERVICES_LAMBDA_DOCKER_HOST_OVERRIDEfloci跳过自动探测。十一、写在最后从示例到你的项目本文给出的三个 Compose 配置无状态、持久化、容器化服务覆盖了从跑个单测到带真实 Redis/PostgreSQL 容器的完整本地环境的全谱系需求。上手时建议按此顺序推进先用最小配置验证4566端口连通性与核心服务可用性需要保留状态时加上FLOCI_STORAGE_MODE与命名卷用到 Lambda/RDS/ElastiCache 等容器化服务时挂载 Docker socket 并按 端口参考 补齐代理端口段映射同时设置FLOCI_SERVICES_DOCKER_NETWORK应用与其他容器互通时把FLOCI_HOSTNAME设为 Compose 服务名并视需要显式设置FLOCI_BASE_URL有预置/清理需求时挂载初始化钩子目录并使用latest-compat镜像最后把这些参数原样搬进 CI 的services块即可获得与仓库 compatibility.yml 同等质量的测试环境。赞分享【免费下载链接】flociLight, fluffy, and always free - The AWS Local Emulator alternative项目地址https://gitcode.com/gh_mirrors/fl/floci点击查看免费下载相关推荐Open Notebook Docker Compose 多容器部署实战从 docker-compose.yml 到 AI 供应商配置的完整指南Open Notebook Docker Compose 多容器部署实战从 docker compose.yml 到 AI 供应商配置的完整指南 本文以 Op人工智能AI 应用RAG后端前端biliTickerBuy Docker 部署实战从 docker run 到 docker compose 的完整配置指南biliTickerBuy Docker 部署实战从 docker run 到 docker compose 的完整配置指南 本文围绕 biliTickerB电商RPAPeerBanHelper 容器化部署最佳实践Docker Compose配置与网络设置PeerBanHelper 容器化部署最佳实践Docker Compose配置与网络设置 PeerBanHelper 是一款强大的 BT 客户端自动封禁工具网络安全后端上一篇furrr错误处理与调试解决并行计算中常见问题的完整方案下一篇FilePizza 上线体检5 项检查让 P2P 文件传输 Demo 走向生产创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考