Floci#

任意云服务，本地运行。

轻盈、蓬松，永远免费

无需账号。无需认证令牌。无功能限制。只需 docker compose up。

快速开始 · 功能特性 · 支持服务 · SDK 集成 · Testcontainers · 迁移 · 文档

什么是 Floci？#

Floci 是一个免费、开源的本地 AWS 模拟器（local AWS emulator），用于开发、测试和 CI。

它在你自己的机器上提供 AWS 形态的服务，无需云账号、认证令牌或付费功能门槛。将你的 AWS SDK、CLI、Terraform、CDK、OpenTofu 或测试套件指向 http://localhost:4566，即可继续使用现有工作流。

已经在使用 LocalStack？Floci 可直接替换（drop-in replacement）：替换镜像即可继续。参见《从 LocalStack 迁移》。

Floci 是 Floci 模拟器家族中的 AWS 成员，名字来自 floccus——一种看起来像爆米花的云。

快速开始#

运行 Floci 最快的方式是使用官方 CLI：

floci start

没有 Docker？每个发行版还提供独立的 floci-aws 二进制文件，适用于 Linux、macOS 和 Windows；参见《原生二进制文件》。

导出 AWS 环境变量：

eval $(floci env)

像平常一样使用现有的 AWS 工具：

aws s3 mb s3://my-bucket

aws dynamodb create-table \
    --table-name demo-table \
    --attribute-definitions AttributeName=pk,AttributeType=S \
    --key-schema AttributeName=pk,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST

aws dynamodb list-tables

观看运行#

这段简短演示展示了 CLI 流程：启动 Floci、导出本地 AWS 环境、运行标准 AWS CLI 命令，然后停止模拟器。

floci-cli-demo.mp4

所有 AWS 服务均可通过 http://localhost:4566 访问。任何已发布的 AWS 区域都可用，覆盖所有分区。除非你显式启用更严格的服务级认证检查，凭据可以是任意非空值。

更喜欢 Docker Compose？#

创建 compose.yaml 文件：

services:
  floci:
    image: floci/floci:latest
    ports:
      - "4566:4566"

启动 Floci：

docker compose up

然后手动配置 AWS 环境：

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

仍在使用旧的 hectorvent/floci 镜像？#

更新你的镜像名称：

# 之前
image: hectorvent/floci:latest

# 之后
image: floci/floci:latest

旧的 hectorvent/floci 仓库已不再接收更新。

Web 控制台#

Floci 附带一个浏览器控制台，用于检查本地模拟器中的资源。

访问地址：http://localhost:4566/_floci/ui

启动时不会运行任何东西。首次请求会拉取控制台镜像，将其作为 sidecar 容器启动在 Floci 的 Docker 网络上，把 Floci 自身可达地址加上标准 AWS 环境交给它，轮询其健康端点，并在其报告能够连接 Floci 后重定向浏览器。sidecar 的端口由 Docker 绑定，因此不需要你自己配置 ports: 条目，其日志会流式写入 CloudWatch Logs 的 /floci/ui 下。

启动容器需要 Docker socket：

services:
  floci:
    image: floci/floci:latest
    ports:
      - "4566:4566"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

运行不同的控制台#

控制台并不固定为 Floci 自带的那个。任何实现了 Floci 控制台约定的控制台，只需一个镜像名称即可运行：监听 PORT 指定的端口，提供 GET /api/health，并通过 AWS_ENDPOINT_URL 与 Floci 通信。

environment:
  FLOCI_SERVICES_UI_IMAGE: acme/my-console:1.0

如果某个控制台与约定默认值不同，它会在自己的 io.floci.console.* 镜像标签中说明，因此其运维人员无需手动配置。例如 StackPort 监听 8080 而不是 4500；对于早于这些标签的镜像，需要手动指定：

environment:
  FLOCI_SERVICES_UI_IMAGE: davireis/stackport:latest
  FLOCI_SERVICES_UI_CONTAINER_NAME: floci-stackport
  FLOCI_SERVICES_UI_PORT: "8080"
  FLOCI_SERVICES_UI_INTERNAL_PORT: "8080"

Floci Dash 是另一个例子。它遵循 PORT，因此只需指定它确实不同的两项：

environment:
  FLOCI_SERVICES_UI_IMAGE: ghcr.io/ofsazib/floci-dash:latest
  FLOCI_SERVICES_UI_CONTAINER_NAME: floci-dash
  FLOCI_SERVICES_UI_ENDPOINT_ENV: FLOCI_URL
  FLOCI_SERVICES_UI_STATUS_PATH: /api/healthz

端点本身从不需要手动配置：Floci 启动时解析自身可达地址，并将其注入为 AWS_ENDPOINT_URL。

