# https://github.com/floci-io/floci 项目说明书

生成时间：2026-07-08 19:33:12 UTC

## 目录

- [Floci 概览与系统架构](#page-overview-architecture)
- [存储后端与持久化模式](#page-storage-persistence)
- [Docker 后端服务与容器集成](#page-docker-backed-services)
- [配置、AWS 线协议与多账户隔离](#page-configuration-protocols)

<a id='page-overview-architecture'></a>

## Floci 概览与系统架构

### 相关页面

相关主题：[存储后端与持久化模式](#page-storage-persistence), [Docker 后端服务与容器集成](#page-docker-backed-services), [配置、AWS 线协议与多账户隔离](#page-configuration-protocols)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/floci-io/floci/blob/main/README.md)
- [pom.xml](https://github.com/floci-io/floci/blob/main/pom.xml)
- [docs/index.md](https://github.com/floci-io/floci/blob/main/docs/index.md)
- [docs/services/index.md](https://github.com/floci-io/floci/blob/main/docs/services/index.md)
- [src/main/java/io/github/hectorvent/floci/core/common/ServiceRegistry.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/ServiceRegistry.java)
- [src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycle.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycle.java)
- [src/main/java/io/github/hectorvent/floci/lifecycle/LambdaRuntime.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/lifecycle/LambdaRuntime.java)
- [src/main/java/io/github/hectorvent/floci/aws/lambda/runtime/api/client/LambdaRuntimeApiClient.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/aws/lambda/runtime/api/client/LambdaRuntimeApiClient.java)
</details>

# Floci 概览与系统架构

## 项目定位与核心目标

Floci 是一个面向 AWS Lambda 与相关托管服务的本地化运行时与仿真平台，目标是让开发者在本地或 CI 环境中以接近生产的方式运行、调试并集成 AWS 资源，而无需真正接入 AWS 云端。项目以 Java 为主语言构建（基于 Maven 的 `pom.xml`），并通过容器化方式承载 AWS 服务仿真与 Lambda 运行时，使本地开发体验与云端保持一致。资料来源：[README.md:1-40]()

根据社区讨论与最新版本说明（1.5.31），Floci 已逐步覆盖 CloudWatch Logs Insights、RDS Data API（PostgreSQL）、Cloud Control API 只读模式等能力，并持续在冷启动速度、持久化与服务兼容性方面进行优化。资料来源：[README.md:41-80]()

## 整体架构分层

Floci 的代码组织遵循"核心 — 仿真 — 运行时"的三层结构，目录命名清晰反映出其职责划分：

- **核心层（core）**：包含通用基础设施，例如 `ServiceRegistry`、`ServiceConfig` 等，负责管理仿真服务的注册与配置加载。资料来源：[src/main/java/io/github/hectorvent/floci/core/common/ServiceRegistry.java:1-60]()
- **生命周期层（lifecycle）**：包含 `EmulatorLifecycle` 与 `LambdaRuntime`，负责协调容器启动、服务装配以及运行时进程的进入与退出流程。资料来源：[src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycle.java:1-80]()
- **AWS 服务仿真层（aws/services）**：每一个 AWS 服务对应独立子目录，包含该服务的 mock 实现、协议适配以及状态持久化逻辑。资料来源：[docs/services/index.md:1-40]()

```mermaid
flowchart TD
    A[开发者 / CI] --> B[Floci 主进程]
    B --> C[EmulatorLifecycle]
    C --> D[ServiceRegistry]
    D --> E1[S3 / DynamoDB Mock]
    D --> E2[Lambda Runtime]
    D --> E3[CloudWatch / EventBridge]
    D --> E4[RDS Data API]
    E2 --> F[LambdaRuntimeApiClient]
    F --> G[用户函数]
```

## 服务注册与生命周期管理

`ServiceRegistry` 是 Floci 的"控制中枢"，它通过统一的注册接口收集所有仿真服务，并根据配置启用或禁用对应模块，避免硬编码依赖。其关键职责包括：

1. **注册阶段**：在启动时扫描可用服务实现，建立服务标识到实例的映射。资料来源：[src/main/java/io/github/hectorvent/floci/core/common/ServiceRegistry.java:20-60]()
2. **配置阶段**：读取环境变量或配置文件中的开关，决定每个服务是否参与本次仿真。资料来源：[src/main/java/io/github/hectorvent/floci/core/common/ServiceRegistry.java:61-120]()
3. **启停阶段**：与 `EmulatorLifecycle` 协同，在合适时机调用服务的 `start()` 与 `stop()`，确保资源正确释放。资料来源：[src/main/java/io/github/hectorvent/floci/lifecycle/EmulatorLifecycle.java:40-100]()

`LambdaRuntime` 则专门负责与 AWS Lambda Runtime API 交互，通过 `LambdaRuntimeApiClient` 拉取调用、转发响应，并支持只读挂载以加速冷启动。资料来源：[src/main/java/io/github/hectorvent/floci/aws/lambda/runtime/api/client/LambdaRuntimeApiClient.java:1-60]()

## 容器与运行时配置

Floci 在容器形态下运行时，会读取一组特定的环境变量来调整行为。其中 `LAMBDA_RUNTIME_API_HOST` 用于覆盖自动检测的 Runtime API 地址，这在 Podman rootless 等自定义网络拓扑下尤为重要（社区 Issue #876 中明确提到自动检测在 Podman 网络中可能失败）。资料来源：[docs/index.md:20-80]()

主要配置维度包括：

| 维度 | 作用 | 典型场景 |
|------|------|----------|
| 服务开关 | 控制某个 AWS 仿真服务是否启用 | 仅启用 S3 + Lambda 进行单元测试 |
| Runtime API 主机 | 覆盖默认 Runtime API 地址 | Podman rootless、自定义 bridge |
| 持久化路径 | 指定本地状态保存目录 | CI 之间共享 mock 数据 |
| 只读挂载 | 加速 Lambda 冷启动 | 大型函数包、只读函数代码 |

## 社区关注与演进方向

从社区互动度来看，Floci 的演进集中在三个方面：

- **协议与兼容性**：AWS SDK 团队在 Issue #156 中提示服务线协议（wire protocol）的变化，Floci 需要跟进以保持与官方 SDK 一致。资料来源：[README.md:60-100]()
- **服务覆盖**：EventBridge Schedules（Issue #7）等被高频请求的功能是路线图重点。资料来源：[docs/services/index.md:30-70]()
- **开发体验**：LocalStack `awslocal` CLI 的内嵌（Issue #66）反映了用户希望减少外部依赖、提升容器内自助调试能力的诉求。资料来源：[docs/services/index.md:70-120]()

总体而言，Floci 通过"统一注册 + 生命周期编排 + AWS 服务仿真"的组合，提供了贴近真实云端的本地开发闭环，是构建可重复 AWS 工作流测试环境的核心组件。

---

<a id='page-storage-persistence'></a>

## 存储后端与持久化模式

### 相关页面

相关主题：[Floci 概览与系统架构](#page-overview-architecture), [配置、AWS 线协议与多账户隔离](#page-configuration-protocols)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/main/java/io/github/hectorvent/floci/core/storage/StorageBackend.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/StorageBackend.java)
- [src/main/java/io/github/hectorvent/floci/core/storage/InMemoryStorage.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/InMemoryStorage.java)
- [src/main/java/io/github/hectorvent/floci/core/storage/PersistentStorage.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/PersistentStorage.java)
- [src/main/java/io/github/hectorvent/floci/core/storage/HybridStorage.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/HybridStorage.java)
- [src/main/java/io/github/hectorvent/floci/core/storage/WalStorage.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/WalStorage.java)
- [src/main/java/io/github/hectorvent/floci/core/storage/StorageFactory.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/StorageFactory.java)

</details>

# 存储后端与持久化模式

## 概述与设计目标

`存储后端与持久化模式` 是 floci 中所有有状态 AWS 服务（S3、DynamoDB、Lambda、CloudWatch 等）共享的底层基础设施。它把"数据放在哪里、怎么放、能不能在重启后恢复"这层关注点从具体服务实现中抽离出来，使上层服务可以在不同部署模式之间无缝切换。

floci 在设计上同时面向两类使用场景：本地开发期需要极快的读写速度，CI/演示环境则需要在容器重启之间保持状态。社区反响显示，1.5.31 版本发布说明强调的"持久化与性能改进""durable-state 家族扩容""Lambda 冷启动通过只读代码挂载加速" 等迭代都直接依赖这套存储抽象（资料来源：社区上下文发布说明）。因此，存储后端并非独立子系统，而是 floci 整体可信度与开发体验的关键支撑。

## 核心抽象与后端实现

### StorageBackend 统一契约

`StorageBackend` 是所有具体后端实现必须满足的接口，定义了 put / get / delete / list / clear 等原子键值操作以及快照相关的可选方法（资料来源：[StorageBackend.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/StorageBackend.java)）。所有 AWS 服务模块都只与该接口交互，从而避免与特定介质（内存、磁盘、WAL）耦合。

### InMemoryStorage 内存模式

`InMemoryStorage` 使用进程内的并发 Map 实现读写，特点是零 IO 延迟、无外部依赖（资料来源：[InMemoryStorage.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/InMemoryStorage.java)）。它最适合单元测试与瞬态演示。社区中常见的 `awslocal` 后置脚本场景（#66）通常也依赖此模式以保证每次容器启动都是干净环境。

### PersistentStorage 持久化模式

`PersistentStorage` 把每个键值对序列化到本地目录，重启后从磁盘恢复（资料来源：[PersistentStorage.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/PersistentStorage.java)）。它是 1.5.31 引入的"durable-state 家族"的共同基底，多个新服务（S3、Lambda、CloudWatch Logs Insights、RDS Data API for PostgreSQL）正是以此切换到持久化存储。

### HybridStorage 混合模式

`HybridStorage` 将"热数据"放在内存层保证速度，"冷数据/快照"落入磁盘层保证可恢复（资料来源：[HybridStorage.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/HybridStorage.java)）。这是默认推荐模式，平衡了内存模式的性能与持久化模式的可靠性，对应了发布说明中"Lambda 冷启动通过只读代码挂载加速"等性能优化。

### WalStorage 预写日志模式

`WalStorage` 在写入正式存储前先追加到 write-ahead log，确保即使在写过程中崩溃也能恢复到一致状态（资料来源：[WalStorage.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/WalStorage.java)）。它通常与 `HybridStorage` 组合使用，为对崩溃一致性敏感的服务（如 Kinesis、EventBridge Schedules，见 issue #7）提供更强的保证。

## 工厂与运行时选择

`StorageFactory` 根据配置文件或环境变量（典型如 `FLOCI_STORAGE_MODE` 之类的开关）选择具体后端实现，并把配置项注入到实例中（资料来源：[StorageFactory.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/storage/StorageFactory.java)）。下表对比了主要模式：

| 后端 | 持久性 | 速度 | 典型场景 |
|------|--------|------|----------|
| InMemoryStorage | 无 | 最快 | 单元测试、临时演示 |
| PersistentStorage | 强 | 中 | CI、跨重启演示 |
| HybridStorage | 中 | 快 | 本地长期开发 |
| WalStorage | 强（带恢复） | 较慢 | 一致性敏感的服务 |

## 选择策略与社区关切

- **本地开发**：优先使用 `HybridStorage`，既保留冷启动速度，又能跨周末重启保留状态。
- **CI / 集成测试**：使用 `PersistentStorage`，配合独立的工作目录实现用例隔离。
- **崩溃后状态对账**：选择 `WalStorage` 或带 WAL 的 `HybridStorage`，契合 issue #7 关于 EventBridge Schedules 与 issue #876 中 Podman rootless 场景下容器频繁重启的诉求。
- **AWS SDK 协议更新**：issue #156 中提到的协议层变更只影响请求/响应编解码，存储层不受影响；只要 `StorageBackend` 契约稳定，服务实现无需变动。

## 总结

`存储后端与持久化模式` 以接口 + 多实现 + 工厂的方式，把 floci 的"状态"维度清晰分离。`InMemoryStorage` 提供速度，`PersistentStorage` 提供可恢复性，`HybridStorage` 在二者之间取得平衡，`WalStorage` 进一步提供崩溃一致保证，`StorageFactory` 将它们按需装配。理解这一层，对于在 issue #876（Podman rootless 配置）、issue #66（容器化 awslocal）等场景下做出正确的部署决策至关重要。

---

<a id='page-docker-backed-services'></a>

## Docker 后端服务与容器集成

### 相关页面

相关主题：[Floci 概览与系统架构](#page-overview-architecture), [配置、AWS 线协议与多账户隔离](#page-configuration-protocols)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/main/java/io/github/hectorvent/floci/core/common/docker/DockerClientProducer.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/docker/DockerClientProducer.java)
- [src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManager.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManager.java)
- [src/main/java/io/github/hectorvent/floci/core/common/docker/DockerHostResolver.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/docker/DockerHostResolver.java)
- [src/main/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncher.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncher.java)
- [src/main/java/io/github/hectorvent/floci/services/rds/container/RdsContainerManager.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/services/rds/container/RdsContainerManager.java)
- [src/main/java/io/github/hectorvent/floci/services/rds/proxy/RdsAuthProxy.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/services/rds/proxy/RdsAuthProxy.java)
</details>

# Docker 后端服务与容器集成

## 1. 概述与定位

Floci 的 Docker 后端服务与容器集成层负责在宿主机上统一管理所有服务容器（Lambda 运行时、RDS 模拟、Cloud Control 等），是整个本地 AWS 模拟栈的运行时底座。该层向下对接 Docker/Podman 引擎，向上为各个服务模块提供容器创建、销毁、查询和健康检查等能力。

核心抽象集中在 `core/common/docker` 包中，包括 Docker 客户端的生产、宿主机解析与容器生命周期管理；服务特定实现则位于 `services/lambda/launcher` 与 `services/rds/container` 子包内。社区中关于 Podman rootless 部署的反馈（#876）以及为运行时容器加入 `awslocal` CLI 的需求（#66）都与该层紧密相关。

资料来源：[DockerClientProducer.java:1-40]()

## 2. Docker 客户端与主机解析

`DockerClientProducer` 作为 CDI/JEE 风格的工厂，集中构造 `DockerClient` 实例，避免在多个服务中重复配置。它读取连接端点、超时参数与 TLS 凭证，并对底层引擎（Docker daemon、Podman、远程 host）保持中立。

`DockerHostResolver` 用于在容器与宿主机之间进行网络地址翻译。当 Lambda 容器需要回连宿主机上的 Runtime API 或当 RDS 代理需暴露给外部客户端时，解析器会判断当前是 rootless 模式、桥接网络还是 host 网络，并据此返回正确的 `DOCKER_HOST`、`localhost` 或容器网关 IP。社区 #876 提到的 `LAMBDA_RUNTIME_API_HOST` 覆写需求正是由该解析器承担。

```mermaid
flowchart LR
    A[服务调用方] --> B[DockerClientProducer]
    B --> C{DockerHostResolver}
    C -->|Docker| D[unix:///var/run/docker.sock]
    C -->|Podman rootless| E[user namespace socket]
    C -->|远程 host| F[tcp://host:2375]
    B --> G[DockerClient 实例]
    G --> H[ContainerLifecycleManager]
```

资料来源：[DockerClientProducer.java:30-80](), [DockerHostResolver.java:20-95]()

## 3. 容器生命周期管理

`ContainerLifecycleManager` 是所有容器操作的统一入口，对外暴露创建、启动、停止、删除、查询与日志流订阅等方法。容器 ID 与服务名的映射、镜像缓存、健康状态轮询都在该类内部维护。

针对 RDS 模拟，`RdsContainerManager` 继承或复用 `ContainerLifecycleManager` 的能力，并在此之上加入 RDS 特有的资源约束：端口分配、初始化脚本注入、数据库启动等待探针。`RdsAuthProxy` 则单独承担鉴权代理职责，它既可以与 RDS 容器一同被编排，也可以在用户已外部署 RDS 时作为独立 sidecar 进程出现，用于签发临时 IAM 数据库令牌。

| 组件 | 职责 | 复用关系 |
| --- | --- | --- |
| `ContainerLifecycleManager` | 通用容器 CRUD、状态机 | 基类 |
| `RdsContainerManager` | RDS 镜像启动、端口、initdb | 组合 `ContainerLifecycleManager` |
| `RdsAuthProxy` | IAM 令牌签发、连接代理 | 与 `RdsContainerManager` 协作 |

资料来源：[ContainerLifecycleManager.java:40-140](), [RdsContainerManager.java:25-110](), [RdsAuthProxy.java:30-90]()

## 4. Lambda 容器启动

`ContainerLauncher` 位于 `services/lambda/launcher` 包内，专门处理 Lambda 运行时容器的引导流程：拉取或复用 `public.ecr.aws/lambda/python` 等镜像、注入用户函数代码（以只读挂载方式，见 1.5.31 发布说明中的“read-only code mounting”）、配置 Runtime API 端点、启动后注册到 `lambda` 服务注册表。

`ContainerLauncher` 接受 `DockerClient`（由 `DockerClientProducer` 注入）与宿主机解析结果，将它们转换为 Lambda 启动所需的 `AWS_LAMBDA_RUNTIME_API` 环境变量和挂载卷。冷启动耗时优化的关键点在于镜像层缓存与代码卷的就地挂载，二者均通过 `ContainerLifecycleManager` 暴露的接口完成。

资料来源：[ContainerLauncher.java:50-160](), [ContainerLifecycleManager.java:120-200]()

## 5. 社区关切与扩展点

- **Podman rootless 支持（#876）**：需要在 `DockerHostResolver` 中识别 `DOCKER_HOST` 指向 user namespace socket 的情形，并在 `ContainerLauncher` 中允许通过环境变量覆写 `LAMBDA_RUNTIME_API_HOST`。
- **运行期 CLI 工具（#66）**：建议在基础镜像构建阶段加入 `awslocal` CLI，便于在容器内进行 post-run 调试；变更应发生在镜像构建侧而非运行时容器层。
- **AWS 服务协议演进（#156）**：当上游 SDK 切换到 JSON/CBOR 等新协议时，`ContainerLifecycleManager` 中持有的镜像标签与启动参数可能需要同步升级。

资料来源：[DockerHostResolver.java:1-20](), [ContainerLauncher.java:1-30](), [RdsContainerManager.java:1-20]()

---

<a id='page-configuration-protocols'></a>

## 配置、AWS 线协议与多账户隔离

### 相关页面

相关主题：[Floci 概览与系统架构](#page-overview-architecture), [Docker 后端服务与容器集成](#page-docker-backed-services), [存储后端与持久化模式](#page-storage-persistence)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java)
- [src/main/java/io/github/hectorvent/floci/core/common/ProtocolClaimer.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/ProtocolClaimer.java)
- [src/main/java/io/github/hectorvent/floci/core/common/WireProtocol.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/WireProtocol.java)
- [src/main/java/io/github/hectorvent/floci/core/common/ProtocolClaim.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/ProtocolClaim.java)
- [src/main/java/io/github/hectorvent/floci/core/common/AccountResolver.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/AccountResolver.java)
- [src/main/java/io/github/hectorvent/floci/core/common/AwsCborContentTypeFilter.java](https://github.com/floci-io/floci/blob/main/src/main/java/io/github/hectorvent/floci/core/common/AwsCborContentTypeFilter.java)
</details>

# 配置、AWS 线协议与多账户隔离

## 概述

Floci 是一个面向 AWS 服务的多协议本地模拟与路由网关,其配置层、协议识别层与账户隔离层共同决定了入站请求如何被分发到对应的处理逻辑。本主题聚焦三个紧密耦合的子系统:通过 `EmulatorConfig` 暴露的运行时配置枚举、由 `WireProtocol` / `ProtocolClaim` / `ProtocolClaimer` 构成的线协议协商机制,以及 `AccountResolver` 实现的多账户隔离策略。这些组件构成了 Floci 处理跨服务、多账户请求的基础设施层。

## 配置系统

`EmulatorConfig` 是 Floci 的统一配置入口,以枚举形式聚合所有可调参数,集中管理服务端口、协议偏好、账户绑定等关键开关。

- **端口与服务开关**:每个枚举常量对应一个独立的配置维度,如监听端口、启用的服务集合等,便于按需启用或禁用具体 AWS 服务模拟。
- **运行时覆盖**:配置项支持通过环境变量或命令行参数进行覆盖,适配容器化部署场景(参考社区 Issue #876 中关于 Podman rootless 网络下 `LAMBDA_RUNTIME_API_HOST` 覆盖的需求)。
- **类型安全**:采用枚举而非字符串键,避免拼写错误,并在编译期提供 IDE 自动补全。

资料来源：[src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java:1-80]()

## AWS 线协议声明与路由

Floci 需要在同一端口上同时识别多种 AWS 线协议(JSON、CBOR、query 等),`WireProtocol` 枚举定义了受支持的协议集合,`ProtocolClaim` 与 `ProtocolClaimer` 协同完成声明式识别。

| 组件 | 职责 |
|------|------|
| `WireProtocol` | 枚举类型,列出 Floci 支持的所有线协议 |
| `ProtocolClaim` | 单条声明规则,描述某服务/操作所采用的协议 |
| `ProtocolClaimer` | 聚合多条声明,提供查询接口用于判定请求所属协议 |
| `AwsCborContentTypeFilter` | 通过 HTTP `Content-Type` 头识别 CBOR 协议请求 |

资料来源：[src/main/java/io/github/hectorvent/floci/core/common/WireProtocol.java:1-40](),[src/main/java/io/github/hectorvent/floci/core/common/ProtocolClaim.java:1-60](),[src/main/java/io/github/hectorvent/floci/core/common/ProtocolClaimer.java:1-80](),[src/main/java/io/github/hectorvent/floci/core/common/AwsCborContentTypeFilter.java:1-50]()

### 协议识别流程

```mermaid
flowchart LR
    A[入站 HTTP 请求] --> B{Content-Type 过滤}
    B -->|application/cbor| C[CBOR 协议]
    B -->|application/x-amz-json| D[JSON 协议]
    B -->|其他| E[默认 query 协议]
    C --> F[ProtocolClaimer 查询]
    D --> F
    E --> F
    F --> G[返回 WireProtocol 判定]
```

### 社区协议变更背景

社区 Issue #156 指出 AWS SDK 团队正在推进多项服务向 JSON/CBOR 等新线协议迁移(参考 2025 年 CloudWatch 协议变更)。`AwsCborContentTypeFilter` 的存在表明 Floci 已预先具备 CBOR 协议的识别能力,可平滑适配这些上游变更;`ProtocolClaimer` 的声明式设计也便于按服务、操作粒度追加新的协议规则。

## 多账户隔离

`AccountResolver` 负责在请求级别解析 AWS 账户标识,确保不同账户的状态、资源与凭据彼此隔离。

- **解析来源**:基于请求中携带的 `Authorization` 头、临时凭据或 `X-Amz-Account-Id` 等元信息提取账户 ID。
- **隔离作用域**:每个账户 ID 形成独立的命名空间,后续访问 RDS Data API、CloudWatch Logs Insights 等有状态服务时按账户路由(参考 1.5.31 版本发布说明)。
- **默认账户**:当请求未携带账户标识时,`AccountResolver` 回退到配置的默认账户,便于本地开发与测试。

资料来源：[src/main/java/io/github/hectorvent/floci/core/common/AccountResolver.java:1-90]()

## 协同关系

三个子系统并非孤立运作: `EmulatorConfig` 提供开关与默认值,`ProtocolClaimer` 在协议识别后调用 `AccountResolver` 进一步定位账户上下文,最终由路由层根据 `(协议, 账户)` 二元组定位具体服务处理器。这种分层设计使 Floci 能够在保持单进程简洁部署的同时,支持多协议、多账户的复杂本地仿真场景。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：floci-io/floci

摘要：发现 17 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[BUG] DynamoDB Query ScanIndexForward=false still returns ascending results on GSI / enhanced-client sortBetween。

## 1. 安装坑 · 来源证据：[BUG] DynamoDB Query ScanIndexForward=false still returns ascending results on GSI / enhanced-client sortBetween

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] DynamoDB Query ScanIndexForward=false still returns ascending results on GSI / enhanced-client sortBetween
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/floci-io/floci/issues/1675 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：[BUG] s3: PHP fopen on S3 objects fails with "Stream is not seekable"

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] s3: PHP fopen on S3 objects fails with "Stream is not seekable"
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/floci-io/floci/issues/1632 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安全/权限坑 · 来源证据：feat(cloudhsmv2): implement AWS CloudHSM v2 service (phased)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(cloudhsmv2): implement AWS CloudHSM v2 service (phased)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/floci-io/floci/issues/1774 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 安装坑 · 依赖 Docker 环境

- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装/运行入口包含 Docker 命令：docker run -d --name floci -p 4566:4566 -v /var/run/docker.sock:/var/run/docker.sock -u root floci/floci:latest
- 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
- 复现命令：`docker run -d --name floci -p 4566:4566 -v /var/run/docker.sock:/var/run/docker.sock -u root floci/floci:latest`
- 证据：identity.distribution | https://github.com/floci-io/floci | docker run -d --name floci -p 4566:4566 -v /var/run/docker.sock:/var/run/docker.sock -u root floci/floci:latest

## 5. 安装坑 · 来源证据：[BUG] ACL headers are ignored

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] ACL headers are ignored
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/floci-io/floci/issues/1766 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 6. 安装坑 · 来源证据：[BUG] S3 DeleteObject on version-enabled buckets does not set isLatest=true to the latest (after delete) version

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] S3 DeleteObject on version-enabled buckets does not set isLatest=true to the latest (after delete) version
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/floci-io/floci/issues/1775 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 7. 安装坑 · 来源证据：[BUG] SAM transform drops `PackageType` on `AWS::Serverless::Function` — a container-image function deploys as a broken…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] SAM transform drops `PackageType` on `AWS::Serverless::Function` — a container-image function deploys as a broken Zip function
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/floci-io/floci/issues/1770 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 8. 安装坑 · 来源证据：[FEAT] Lambda Extensions API — no `/2020-01-01/extension/*` endpoints, and `/opt/extensions/*` binaries are never launc…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[FEAT] Lambda Extensions API — no `/2020-01-01/extension/*` endpoints, and `/opt/extensions/*` binaries are never launched
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/floci-io/floci/issues/1771 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 9. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/floci-io/floci | README/documentation is current enough for a first validation pass.

## 10. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/floci-io/floci | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/floci-io/floci | no_demo; severity=medium

## 12. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/floci-io/floci | no_demo; severity=medium

## 13. 安全/权限坑 · 来源证据：[BUG] ACL grant is not honoured

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] ACL grant is not honoured
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/floci-io/floci/issues/1767 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 14. 安全/权限坑 · 来源证据：[BUG] ECS services with load balancers fail to register ELBv2 targets when multiple tasks use container port 80

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] ECS services with load balancers fail to register ELBv2 targets when multiple tasks use container port 80
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/floci-io/floci/issues/1778 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 15. 安全/权限坑 · 来源证据：[BUG] Lambda execution role is not assumed; runtime always authenticates as root

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Lambda execution role is not assumed; runtime always authenticates as root
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/floci-io/floci/issues/1777 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 16. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/floci-io/floci | issue_or_pr_quality=unknown

## 17. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/floci-io/floci | release_recency=unknown

<!-- canonical_name: floci-io/floci; human_manual_source: deepwiki_human_wiki -->