floci v2.3.0 常用 CLI 命令详解

目标：系统梳理 floci CLI 0.4.0 的全部子命令与常用参数，逐条给出实测回显，并用 AWS CLI 对 S3、DynamoDB、SQS、IAM、SSM、Secrets Manager、KMS、CloudWatch Logs、EventBridge、Lambda（真实执行）、EC2（真实实例）、ElastiCache（真实引擎）做全套对拍。本文全部命令与回显均在 Ubuntu 22.04 LTS、Docker Engine 29.1.3 环境、floci CLI 0.4.0 / Server 2.3.0（2026-10-25）实测取得，逐行照抄；部署过程见《floci v2.3.0 Docker Compose 部署指南》。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64），Docker Engine 29.1.3
floci：CLI 0.4.0；Server 2.3.0（floci-always-free 发行标识）；部署形态为 floci start（CLI 托管）与 Compose 持久化两种，见部署篇
AWS CLI：aws-cli/2.x；连接凭据来自 eval $(floci env)（AWS_ACCESS_KEY_ID='test'、AWS_SECRET_ACCESS_KEY='test'、AWS_DEFAULT_REGION='us-east-1'、AWS_ENDPOINT_URL='http://localhost.floci.io:4566'）
文中所有 aws 命令默认已执行过 eval $(floci env)

二、floci CLI 命令总览

命令	作用	本文实测
`floci version`	版本信息	第三章
`floci start`	拉起模拟器（含 `--detach/--services/--persist` 等参数）	第四章
`floci status`	运行状态	第五章
`floci env`	输出 AWS CLI/SDK 所需环境变量	第六章
`floci doctor`	环境自检（11 项检查）	第七章
`floci services`	列出启用的服务面	第八章
`floci logs`	查看模拟器日志	第九章
`floci wait`	阻塞等待就绪	第十章
`floci reset`	清空全部资源（需 `--yes`）	第十一章
`floci stop` / `floci restart`	停止 / 重启	第十二章
`floci update`	升级检查与执行	第十三章
`floci config validate` / `config profile`	编排体检 / 配置档案	第十四章
`floci snapshot`	状态快照	第十五章（v2.3.0 未开放，排障实录）

三、floci version

模拟器未启动时：

floci version

实测输出：

Floci CLI version 0.4.0

模拟器运行中时，会附带探测到的服务端信息与镜像摘要（逐行照抄）：

Floci CLI  0.4.0
Server:      2.3.0 (floci-always-free)
Image:       floci/floci@sha256:e0b292df4dc9559b7b1bf4f51bdda4bb8e269276236438cd03cae661260ea8a9

Server: 2.3.0 (floci-always-free) 是确认「免费全功能发行版」的直观标志；排查"CLI 与服务端版本不匹配"类问题时，先看这两行。

四、floci start

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.

floci start --help 的完整参数（实测摘录）：

参数	默认	说明
`--container=<name>`	`floci`	服务实例名
`--detach`	关	立即返回，不等就绪（CI 流水线配合 `floci wait` 使用）
`--endpoint=<url>`	`http://localhost:4566`	服务端点
`--image=<ref>`	`floci/floci:latest`	镜像引用（可钉版本）
`--namespace=<name>`	派生自 `--container`	本实例启动的资源命名空间（多实例隔离）
`--persist=<dir>`	关	指定持久化目录（等价 Compose 的 `FLOCI_STORAGE_MODE: persistent`）
`--port=<port>`	`4566`	宿主端口
`--profile=<name>`	关	使用 `~/.floci/profiles/` 下的配置档案
`--pull=always\|missing\|never`	`missing`	镜像拉取策略
`--services=<csv>`	全部	按需启用服务面（如 `--services=s3,dynamodb,sqs`，可显著降内存）
`-o, --output=text\|json\|yaml`	`text`	输出格式（`--json` 为 json 简写）

前置检查失败的真实报错（Docker 守护进程未运行时，逐行照抄）：

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.

处理：systemctl start docker 后重跑。

五、floci status

运行中：

