Fns

Overview

Fns（Fast Note Sync）係一套輕量級、自架（self-hosted）筆記同步服務，專為個人用戶設計，主要運行喺 Oracle Cloud 嘅 Always Free 實例之上。佢嘅核心功能係快速、可靠咁同步筆記資料，讓用戶可以隨時隨地透過網頁或 API 存取自己嘅內容。Fns 採用 Docker 容器化部署，配合 PostgreSQL 資料庫儲存資料，確保數據一致性同持久性。

同市面上嘅商業筆記服務唔同，Fns 完全由用戶自行控制，所有資料均儲存喺自己嘅雲端伺服器，唔經第三方服務，隱私同安全性更高。由於部署喺 Oracle Cloud，用戶可以善用免費資源，以接近零成本建立私人筆記系統。Fns 嘅設計理念係「快、簡、穩」，特別適合注重數據主權嘅技術用戶。

Architecture

Fns 嘅整體架構由幾個核心部分組成，全部透過 Docker Compose 編排，並運行於同一外部網絡 cf_network 內：

• 應用程式容器：使用 haierkeys/fast-note-sync-service:latest 映像檔，容器名稱係 fast-note-sync，主機名設定為 oracle-fns。呢個容器負責處理筆記同步嘅業務邏輯、API 請求同前端介面。
• 網絡層：服務加入預先建立嘅外部 Docker 網絡 cf_network，並指定固定 IP 172.21.0.41。呢個做法令 Fns 可以同其他容器（例如同網段嘅 PostgreSQL 或 API 網關）直接以內網 IP 通訊，避免經外部網絡造成延遲或安全風險。
• 數據儲存：容器掛載兩個本地磁區：
• /home/opc/fns/storage：存放筆記檔案、附件或其他非結構化數據。
• /home/opc/fns/config：保存應用程式設定檔。 呢啲掛載確保容器重啟或更新後，數據仍然保留。
• 資料庫連接：Fns 預設使用 PostgreSQL 作為後端資料庫，透過環境變數指向同一個 cf_network 內嘅 pg-main 主機（連接埠 5432）。由於兩個容器身處同一內網，可以安全噉將 DB_SSLMODE 設為 disable，減少 SSL 加密解密運算所帶來嘅 CPU 開銷，提升效能。

容器嘅 restart: unless-stopped 策略確保服務喺意外崩潰或系統重啟後自動恢復，適合長期運行嘅伺服器環境。

Deployment

部署 Fns 需要一部運行 Oracle Cloud Linux 或 Ubuntu 嘅實例，並已安裝 Docker Engine 同 Docker Compose 外掛程式。以下係基本步驟：

1. 建立目錄結構：

   mkdir -p /home/opc/fns/{storage,config}
   

2. 建立 .env 檔案，設定資料庫密碼（DB_PASSWORD）及其他敏感環境變數：

   DB_PASSWORD=your_secure_password
   

3. 撰寫 docker-compose.yml 並放入 /home/opc/fns/，內容如下：

   services:
     fast-note-sync:
       image: haierkeys/fast-note-sync-service:latest
       container_name: fast-note-sync
       hostname: oracle-fns
       restart: unless-stopped
       networks:
         cf_network:
           ipv4_address: 172.21.0.41
       volumes:
         - /home/opc/fns/storage:/fast-note-sync/storage
         - /home/opc/fns/config:/fast-note-sync/config
       environment:
         - TZ=Asia/Hong_Kong
         - DB_TYPE=postgres
         - DB_HOST=pg-main
         - DB_PORT=5432
         - DB_USER=fns_user
         - DB_PASSWORD=${DB_PASSWORD}
         - DB_NAME=fns_db
         - DB_SSLMODE=disable
   
   networks:
     cf_network:
       external: true
   

4. 啟動服務：

   cd /home/opc/fns
   docker compose up -d
   

   Compose 會自動拉取映像檔，建立容器並連接至 cf_network。部署完成後，可以透過 Oracle Cloud 實例嘅公共 IP（配合反向代理如 Nginx 或 Cloudflare Tunnel）存取 Fns 服務。

注意：cf_network 必須預先存在，並包含 PostgreSQL 容器（例如 pg-main）。如果未建立，可以執行 docker network create cf_network，並確保 pg-main 容器加入此網絡。

Configuration

Fns 嘅配置主要透過環境變數同掛載檔案進行，所有設定均可喺 docker-compose.yml 中修改：

