floci

Floci

Floci 是一系列本地云模拟器，使用真实的云线协议。 floci 命令（floci-cli）负责管理它们的生命周期；原生工具（aws、gcloud、 az、oci、SDK、Terraform）则通过模拟器执行资源操作。floci-cli 本身不会 创建云资源。

云	模拟器	CLI 命令树	端口	默认容器	参考文档
AWS	floci	floci aws	4566	floci	references/aws.md
GCP	floci-gcp	floci gcp	4588	floci-gcp	references/gcp.md
Azure	floci-az	floci az	4577	floci-az	references/azure.md
OCI	floci-oci	floci oci	4599	floci-oci	references/oci.md

本技能中的所有路径（references/、scripts/、assets/）均相对于此文件所在目录， 而不是用户的工作目录。

何时阅读哪些内容：

• 在执行该云的第一个资源命令之前，先阅读该云的参考文档。
• 在编写本次会话中尚未使用过的服务的相关代码之前，以及遇到似乎不受支持的操作时，阅读 references/docs.md。该文档会告诉你如何获取已发布文档中的正确页面。
• 当用户需要 docker run、docker-compose.yml 或与模拟器通信的应用容器时，阅读 references/docker.md。
• 在运行多个实例、共用 Docker 主机或清理容器时，阅读 references/namespaces.md。
• 对于流水线和 Testcontainers，阅读 references/ci.md。
• 出现任何故障时，阅读 references/troubleshooting.md。

前置条件（先检查）

command -v floci && floci version     # floci-cli present?
docker info >/dev/null && echo ok     # Docker (or Podman via DOCKER_HOST) reachable?

如果缺少 floci，请先征求用户同意，再安装软件，然后运行：

scripts/install-floci.sh                   # brew if available, else official script into ~/.local/bin
scripts/install-floci.sh --version 0.4.0   # pin a version (uses the install script)

• Windows：iwr https://floci.io/install.ps1 | iex（仅针对当前用户，无需管理员权限）。此处的辅助脚本使用 bash；在 Windows 上直接运行它们封装的 floci 命令。
• 如果该平台没有原生二进制文件：从最新版本下载 floci.jar 并运行 java -jar floci.jar（需要 Java 25+）。
• 未经询问，不要使用 sudo 或编辑 shell 配置文件（~/.bashrc、~/.zshrc）；如果安装目录不在 PATH 中，仅为当前会话导出该目录。
• 更新：floci update --check 在已是最新版本时以 0 退出，存在更新时以 1 退出，检查本身失败时以 2 退出。仅在退出码为 1 时运行 floci update（通过 Homebrew 安装的版本运行： brew upgrade floci）。
• 如果用户完全不想使用 CLI：模拟器是普通容器镜像，参见 references/docker.md。

floci-cli 不会安装 Docker。如果缺少守护进程，请告知用户；不要自行安装 Docker。仅当用户需要使用相应云时，才需要原生云 CLI（aws、gcloud、az、oci）；可以建议安装，但不要在未经允许的情况下安装。

硬性规则

1. 绝不连接真实云服务。 只能使用模拟器接受的虚假凭据 （AWS 使用 test/test，以及 floci az setup 和 floci oci setup 创建的开发身份）。 绝不读取、导出或重复使用用户的真实云凭据或配置文件。
2. 每次执行会更改状态的命令前，都要验证端点。 端点必须指向模拟器 （localhost、127.0.0.1、localhost.floci.io 或 Compose 服务名称）。如果命令 可能连接到公有云（参见各参考文档中的「泄漏」部分），请停止并修复连接配置。
3. 始终明确指定树：使用 floci aws start，而不是 floci start。裸命令会遵循 floci config default-product，用户可能已更改该配置。
4. 使用 -o json 解析输出，绝不抓取文本输出。在脚本中使用 -q 静默输出。
5. 不要删除本次会话中由你之外的人创建的容器、卷或快照。 将任何清理操作限定在某个命名空间内（参见 namespaces.md），并先向用户确认。
6. 除非实例以 --persist <dir> 启动，或配置文件中设有 persistDir，否则状态都是临时的。 在已停止的容器上执行 start 和执行 restart 都会删除容器并创建新容器：restart 会保留设置（端口、镜像、服务、持久化目录、命名空间），但不会保留内存中的状态；在 Azure 上，新容器还会获得新的证书， 因此必须重新运行 floci az setup。在运行中的容器上执行 start 会失败。重新创建任何内容前都要说明这一点。
7. 绝不要给 env 添加 -q：它会抑制导出的内容本身。
8. 不要猜测模拟器支持哪些功能。 请检查 floci <tree> services -o json 和 已发布的文档（references/docs.md，不要凭记忆作答。
9. 使用配置文件时，先启动并等待，再运行 env。 在配置文件对应的容器运行之前， env 和 status 会回退到默认端口，并描述默认实例。请以 status -o json 中的 "state": "running" 为准，而不是 reachable。

