Floci

Overview

Floci 係一套用嚟模擬多雲端 API 嘅自架（self-hosted）服務平台。佢特別適合喺 Oracle Cloud（OCI）上以 Docker Compose 方式部署，提供一個近似公有雲環境嘅本地端開發介面。Floci 同時支援 AWS、Azure 同 GCP 風格嘅 API 端點，令開發團隊可以喺唔使直接連接真正雲端帳戶嘅情況下，測試應用程式嘅雲端整合邏輯。

Floci 嘅核心設計理念係「一個介面，模擬三個雲端」。佢除咗有 floci 引擎去處理雲端 API 請求之外，仲有 floci-ui 提供圖像化控制台，方便使用者睇到而家系統嘅狀態、端點設定同儲存情況。由於 Floci 可以喺 Oracle Cloud 免費層（Always Free）上執行，所以好啱個人開發者或者小團隊用嚟做 CI/CD、自動化測試同技術驗證。

Floci 使用容器化方式運行，官方提供 floci/floci:latest 同 floci/floci-ui:latest 兩個 Docker 映像。部署時只需要將一個 Docker Compose 檔案放入 Oracle Cloud VM，執行 docker compose up -d 就能夠啟動。佢亦可以配合 Cloudflare Tunnel、Nginx Proxy Manager 或者其他反向代理工具，令介面喺唔公開連接埠嘅情況下安全存取。

Architecture

Floci 嘅架構主要分為兩個容器：核心引擎 floci 同使用者介面 floci-ui。喺預設設定入面，floci 負責模擬 AWS 風格嘅 API，而 Azure 同 GCP 嘅端點則透過環境變數指向 floci-az:4577 同 floci-gcp:4588。呢兩個端點唔一定由 Floci 本身提供，可以係其他容器或外部服務。

floci 容器掛載咗 Docker socket（/var/run/docker.sock），呢個設計令 Floci 可以喺收到 API 請求時，按需要動態建立同管理 sidecar 容器，以便執行對應嘅雲端服務模擬。正因為咁，Floci 需要運行喺有 Docker 權限嘅環境，亦要留意掛載 Docker socket 嘅安全風險。

Floci 使用 FLOCI_STORAGE_MODE=hybrid 作為儲存模式。呢個模式會同時使用 Docker named volume floci-data 同宿主機上嘅暫存空間，去保存模擬服務嘅狀態、設定檔同物件資料。Volume 掛載到 /app/data，方便備份同遷移。

網絡方面，兩個容器都連接去外部網絡 cf_network，並各自設定固定 IP：

• floci：172.21.0.82
• floci-ui：172.21.0.83

cf_network 通常係由 Cloudflare Tunnel 或其他反向代理容器建立嘅外部網絡。採用靜態 IP 可以令反向代理設定更穩定，唔使每次重建容器都變更 IP。

Deployment

要喺 Oracle Cloud 上部署 Floci，你需要準備以下環境：

• 一部 Oracle Cloud Compute VM，建議使用 Ubuntu 22.04 或 24.04
• 已安裝 Docker Engine 同 Docker Compose Plugin
• 已建立名為 cf_network 嘅外部 Docker network
• 確保 VCN 嘅 Security List 允許所需流量

若然尚未建立 cf_network，可以先用以下指令建立：

docker network create cf_network --subnet=172.21.0.0/24

然後建立 docker-compose.yml，內容如下：

services:
  floci:
    image: floci/floci:latest
    container_name: floci
    restart: unless-stopped
    environment:
      - TZ=Asia/Hong_Kong
      - FLOCI_STORAGE_MODE=hybrid
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - floci-data:/app/data
    networks:
      cf_network:
        ipv4_address: 172.21.0.82

  floci-ui:
    image: floci/floci-ui:latest
    container_name: floci-ui
    restart: unless-stopped
    environment:
      - TZ=Asia/Hong_Kong
      - FLOCI_ENDPOINT=http://floci:4566
      - FLOCI_AZURE_ENDPOINT=http://floci-az:4577
      - FLOCI_GCP_ENDPOINT=http://floci-gcp:4588
      - FLOCI_GCP_PROJECT=floci-local
      - AWS_REGION=us-east-1
      - AWS_ACCESS_KEY_ID=test
      - AWS_SECRET_ACCESS_KEY=test
    networks:
      cf_network:
        ipv4_address: 172.21.0.83

volumes:
  floci-data:

networks:
  cf_network:
    external: true

