Pg Main

Overview

Pg Main 係本站（wiki.benhoweb.com）嘅核心自托管數據庫服務，採用 PostgreSQL 搭配 pgvector 擴展，部署於 Oracle Cloud 嘅單一容器應用。Pg Main 主要用於儲存 AI／LLM 工作流程嘅結構化數據同向量嵌入（vector embeddings），支援語意搜尋、RAG（Retrieval-Augmented Generation）、快取、以及應用程式狀態持久化。

此服務以 Docker Compose 管理，使用官方 pgvector/pgvector 映像檔，基於 PostgreSQL 18，並預載 pgvector 0.8.5。容器加入預先建立嘅外部 Docker 網絡 cf_network，以固定 IP 172.21.0.8 與其他內部服務（如 LiteLLM、網關、反向代理）通訊，而唔直接公開連接埠，藉此降低攻擊面。整個資料庫目錄掛載到 Oracle Cloud 實例嘅磁碟上，實現持久化儲存，重啟容器或升級映像都唔會流失資料。

Architecture

Pg Main 採用「單一容器 + 外部網絡 + 宿主機磁碟掛載」嘅簡潔架構。

• 映像檔：pgvector/pgvector:0.8.5-pg18，包含 PostgreSQL 18 核心同 pgvector 擴展，適合處理傳統 relational data 同向量數據。
• 容器名稱：pg-main，方便於 Docker 網絡內以容器名直接解析。
• 重啟策略：unless-stopped，確保服務喺系統啟動或者異常退出後自動恢復，除非手動停止。
• 持久化卷：將宿主機目錄 /home/opc/pg-main/data 掛載到容器內 /var/lib/postgresql。呢個係父目錄，而實際數據目錄由 PGDATA 參數指向 /var/lib/postgresql/18/docker，為日後升級 PostgreSQL 19 預留更清晰嘅路徑結構，可以直接使用 pg_upgrade 工具。
• 網絡：cf_network 被標記為 external: true，即係由 Docker 外部預先建立嘅 bridge 網絡。容器喺此網絡獲分派固定 IPv4 172.21.0.8。咁樣，其他連接到 cf_network 嘅容器（例如 LiteLLM、Nginx、Cloudflare Tunnel）就可以用 172.21.0.8:5432 或者 pg-main:5432 存取資料庫。
• 環境變數：時區設定為 Asia/Hong_Kong；超級用戶名為 postgres；密碼透過 Compose 檔案外嘅 ${POSTGRES_PASSWORD} 環境變數注入，避免硬編碼。
• 健康檢查：使用 pg_isready 每 15 秒檢查一次，最長等待 5 秒，連續失敗 10 次視為 unhealthy，並設有 30 秒啟動寬限期。

呢個架構優點係簡單、可預測，並將唔同服務之間嘅依賴收斂到單一 Docker 網絡，適合中小型自托管環境。

Deployment

部署 Pg Main 前，需要準備以下條件：

1. 一部已安裝 Docker 同 Docker Compose 嘅 Oracle Cloud 實例（例如 Ubuntu／Oracle Linux）。
2. 宿主機上建立資料目錄 /home/opc/pg-main/data。
3. 建立外部 Docker 網絡 cf_network，確保其他服務共用同一網絡。

建立網絡指令：

docker network create cf_network --subnet=172.21.0.0/24

然後喺 /home/opc/pg-main/ 目錄下建立 docker-compose.yml，內容如下：

networks:
  cf_network:
    external: true

services:

  pg-main:
    image: pgvector/pgvector:0.8.5-pg18
    container_name: pg-main
    restart: unless-stopped

    volumes:
      # mount 父目錄，PGDATA 喺 /var/lib/postgresql/18/docker（將來升 PG19 可以 pg_upgrade）
      - /home/opc/pg-main/data:/var/lib/postgresql

    networks:
      cf_network:
        ipv4_address: 172.21.0.8

    environment:
      TZ: Asia/Hong_Kong
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      PGDATA: /var/lib/postgresql/18/docker

    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d postgres"]
      interval: 15s
      timeout: 5s
      retries: 10
      start_period: 30s

部署前，喺同一個目錄建立 .env 檔案：

POSTGRES_PASSWORD=your_strong_password_here

然後執行：

docker compose up -d

檢查容器狀態同日誌：

docker compose ps
docker compose logs -f pg-main

