GGitHub 趋势观察站
每日 07:00 更新订阅EN
← 返回今日榜单

精选指南 · 编程与开发

Floci

在本机模拟 AWS 服务接口,供应用开发和集成测试使用。本文用 Docker Compose 和 AWS CLI 完成一次 S3 上传、下载、内容核对与清理。

访问 GitHub 仓库 ↗
最近上榜 · 2026-11-06#14

当日排名

+784当日新增 Star30,369总 Star
← 全部精选指南

入选理由:用 Docker Compose 和 AWS CLI 即可在本地核对 S3 上传、下载与清理,不要求真实云账号;官方对接口差异和持久化有明确说明,补充现有指南目录中的云开发测试场景。

入选:2026-11-05 · 资料核对:2026-11-05。根据官方资料整理,未进行安装与功能实测。

Floci:在本机完成一次 S3 文件上传、下载与结果核对

它解决什么问题

开发使用 AWS 接口的应用时,常常只是想确认“能创建资源、能存取文件、错误处理是否正确”,不必每次都先创建真实云资源。Floci 在本机提供 AWS 风格的服务端点,让现有 AWS CLI、SDK 和测试代码连接本地模拟器。

这篇指南选择一个具体任务:启动 Floci,创建本地 S3 存储桶,上传一个文本文件,再下载并核对内容。S3 的“桶”可以理解为存放对象的容器,对象则是带名称的数据文件。完成这条链路后,再考虑把它接入自己的应用测试。

本文依据官方 README、安装、Quick Start、S3 与存储文档,以及已发布的 2.4.0 信息整理;没有实际拉取镜像、安装程序或验证兼容性与性能。

适合谁,哪些情况不适合

  • 正在开发文件上传、消息队列或数据库调用,希望先在本机做集成测试的人。
  • 需要为测试流水线临时准备一组 AWS 风格资源的开发者。
  • 已会用基础终端命令,希望理解应用如何切换云端与本地端点的人。

它适合模拟接口和应用流程。真实 AWS 的权限、网络、配额、可用性和性能,仍需在目标环境验证;本地测试通过不能自动代表云端部署正确。

如果只是想备份照片或共享文件,云服务模拟器通常不是合适的最终存储产品。下面的练习采用临时内存模式,资源会随模拟器停止而丢失。

环境与准备

示例使用 macOS 或 Linux 的 Bash/Zsh。需要已经可用的 Docker Engine 23.0 或以上、Compose v2,以及安装在宿主机上的 AWS CLI v2。官方镜像采用 zstd 压缩,旧 Docker 版本可能无法拉取。

先在终端检查:

docker version
docker compose version
aws --version

docker version 应能连接服务端;只有客户端版本不代表 Docker 后台已经运行。AWS CLI 尚未安装时,按 AWS 官方安装指南选择系统版本。Windows 用户需要先按自己的 Docker 环境和 AWS CLI 安装方式准备终端;下面的 export 和文件命令不能原样当作 PowerShell 语法使用。

准备一个新的练习目录,以及可用于拉取镜像的网络。本例使用测试凭据,不需要真实 AWS 账号、云端资源或模型 API。官方安装文档也提供无需 Docker 的原生程序路线,本篇采用 Compose 便于说明启动和清理。

安装与第一次使用

1. 在专用目录保存 Compose 配置

在你放练习项目的父目录打开终端,确认 floci-s3-demo 尚未被使用,再执行:

mkdir floci-s3-demo
cd floci-s3-demo

用编辑器在这个目录新建 compose.yaml,写入:

services:
  floci:
    image: floci/floci:2.4.0
    ports:
      - "127.0.0.1:4566:4566"
    environment:
      FLOCI_STORAGE_MODE: memory

2.4.0 是本次核实的已发布版本;官方文档支持用 x.y.z 镜像标签固定版本。端口发布地址绑定在本机回环地址,示例里的客户端统一访问 http://127.0.0.1:4566。本例明确选择 memory,方便结束后清理临时资源。

2. 启动并查看容器状态

仍在保存 compose.yaml 的目录执行:

docker compose up -d
docker compose ps
docker compose logs --tail=50 floci

先确认容器没有立即退出,日志没有启动错误。首次会下载镜像;在没有完成下载或服务尚未启动时,不要继续创建测试资源。

3. 为当前终端设置测试凭据

在同一终端执行:

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

这些值用于当前终端的本地练习。下面每条 AWS 命令还显式指定本地端点,便于检查目标。保持这个练习终端专用,操作真实云资源时另开按团队流程配置的环境。

先列出本地存储桶:

aws --endpoint-url http://127.0.0.1:4566 s3 ls