完整参考：Web 控制台 和 控制台约定 v1。

功能特性#

无需云账号的本地 AWS#

在本地运行 AWS 兼容服务，无需 AWS 账号、认证令牌或付费功能门槛。

在对保真度有要求的地方使用真实 Docker#

Lambda、RDS、Neptune、ElastiCache、MSK、ECS、EC2、EKS、OpenSearch、CodeBuild 以及 Managed Service for Apache Flink 使用真实的 Docker 支撑执行，而不是浅层模拟。

即插即用的 AWS 兼容性#

将标准 AWS 客户端指向 http://localhost:4566。现有凭据、区域、SDK、CLI 命令和 IaC 工作流保持熟悉。

Terraform 可以通过 Floci 使用标准 HashiCorp AWS provider 在本地预置 AWS 形态的资源。provider 配置、资源示例以及可选的模拟 S3 状态请参见《Terraform 与 Floci》指南。

快到足以用于 CI#

原生镜像在毫秒级启动，并保持低空闲内存，适合本地开发和测试流水线。

可配置的持久化#

根据所需的持久性配置，选择内存、持久化、混合和预写日志（write-ahead log）存储。

为什么选择 Floci？#

LocalStack 社区版于 2026 年 3 月停止服务，要求认证令牌并冻结安全更新。Floci 是没有任何附加条件的替代方案。

广泛的 AWS 覆盖。永久免费。完整的模拟服务列表请参见《服务总览》。

架构概览#

flowchart LR
    Client["AWS SDK / CLI"]

    subgraph Floci ["Floci, port 4566"]
        Router["HTTP Router\nJAX-RS / Vert.x"]

        subgraph Stateless ["Stateless Services"]
            A["SSM · SQS · SNS\nIAM · STS · KMS\nSecrets Manager · SES\nCognito · Kinesis\nEventBridge · Scheduler · AppConfig\nCloudWatch · Step Functions\nCloudFormation · ACM · Config · CloudTrail\nAPI Gateway · AppSync · ELB v2 · Auto Scaling\nElastic Beanstalk · CodeDeploy · CodePipeline · Backup · FIS · Bedrock Runtime · Bedrock AgentCore · Route53 · Transfer"]
        end

        subgraph Stateful ["Stateful Services"]
            B["S3 · DynamoDB\nDynamoDB Streams"]
        end

        subgraph Containers ["Container Services"]
            C["Lambda\nElastiCache\nRDS\nNeptune\nECS\nEC2\nMSK\nEKS\nOpenSearch\nCodeBuild\nManaged Flink"]
            D["Athena -> floci-duck\nDuckDB sidecar"]
        end

        Router --> Stateless
        Router --> Stateful
        Router --> Containers
        Stateless & Stateful --> Store[("StorageBackend\nmemory · hybrid · persistent · wal")]
    end

    Docker["Docker Engine"]
    Client -->|"HTTP :4566\nAWS wire protocol"| Router
    Containers -->|"Docker API\nIAM / SigV4 auth"| Docker

支持的服务#

Floci 支持对应用服务、数据服务、事件、身份、基础设施、计费以及容器支撑工作负载的本地模拟。

操作级别的兼容性请参见《服务总览》。

详细服务说明#

真实 Docker 集成#

当进程内模拟会降低保真度时，Floci 使用真实 Docker 容器。这适用于有状态数据库、连接密集型协议、运行时和构建系统。

Docker 支撑的服务需要 Docker socket：

docker run -d --name floci \
  -p 4566:4566 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -u root \
  floci/floci:latest

覆盖默认镜像#

持久化与存储模式#

Floci 可以根据工作流在速度和持久性之间取舍。通过 FLOCI_STORAGE_MODE 配置默认模式，或按服务覆盖存储方式。

使用 memory 进行快速测试运行。如果希望在容器重启后保留状态而又不想增加太多开销，请使用 hybrid。

更多细节请参见《存储配置》文档。

多账号隔离#

Floci 无需额外配置即可支持按账号隔离资源。如果 AWS_ACCESS_KEY_ID 恰好是 12 位数字，Floci 会将其用作账号 ID。一个账号创建的资源对另一个账号不可见。

AWS_ACCESS_KEY_ID=111111111111 aws sqs create-queue --queue-name orders
AWS_ACCESS_KEY_ID=222222222222 aws sqs create-queue --queue-name orders

任何其他格式的密钥，例如 test 或 AKIA...，会使 Floci 回退到 FLOCI_DEFAULT_ACCOUNT_ID，其默认值为 000000000000。

STS 临时凭据也会被路由：来自 AssumeRole 的凭据会解析为所代入角色的账号，因此跨账号的“先 assume-role 再预置资源”模式可以在本地工作。解析优先级为：12 位 AKID → 临时会话查找 → FLOCI_DEFAULT_ACCOUNT_ID。

