floci v2.3.0 配置参数详解
逐项梳理 floci v2.3.0 全部 FLOCI_* 环境变量与默认值，持久化/多区域/SigV4 签名校验/SSM 历史上限等关键行为全量实测，并沉淀 SQS 端点策略未生效等排障实录。
floci v2.3.0 配置参数详解
目标：逐项梳理 floci v2.3.0 的全部配置参数（
FLOCI_*环境变量单一形态），讲清全局、存储、区域、认证、Web 控制台与各服务行为参数的默认值与实测效果，并对参数生效方式、持久化与内存态差异、SigV4 签名校验、SSM 参数历史上限、SQS 端点策略等关键行为做全量实测。本文全部命令与回显已在 Ubuntu 22.04 LTS + Docker Engine 29.1.3 环境、floci v2.3.0（floci CLI 0.4.0）实测通过（2026-10-25）；部署过程见 《floci v2.3.0 Docker Compose 部署指南》。
一、环境信息
- 操作系统：Ubuntu 22.04 LTS（x86_64），Docker Engine 29.1.3，Compose v2.40.3
- floci 版本：v2.3.0；floci CLI：0.4.0；Web 控制台：floci/floci-ui 0.7.0
- 部署形态：按 《floci v2.3.0 Docker Compose 部署指南》第四章 Compose 部署，
FLOCI_STORAGE_MODE: persistent、服务端口 4566 - 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'） - 说明：文中「实测」指在上述环境逐条执行并记录回显；「官方文档」指 floci.io 的 Environment Variables Reference（2026-10-25 版本）
二、参数体系总览
floci 只通过环境变量配置——官方文档原话："Floci is configured exclusively through environment variables. Every option below maps directly to a FLOCI_* variable — no YAML file is needed when running the published image."（无配置文件、无命令行旗标两种形态，这与很多组件的多形态配置不同）。
参数分三组：
- 全局参数（
FLOCI_BASE_URL/FLOCI_HOSTNAME/FLOCI_DEFAULT_REGION/FLOCI_REGIONS/FLOCI_LOG_LEVEL）：控制端点、区域与日志； - 存储参数（
FLOCI_STORAGE_MODE/FLOCI_STORAGE_PERSISTENT_PATH）：决定状态在内存还是落盘，是唯一影响数据安全的参数组； - 服务行为参数（
FLOCI_SERVICES_*，40 余项）与认证参数（FLOCI_AUTH_*）：按服务开关、调阈值、改端点形态。
改动方式：Compose 场景改 environment: 段后 docker compose up -d 重建生效；CLI 场景用 floci start --env-file <file> 注入。没有热加载——所有参数都要求进程重启。
三、全局参数表
| 参数 | 默认值 | 说明与实测 |
|---|---|---|
FLOCI_BASE_URL | http://localhost:4566 | 写入响应体的基础 URL（如 SQS 的 QueueUrl 字段）。实测改为 http://floci:4566 后，aws sqs create-queue 返回的 QueueUrl 变为 http://floci:4566/000000000000/… |
FLOCI_HOSTNAME | （空） | 仅覆盖 FLOCI_BASE_URL 的主机名部分；Compose 内服务互访时设为服务名。实测 Compose 里设 FLOCI_HOSTNAME: floci 后 QueueUrl 主机为 floci:4566；移除该变量重建后回到 localhost:4566 |
FLOCI_DEFAULT_REGION | us-east-1 | 默认区域，决定未显式指定区域时的资源归属。实测设 cn-north-1 后，aws s3 ls 与 dynamodb list-tables 只看到该区域资源 |
FLOCI_REGIONS | 单区域 | 预置多区域列表（逗号分隔），配合上面的默认区域使用；多区域硬隔离行为见第五章 |
FLOCI_LOG_LEVEL | info | 日志级别（debug/info/warn/error），影响 floci logs 的输出粒度 |
四、存储参数：内存态与持久化（核心）
| 参数 | 默认值 | 取值 | 说明 |
|---|---|---|---|
FLOCI_STORAGE_MODE | ephemeral | ephemeral / persistent | 内存态 / 持久化态 |
FLOCI_STORAGE_PERSISTENT_PATH | /app/data | 任意挂载路径 | persistent 模式的落盘目录，必须配卷挂载 |
两种模式的实测差异（同一组操作：建桶 persist-bucket、建表 persist-tbl、上传对象，然后停掉再拉起）：
| 验证项 | ephemeral（默认） | persistent（实测配置） |
|---|---|---|
停止后 aws s3 ls | 空（资源全部丢失） | 2026-10-25 00:47:04 persist-bucket |
停止后 dynamodb list-tables | 空 | "TableNames": ["persist-tbl"] |
| 对象内容读回 | 失败 | 成功（aws s3 cp s3://… - 读回原文） |
| 区域设置本身 | 回到默认 | 也被持久化（实测重启后仍是 cn-north-1，需显式改回） |
官方存储文档（2026-10-25）另列出
hybrid（内存 + 定期落盘快照，可配FLOCI_STORAGE_HYBRID_*系列）与wal（预写日志，可配FLOCI_STORAGE_WAL_*系列）两种模式；本次实测覆盖默认ephemeral与persistent，hybrid/wal参数以官方 Environment Variables Reference 为准。
三条实操纪律：
- 只挂卷不开 persistent 等于没挂——实测该场景下
data/目录始终为空（模拟器状态留在内存）；floci config validate能在部署前查出这个组合并给出警告； - persistent 模式下连区域设置都会被持久化：实测把
FLOCI_DEFAULT_REGION临时改成cn-north-1跑完测试后重启，aws s3 ls仍为空列表（资源在cn-north-1），把环境变量改回us-east-1重建才恢复——排查"重启后资源找不到了"先看区域； - 快照（
floci snapshot）与持久化是两条独立通道：但注意 v2.3.0 服务端尚未开放快照接口（实测floci snapshot save报Snapshot API not available on this server version，详见 CLI 篇第十五章），当前状态回滚靠floci reset --yes。
五、区域参数与硬隔离实测
FLOCI_DEFAULT_REGION / FLOCI_REGIONS 组合出多区域环境，且区域之间是硬隔离（非仅前缀区分）。实测两个证据：
- 在
us-east-1建桶region-test后，导出AWS_DEFAULT_REGION=cn-north-1再aws s3 ls，输出为空——该区域看不到 us-east-1 的资源； - 在
us-east-1与cn-north-1分别aws s3 mb s3://shared-name都成功——同名桶可在两个区域各自存在，互不冲突。
对应的 ARN 也带区域（如 DynamoDB 表 ARN arn:aws:dynamodb:cn-north-1:000000000000:table/cn-tbl），依赖区域硬编码的测试脚本要注意切换区域后的资源可见性。
六、认证与签名校验参数
| 参数 | 默认值 | 说明 |
|---|---|---|
FLOCI_AUTH_VALIDATE_SIGNATURES | false | 是否校验请求的 SigV4 签名正确性 |
官方语义：开启后"verify the SigV4 signature of every signed request without evaluating policies"——校验"带签名的请求"的签名对不对，但不强制所有请求必须带签名。实测三组行为（设为 true 后）：
| 请求形态 | 实测结果 |
|---|---|
AWS CLI（SigV4 正确签名）aws s3 cp 上传 | 成功，aws s3 ls 可见对象 |
curl 直接 PUT（完全无签名头） | 200 成功（匿名请求按设计放行，不校验也不拒绝） |
curl 带伪造 SigV4 头（错误 Signature） | 403 拒绝，回显 XML（逐行照抄）：<Error><Code>AccessDenied</Code><Message>AWS authentication requires a valid Date or x-amz-date header</Message></Error> |
结论：该参数用于拦截签名写错的客户端（排查 SDK 签名配置问题时打开很有用），不是访问控制开关——floci 本身就不做账号级鉴权，任何 Access Key 都被接受。
七、Web 控制台参数
| 参数 | 默认值 | 说明与实测 |
|---|---|---|
FLOCI_SERVICES_UI_ENABLED | true | 实测设为 false 重建后，GET /_floci/ui 返回 404，不再拉起控制台 |
FLOCI_SERVICES_UI_IMAGE | floci/floci-ui:0.7.0 | 控制台镜像版本，可固定升级节奏 |
FLOCI_SERVICES_UI_SIDECAR_PORT | 4500 | 控制台宿主端口；被占用时改这个而不是 4566 |
FLOCI_SERVICES_UI_SESSION_TTL | 1h | 控制台会话有效期 |
控制台为按需拉起：首次 GET http://<服务器>:4566/_floci/ui 才启动，发布到 FLOCI_SERVICES_UI_SIDECAR_PORT。健康检查 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"]}
八、服务行为参数精选表
以下为最常用的服务级参数（全部来自官方 Environment Variables Reference，2026-10-25；标注「已实测」的条目在本环境验证过效果）：
| 参数 | 默认值 | 作用 | 实测结论 |
|---|---|---|---|
FLOCI_SERVICES_S3_LIST_OBJECTS_V1 | false | ListObjectsV2 之外再启用 V1 接口 | 官方文档 |
FLOCI_SERVICES_S3_SIGNED_URL_TTL | 1h | S3 预签名 URL 有效期 | 官方文档 |
FLOCI_SERVICES_S3_ENABLE_PRESIGNED_POST | false | 启用预签名 POST 表单上传 | 官方文档 |
FLOCI_SERVICES_S3_FORCE_PATH_STYLE | true | 强制路径风格端点（本地模拟器应保持 true） | 官方文档 |
FLOCI_SERVICES_SQS_ENDPOINT_STRATEGY | floci | SQS QueueUrl 主机名策略（floci 用 BASE_URL；aws 回显请求所用的主机） | v2.3.0 实测未生效：设为 aws 后无启动告警，但 GetQueueUrl/ListQueues 仍返回 http://localhost:4566/… 形态；已知行为，不要依赖 |
FLOCI_SERVICES_SSM_MAX_PARAMETER_HISTORY | 1000 | 每个参数保留的历史版本数 | 已实测：设为 3 后连续写入 4 个版本，get-parameter-history 只返回 [2, 3, 4]，v1 被淘汰 |
FLOCI_SERVICES_SSM_SECURE_DEFAULTS | no-encryption | SecureString 是否加密（no-encryption/kms） | 官方文档 |
FLOCI_SERVICES_LAMBDA_ARCHITECTURES | x86_64,arm64 | Lambda 支持的 CPU 架构 | 官方文档 |
FLOCI_SERVICES_LAMBDA_MAX_PAYLOAD_MB | 6 | Lambda 载荷上限（与 AWS 一致） | 官方文档 |
FLOCI_SERVICES_LAMBDA_ENABLE_SNAPSTART | true | SnapStart 兼容行为 | 官方文档 |
FLOCI_SERVICES_DYNAMODB_TTL_SWEEPER_ENABLED | true | TTL 过期项清理（实测日志可见 DynamoDB TTL sweeper scheduled (60s interval)） | 已实测 |
FLOCI_SERVICES_DYNAMODB_TTL_SWEEPER_INTERVAL | 60s | 清理扫描间隔 | 官方文档 |
FLOCI_SERVICES_EVENTBRIDGE_SCHEDULER_ENABLED | true | 定时调度器（实测日志 Scheduler dispatcher started (tick every 10s)） | 已实测 |
FLOCI_SERVICES_EVENTBRIDGE_MAX_TARGETS | 5 | 单规则目标数上限 | 官方文档 |
FLOCI_SERVICES_SECRET_ROTATION_ENABLED | true | Secrets Manager 轮换调度（实测日志 SecretRotationScheduler started (tick every 60s)） | 已实测 |
FLOCI_SERVICES_MQ_BROKERS_ENABLED | true | Amazon MQ 代理开关 | 官方文档 |
FLOCI_SERVICES_ELASTICACHE_LOCAL_PORTS | 6379-6399 | ElastiCache 端口池（宿主需映射同段端口） | 已实测：建集群后宿主 6379 可 redis-cli 直连 |
FLOCI_SERVICES_ELASTICACHE_REDIS_VERSION | 7.2 | Redis 兼容引擎版本 | 官方文档 |
FLOCI_SERVICES_MYSQL_PORT_RANGE | 3306-3399 | RDS MySQL 端口池 | 官方文档 |
FLOCI_SERVICES_MYSQL_VERSION | 8.0.36 | MySQL 引擎版本 | 官方文档 |
FLOCI_SERVICES_POSTGRES_PORT_RANGE | 5432-5599 | RDS PostgreSQL 端口池 | 官方文档 |
FLOCI_SERVICES_POSTGRES_VERSION | 15.6 | PostgreSQL 引擎版本 | 官方文档 |
FLOCI_SERVICES_ORACLE_IMAGE | gvenzl/oracle-free:23.4-slim | Oracle Free 引擎镜像 | 官方文档 |
FLOCI_SERVICES_ORACLE_MEMORY | 2g | Oracle 引擎内存上限 | 官方文档 |
FLOCI_SERVICES_MSK_BROKER_IMAGE | apache/kafka:3.7.0 | MSK 真实 Kafka 引擎镜像 | 官方文档 |
FLOCI_SERVICES_MSK_NUM_BROKERS | 1 | MSK broker 数 | 官方文档 |
FLOCI_SERVICES_KINESIS_MAX_SHARDS | 10 | Kinesis 分片上限 | 官方文档 |
FLOCI_SERVICES_SES_SMTP_ENABLED | true | SES 本地 SMTP 服务（实测日志可见 SMTP 监听） | 已实测 |
FLOCI_SERVICES_SES_SMTP_PORT | 2525 | SES SMTP 端口 | 官方文档 |
FLOCI_SERVICES_DB_MAX_TOTAL_INSTANCES | 30 | 数据面数据库实例总数上限 | 官方文档 |
FLOCI_SERVICES_DB_INSTANCE_RETENTION | 1h | 数据库实例空闲保留时长 | 官方文档 |
FLOCI_SERVICES_CLOUDWATCH_LOG_RETENTION | 30d | 日志保留期 | 官方文档 |
未覆盖的长尾服务参数（MediaConvert/Polly/Transcribe/Rekognition/QuickSight/Timestream/Neptune/DocumentDB/OpenSearch/KeySpaces/Transfer SFTP 等）命名规律一致：FLOCI_SERVICES_<服务>_<项>，查官方 Environment Variables Reference 即可，行为开关默认大多为 true（启用）。
九、参数生效方式实测
环境变量没有热加载，两种生效路径：
- Compose 场景：改
environment:后docker compose up -d（会重建服务进程）； - CLI 场景：把参数写进 env 文件，
floci start --env-file <file>（floci start --help实测可见--env-file选项）。
实测生效链路（SSM 历史上限为例）：compose 加 FLOCI_SERVICES_SSM_MAX_PARAMETER_HISTORY: 3 → docker compose up -d 重建 → 连续 4 次写同名参数 → aws ssm get-parameter-history --name /hist/demo --query "Parameters[].Version" --output text 返回 2 3 4——第 1 版已被按上限淘汰，参数确定生效。
十、排障实录
1. 设了 FLOCI_SERVICES_SQS_ENDPOINT_STRATEGY=aws 但 QueueUrl 没变。
现象：实测设为 aws 后 aws sqs get-queue-url 仍返回 http://localhost:4566/000000000000/…，且启动日志无任何告警。结论：该参数在 v2.3.0 未实现或默认未启用（官方文档描述了 aws 策略语义，但实测无效）。处理：依赖 QueueUrl 的脚本统一走 FLOCI_BASE_URL/FLOCI_HOSTNAME 控制主机名；升级新版本后再复测。
2. 重启后 aws s3 ls 变空，以为持久化失效。
实测原因：persistent 模式把 FLOCI_DEFAULT_REGION=cn-north-1 也持久化了，当前会话的 AWS_DEFAULT_REGION 却还是 us-east-1，资源在另一个区域。处理：区域与会话导出保持一致再查；多区域测试后务必把 FLOCI_DEFAULT_REGION 改回主区域重建。
3. 部署警告 "A volume is mounted at /app/data but FLOCI_STORAGE_MODE is not 'persistent'"。
原因与处理见第四章纪律 1；用 floci config validate --file <compose> 可在 up 之前发现（实测输出 1 error(s) found.、退出码 1）。
4. 控制台端口 4500 被占。
现象：首次访问 /_floci/ui 后控制台起不来。处理：改 FLOCI_SERVICES_UI_SIDECAR_PORT 为空闲端口重建；或临时不要控制台就设 FLOCI_SERVICES_UI_ENABLED=false（实测关闭后 /_floci/ui 返回 404）。
5. 伪签名请求 403 但匿名请求却成功。
这不是 bug：FLOCI_AUTH_VALIDATE_SIGNATURES=true 的语义是"校验带签名请求的签名正确性"，匿名无签名请求不在校验范围（见第六章三组实测）。要限制来源请用网络层（防火墙/内网绑定），不要指望这个参数。
十一、系列导航
- 选型与架构：《floci v2.3.0 介绍与选型指南》（定位、真实执行模型与 LocalStack/Moto 量化对比）
- 部署：《floci v2.3.0 Docker Compose 部署指南》（两条部署路径、持久化实测与排障）
- CLI 实操：《floci v2.3.0 常用 CLI 命令详解》（floci CLI 全子命令 + AWS CLI 对拍 S3/DynamoDB/Lambda/ElastiCache 实测回显）