Floci:用 4566 端口本地模拟 AWS,替代 LocalStack
给开发、测试和 CI 用的本地 AWS 模拟器,4566 端口兼容现有工具且无需 LocalStack 令牌。
GitHub floci-io/floci 更新 2026-11-04 分支 main 星标 28.8K 分叉 3.2K
Java AWS 本地模拟 Docker Terraform CI

🧭 决策指南

适合,如果你

  • 你要在本机或 CI 中运行 AWS CLI、Terraform、CDK 或 OpenTofu
    README 的 What is Floci? 和 Compatibility Testing:支持 AWS CLI、Terraform、CDK、OpenTofu,并列出 2,576 个兼容性测试。
  • 你需要无 AWS 账号、auth token 或付费功能开关的本地环境
    README 的 What is Floci? 和 Features:无需 cloud account、auth token 或 paid feature gates。
  • 你的测试涉及 Lambda、RDS、ECS、Neptune 或 MSK 的容器执行
    README 的 Features 和 Architecture Overview:这些服务使用 real Docker-backed execution,并通过 Docker API 连接 Docker Engine。
  • 你正在从 LocalStack 迁移,并希望保留现有 AWS 工作流
    README 的 What is Floci?:Floci 是 drop-in replacement,可替换镜像继续使用;另有 Migrating from LocalStack 章节。

不适合,如果你

  • 你的验证目标是 AWS 真实云端而不是 localhost:4566 的本地模拟
    README 的 What is Floci? 明确将 Floci 定义为 local AWS emulator,服务运行在本机 localhost:4566。
  • 你需要 Lambda、RDS 或 ECS 的 Docker 执行,但运行环境不能使用 Docker Engine
    README 的 Architecture Overview:Container Services 通过 Docker API 连接 Docker Engine;Features 也明确使用 real Docker-backed execution。
  • 你依赖旧的 hectorvent/floci 镜像且不准备更新镜像名
    README 的 Quick Start:旧 hectorvent/floci 仓库 no longer receives updates,迁移后使用 floci/floci:latest。

前置条件

  • {'text': '使用官方 CLI 时运行 floci start;README 也提供 Linux、macOS 和 Windows 的 standalone floci-aws binary。', 'text_en': 'Use floci start with the official CLI; the README also provides a standalone floci-aws binary for Linux, macOS, and Windows.'}
  • {'text': 'Docker Compose 路径需要暴露 4566:4566,并运行 docker compose up。', 'text_en': 'The Docker Compose path exposes 4566:4566 and runs docker compose up.'}
  • {'text': '标准 AWS 工具连接 http://localhost:4566;凭据可使用任意非空值,除非启用更严格的服务级认证检查。', 'text_en': 'Standard AWS tools connect to http://localhost:4566; credentials may be any non-empty values unless stricter service-specific auth checks are enabled.'}

第一步命令(README 原文)

floci start

要注意

  • 自定义 Web Console 必须遵守 Floci console contract,例如 GET /api/health 和 AWS_ENDPOINT_URL。
    README 的 Running a different console:自定义 console 需监听 PORT、提供 GET /api/health,并通过 AWS_ENDPOINT_URL 连接 Floci。
  • StackPort 监听 8080 时需设置 FLOCI_SERVICES_UI_PORT 与 INTERNAL_PORT。
    README 的 Running a different console:StackPort 示例同时设置两个 8080 端口变量。
  • 默认非空凭据并不等于所有服务都跳过认证检查。
    README 的 Quick Start:任意非空凭据可用,但明确启用 stricter service-specific auth checks 时例外。

材料未说明

  • README 未提供完整 Supported Services 清单,无法确认目标 AWS 服务是否全部实现。
  • README 未说明 Java、Python、Shell、TypeScript 和 Go 各组件的具体版本要求。
  • README 未提供 Persistence and Storage Modes 章节内容,无法比较 memory、hybrid、persistent 和 wal 的具体限制。
  • README 未说明 2.4.0 的发布日期、变更范围及与 2,576 项兼容性测试的对应关系。
  • README 未给出 native floci-aws binary 的安装命令和运行时依赖。

💡 深度解析