由於 Compose 檔案冇定義 ports，Pg Main 唔會直接暴露任何宿主機連接埠。所有外部存取必須透過同一個 cf_network 上嘅其他服務，例如 Cloudflare Tunnel、Nginx 反向代理，或者連接到同一網絡嘅應用容器。

Configuration

Pg Main 嘅主要設定集中在環境變數同掛載路徑。

• POSTGRES_USER=postgres：設定超級用戶名稱。呢個用戶擁有全部權限，建議只喺內部服務使用，並透過角色管理建立具最小權限嘅應用用戶。
• POSTGRES_PASSWORD：由外部 .env 提供。PostgreSQL 預設只容許 localhost 連接，但 Docker 容器透過 PostgreSQL 映像嘅機制會將此密碼設定俾 postgres 用戶。由於容器連接到內部網絡，任何能夠進入 cf_network 嘅服務都可以嘗試連線，因此密碼必須夠強。
• PGDATA=/var/lib/postgresql/18/docker：指向實際數據檔案目錄。呢個路徑位於掛載父目錄之下，資料持久化於宿主機 /home/opc/pg-main/data/18/docker。日後升級到 PostgreSQL 19 時，可以安裝新版映像，再以 pg_upgrade 指向上一個 major version 嘅數據目錄，避免一次性 dump 還原。
• TZ=Asia/Hong_Kong：容器內 PostgreSQL 程式嘅時區，影響時間戳顯示同日誌。
• cf_network 固定 IP：設為 172.21.0.8。呢個 IP 必須喺網絡 subnet 範圍內，且未被其他容器佔用。使用固定 IP 令依賴此服務嘅容器唔需要動態解析。

若果要修改任何設定，直接編輯 docker-compose.yml 後執行：

docker compose up -d

PostgreSQL 會自動讀取原有數據目錄，並套用新環境變數（例如時區）。注意，POSTGRES_PASSWORD 只喺數據目錄初始化嗰陣生效；若果要修改密碼，需要透過 psql 或者 ALTER USER。

Operations

日常操作主要圍繞備份、還原、健康檢查同升級。

連入 PostgreSQL 命令列：

docker exec -it pg-main psql -U postgres -d postgres

建立向量擴展（如果尚未存在）：

CREATE EXTENSION IF NOT EXISTS vector;

備份單一資料庫：

docker exec pg-main pg_dump -U postgres -d postgres > backup.sql

備份全部資料庫（使用 pg_dumpall）：

docker exec pg-main pg_dumpall -U postgres > all_databases.sql

還原備份：

cat backup.sql | docker exec -i pg-main psql -U postgres -d postgres

檢查健康狀態：

docker inspect --format='{{json .State.Health}}' pg-main

睇 PostgreSQL 日誌：

docker logs --tail 100 pg-main

升級 PostgreSQL major version 時，建議先停止應用、進行完整備份，然後拉取新映像，調整 PGDATA 路徑，再用 docker compose up -d 啟動。若係 pgvector 版本同 PostgreSQL 版本兼容，資料目錄可以保留；否則需要按 PostgreSQL 官方流程進行 pg_upgrade 或 dump 還原。

FAQ

問：Pg Main 係咪公開俾互聯網存取？
答：唔係。Compose 檔案無 ports，容器只喺 cf_network 內部提供服務。如果要公開，可以透過 Cloudflare Tunnel 或者反代服務，並加上 TLS 同認證。

問：點解要將 /home/opc/pg-main/data 掛載去 /var/lib/postgresql，而唔直接掛載去 PGDATA？
答：咁做係為咗保留父目錄結構，令 PGDATA 路徑內含 major version（例如 18/docker）。將來升級 PostgreSQL 19 時，可以保留舊數據目錄並使用 pg_upgrade，減少遷移步驟。

問：點樣與 LiteLLM 連接？
答：喺同一個 cf_network 上，LiteLLM 可以使用以下連線字串：

postgresql://postgres:${POSTGRES_PASSWORD}@pg-main:5432/postgres

或者使用固定 IP 172.21.0.8。

問：pgvector 擴展係咪已經裝好？
答：係。pgvector/pgvector 映像檔預先編譯咗 pgvector 擴展，只需要喺具體數據庫執行 CREATE EXTENSION vector; 即可使用。

問：點解容器顯示 unhealthy？
答：可能係 PostgreSQL 未完成初始化、密碼錯誤、或者磁碟空間不足。可以睇 docker compose logs pg-main 確認實際錯誤。

Related Links

• docker
• postgres
• pgvector
• litellm
• oracle-cloud
• cloudflare-tunnel

Source

Coverage auto (container scan)