floci

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Floci

Floci is a family of local cloud emulators that speak the real cloud wire protocols. The

floci

command (floci-cli) manages their lifecycle; the native tools (

aws

gcloud

az

oci

, SDKs, Terraform) do the resource work against the emulator. floci-cli never creates cloud resources itself.

Cloud	Emulator	CLI tree	Port	Default container	Reference
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

All paths in this skill (

references/

scripts/

assets/

) are relative to the directory that holds this file, not to the user's working directory.

When to read what:

The cloud's reference, before the first resource command for that cloud.
references/docs.md, before writing code against a service you have not used in this session, and whenever an operation looks unsupported. It tells you how to fetch the right page of the published documentation.
references/docker.md, when the user wants
```
docker run
```
, a
```
docker-compose.yml
```
, or an app container that talks to the emulator.
references/namespaces.md, when running more than one instance, sharing a Docker host, or cleaning up containers.
references/ci.md for pipelines and Testcontainers.
references/troubleshooting.md when anything fails.

Floci 是一组使用真实云端 wire protocol 的本地云模拟器。

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

此 skill 中的所有路径（

references/

、

scripts/

、

assets/

）均相对于存放此文件的目录，而不是用户当前的工作目录。

何时阅读哪些内容：

在为某个云端首次执行资源命令前，阅读该云端的参考文档。
references/docs.md：在针对本次会话中尚未使用过的服务编写代码前，以及每当某项操作看起来不受支持时阅读。其中说明了如何获取已发布文档中的正确页面。
references/docker.md：当用户需要
```
docker run
```
、
```
docker-compose.yml
```
，或需要与模拟器通信的应用容器时阅读。
references/namespaces.md：当需要运行多个实例、共享 Docker 主机或清理容器时阅读。
references/ci.md：用于流水线和 Testcontainers。
references/troubleshooting.md：当出现任何故障时阅读。

Prerequisites (check first)

先决条件（首先检查）

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

floci

is missing, ask the user before installing software, then run:

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
```
(per-user, no admin). The helper scripts here are bash; on Windows run the
```
floci
```
commands they wrap directly.
No native binary for the platform: download
```
floci.jar
```
from the latest release and run
```
java -jar floci.jar
```
(needs Java 25+).
Do not use
```
sudo
```
or edit shell profiles (
```
~/.bashrc
```
,
```
~/.zshrc
```
) without asking; if the install dir is not on
```
PATH
```
, export it for the current session only.
Updates:
```
floci update --check
```
exits 0 when up to date, 1 when an update exists and 2 when the check itself failed. Run
```
floci update
```
only on exit 1 (Homebrew installs:
```
brew upgrade floci
```
).
The user does not want the CLI at all: the emulators are plain container images, see references/docker.md.

floci-cli does not install Docker. If the daemon is missing, tell the user; do not install Docker yourself. The native cloud CLIs (

aws

gcloud

az

oci

) are only needed for the clouds the user works with; suggest installing them, do not install them unasked.

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 守护进程缺失，告知用户；不要自行安装 Docker。只有用户使用的云端才需要原生云 CLI（

aws

、

gcloud

、

az

、

oci

）；可以建议安装，但未经用户同意不要安装。

Hard rules

硬性规则

Never touch real cloud. Use only the fake credentials the emulators accept (
```
test
```
/
```
test
```
for AWS, the dev identities
```
floci az setup
```
and
```
floci oci setup
```
create). Never read, export or reuse the user's real cloud credentials or profiles.
Verify the endpoint before every mutating command. It must point at the emulator (
```
localhost
```
,
```
127.0.0.1
```
,
```
localhost.floci.io
```
, or a Compose service name). If a command might reach public cloud (see each reference's "leaks" section), stop and fix the wiring.
Always name the tree explicitly:
```
floci aws start
```
, not
```
floci start
```
. Bare commands follow
```
floci config default-product
```
, which the user may have changed.
Parse with
-o json
, never scrape text output. Use
```
-q
```
to silence noise in scripts.
Do not remove containers, volumes or snapshots you did not create in this session. Scope any cleanup to a namespace (see namespaces.md) and confirm with the user first.
State is ephemeral unless the instance was started with
```
--persist <dir>
```
or a profile with
```
persistDir
```
. Both
```
start
```
on a stopped container and
```
restart
```
remove the container and create a new one:
```
restart
```
keeps the settings (port, image, services, persist dir, namespace) but not in-memory state, and on Azure the new container has a new certificate, so
```
floci az setup
```
must be run again.
```
start
```
on a running container fails. Say so before recreating anything.
Never add
-q
to
env
: it suppresses the exports themselves.
Do not guess what an emulator supports. Check
```
floci <tree> services -o json
```
and the published docs (references/docs.md) instead of answering from memory.
With a profile, start and wait before
env
. Until the profile's container is running,
```
env
```
and
```
status
```
fall back to the default port and describe the default instance. Trust
```
"state": "running"
```
in
```
status -o json
```
, not
```
reachable
```
.

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

Lifecycle (same for every tree)

生命周期（每个产品树均相同）

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

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


`-o text` keeps the exports correct even when a profile sets `output: json`. In other shells:
`floci <tree> env --shell fish | source`, or
`floci <tree> env --shell powershell | Invoke-Expression`.

Or use the helper, which starts the container only when none exists, then waits and prints
the exports:

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

Keep the two steps:

eval "$(...)"

in one go succeeds even when the helper fails, and the commands after it would run with missing or stale wiring. The helper exits 3 without touching anything when the container exists but is stopped, because starting it replaces it (rule 6). Tell the user, and re-run with

FLOCI_REPLACE_STOPPED=1

once they agree.

One-time per instance, before using the native CLI:

Azure:
```
floci az setup
```
(trusts the emulator cert, registers an az cloud, logs in).
OCI:
```
floci oci setup
```
(writes a throwaway key and a
```
[FLOCI]
```
profile in
```
~/.oci/config
```
).

eval

only affects the current shell. If each tool call runs in a fresh shell, prefix every command:

eval "$(floci aws env -o text)" && aws s3 ls

The examples are written for bash. In zsh (the macOS default) an unquoted variable is not split into words, so

flags="--profile aws-b"; floci aws status $flags

passes one argument and fails. Write the flags out, or use an array:

flags=(--profile aws-b)

and

"${flags[@]}"

floci <tree> stop --remove # when done, only if you started it


`-o text` 即使在 profile 设置了 `output: json` 时，也能保持导出项正确。在其他 shell 中：
`floci <tree> env --shell fish | source`，或
`floci <tree> env --shell powershell | Invoke-Expression`。

也可以使用辅助脚本；它仅在容器不存在时启动容器，然后等待并打印导出项：

```sh
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 cloud 并登录）。
OCI：
```
floci oci setup
```
（在
```
~/.oci/config
```
中写入一次性密钥和
```
[FLOCI]
```
profile）。

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，或使用数组：