6
适合 我正在用 AWS SDK 开发 S3、DynamoDB 和 SQS 集成,希望在没有 AWS 账号的本机环境里运行测试,同时不改写现有 SDK 调用;Floci 是否适合?
适合读者: 使用 AWS SDK 开发 S3、DynamoDB 和 SQS 应用、希望在本机不连接真实 AWS 账号的后端开发者

适合,因为 Floci 直接提供 AWS 兼容入口,并允许现有 SDK 继续使用。

  • README 的“What is Floci?”说明,AWS SDK、CLI、Terraform、CDK、OpenTofu 和测试套件都可以指向 http://localhost:4566。
  • “Quick Start”列出了 S3 建桶、DynamoDB 建表和查询命令,与你的服务组合直接对应。
  • 本地不要求 AWS 账号、认证令牌或付费功能开关;凭证可以是任意非空值。
  • S3 和 DynamoDB 属于有状态服务,架构图显示它们通过可配置的 storage backend 保存状态,因此可按测试需要选择内存或持久化模式。

不过,README 没有证明每一个 SDK 版本、错误码、并发时序和 IAM 语义都与真实 AWS 完全一致。

  • What is Floci?:"Point your AWS SDK, CLI, Terraform, CDK, OpenTofu, or test suite at http://localhost:4566"
  • Quick Start:"aws s3 mb"、"aws dynamodb create-table"、"aws dynamodb list-tables"
  • Quick Start:"Credentials can be any non-empty values"
  • Architecture Overview:S3、DynamoDB 位于 Stateful Services
floci start
材料未说明:README 节选未说明你所用 AWS SDK 语言和版本的完整 API 覆盖率。;README 节选未说明 S3、DynamoDB、SQS 在并发、错误码和 IAM 细节上的差异范围。
适合 我同时使用 Terraform、OpenTofu 和 CDK,并已有 LocalStack 流程;团队希望迁移到 MIT 许可、无需认证令牌的本地 AWS 模拟器,同时尽量保留现有 IaC 配置,Floci 是否适合?
适合读者: 使用 Terraform、OpenTofu 和 CDK 管理 AWS 基础设施、希望把现有 LocalStack 工作流迁移到 MIT 许可项目的 DevOps 工程师

适合,Floci 的接入方式和迁移定位都直接覆盖你的约束,但仍需核对现有 LocalStack 配置。

  • “What is Floci?”明确把 Floci 描述为 LocalStack 的 drop-in replacement,可通过替换镜像继续使用既有流程。
  • 同一章节列出 Terraform、CDK 和 OpenTofu 可通过标准 endpoint 接入;“Features”还说明 Terraform 可使用标准 HashiCorp AWS provider 在本地创建 AWS-shaped 资源。
  • “Why Floci?”列出 MIT 许可证、无需 auth token,并宣称支持 API Gateway v2、Cognito,以及 RDS、ElastiCache、MSK、ECS、EC2、EKS 等真实 Docker 服务。
  • README 的 compose 示例使用 floci/floci:latest,而旧的 hectorvent/floci 仓库不再更新,因此迁移时至少要替换镜像名称。

这适合降低迁移的入口成本,但不等于原有初始化脚本、卷、IAM 行为和所有资源参数无需调整。

  • What is Floci?:"Already using LocalStack? Floci is a drop-in replacement: swap the image and keep going."
  • What is Floci?:"AWS SDK, CLI, Terraform, CDK, OpenTofu"
  • Features:Terraform 使用标准 HashiCorp AWS provider
  • Why Floci?:"License | MIT"、"Auth token required | No"
  • Quick Start:"The old hectorvent/floci repository no longer receives updates."
docker compose up
材料未说明:README 节选未提供完整的 LocalStack 环境变量、初始化脚本、卷和 Terraform provider 迁移映射。;README 节选未说明你现有 Terraform、OpenTofu 和 CDK 版本的兼容矩阵。
适合 我的 CI 流水线不能依赖 AWS 账号和认证令牌,需要测试 SQS、Lambda、API Gateway,并且希望启动时间和空闲内存足够低;Floci 是否适合?
适合读者: 维护无 AWS 账号的 CI 测试流水线、需要运行 SQS、Lambda 和 API Gateway 集成测试的测试工程师