参见《多账号隔离》文档。

SDK 集成#

将你现有的 AWS SDK 指向 http://localhost:4566。

Java，AWS SDK v2#

var client = DynamoDbClient.builder()
    .endpointOverride(URI.create("http://localhost:4566"))
    .region(Region.US_EAST_1)
    .credentialsProvider(StaticCredentialsProvider.create(
        AwsBasicCredentials.create("test", "test")))
    .build();

client.createTable(b -> b
    .tableName("demo-table")
    .billingMode(BillingMode.PAY_PER_REQUEST)
    .attributeDefinitions(
        AttributeDefinition.builder().attributeName("pk").attributeType(ScalarAttributeType.S).build())
    .keySchema(
        KeySchemaElement.builder().attributeName("pk").keyType(KeyType.HASH).build()));

System.out.println(client.listTables().tableNames());

Python，boto3#

import boto3

client = boto3.client(
    "ssm",
    endpoint_url="http://localhost:4566",
    region_name="us-east-1",
    aws_access_key_id="test",
    aws_secret_access_key="test",
)

client.put_parameter(
    Name="/demo/app/message",
    Value="hello from floci",
    Type="String",
    Overwrite=True,
)

response = client.get_parameter(Name="/demo/app/message")
print(response["Parameter"]["Value"])

Node.js，AWS SDK v3#

import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";

const client = new SQSClient({
  endpoint: "http://localhost:4566",
  region: "us-east-1",
  credentials: { accessKeyId: "test", secretAccessKey: "test" },
});

await client.send(
  new SendMessageCommand({
    QueueUrl: "http://localhost:4566/000000000000/demo-queue",
    MessageBody: "hello from floci",
  }),
);

Go，AWS SDK v2#

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/credentials"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
    cfg, err := config.LoadDefaultConfig(context.TODO(),
        config.WithRegion("us-east-1"),
        config.WithCredentialsProvider(
            credentials.NewStaticCredentialsProvider("test", "test", ""),
        ),
        config.WithBaseEndpoint("http://localhost:4566"),
    )
    if err != nil {
        log.Fatal(err)
    }

    client := s3.NewFromConfig(cfg, func(o *s3.Options) {
        o.UsePathStyle = true
    })

    out, err := client.ListBuckets(context.TODO(), nil)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(out.Buckets)
}

Rust，AWS SDK#

use aws_sdk_secretsmanager::config::{Credentials, Region};
use aws_sdk_secretsmanager::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = aws_config::defaults(aws_config::BehaviorVersion::latest())
        .region(Region::new("us-east-1"))
        .credentials_provider(Credentials::new("test", "test", None, None, "floci"))
        .endpoint_url("http://localhost:4566")
        .load()
        .await;

    let client = Client::new(&config);

    client
        .create_secret()
        .name("demo/secret")
        .secret_string("hello from floci")
        .send()
        .await?;

    Ok(())
}

Bash，AWS CLI#

export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_DEFAULT_REGION=us-east-1

aws --endpoint-url http://localhost:4566 s3 mb s3://my-bucket
aws --endpoint-url http://localhost:4566 s3 ls

Testcontainers#

Floci 提供 Testcontainers 模块，可直接从测试中启动隔离的 Floci 实例。这避免了共享状态、手动守护进程设置和端口冲突。

对于 Testcontainers 1.x，请使用下表所示的版本。

Java#

<dependency>
    <groupId>io.floci</groupId>
    <artifactId>testcontainers-floci</artifactId>
    <version>1.14.0</version>
    <scope>test</scope>
</dependency>

@Testcontainers
class S3IntegrationTest {

    @Container
    static FlociContainer floci = new FlociContainer();

    @Test
    void shouldCreateBucket() {
        S3Client s3 = S3Client.builder()
            .endpointOverride(URI.create(floci.getEndpoint()))
            .region(Region.of(floci.getRegion()))
            .credentialsProvider(StaticCredentialsProvider.create(
                AwsBasicCredentials.create(floci.getAccessKey(), floci.getSecretKey())))
            .forcePathStyle(true)
            .build();

        s3.createBucket(b -> b.bucket("my-bucket"));
    }
}

对于 Testcontainers 2.x / Spring Boot 4.x，请使用版本 2.15.0。

Node.js / TypeScript#

npm install --save-dev @floci/testcontainers

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