flags=(--profile aws-b)

和

"${flags[@]}"

。

Inspecting state

检查状态

Need	Command
Is it running and healthy?	`floci <tree> status -o json`
Which services are enabled?	`floci <tree> services -o json` (Azure: returns an empty list, see azure.md)
CLI and server versions	`floci <tree> version -o json` (Azure: read the version from `status -o json` )
Recent server logs	`floci <tree> logs --tail 100` or `--since 5m`
Environment problems	`floci <tree> doctor -o json` (an array of checks with `status` `ok` , `warn` or `fail` ; see troubleshooting.md before acting on a `fix` )
Effective config	`floci <tree> config show --profile <name>` (the namespace row appears only with a profile that yields one)
All instances	`floci <tree> config profile list -o json` (profiles are shared by all trees; `image` tells the cloud). Also `config profile show` , `edit` and `delete <name>`
Any command's flags	`floci <tree> <command> --help`

需求	命令
是否正在运行且健康？	`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>` （仅当 profile 产生一个 namespace 时，才会显示 namespace 行）
所有实例	`floci <tree> config profile list -o json` （profiles 由所有产品树共享； `image` 指示所属云端）。另可使用 `config profile show` 、 `edit` 和 `delete <name>`
任意命令的参数	`floci <tree> <command> --help`

Several instances

多个实例

An instance is a profile: its container name is its identity, its port must be unique, and its Docker resource namespace keeps the containers it launches apart from other instances. Pass the same

--profile <name>

to every command for that instance. Details and the namespace derivation rules are in 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 keeps its own files under

~/.floci

(profiles in

~/.floci/profiles/

, per-instance state in

~/.floci/<product>/<container>/

), so instance data goes there too, as

~/.floci/data/<name>

实例即一个 profile：其容器名称就是身份标识，端口必须唯一，Docker 资源 namespace 会将其启动的容器与其他实例隔离开来。

对实例的每条命令都传入相同的

--profile <name>

。详细信息和 namespace 派生规则见 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

下（profiles 位于

~/.floci/profiles/

，各实例状态位于

~/.floci/<product>/<container>/

），因此实例数据也保存在那里，即

~/.floci/data/<name>

。

Choosing the right integration

选择合适的集成方式

Ad-hoc commands or a dev server: the CLI lifecycle above.
The user asks for
docker run
or a Compose file, or the app itself runs in a container: references/docker.md. Start from the templates in
```
assets/compose/
```
instead of writing YAML from memory.
Integration tests in code: a Testcontainers module where one exists (AWS in Java, Node, Python, Go and .NET; Azure in Java only; none for GCP or OCI, see ci.md). Otherwise start the emulator with the CLI or Compose before the tests.

临时命令或开发服务器：使用上述 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 启动模拟器。

When something is not supported

不支持某项操作时

Coverage differs per service: some are full engines, some are in-process, some answer with canned responses. Before writing code against a service, check that it is enabled (

floci <tree> services -o json

) and read its page in the published docs (references/docs.md). If an operation is missing, say so plainly, suggest a workaround, and point the user to the emulator's issue tracker (

https://github.com/floci-io/<floci|floci-gcp|floci-az|floci-oci>/issues

) instead of retrying variations.

各服务的覆盖范围不同：有些是完整引擎，有些是进程内实现，有些则返回预置响应。在针对某项服务编写代码前，检查它是否已启用（

floci <tree> services -o json

）并阅读已发布文档中的对应页面（references/docs.md）。如果缺少某项操作，请明确说明，提出变通方案，并指向模拟器的 issue tracker（

https://github.com/floci-io/<floci|floci-gcp|floci-az|floci-oci>/issues

），而不是反复尝试各种变体。