Floci AWS Status

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

Stop with 'floci stop'.

停止后（注意退出码为 1，脚本判断要按 Reachable: no 或退出码处理）：

Floci AWS Status

  Container:  floci  exited
  Image:      floci/floci:latest
  Endpoint:   http://localhost:4566
  Reachable:  no

Run 'floci start' to launch Floci AWS.
Command failed with exit code 1

六、floci env

floci env

实测输出（逐行照抄）：

export AWS_ENDPOINT_URL='http://localhost.floci.io:4566'
export AWS_ACCESS_KEY_ID='test'
export AWS_SECRET_ACCESS_KEY='test'
export AWS_DEFAULT_REGION='us-east-1'

# Run: eval "$(floci env)"

要点：

凭据为占位值 test/test——floci 接受任意 Access Key，密钥不会泄露也不会校验（签名校验行为见配置篇第六章）；
AWS_ENDPOINT_URL 用 localhost.floci.io（解析回 127.0.0.1 的官方域名），这是为了让 SDK 的主机名类断言与路由行为更接近真实 AWS；所有实测请求实际都打到本机 4566；
--shell zsh 等参数可按 Shell 输出（实测 zsh 输出与 bash 相同的四行 export）；
标准用法就是注释行：eval "$(floci env)"。

七、floci doctor（11 项自检）

floci doctor

实测输出（逐行照抄）：

Floci AWS Doctor — checking your environment

  + docker.installed           Docker 29.1.3 detected
  + docker.daemon              Daemon reachable
  + docker.socket              /var/run/docker.sock accessible
  + docker.version             Docker 29.1.3 (>= 20.10)
  + port.available             Port 4566 in use by container 'floci' (expected)
  + image.present              floci/floci image present locally
  + image.version              Server image version 2.3.0 (>= 1.5.0)
  + container.running          Container 'floci' is running
  + endpoint.reachable         http://localhost:4566 is reachable (server v2.3.0)
  ! aws.cli.endpoint           AWS_ENDPOINT_URL is not set
                               Fix: export AWS_ENDPOINT_URL='http://localhost.floci.io:4566'
  + aws.cli.s3.pathstyle       ~/.aws/config not found — skipped

No failures, 1 warning(s) to review.

11 项检查分三类：Docker 环境（docker.* 4 项）、服务实例（port/image/container/endpoint 4 项）、AWS CLI 集成（aws.cli.* 3 项）。! 为警告（上面示例：当前 Shell 没导出 AWS_ENDPOINT_URL，按 Fix 提示执行 eval "$(floci env)" 即消除）；✗ 为失败（如引擎版本过低、socket 不可读），有失败时先修再启动。

八、floci services（127 项服务）

floci services

实测输出首行与节选（逐行照抄，完整列表 127 行）：

Floci AWS Services  (127 enabled)

  +  ssm
  +  sqs
  +  s3
  +  dynamodb
  +  sns
  +  lambda
  +  apigateway
  +  iam
  +  kafka
  +  mq
  +  elasticache
  +  memorydb
  +  rds
  +  neptune
  +  docdb
  +  redshift
  +  events
  +  logs
  +  kms
  +  states
  +  cloudformation
  +  athena
  +  glue
  +  kinesis
  +  es
  +  ec2
  +  ecs
  +  ecr
  +  eks
  +  mwaa
  +  sagemaker
  +  codebuild
  +  batch
  +  bedrock
  +  cognito-idp
  +  route53
  +  transfer
  +  datasync
  +  organizations

（完整列表还含 secretsmanager、monitoring、scheduler、swf、acm、emr-serverless、cloudfront、iot、cloudtrail、dms 等 127 项。）需要缩减内存占用时，用 floci start --services=s3,dynamodb,sqs,lambda 只启用所需服务面。

九、floci logs

floci logs            # 全量日志
floci logs --tail 3   # 末尾 N 行
floci logs -f         # 跟随输出

floci logs --tail 3 实测输出（逐行照抄）：