• TZ=Asia/Hong_Kong：設定容器時區為香港時間，確保筆記時間戳正確。
• DB_TYPE=postgres：指定使用 PostgreSQL 資料庫。Fns 亦可支援其他資料庫，但喺 Oracle Cloud 環境下通常選用 PostgreSQL。
• DB_HOST=pg-main：指向同網絡內嘅 PostgreSQL 容器主機名。如果資料庫位於外部，可以改為 IP 或域名。
• DB_PORT=5432：PostgreSQL 預設連接埠。
• DB_USER=fns_user：資料庫用戶名。需要確保喺 PostgreSQL 入面已經建立相應用戶並授予權限。
• DB_PASSWORD=${DB_PASSWORD}：取自 .env 檔案，避免將密碼硬編碼喺 Compose 檔案中。
• DB_NAME=fns_db：指定 Fns 使用嘅資料庫名稱，首次啟動時會自動建立或連接。
• DB_SSLMODE=disable：因為容器之間喺受保護嘅內網通訊，關閉 SSL 可減低 CPU 開銷；如果改用外部資料庫，建議設定為 require 以增加安全性。
• Volume 配置：
• storage 目錄存放所有筆記內容，必須定期備份。
• config 目錄保存設定檔，例如網站標題、用戶角色等，編輯後需要重啟容器先會生效。

所有配置改動完成後，執行 docker compose down && docker compose up -d 重建容器即可套用。

Operations

日常操作 Fns 需要熟悉幾個常用指令：

• 查看服務狀態：docker compose ps，確認容器運行正常。
• 查看日誌：docker compose logs -f fast-note-sync，有助於排查錯誤或監控請求。
• 備份資料：
• 備份 storage 目錄：tar -czvf fns_storage_backup.tar.gz /home/opc/fns/storage
• 備份 PostgreSQL 數據庫：docker exec pg-main pg_dump -U fns_user fns_db > fns_db_backup.sql
• 升級版本：編輯 Compose 檔案中嘅映像檔版本（或使用 latest），然後執行 docker compose pull && docker compose up -d。升級前務必先備份。
• 重啟容器：當修改咗 config 目錄內嘅設定，執行 docker compose restart fast-note-sync 載入新配置。
• 監控資源：Oracle Cloud 免費實例資源有限，可以使用 docker stats 檢查 CPU 同記憶體使用量，確保服務唔會超出配額。

如果服務無法正常啟動，最常見原因包括：cf_network 未存在、資料庫連線資訊錯誤，或者 storage/config 目錄權限不足。檢查日誌通常可以快速定位問題。

FAQ

問：Fns 係咪一定要用 Oracle Cloud？
答：唔係。Fns 係完全自架服務，可以運行喺任何支援 Docker 嘅伺服器，例如 VPS、樹莓派或家用 NAS。Oracle Cloud 只係其中一個免費選項，特別適合香港用戶因為低延遲。

問：點解要用 PostgreSQL 而唔用 SQLite？
答：PostgreSQL 提供更好嘅並發控制、數據完整性同備份機制，適合日後擴展或多人使用。SQLite 雖然輕量，但喺網絡服務場景下容易出現鎖定問題。

問：點樣透過網域名稱存取 Fns？
答：可以使用 Nginx 或 Caddy 做反向代理，將域名指向容器嘅 172.21.0.41 嘅內部連接埠，或者直接映射主機端口並用防火牆開放。亦可用 Cloudflare Tunnel 提供 HTTPS 而無需開端口。

問：點解需要 DB_SSLMODE=disable？
答：因為 pg-main 同 fast-note-sync 都喺同一 Docker 內網，流量唔會經過公開網絡，關閉 SSL 可以節省 CPU 資源。若資料庫位於外部，就唔應該噉樣設定。

問：如果唔見咗 .env 檔案，點算？
答：直接編輯 docker-compose.yml 並填入明文密碼（唔建議），或者重新建立 .env，然後執行 docker compose up -d 重新載入。如果資料庫已經有資料，密碼必須同之前一致。

Related Links

• docker
• postgres
• oracle-cloud
• Self-hosted
• litellm
• Nginx
• docker-compose

以上連結提供相關技術背景同部署方法，可進一步了解容器化、數據庫管理同雲端服務嘅細節。Fns 作為一套簡潔高效嘅筆記同步方案，結合 Oracle Cloud 免費資源，絕對係技術愛好者嘅理想選擇。

Source

Coverage auto (container scan)