适合,尤其适合不想为 CI 配置云账号的本地模拟层,但 Lambda 测试需要 Docker Engine。

  • “Features”明确写出 Floci 面向 development、testing 和 CI,且无需云账号、auth token 或 paid feature gates。
  • README 的“Why Floci?”给出原生镜像约 24 ms 启动、约 13 MiB 空闲内存;这与短生命周期 CI 作业的约束相符。
  • 架构图列出 SQS、API Gateway 等服务,Lambda 则属于 Container Services;“Real Docker where fidelity matters”说明 Lambda 使用真实 Docker-backed execution,而不是浅层 mock。
  • 项目支持独立原生二进制,发布物覆盖 Linux、macOS 和 Windows,但这不代表 Lambda 等容器服务脱离 Docker 后仍可完整运行。

因此,基础 API 测试可采用轻量运行方式;包含 Lambda 的流水线必须准备 Docker 权限、镜像和网络资源。

  • Features:"Floci is a free, open-source local AWS emulator for development, testing, and CI"
  • Features:"without an AWS account, an auth token, or paid feature gates"
  • Why Floci?:"Startup time ~24 ms"、"Idle memory ~13 MiB"
  • Features:"Lambda ... use real Docker-backed execution"
  • Quick Start:standalone floci-aws binary supports Linux、macOS 和 Windows
floci start
材料未说明:README 节选未给出 CI runner 所需的最低 CPU、内存、Docker 版本和并行 Lambda 数量。;README 节选未说明 API Gateway、SQS 与 Lambda 组合的异步时序是否覆盖你的测试路径。
适合 我的测试必须覆盖多个 AWS region 和 partition,并验证多账户隔离;同时希望所有请求仍通过一个本地 endpoint 发送,Floci 是否适合?
适合读者: 需要验证多个 AWS region、partition 和测试账户隔离逻辑的后端平台工程师

适合,Floci 明确支持统一本地 endpoint、已发布 AWS region、所有 partition 和多账户隔离。

  • “Quick Start”说明所有 AWS 服务都可通过 http://localhost:4566 访问,并称任意 published AWS region、每个 partition 都可使用。
  • 项目洞察列出支持多账户隔离、不同 AWS region 和 AWS partition 配置,正好对应你的测试维度。
  • README 说明凭证可以是任意非空值,且可按需启用更严格的服务级认证检查,因此可以构造不同测试账户的配置,但不应默认把宽松凭证行为当成真实 IAM。
  • 统一 endpoint 和 AWS wire protocol 路由层可以保持现有 SDK、CLI 和测试流程不变,区域与账户主要通过客户端配置和请求上下文切换。

它适合验证账户、区域和 partition 相关的应用分支;但真实 AWS 的组织策略、VPC、配额和区域级服务差异不在本地模拟范围内。

  • Quick Start:"All AWS services are available at http://localhost:4566"
  • Quick Start:"Any published AWS region works, in every partition."
  • 项目洞察 solution_analysis:支持多账户隔离、不同 AWS region 和 AWS partition 配置
  • Quick Start:"Credentials can be any non-empty values unless you explicitly enable stricter service-specific auth checks."
eval $(floci env)
材料未说明:README 节选未说明多账户隔离的具体配置键、资源命名规则和并发边界。;README 节选未说明各 AWS partition 的服务覆盖是否完全一致。
视情况 我在 Linux、macOS 或 Windows 开发机上没有 Docker,但需要用 AWS CLI 验证 S3 和 DynamoDB 的本地流程;我是否还能使用 Floci?
适合读者: 需要在无 Docker 的 Linux、macOS 或 Windows 开发机上运行基础 AWS 模拟、同时使用 AWS CLI 验证 S3 和 DynamoDB 的个人开发者

视情况:Floci 提供无 Docker 的原生二进制路径,但不能据此保证所有 Docker-backed 服务都可用。

  • “Quick Start”说明每个 release 都提供独立的 floci-aws 二进制,支持 Linux、macOS 和 Windows,因此基础本地运行不一定依赖 Docker。
  • 同一章节的 AWS CLI 示例直接覆盖 S3 建桶、DynamoDB 建表和查询;这些服务属于核心本地使用路径。
  • “Real Docker where fidelity matters”明确把 Lambda、RDS、ECS、EC2、EKS、MSK 等交给真实 Docker 执行,所以没有 Docker 时,涉及这些服务的测试会受到限制。
  • 项目说明原生二进制约 40 MB,且“Why Floci?”给出约 24 ms 启动和约 13 MiB 空闲内存,适合轻量开发环境。

