floci v2.3.0 Docker Compose 部署指南

用官方安装脚本与 Docker Compose 两条路径部署 floci v2.3.0 本地 AWS 模拟器，完成 doctor 七项自检、persistent 模式跨重启验证与 Web 控制台访问，含六条排障实录。

floci自托管云原生CLI命令运维2026/10/25

floci v2.3.0 Docker Compose 部署指南

目标：在一台 Ubuntu 服务器上部署 floci v2.3.0 本地 AWS 模拟器，覆盖「官方安装脚本 + floci start 一键起」与「Docker Compose 持久化部署」两条路径，完成 AWS CLI 连接验证、持久化跨重启验证与 Web 控制台访问。本文全部命令与回显均在 Ubuntu 22.04 LTS + Docker Engine 29.1.3（Compose v2.40.3）环境、floci CLI 0.4.0 / floci v2.3.0 实测通过（2026-10-25）。

一、环境信息

  • 操作系统：Ubuntu 22.04 LTS（x86_64）
  • Docker Engine：29.1.3，Docker Compose 插件 v2.40.3
  • floci 版本：v2.3.0（2026-10-25 经 shields.io latest release 徽章核实的最新稳定版），官方镜像 floci/floci
  • floci CLI 版本：0.4.0
  • AWS CLI：aws-cli/2.x（用于连接验证与对拍）
  • 端口规划：模拟器 API 端口 4566（AWS 协议统一入口）、Web 控制台 4500（首次访问时按需拉起）；若宿主 4566 已被占用，可将映射改为 8128:4566 等空闲端口，后续所有 localhost:4566 相应替换
  • 编排目录：/opt/floci/（含 compose.yaml 与数据目录 data/）
  • 内存要求：控制面为 Quarkus native 服务（实测启动毫秒级），叠加数据面真实引擎后整体吃内存，建议宿主机内存 ≥ 8GB

二、部署路径怎么选

路径适用场景状态管理
路径 A：安装脚本 + floci start快速体验、开发机自用floci CLI 托管（默认内存态，floci stop/start 控制）
路径 B：Docker Compose服务器长期运行、CI 节点、需要持久化自持一份 compose.yaml，docker compose 管理

两条路径共用同一官方镜像，功能完全一致；区别只在「谁管生命周期」。生产/CI 建议路径 B（配置即代码 + 持久化），本机试用建议路径 A。

三、路径 A：安装脚本一键起

3.1 安装 floci CLI

curl -fsSL https://floci.io/install.sh | sh

实测输出（逐行照抄）：

+ Found latest CLI version: v0.4.0
+ Downloading floci-cli-linux-amd64 v0.4.0...
+ Installing to /usr/local/bin
+ floci installed successfully.

Run 'floci --help' to get started.

排障：安装脚本从 GitHub Releases 下载二进制。若服务器直连 GitHub 失败（超时/连接重置），给当前 Shell 注入代理后重试，例如 export https_proxy=http://<代理IP>:<端口> 再执行同一条命令。实测受限网络下直连报连接错误、走代理后一次成功；脚本探测最新版本失败时还会自动重试 4 次，仍失败可按官方提示用 FLOCI_CLI_VERSION=<tag> 钉版本重试。

安装后验证：

floci version

实测输出：

Floci CLI version 0.4.0

3.2 环境自检与拉起

floci install 子命令在 0.4.0 中不存在（floci install 实测报 unknown command "install" for "floci"），环境检查由 floci start 内置完成；若需单独体检，用 floci doctor（详见 《floci v2.3.0 常用 CLI 命令详解》第七章）。直接拉起：

floci start

实测输出（逐行照抄）：

Starting Floci AWS...

=== AWS Local Emulator Ready ===