2026-10-25 01:11:07,382 INFO  [io.quarkus] floci 2.3.0 native (powered by Quarkus 3.40.1) started in 0.052s. Listening on: http://0.0.0.0:4566
2026-10-25 01:11:07,382 INFO  [io.quarkus] Profile prod activated. 
2026-10-25 01:11:07,382 INFO  [io.quarkus] Installed features: [cdi, config-yaml, rest, rest-jackson, security, smallrye-context-propagation, vertx]

服务端是 Quarkus native 构建（floci 2.3.0 native），启动毫秒级。日志里还能看到各后台调度器的启动行（DynamoDB TTL sweeper scheduled (60s interval)、Scheduler dispatcher started (tick every 10s)、SecretRotationScheduler started、EC2 IMDS server listening on port 9169 等），排查"某服务行为不符预期"时先来这里找线索。

十、floci wait

floci wait

实测输出：

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

配合 floci start --detach 使用：先异步拉起，脚本里 floci wait 阻塞到就绪再跑测试——CI 流水线的标准姿势。

十一、floci reset（清空状态）

不带 --yes 会被拒绝（退出码 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)

实测清空效果：reset 前建了桶 pre-reset，reset 后 aws s3 ls 输出为空。这是用例之间"回滚到白板"的主要手段（persistent 模式下 reset 同样生效，清的是当前全部资源）。

十二、floci stop / restart

floci stop

实测输出：

Stopping Floci AWS container 'floci'...
Stopped.

floci restart

实测输出：