describe("S3", () => {
  let floci: FlociContainer;

  beforeAll(async () => {
    floci = await new FlociContainer().start();
  });

  afterAll(async () => {
    await floci.stop();
  });

  it("creates a bucket", async () => {
    const s3 = new S3Client({
      endpoint: floci.getEndpoint(),
      region: floci.getRegion(),
      credentials: {
        accessKeyId: floci.getAccessKey(),
        secretAccessKey: floci.getSecretKey(),
      },
      forcePathStyle: true,
    });

    await s3.send(new CreateBucketCommand({ Bucket: "my-bucket" }));
  });
});

Python#

pip install testcontainers-floci

import boto3
from floci import FlociContainer

def test_s3_create_bucket():
    with FlociContainer() as floci:
        s3 = boto3.client(
            "s3",
            endpoint_url=floci.get_endpoint(),
            region_name=floci.get_region(),
            aws_access_key_id=floci.get_access_key(),
            aws_secret_access_key=floci.get_secret_key(),
        )
        s3.create_bucket(Bucket="my-bucket")

兼容性测试#

compatibility-tests 目录跨 SDK 和工具工作流验证 Floci。

5 个 SDK 和 3 个 IaC 工具共 2,576 个自动化兼容性测试。

从 LocalStack 迁移#

Floci 是 LocalStack 社区版的可直接替换方案。端口、凭据、SDK 配置和 CLI 端点模式的工作方式相同。替换镜像即可继续。

# 之前
image: localstack/localstack

# 之后，标准镜像
image: floci/floci:latest

# 之后，如果初始化脚本需要 AWS CLI 或 boto3
image: floci/floci:latest-compat

LocalStack 环境变量会自动转换：

挂载在 /etc/localstack/init/ 下的初始化脚本可原样运行。/_localstack/init 和 /_localstack/health 端点仍会提供。模拟器启动后，日志还会以 LocalStack 风格的 Ready. 行结尾，因此依赖监听该日志行的工具（例如 Testcontainers 的 LocalStackContainer 默认等待策略）可原样工作。设置 LOCALSTACK_PARITY=false 可关闭自动转换。

参见完整迁移指南。

镜像标签#

每个标签由变体（variant）和通道（channel）组合而成。

稳定发行版使用 latest，可复现构建使用固定版本，跟踪 main 使用 nightly。

# 推荐
image: floci/floci:latest

# 包含 AWS CLI 和 boto3
image: floci/floci:latest-compat

# 适用于 Raspberry Pi 4 / 早期 LSE 核心的 ARM64 基线
image: floci/floci:latest-baseline

# 固定发行版
image: floci/floci:x.y.z

# 跟踪 main
image: floci/floci:nightly

发布节奏#

稳定版本在每月 15 日和最后一天发布，于美国中部时间 00:30 自动切出。两次发布之间，floci/floci:nightly 跟踪 main。每个合并的修复次日即可用，带日期的 nightly-mmddyyyy 标签可让你固定某个夜晚的构建。

版本由 semantic-release 从 Conventional Commits 推导；CHANGELOG.md 为自动生成，从不手工编辑。发行版仅从 main 切出：没有维护分支。

配置#

所有设置都可以通过带 FLOCI_ 前缀的环境变量覆盖。

完整参考：配置文档

多容器 Docker Compose#

当你的应用运行在另一个容器中时，将 FLOCI_HOSTNAME 设置为 Floci 的服务名，以便返回的 URL（例如 SQS 的 QueueUrl 值）能够正确解析。

services:
  floci:
    image: floci/floci:latest
    ports:
      - "4566:4566"
    environment:
      - FLOCI_HOSTNAME=floci

  my-app:
    environment:
      - AWS_ENDPOINT_URL=http://floci:4566
    depends_on:
      - floci

否则，服务可能返回使用 localhost 的 URL，从应用容器看过去会指向错误的容器。

社区#

在 Slack 或 GitHub Discussions 加入 Floci 社区。欢迎功能想法、兼容性问题、设计取舍以及初步提案。

赞助商#

Floci 是独立的开源项目，由使用它的人和公司资助。 赞助只换来感谢，别无其他：每个模拟服务对所有人永久免费，没有赞助商能获得 其他 Flock 成员没有的功能、优先级或路线图影响力。

🥇 金牌

在模拟器 README 和 floci.io 上放置大号 logo 并置于顶部位置，同时在发行说明中提及。

IceGuard · Softmax

🥈 银牌

在模拟器 README 和 floci.io 上放置 logo，同时在发行说明中提及。

这里放你的 logo。成为赞助商。

🥉 社区

在模拟器 README 中列出名称、GitHub 上的赞助商徽章，以及我们诚挚的感谢。

AutoScout24 · Nexxion AI

每位赞助商，包括在这些层级之外支持 Floci 的“Friends of the Flock”，都列在 THANKS.md 中。

赞助 Floci

星标历史#

贡献者#

许可证#

MIT。随便你怎么用。