因此,你的 S3/DynamoDB CLI 流程可以尝试原生二进制;若后续扩展到 Lambda 或数据库容器,仍需 Docker 环境。

  • Quick Start:"Each release also ships a standalone floci-aws binary for Linux, macOS and Windows"
  • Quick Start:AWS CLI 的 S3 和 DynamoDB 示例
  • Features:"Lambda, RDS, ... ECS ... use real Docker-backed execution"
  • Why Floci?:"Native binary | ~40 MB"、"Startup time | ~24 ms"、"Idle memory | ~13 MiB"
floci start
材料未说明:README 节选未说明原生二进制是否包含 S3、DynamoDB 之外所有服务的完整实现。;README 节选未说明不同操作系统上的安装依赖、端口权限和文件持久化差异。
视情况 我的项目主体是 Java,集成测试通过 Testcontainers 启动应用容器,并需要验证 Lambda、RDS 和 ECS;Floci 是否适合作为容器化测试依赖?
适合读者: 在应用容器和 Testcontainers 中运行 AWS 集成测试、需要访问 Lambda、RDS 和 ECS 的 Java 开发者

视情况:服务覆盖和 Docker-backed 执行很匹配,但 Testcontainers 网络、Docker 权限和嵌套容器配置会决定能否顺利运行。

  • 项目数据表明 Floci 主体语言为 Java,README 的 Features 列出 Lambda、RDS、ECS 使用真实 Docker-backed execution,适合验证容器和运行时交互。
  • 架构图显示 Floci 监听 4566,并通过 Docker API 与 Docker Engine 通信;应用容器不能把 localhost:4566 误当成宿主机或 Floci 容器地址。
  • README 提供 Docker Compose 方式,示例将 4566 端口暴露出来;这说明容器化接入路径存在,但没有自动解决 Testcontainers 网络发现或 Docker socket 权限。
  • 项目数据的 topics 包含 testcontainers,但这只能证明项目关注该集成,不能证明你的 Java 测试配置无需调整。

如果测试只调用普通 AWS API,接入较简单;如果需要 Lambda、RDS 和 ECS 的真实执行,环境条件会明显更严格。

  • 项目核心数据:main_language 为 Java
  • Features:"Lambda, RDS, ... ECS ... use real Docker-backed execution"
  • Architecture Overview:Floci 监听 port 4566,并通过 Docker API 连接 Docker Engine
  • Quick Start:Docker Compose 示例暴露 "4566:4566"
  • 项目核心数据:topics 包含 "testcontainers"
docker compose up
材料未说明:README 节选未给出 Testcontainers 的 Java 示例、网络别名或 Docker socket 配置。;README 节选未说明 Lambda、RDS、ECS 同时运行时的 CPU、内存、端口和镜像要求。

✨ 核心亮点

  • 原生镜像启动约 24 ms,空闲内存约 13 MiB
  • 覆盖 2,576 个 SDK 与 IaC 兼容性测试
  • MIT 许可且无需账号、令牌或付费功能开关
  • Lambda、RDS、ECS 等服务使用真实 Docker 执行

🔧 工程化

  • 通过 floci start 启动 AWS 模拟器,工具连接 localhost:4566
  • 兼容 AWS CLI、Terraform、CDK、OpenTofu 与 AWS SDK
  • 提供 S3、DynamoDB、Cognito 与 API Gateway v2 等服务
  • 支持内存、持久化、混合和 WAL 存储后端

⚠️ 风险

  • Lambda、RDS、ECS 等容器服务依赖 Docker Engine
  • README 仅列出 2,576 项兼容性测试,未覆盖所有工作流
  • 旧 hectorvent/floci 镜像已停止更新,需改用 floci/floci
  • AWS 真实云端行为不在 Floci 的本地模拟范围内

👥 适合谁?

  • 需要本地运行 AWS CLI、Terraform 或 CDK 的开发团队
  • 使用 Java、Python、Node.js 或 Go SDK 的测试项目
  • 需要 Lambda、RDS 或 ECS Docker 执行环境的 CI 流程