Floci AWS is ready (http://localhost:4566)

Regional endpoints:
  http://us-east-1.localhost:4566
  http://eu-west-1.localhost:4566
  http://ap-southeast-1.localhost:4566

Web Console:  http://localhost:4566/_floci/ui
  Click or GET the URL to start the sidecar container.
  Configure FLOCI_SERVICES_UI_ENABLED=false to disable.

若要启用 Lambda 和 EC2 的真实执行能力，按官方提示安装运行时组件（floci install 提示原文已随 0.4.0 移除，实际做法见 D1 篇 16.10/16.11——首次调用时自动拉取对应运行时镜像）。

3.3 状态与连接验证

floci status

实测输出：

Floci AWS Status

  Container:  floci  running (healthy)
  Image:      floci/floci:latest
  Endpoint:   http://localhost:4566
  Reachable:  yes

Stop with 'floci stop'.

配置 AWS CLI（floci 接受任意 Access Key，floci env 输出的占位凭据即可）：

eval $(floci env)
aws sts get-caller-identity

实测输出：

{
    "UserId": "000000000000",
    "Account": "000000000000",
    "Arn": "arn:aws:iam::000000000000:root"
}

四、路径 B：Docker Compose 持久化部署（推荐）

4.1 编排文件

创建 /opt/floci/compose.yaml（实测通过的完整版本）：

name: floci-v2.3.0-stack
services:
  floci:
    image: floci/floci:latest
    container_name: floci
    restart: unless-stopped
    ports:
      - "4566:4566"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data
    environment:
      FLOCI_STORAGE_MODE: persistent
      FLOCI_STORAGE_PERSISTENT_PATH: /app/data
      FLOCI_DEFAULT_REGION: us-east-1

三个关键点：

  • FLOCI_STORAGE_MODE: persistent + FLOCI_STORAGE_PERSISTENT_PATH: /app/data 必须成对出现——只挂 ./data 而不开 persistent，模拟器仍把状态放内存，数据目录永远为空（见第 7.2 节排障）；官方存储文档另有 hybrid（内存 + 定期落盘快照）与 wal（预写日志）两种模式可选；
  • /var/run/docker.sock 是 Lambda、EC2、EKS、MSK、ECR、CodeBuild 等「真实执行」能力的前提，缺了它基础服务可用但真实负载不执行（floci config validate 会直接报错，见 4.3）；
  • name: floci-v2.3.0-stack 固定栈名，避免目录名变化导致资源漂移。

4.2 启动与验证

cd /opt/floci
docker compose up -d
docker compose ps

实测输出：

NAME      IMAGE                STATUS                    PORTS
floci     floci/floci:latest   Up 10 minutes (healthy)   0.0.0.0:4566->4566/tcp, [::]:4566->4566/tcp

（实测栈还开放了 ElastiCache 端口池 6379-6399 的映射，属后续按需加配，见第 4.4 节。）

就绪探测：curl -s -o /dev/null -w "%{http_code}\n" http://localhost:4566 返回 200 即就绪；或等 docker compose ps 出现 (healthy)。

4.3 部署前自检：floci config validate

把 compose 文件交给 floci CLI 做部署前体检（能查出缺 sock 挂载、声明了持久化目录却没开 persistent 等错误）：

floci config validate --file /opt/floci/compose-bad.yaml

对一个故意缺 sock 挂载、挂了 /app/data 却没开 persistent 的坏文件，实测输出（逐行照抄）：

Validating /opt/floci/compose-bad.yaml  (service: floci)

  x  Missing /var/run/docker.sock volume mount — required for Lambda, EC2, EKS, MSK, ECR, CodeBuild
  !  A volume is mounted at /app/data but FLOCI_STORAGE_MODE is not 'persistent' — the emulator keeps its state in memory by default, so the volume stays empty

1 error(s) found.
exit=1

x 为错误（退出码 1），! 为警告；上线前务必跑到 0 error。

4.4 按需开放数据面端口池

要用 ElastiCache（真实 Valkey 引擎）、RDS MySQL（3306-3399）、RDS PostgreSQL（5432-5599，官方文档标注端口池 5432-5999/7001-7099 两段）等需要原生客户端直连的服务，把端口池映射加进 compose 再 docker compose up -d：

    ports:
      - "4566:4566"
      - "6379-6399:6379-6399"

实测建 ElastiCache 集群后宿主机 redis-cli -h 127.0.0.1 -p 6379 PING 直接返回 PONG（完整对拍见 D1 篇 16.12）。

五、持久化跨重启实测

在 persistent 模式下创建一个桶和一张表，重启整个栈后验证资源仍在：

export AWS_ENDPOINT_URL=http://localhost:4566 AWS_DEFAULT_REGION=us-east-1 AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test
aws s3 mb s3://persist-bucket
aws s3 cp /etc/hostname s3://persist-bucket/host.txt --quiet
aws dynamodb create-table --table-name persist-tbl \
  --attribute-definitions AttributeName=id,AttributeType=S \
  --key-schema AttributeName=id,KeyType=HASH --billing-mode PAY_PER_REQUEST
cd /opt/floci && docker compose down && docker compose up -d && sleep 8
aws s3 ls
aws dynamodb list-tables
aws s3 cp s3://persist-bucket/host.txt -

实测输出（重启后）：

2026-10-25 00:47:04  persist-bucket
{
    "TableNames": [
        "persist-tbl"
    ]
}
<宿主机名>

桶、对象、表全部跨 compose down/up 存活，/app/data 目录可见持久化文件。作为对照组：默认内存态（ephemeral）下同样操作，compose down 再起后 aws s3 ls 输出为空——资源全部丢失。结论：长期使用必须开 persistent 模式。

另注：persistent 模式会把 FLOCI_DEFAULT_REGION 一并持久化——实测把区域临时改为 cn-north-1 后重启，aws s3 ls 在 us-east-1 会话下为空，需把区域变量改回并重建栈才恢复（详见配置篇第四章）。

六、Web 控制台访问

floci 内置免费 Web 控制台（floci/floci-ui 镜像，实测版本 0.7.0），首次访问 http://<服务器IP>:4566/_floci/ui 时自动按需拉起并发布到 4500 端口，浏览器打开 http://<服务器IP>:4500 即可使用。

实测健康端点（控制台就绪后）：

curl -s http://localhost:4500/api/health

实测输出：

{"status":"ok","version":"0.7.0","panels":["app-config","compute","kms-crypto","lambda-trigger","logs-explorer","logs-explorer-query","networking","sagemaker-dashboard","sqs-messaging","workflow-executions","expandable"]}

控制台面板覆盖应用配置、计算资源、KMS、Lambda 触发器、日志浏览/查询、网络、SageMaker 仪表盘、SQS 消息收发、工作流执行等。若不希望开放控制台，设置 FLOCI_SERVICES_UI_ENABLED=false（实测关闭后 /_floci/ui 返回 404，不再拉起）。

七、排障实录

7.1 floci start 报 Cannot connect to the Docker daemon

现象：floci start 直接失败，实测回显：

Error: Failed to inspect container: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
Check that Docker is running ('docker info') and re-run the command.

原因：Docker 引擎没起来。处理：systemctl start docker（并 systemctl enable docker 防止重启后复发）后重跑 floci start。

7.2 挂了 /app/data 但目录始终为空

现象：compose 里挂了 ./data:/app/data，ls data/ 一直为空。 原因：没设 FLOCI_STORAGE_MODE: persistent，模拟器状态留在内存。处理：补上 FLOCI_STORAGE_MODE: persistent 与 FLOCI_STORAGE_PERSISTENT_PATH: /app/data 两个变量并重建栈；用 floci config validate 可在部署前查出（见 4.3）。

7.3 floci reset 拒绝执行

现象：floci reset 报错退出（退出码 1）：

Error: reset deletes every resource in Floci AWS and needs confirmation.
Pass --yes to reset without asking.

处理：确认要清空全部资源后执行 floci reset --yes（实测输出 + Floci AWS state reset (http://localhost:4566)）。

7.4 内存不足导致进程被杀

现象：模拟器进程无故退出（退出码 137）。floci 控制面为 Quarkus native 服务，叠加数据面真实引擎（Lambda 运行时、ElastiCache、RDS 等）后整体内存占用可观；宿主内存不足时会被 OOM Killer 结束。处理：保障 ≥ 8GB 内存、预留磁盘；用 floci status 确认后 floci start 重新拉起。

7.5 拉取镜像缓慢或失败

现象：floci start/docker compose up 卡在拉取 floci/floci 镜像或报超时。原因：服务器到 Docker Hub 链路受限。处理：为 Docker 引擎配置镜像加速或代理（/etc/docker/daemon.json 的 registry-mirrors，或 systemd drop-in 注入 HTTPS_PROXY）后 systemctl restart docker 重试。

7.6 防火墙放行

服务器启用防火墙时放行 4566（与按需开放的 4500、数据面端口池）：

ufw allow 4566/tcp && ufw reload

八、收尾与系列导航