🧭 核心概念与定位

floci-oci 是 Floci 模拟器家族中针对 OCI 的成员（类似于 AWS 的 LocalStack）。它通过模拟 OCI 的线协议（wire protocol），让你现有的 OCI 工具（SDK、CLI、Terraform）可以无缝指向本地端点 http://localhost:4599 进行开发和测试。

核心优势：

  • 免费且本地化：无需 Oracle Cloud 账户、上传 API 密钥或付费功能限制。
  • 即用即走：通过 docker compose up 即可快速启动。
  • 工具链兼容：与官方 OCI SDK（Java、Python、Go）、OCI CLI、Terraform/OpenTofu 提供商兼容。
  • 快速且轻量：基于 Quarkus 构建，启动快，适合 CI 环境。
  • 可配置持久化：支持内存、持久化、混合和预写日志等多种存储模式。

重要说明：floci-oci 并不实现 OCI 的全部服务，而是专注于常用核心服务（如对象存储、身份、队列、Vault、函数、OKE）。对于未实现的服务或高级功能，它会返回模拟响应或占位符，以保证工具的基本操作不会中断。

📦 部署与启动

方式一：Docker（推荐）

这是最快捷的方式。创建一个 compose.yaml 文件：

1
2
3
4
5
services:
  floci-oci:
    image: floci/floci-oci:latest
    ports:
      - "4599:4599"

然后启动：

1
docker compose up

验证服务是否正常运行：

1
curl http://localhost:4599/_floci-oci/health

方式二：从源码构建

需要 JDK 25。

1
2
3
4
5
6
# 开发模式（自动重载）
./mvnw quarkus:dev

# 或构建原生镜像并运行
./mvnw clean package -DskipTests
java -jar target/quarkus-app/quarkus-run.jar

🚀 使用指南

启动后，你可以像使用真实 OCI 一样使用你的工具，只需将端点指向 http://localhost:4599。

1. 使用 OCI CLI

创建一个一次性配置文件，然后执行命令：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 生成一个临时密钥（任何密钥都可以，floci-oci 只解析签名，不验证）
mkdir -p ~/.oci && openssl genrsa -out ~/.oci/floci_key.pem 2048

# 创建 CLI 配置文件
cat >> ~/.oci/config <<'EOF'
[FLOCI]
user=ocid1.user.oc1..flocilocaluser0000000000000000000000000000000000000000000000
fingerprint=aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99
tenancy=ocid1.tenancy.oc1..flocilocaltenancy0000000000000000000000000000000000000000
region=us-ashburn-1
key_file=~/.oci/floci_key.pem
EOF

# 使用 --endpoint 参数指向本地模拟器
oci --profile FLOCI os ns get --endpoint http://localhost:4599
oci --profile FLOCI os bucket create --endpoint http://localhost:4599 \
  --compartment-id ocid1.tenancy.oc1..flocilocaltenancy... \
  --namespace floci-local --name my-bucket

2. 使用 Python SDK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import oci

config = {
    "user": "ocid1.user.oc1..anyuser",
    "fingerprint": "aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99",
    "tenancy": "ocid1.tenancy.oc1..flocilocaltenancy...",
    "region": "us-ashburn-1",
    "key_file": "~/.oci/floci_key.pem",  # 任意生成的密钥
}

client = oci.object_storage.ObjectStorageClient(
    config, service_endpoint="http://localhost:4599")

namespace = client.get_namespace().data
client.put_object(namespace, "my-bucket", "hello.txt", b"hello from floci-oci")
print(client.get_object(namespace, "my-bucket", "hello.txt").data.content)

3. 使用 Terraform

通过环境变量或提供者配置中的 client_host_overrides 来覆盖端点。

1
export TF_VAR_CLIENT_HOST_OVERRIDES="oci_identity.IdentityClient=http://localhost:4599;oci_object_storage.ObjectStorageClient=http://localhost:4599"

然后在 Terraform 配置中使用标准的 oracle/oci 提供者即可。

⚙️ 高级配置

1. 持久化数据

默认数据在内存中，容器重启后丢失。可以通过环境变量启用持久化：

1
2
3
4
5
environment:
  - FLOCI_OCI_STORAGE_MODE=persistent
  - FLOCI_OCI_STORAGE_PERSISTENT_PATH=/data
volumes:
  - ./floci-data:/data

2. 启用签名验证（可选）

生产环境建议开启，以模拟真实 OCI 的认证行为：

1
2
environment:
  - FLOCI_OCI_AUTH_REQUIRE_SIGNATURE=true

3. 多容器网络

当你的应用在另一个容器中运行时，需要设置 FLOCI_OCI_HOSTNAME 为 floci-oci 的服务名，以便返回正确的内部 URL。

1
2
3
4
5
6
7
8
services:
  floci-oci:
    image: floci/floci-oci:latest
    environment:
      - FLOCI_OCI_HOSTNAME=floci-oci
  my-app:
    depends_on:
      - floci-oci

📋 支持的服务概览

类别 服务 说明
身份 (Identity) 用户、组、策略、区域、租户 支持基本的 CRUD 和列表操作
对象存储 命名空间、存储桶、对象 支持上传、下载、列出、复制、分段上传、预认证请求
消息队列 队列、流 支持可见性超时、死信队列、分区日志和游标
安全 Vault、KMS、密钥 真实的 AES-GCM/RSA/ECDSA 加密操作（在 Java 中实现）
无服务器 函数 (Functions) 通过 Fn Project 侧车容器真实运行你的函数镜像
Kubernetes OKE 容器引擎 通过 k3s 侧车容器真实启动本地 K8s 集群

注意：启用 Functions 和 OKE 的真实模式需要挂载 Docker 套接字 (-v /var/run/docker.sock:/var/run/docker.sock)。若不需要，可设置 FLOCI_OCI_SERVICES_FUNCTIONS_MOCK=true 跳过。

❓ 常见问题与限制

  • 没有官方 OCI 模拟器：floci-oci 填补了这一空白，但不保证 100% 与真实 OCI 行为一致。
  • 暂未实现的服务：身份域、API 密钥、对象版本控制、生命周期策略、复制、S3 兼容 API、流池的 Kafka 设置等。使用这些功能时，模拟器可能返回占位符或错误。
  • 签名验证：默认不验证请求签名。如需更真实的测试，可启用 FLOCI_OCI_AUTH_REQUIRE_SIGNATURE=true，但仍需配置有效的密钥格式。

总结

floci-oci 提供了一个极其轻量、便捷的本地 OCI 开发环境。对于开发者，强烈推荐通过 Docker 快速启动，并利用其提供的 SDK/CLI/Terraform 示例进行集成测试。它的核心价值在于打破对真实云环境的依赖，加速 OCI 应用的开发和 CI 流程。使用时，请关注其支持的服务列表，对于尚未实现的部分，可将其视为“模拟桩”以保持工具链的完整运行。如果你需要 Functions 或 OKE 的真实运行环境，记得挂载 Docker 套接字。