新实例可能没有输出;命令成功且无资源,与连接失败是不同情况。若出现连接错误,先检查容器和端口。

4. 创建桶并上传一个文本文件

aws --endpoint-url http://127.0.0.1:4566 s3 mb s3://repowatch-local-demo
printf 'hello floci
' > hello.txt
aws --endpoint-url http://127.0.0.1:4566 s3 cp hello.txt s3://repowatch-local-demo/hello.txt
aws --endpoint-url http://127.0.0.1:4566 s3 ls s3://repowatch-local-demo/

列表应能找到 hello.txt。存储桶和文件路径只是练习名称;若同一实例已存在这个桶,先查明是否来自之前的练习,再决定复用或改名。

5. 下载并检查内容

aws --endpoint-url http://127.0.0.1:4566 s3 cp s3://repowatch-local-demo/hello.txt restored.txt
cat restored.txt
cmp hello.txt restored.txt

应看到 hello floci。cmp 在文件一致时成功结束且没有输出;如果报告差异,就需要回看上传和下载目标。到这里,创建、上传、列举、下载和内容核对都完成了一次有检查点的操作。

6. 清理本次练习资源

确认目标仍是本地端点和本次桶名,再执行:

aws --endpoint-url http://127.0.0.1:4566 s3 rm s3://repowatch-local-demo/hello.txt
aws --endpoint-url http://127.0.0.1:4566 s3 rb s3://repowatch-local-demo
docker compose down

rb 删除空桶;桶不为空时先查看内容,不使用强制参数跳过检查。hello.txt 和 restored.txt 留在练习目录,可自己确认后处理。本例使用 memory,停止模拟器也会失去其中未持久化的测试资源。

主要能力与典型场景

文件接口的集成测试。 把应用 SDK 的 endpoint 配置为本地地址,使用测试凭据和明确 region,验证上传、读取和错误处理。Node.js 的 S3 SDK 还要按官方示例考虑 forcePathStyle;各语言的配置方式并不完全相同。

消息和数据流程练习。 官方 Quick Start 还提供 SQS 队列与 DynamoDB 表的例子。先在单个服务上完成结果核对,再增加多服务交互,避免同时引入太多未知条件。

临时 CI 环境。 为某次测试启动实例,准备已知资源并在结束后清理。测试断言应该检查返回值和数据,而不是只检查容器在运行。

保留开发状态。 若想重启后保留资源,需要按官方存储说明选择 persistent、hybrid 或 wal,并把存储路径挂载到保留的目录或卷。只增加一个 data 挂载而仍使用 memory,不会自动获得持久化。应在改变模式后重新建立练习资源,再验证重启后的状态。

常见问题与排错

镜像拉不下来。 核对网络、完整镜像名、固定版本和 Docker 版本。官方仓库当前使用 floci/floci,旧 hectorvent/floci 命名空间不再更新。

容器启动但客户端连不上。 查看 docker compose ps 和日志,确认 4566 没有被其他服务占用。更改主机映射端口后,AWS_ENDPOINT_URL 和每条命令中的端点也要一起修改。

提示缺少凭据或地区。 检查是否仍在设置过四项测试变量的终端。测试凭据也需要被客户端读取;更换终端后重新配置本地练习变量。

容器里的应用无法访问 127.0.0.1。 本文 AWS CLI 运行在宿主机;另一个容器中的 127.0.0.1 指它自己。将应用容器接入同一 Compose 网络后,按实际服务名与内部端口配置端点,不把宿主机示例地址直接复制过去。

重启后资源不见了。 先检查 FLOCI_STORAGE_MODE,本篇明确使用临时 memory。需要保存时同时配置存储模式和数据挂载,再做一次重启验证。

某项 AWS 操作行为不一致。 查对应服务文档。官方 S3 文档明确说明部分功能只实现部分行为,例如 RestoreObject 接受请求但不运行恢复状态机,复制配置可保存但不会实际复制对象。接口名称出现不代表完整云端语义已经模拟。

费用、隐私与限制

Floci 采用 MIT,本地模拟器不要求 AWS 云账号或产品授权令牌。运行本例主要使用自己的计算、磁盘和镜像下载资源;若改为访问真实云端点,则应按真实服务规则处理账号与费用。

本例文件交给本机模拟器。镜像下载仍需访问镜像服务,测试文件、日志和以后配置的持久化目录也需要自己管理。本篇基础 S3 流程不配置 Docker socket;Web 控制台侧车和部分计算服务另外依赖 Docker 控制能力,应在确实需要时阅读对应说明。

默认接受测试凭据不能代表生产身份验证已经通过。把本地测试用作应用流程检查,再分别验证真实云环境中的权限、策略、网络与运维要求。不要把临时模拟资源当作备份。

官方资料