Container started (a10d7f639c86)
Waiting for Floci AWS to be ready...
Floci AWS is ready (http://localhost:4566)

十三、floci update

floci update --check

实测输出：

+ floci 0.4.0 is up to date

去掉 --check 则执行升级（重新下载 CLI 并按需更新服务端镜像）。

十四、floci config validate / config profile

config validate 对编排文件做部署前体检（详见部署篇 4.3，这里给实测原样）。对一个缺 Docker socket 挂载、挂了数据目录却没开 persistent 的坏文件：

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

实测输出（逐行照抄，退出码 1）：

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.

config profile 管理启动档案（floci config profile --help 实测可见）：--create <名称> 创建、--list 列出、--delete 删除、--set/--get 读写档案项，配合 floci start --profile <名称> 在多套参数（不同区域/端口/服务面）之间一键切换。

十五、floci snapshot（v2.3.0 未开放，排障实录）

CLI 存在该子命令，但 v2.3.0 服务端尚未实现快照接口。实测：

floci snapshot save snap-check

Error: Failed to save snapshot: Server returned HTTP 400 for /_floci/snapshots/snap-check
Run 'floci status' to check the emulator.
Error: Snapshot API not available on this server version.
Track progress: https://github.com/floci-io/floci/issues

结论与替代：v2.3.0 上不要依赖快照做用例间回滚，持久化跨重启靠 persistent 模式，状态回滚靠 floci reset --yes；升级版本后可用 floci snapshot save 复测。

十六、AWS CLI 对拍实战（核心）

以下每组均为本机实测回显，可直接作为冒烟脚本素材。

16.1 STS 身份

aws sts get-caller-identity

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

固定账号 000000000000（可用 FLOCI_DEFAULT_ACCOUNT_ID 修改）。

16.2 S3

aws s3 mb s3://demo-bucket
echo "hello floci" > /tmp/hello.txt
aws s3 cp /tmp/hello.txt s3://demo-bucket/hello.txt
aws s3 ls
aws s3 ls s3://demo-bucket/

实测输出（逐行照抄）：

make_bucket: demo-bucket
Completed 12 Bytes/12 Bytes (1.5 KiB/s) with 1 file(s) remainingupload: tmp/hello.txt to s3://demo-bucket/hello.txt             
2026-10-25 01:12:00 demo-bucket
2026-10-25 01:11:08 awslambda-us-east-1-tasks
2026-10-25 01:12:01         12 hello.txt

注意 awslambda-us-east-1-tasks 是 Lambda 服务面自动创建的内部桶——别把它当脏数据删。

16.3 DynamoDB

aws dynamodb create-table --table-name users \
  --attribute-definitions AttributeName=id,AttributeType=S \
  --key-schema AttributeName=id,KeyType=HASH --billing-mode PAY_PER_REQUEST \
  --query "TableDescription.[TableName,TableStatus]" --output text
aws dynamodb list-tables
aws dynamodb put-item --table-name users \
  --item '{"id": {"S": "u001"}, "name": {"S": "zhang"}}'
aws dynamodb get-item --table-name users --key '{"id": {"S": "u001"}}'

实测输出（逐行照抄）：

users	ACTIVE
{
    "TableNames": [
        "users"
    ]
}
{
    "Item": {
        "id": {
            "S": "u001"
        },
        "name": {
            "S": "zhang"
        }
    }
}

16.4 SQS

aws sqs create-queue --queue-name orders --query QueueUrl --output text
aws sqs send-message --queue-url http://localhost:4566/000000000000/orders --message-body "task-1"
aws sqs receive-message --queue-url http://localhost:4566/000000000000/orders --query "Messages[0].[Body]" --output text

实测输出（逐行照抄）：

http://localhost:4566/000000000000/orders
{
    "MD5OfMessageBody": "c146b6ad38277b931d94d82f20703136",
    "MessageId": "fbb088ca-f325-4ad6-a532-7697330c9d45"
}
task-1

QueueUrl 主机段由 FLOCI_BASE_URL/FLOCI_HOSTNAME 决定（默认 localhost:4566），账号段默认 000000000000——多账号隔离见 16.9。

16.5 IAM

aws iam create-user --user-name dev-alice --query "User.[UserName,Arn]" --output text
aws iam list-users --query "Users[].[UserName,Arn]" --output table

实测输出（逐行照抄）：

dev-alice	arn:aws:iam::000000000000:user/dev-alice
-----------------------------------------------------------
|                        ListUsers                        |
+-----------+---------------------------------------------+
|  dev-alice|  arn:aws:iam::000000000000:user/dev-alice   |
+-----------+---------------------------------------------+

16.6 SSM 参数仓库

aws ssm put-parameter --name /app/db/host --type String --value 10.0.0.12
aws ssm get-parameter --name /app/db/host --query Parameter --output json

实测输出（逐行照抄）：

{
    "Version": 1
}
{
    "Name": "/app/db/host",
    "Type": "String",
    "Value": "10.0.0.12",
    "Version": 1,
    "LastModifiedDate": "2026-10-25T01:12:14.715000+00:00",
    "ARN": "arn:aws:ssm:us-east-1:000000000000:parameter/app/db/host",
    "DataType": "text"
}

16.7 Secrets Manager

aws secretsmanager create-secret --name prod/db-password --secret-string q1w2e3r4 --query "[Name,ARN]" --output text
aws secretsmanager get-secret-value --secret-id prod/db-password --query SecretString --output text

实测输出（逐行照抄）：

prod/db-password	arn:aws:secretsmanager:us-east-1:000000000000:secret:prod/db-password-EWH0RM
q1w2e3r4

密文原样可读（无 KMS 加密），符合模拟器定位；示例值仅作演示，请勿放真实密码。

16.8 KMS / CloudWatch Logs / EventBridge

aws kms list-keys --query "length(Keys)" --output text

实测输出 25——服务端预置了 25 个 KMS 密钥，create-key 之外大部分加解密测试可直接用预置键。

CloudWatch Logs 有一个真实坑：必须先建日志流再写日志，否则真实报错：

aws logs create-log-group --log-group-name /app/demo
aws logs put-log-events --log-group-name /app/demo --log-stream-name s1 --log-events timestamp=$(date +%s000),message="first line"

实测报错（逐行照抄）：

aws: [ERROR]: An error occurred (ResourceNotFoundException) when calling the PutLogEvents operation: The specified log stream does not exist: s1

按正确顺序补齐后（create-log-stream → put-log-events → get-log-events）：

39c553f7-a1d4-42f6-b81c-350eedde88f8
1792890755000	first line

EventBridge 定时规则：

aws events put-rule --name nightly --schedule-expression "rate(1 day)"
aws events list-rules --query "Rules[].[Name,ScheduleExpression,State]" --output table

实测输出（逐行照抄；注意 put-rule --query Arn 返回 None，取响应字段要用 list-rules/describe-rule）：

None
---------------------------------------
|              ListRules              |
+---------+---------------+-----------+
|  nightly|  rate(1 day)  |  ENABLED  |
+---------+---------------+-----------+

16.9 多账号资源隔离（12 位 AccessKey 实测）

用不同长度的 12 位 Access Key 模拟两个账号，同名队列互不干扰：

AWS_ACCESS_KEY_ID=111111111111 aws sqs create-queue --queue-name orders --query QueueUrl --output text
AWS_ACCESS_KEY_ID=222222222222 aws sqs create-queue --queue-name orders --query QueueUrl --output text
AWS_ACCESS_KEY_ID=111111111111 aws sqs list-queues --query QueueUrls --output text
AWS_ACCESS_KEY_ID=222222222222 aws sqs list-queues --query QueueUrls --output text

实测输出（逐行照抄）：

http://localhost:4566/111111111111/orders
http://localhost:4566/222222222222/orders
http://localhost:4566/111111111111/orders
http://localhost:4566/222222222222/orders

QueueUrl 的账号段随 Access Key 变化，list-queues 各自只能看到自己账号的队列——多租户测试用例可直接编排。

16.10 Lambda 真实执行（含报错修复全记录）

创建函数（真实拉取 python3.12 运行时，首次需数秒）：

cd /root/lambda-demo
zip -q function.zip handler.py
aws lambda create-function --function-name demo-fn --runtime python3.12 \
  --handler handler.handler --role arn:aws:iam::000000000000:role/lambda-demo \
  --zip-file fileb://function.zip --query FunctionName --output text

实测输出 demo-fn。

第一次调用——故意把 handler 写坏（少了右括号）：

aws lambda invoke --function-name demo-fn \
  --cli-binary-format raw-in-base64-out --payload '{"name": "floci"}' /tmp/out.json

实测输出：

{
    "StatusCode": 200,
    "FunctionError": "Unhandled",
    "ExecutedVersion": "$LATEST"
}

/tmp/out.json 内容（逐行照抄）——这是真实 Python 运行时的语法错误定位，不是模拟器编的：

{"errorMessage": "Syntax error in module 'handler': '{' was never closed (handler.py, line 3)", "errorType": "Runtime.UserCodeSyntaxError", "requestId": "", "stackTrace": ["  File \"/var/task/handler.py\" Line 3\n        return {\"statusCode\": 200, \"body\": \"hello \" + name + \" from lambda\"\n"]}

修复 handler 后更新并重调：

aws lambda update-function-code --function-name demo-fn --zip-file fileb://function.zip --query LastModified --output text
aws lambda invoke --function-name demo-fn \
  --cli-binary-format raw-in-base64-out --payload '{"name": "floci"}' /tmp/out2.json
cat /tmp/out2.json

实测输出（逐行照抄）：

2026-10-25T01:11:42.889+0000
{
    "StatusCode": 200,
    "ExecutedVersion": "$LATEST"
}
{"statusCode": 200, "body": "hello floci from lambda"}

结论：Lambda 是真实执行——代码错就报真实 traceback，对了就返回真实业务 JSON。S3 事件触发同样可用（put-bucket-notification-configuration 指向函数 ARN，实测返回结构体含 LambdaFunctionConfigurations）。前提：宿主已挂载 Docker socket（缺 socket 时函数能注册但不执行，config validate 会提示，见部署篇 4.3）。

16.11 EC2 真实实例

aws ec2 run-instances --image-id ami-12345678 --instance-type t3.micro --count 1 \
  --query "Instances[0].[InstanceId,InstanceType,State.Name,PrivateIpAddress]" --output text
sleep 8
aws ec2 describe-instances --query "Reservations[].Instances[].[InstanceId,InstanceType,State.Name,PrivateIpAddress]" --output table

实测输出（逐行照抄）：

i-ddd7fc50a32d6ff45	t3.micro	pending	172.31.32.10
----------------------------------------------------------------
|                       DescribeInstances                      |
+----------------------+-----------+----------+----------------+
|  i-ddd7fc50a32d6ff45 |  t3.micro |  running |  172.31.32.10  |
+----------------------+-----------+----------------+

run-instances 会创建真实运行的实例进程（约 8 秒从 pending 到 running），分配 172.31.x.x 私网地址；配套 IMDS 元数据服务监听 9169 端口。镜像 ID 可用任意 ami-* 占位——实例内容与 AMI 无关，测的是生命周期编排。

16.12 ElastiCache（真实引擎直连）

aws elasticache create-cache-cluster --cache-cluster-id demo-cache \
  --engine redis --cache-node-type cache.t3.micro --num-cache-nodes 1
sleep 12
aws elasticache describe-cache-clusters --show-cache-node-info \
  --query "CacheClusters[].[CacheClusterId,CacheClusterStatus,Engine,EngineVersion]" --output text

实测输出：

demo-cache	available	redis	7.2

随后用原生客户端直连真实引擎（宿主需映射 6379-6399 端口池，见部署篇 4.4）：

redis-cli -h 127.0.0.1 -p 6379 PING
redis-cli -h 127.0.0.1 -p 6379 SET floci:key "hello"
redis-cli -h 127.0.0.1 -p 6379 GET floci:key

实测输出（逐行照抄）：

PONG
OK
"hello"

16.13 区域硬隔离对拍

aws s3 mb s3://region-test                          # us-east-1
AWS_DEFAULT_REGION=cn-north-1 aws s3 ls             # 空
AWS_DEFAULT_REGION=cn-north-1 aws s3 mb s3://region-test   # 成功

实测结论：区域之间完全隔离，同名桶可在不同区域共存（细节见配置篇第五章）。

十七、CI 流水线标准用法

把上述命令串成一套完整的 CI 冒烟流程：

floci start --detach && floci wait          # 异步拉起 + 等就绪
eval "$(floci env)"
pytest tests/                                # 业务断言打 localhost:4566
floci reset --yes                            # 用例间重置
floci stop                                   # 收尾

内存紧张或不需全量服务面时，把第一行换成 floci start --detach --services=s3,dynamodb,sqs,lambda。

十八、排障实录汇总

floci start 报 Cannot connect to the Docker daemon：引擎未启动，systemctl start docker 后重跑（回显见第四章）；
floci reset 拒绝执行：需 --yes 确认（回显见第十一章）；
floci snapshot 报 Snapshot API not available on this server version：v2.3.0 未开放快照接口，用 persistent + reset 替代（回显见第十五章）；
PutLogEvents 报 ResourceNotFoundException：先 create-log-stream 再写日志（见 16.8）；
Lambda 函数创建成功但 invoke 无执行：宿主未挂载 Docker socket，真实运行时无法拉起；floci config validate 能查出；
floci status 退出码为 1：停止态下命令"成功返回状态但进程退出码为 1"，Shell 脚本判断别用 $? 判空，要匹配输出里的 Reachable（见第五章）；
安装脚本 403/404：受限网络下 install.sh 解析最新版本失败会重试 4 次后报 could not reach GitHub to determine the latest version，官方提示可 FLOCI_CLI_VERSION=<tag> 钉版本重试（实测钉 v0.4.0 时发布资产名 404，属该版本资产命名问题，走代理下载或手动放置二进制均可）。

十九、系列导航

选型与架构：《floci v2.3.0 介绍与选型指南》（定位、真实执行模型与 LocalStack/Moto 量化对比）
部署：《floci v2.3.0 Docker Compose 部署指南》（两条部署路径、持久化实测与排障）
配置：《floci v2.3.0 配置参数详解》（FLOCI_* 全参数表与生效方式实测）