一切準備好之後，執行：

docker compose up -d

你可以用以下指令確認服務狀態：

docker compose ps
curl http://localhost:4566

如果你嘅 Oracle Cloud VM 係透過公共 IP 存取，請記住要喺 OCI Console 嘅 VCN Security List 加入 Ingress Rule。預設最好只開放反向代理或 Cloudflare Tunnel 需要嘅連接埠，例如 80、443，而唔好直接將 4566 或者 UI 介面暴露去公網。

Configuration

Floci 嘅主要設定透過環境變數完成。喺 docker-compose.yml 入面，floci 同 floci-ui 各自有唔同嘅設定項目。

floci 容器最緊要嘅環境變數係 FLOCI_STORAGE_MODE。設定為 hybrid 代表使用混合儲存模式，結合 Docker Volume 同宿主機空間，以便保存模擬服務嘅資料。TZ=Asia/Hong_Kong 將時區設定做香港時間，令日誌同時間戳記更符合香港使用者嘅習慣。

floci-ui 嘅設定就集中喺後端端點：

• FLOCI_ENDPOINT：指向 floci 核心引擎，預設係 http://floci:4566
• FLOCI_AZURE_ENDPOINT：指向 Azure 模擬服務，預設係 http://floci-az:4577
• FLOCI_GCP_ENDPOINT：指向 GCP 模擬服務，預設係 http://floci-gcp:4588
• FLOCI_GCP_PROJECT：設定 GCP Project ID，預設係 floci-local
• AWS_REGION、AWS_ACCESS_KEY_ID 同 AWS_SECRET_ACCESS_KEY：用嚟設定 AWS 風格 API 嘅測試憑證，預設係 test/test

要注意，floci-az 同 floci-gcp 並冇喺上面嘅 compose 檔案入面定義。如果呢啲服務唔存在，floci-ui 依然可以啟動，但相關平台嘅功能就無法使用。你需要自行安排額外容器或者服務去對應呢兩個 hostname。

Operations

日常操作 Floci 好簡單，主要用 Docker Compose 指令。

查看服務狀態：

docker compose ps

查看 floci 日誌：

docker compose logs -f floci

重啟服務：

docker compose restart

更新 Floci 映像：

docker compose pull
docker compose up -d

由於 floci-data 係 Docker named volume，所以備份可以透過執行一個臨時容器去打包：

docker run --rm -v floci-data:/data -v $(pwd):/backup alpine tar czf /backup/floci-data.tar.gz -C /data .

還原時就解壓返去 volume：

docker run --rm -v floci-data:/data -v $(pwd):/backup alpine tar xzf /backup/floci-data.tar.gz -C /data

安全方面，因為 floci 掛載咗 Docker socket，萬一容器被入侵，攻擊者理論上可以控制宿主機 Docker。所以最好將 Floci 放喺內網，並透過 Cloudflare Access、Tailscale 或者 VPN 限制存取。Floci UI 亦唔應該直接暴露喺公網，應交由反向代理處理 TLS 同認證。

FAQ

問：Floci 同 LocalStack 有咩分別？

Floci 主打多雲端模擬，除咗 AWS 之外仲提供 Azure 同 GCP 嘅 API 端點。LocalStack 主力係 AWS 模擬；Floci 就嘗試用一個平台統一三個雲端環境，配合 floci-ui 提供更完整嘅儀表板。

問：Floci 可以喺 Oracle Cloud Always Free 度行嗎？

可以。Oracle Cloud Always Free 提供 ARM 同 AMD 架構嘅 VM，只要 VM 有足夠記憶體同磁碟空間，就可以運行 Docker 同 Floci。建議使用 Ubuntu 或 Oracle Linux 映像。

問：點解 floci-ui 冇 ports 設定？

因為 Floci UI 預設係透過內部網絡連接，並由 Cloudflare Tunnel 或者其他反向代理轉發流量。如果一定要直接暴露，可以加入 ports: - "3000:80" 之類嘅設定，但唔建議喺公網直接開放。

問：floci-az 同 floci-gcp 唔存在會點？

如果冇呢兩個服務，floci 主體仍然可以正常執行，但 UI 入面嘅 Azure 同 GCP 功能會顯示為無法連接。你需要另外部署相關模擬容器，或者修改環境變數指向真實雲端測試環境。

Related Links

• docker
• oracle-cloud
• cloudflare
• AWS
• Azure
• google
• litellm

Source

Coverage auto (container scan)