跳轉至

Floci Gcp

Overview

Floci Gcp（亦以全小寫 floci-gcp 出現）是一個自我託管（self-hosted）服務，為 Oracle Cloud Infrastructure（OCI）上的容器環境而設。它基於 Docker 容器執行，透過掛載 Docker Socket 控制宿主主機上的 Docker 資源，並與既有的外部網絡 cf_network 連接。cf_network 通常與 Cloudflare Tunnel 或反向代理相關，使服務可以穩定地與外圍網絡基礎設施配合。

Floci Gcp 的名稱容易令人聯想到 Google Cloud Platform（GCP），但在此語境下，「Gcp」並非指 Google Cloud，而是該項目的內部代號或子項目名稱。Floci Gcp 的設計重點是「自我託管」，即使用者自行在雲端虛擬機器上部署、管理及維護，而無需依賴第三方 SaaS 服務。

Architecture

Floci Gcp 的架構由一個 Docker Compose 定義組成，核心元件包括：

  • Docker 映像檔：floci/floci-gcp:latest，由 Floci 項目發佈。
  • Docker Socket：主機的 /var/run/docker.sock 被掛載至容器內相同路徑。此機制讓 Floci Gcp 可以直接與 Docker Daemon 通訊，以管理容器、網絡及映像檔。
  • 數據卷：floci-gcp-data 掛載至容器內的 /app/data，用作儲存持久性資料與狀態。
  • 外部網絡：容器指定連接到已存在的外部網絡 cf_network，並固定使用 IPv4 位址 172.21.0.85。網絡本身不會由 Compose 自動建立，而是由外部預先建立。
  • 時區設定：環境變數 TZ 設為 Asia/Hong_Kong，確保日誌、排程及時間記錄使用香港時間。

由於 Floci Gcp 需要掛載 Docker Socket，其執行權限實際上等同於 Docker Daemon 的管理者。任何有此容器存取權限的人，都可以在宿主主機上執行任意 Docker 指令。因此，部署時應只在可信賴環境中使用，並避免將容器暴露予非授權使用者。

Deployment

Floci Gcp 設計為在 Oracle Cloud 上的 Linux 虛擬機器執行，尤其適合使用 OCI 的 Always Free 計算實例。使用者只需要一個具備 Docker Engine 及 Docker Compose Plugin 的環境。

以 Oracle Cloud 上的 Ubuntu 或 Oracle Linux 實例為例，部署步驟如下：

  1. 建立且連入虛擬機器
    在 OCI Console 建立一個 VM 實例，使用 Ubuntu 22.04/24.04 或 Oracle Linux 8/9，並以 SSH 連入。

  2. 安裝 Docker 與 Compose Plugin
    執行系統更新，然後安裝 docker-ce、docker-ce-cli、containerd.io 及 docker-compose-plugin。

  3. 建立外部網絡
    cf_network 必須在執行 Compose 前存在。若尚未建立，可執行：

docker network create cf_network --subnet 172.21.0.0/24

若 cf_network 已經由其他容器或 Cloudflare Tunnel 建立，則毋需重複建立。

  1. 準備 Compose 檔案
    建立一個目錄，例如 /opt/floci-gcp，在內存放 docker-compose.yml。內容如下：
services:
  floci-gcp:
    image: floci/floci-gcp:latest
    restart: unless-stopped
    networks:
      cf_network:
        ipv4_address: 172.21.0.85
    environment:
      TZ: Asia/Hong_Kong
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - floci-gcp-data:/app/data

networks:
  cf_network:
    external: true

volumes:
  floci-gcp-data:
  1. 啟動服務
    在該目錄下執行：
docker compose up -d

此指令會下載映像檔、建立數據卷，並以背景模式啟動 Floci Gcp。

Configuration

Floci Gcp 的設定主要透過 Compose 檔案完成。最常調整的部分包括：

  • 時區（TZ）：預設為 Asia/Hong_Kong，可依部署位置更改，例如 Asia/Tokyo 或 UTC。
  • 容器 IP 位址：172.21.0.85 是一個固定 IP。若 cf_network 的子網路不同，需要調整至對應網段。
  • 數據卷位置：floci-gcp-data 可改用 bind mount，例如 ./data:/app/data，以便直接備份宿主主機上的檔案。
  • Docker Socket 路徑：部分環境可能使用 tcp:// 或受保護的 Socket 路徑，但一般 Linux 安裝均為 /var/run/docker.sock。
  • 環境變數：除 TZ 外，Floci Gcp 可能支援其他設定選項，例如 API 金鑰、外部服務端點或日誌等級。相關變數應參考項目官方文件，並以 environment 區段加入。

由於 cf_network 被設定為 external: true，該網絡必須事先存在。若 Compose 無法找到該網絡，服務會啟動失敗，並顯示類似 network cf_network not found 的錯誤。

Operations

Floci Gcp 的日常操作以 Docker Compose 指令為主。常用操作包括：

  • 查看日誌：
docker compose logs -f floci-gcp
  • 重新啟動服務：
docker compose restart floci-gcp
  • 更新映像檔：
docker compose pull
docker compose up -d
  • 停止服務：
docker compose down

注意：down 不會刪除 floci-gcp-data 數據卷，因此資料仍然保留。

  • 備份數據卷：
docker run --rm \
  -v floci-gcp-data:/app/data \
  -v "$(pwd)":/backup \
  alpine tar czf /backup/floci-gcp-data.tar.gz /app/data

備份檔案會儲存在目前目錄下，需定期複製至其他儲存位置。

  • 還原數據卷：
docker run --rm \
  -v floci-gcp-data:/app/data \
  -v "$(pwd)":/backup \
  alpine tar xzf /backup/floci-gcp-data.tar.gz -C /

由於服務使用 Docker Socket，操作時必須確保系統有足夠的磁碟空間，並監察 Docker Daemon 的日誌。Oracle Cloud 實例的故障排查亦應包括檢視 OCI 的 Security List，確保所需連接埠允許訪問，尤其是當服務需要對外提供 HTTP/HTTPS 或 WebSocket 時。

FAQ

Floci Gcp 與 Google Cloud Platform 有關嗎？
無關。雖然名稱包含「Gcp」，但此處為項目代號，與 Google Cloud 沒有任何關係。

為什麼需要掛載 Docker Socket？
Floci Gcp 需要透過 Docker API 管理宿主主機上的容器、網絡及映像檔。掛載 Socket 是常見做法，但會帶來高權限風險，因此應該只在專用環境中使用。

可否不使用 Oracle Cloud 部署？
可以。只要主機具備 Docker 及 Compose，且能建立或連接 cf_network，就能執行 Floci Gcp。Oracle Cloud 只是常見的部署目標，並非唯一限制。

如何更新 Floci Gcp？
進入 Compose 檔案所在目錄，執行 docker compose pull 與 docker compose up -d。更新後可使用 docker image prune 清理舊映像檔。

為什麼出現 network cf_network not found？
因為 Compose 設定要求 cf_network 是外部網絡，但該網絡尚未建立。需要先執行 docker network create cf_network，並確認子網段與 IP 設定相容。

Source

Coverage auto (container scan)