生命周期（所有树均相同）

floci <tree> start --detach          # pull if needed, start, return immediately
floci <tree> wait --timeout 2m       # block until healthy (exit 0 = ready)
eval "$(floci <tree> env -o text)"   # export SDK/CLI wiring into this shell
# ... run aws / gcloud / az / oci / tests ...
floci <tree> stop --remove           # when done, only if you started it

即使配置文件设置了 output: json，-o text 也能确保导出的内容正确。在其他 shell 中： floci <tree> env --shell fish | source，或 floci <tree> env --shell powershell | Invoke-Expression。

也可以使用辅助工具：只有在容器不存在时才会启动容器，然后等待并打印 导出的内容：

exports="$(scripts/ensure-running.sh <aws|gcp|az|oci> [profile])" && eval "$exports"

保留这两个步骤：如果辅助工具失败，eval "$(...)" 一次性执行仍会成功， 后续命令便会在连接配置缺失或过时的情况下运行。当容器存在但已停止时，辅助工具会在不做任何 操作的情况下以状态码 3 退出，因为启动容器会替换它（规则 6）。请告知用户，并在用户同意后使用 FLOCI_REPLACE_STOPPED=1 重新运行。

使用原生 CLI 前，每个实例都需执行一次：

• Azure：floci az setup（信任模拟器证书、注册 az 云并登录）。
• OCI：floci oci setup（写入一次性密钥，并在 ~/.oci/config 中创建 [FLOCI] 配置文件）。

eval 只会影响当前 shell。如果每次工具调用都在全新 shell 中运行，请在每条命令前加上前缀： eval "$(floci aws env -o text)" && aws s3 ls。

示例适用于 bash。在 zsh（macOS 默认 shell）中，不加引号的变量不会拆分为多个词，因此 flags="--profile aws-b"; floci aws status $flags 会传入一个参数并失败。请直接写出各标志， 或使用数组：flags=(--profile aws-b) 和 "${flags[@]}"。

检查状态

需求	命令
是否正在运行且状态正常？	floci <tree> status -o json
启用了哪些服务？	floci <tree> services -o json（Azure：返回空列表，参见 azure.md）
CLI 和服务版本	floci <tree> version -o json（Azure：从 status -o json 中读取版本）
最近的服务日志	floci <tree> logs --tail 100 或 --since 5m
环境问题	floci <tree> doctor -o json（检查项数组，status 为 ok、warn 或 fail；执行 fix 前请参阅 troubleshooting.md）
生效配置	floci <tree> config show --profile <name>（只有在配置文件会产生命名空间时才会显示命名空间行）
所有实例	floci <tree> config profile list -o json（所有树共享配置文件；image 表示云平台）。另有 config profile show、edit 和 delete <name>
任意命令的标志	floci <tree> <command> --help

多个实例

实例对应一个配置文件：容器名称是其实例标识，端口必须唯一，其 Docker 资源命名空间会将其启动的容器与其他实例隔离。 对该实例的每条命令都传入相同的 --profile <name>。详情和命名空间派生规则见 references/namespaces.md。

floci aws config profile create aws-b --container floci-b --port 14566 --persist ~/.floci/data/aws-b
floci aws start --profile aws-b          # waits up to 30s; or --detach, then wait
eval "$(floci aws env -o text --profile aws-b)"

floci-cli 将自身文件保存在 ~/.floci 下（配置文件位于 ~/.floci/profiles/，每个实例的状态位于 ~/.floci/<product>/<container>/），因此实例数据也保存在此处，即 ~/.floci/data/<name>。

选择合适的集成方式

• 临时命令或开发服务器：使用上述 CLI 生命周期管理方式。
• 用户要求使用 docker run 或 Compose 文件，或者应用本身运行在容器中： 参见 references/docker.md。请从 assets/compose/ 中的模板开始，而不是凭记忆编写 YAML。
• 代码中的集成测试：在有相应模块时使用 Testcontainers 模块（AWS 支持 Java、Node、Python、Go 和 .NET；Azure 仅支持 Java；GCP 和 OCI 均不支持，参见 ci.md）。否则，请在测试开始前通过 CLI 或 Compose 启动模拟器。

遇到不支持的功能时

各服务的覆盖范围不同：有些是完整引擎，有些在进程内运行，有些则返回预设响应。针对某项服务编写代码前，请确认该服务已启用（floci <tree> services -o json），并阅读已发布文档中的对应页面（references/docs.md）。如果缺少某项操作，请明确说明，提出变通方法，并引导用户访问模拟器的问题跟踪页 （https://github.com/floci-io/<floci|floci-gcp|floci-az|floci-oci>/issues），而不是反复尝试不同变体。