Blinko¶

概述¶

Blinko（又稱 BlinkoSpace）係一套開源嘅 AI 速記／閃念筆記工具，專為快速捕捉靈感而設計。佢嘅核心概念係「閃念」——用戶可以隨時隨地用極短時間記低一件事，系統會自動整理、歸類，甚至透過 AI 進行語意理解同關聯。Blinko 提供網頁介面同流動裝置適配，支援 Markdown 編輯、標籤管理、全文搜尋，以及與 OpenAI 兼容嘅 API 整合，令筆記可以自動生成摘要、抽取關鍵字，或者透過自然語言查詢既有內容。

Blinko 特別適合需要高頻率記錄嘅用戶，例如開發者、產品經理、研究人員。佢唔似一般重筆記軟件（如 Notion、Obsidian）咁強調結構化，反而鼓勵用戶先記錄、後整理，將「捕捉」同「加工」分開，減少認知負擔。香港團隊或個人用戶可以自托管喺自家伺服器或 VPS，完全掌控數據。

架構¶

Blinko 採用前後端分離架構，但官方 Docker 鏡像將 Next.js 應用同 API 服務整合為單一容器，簡化部署。主要組件包括：

Web 應用（Next.js）：提供用戶介面、認證流程、REST API。
PostgreSQL 資料庫：儲存筆記、用戶、標籤、AI 快取等結構化數據。
檔案儲存（Volume）：存放上傳圖片、附件同資料庫備份，掛載至 /app/.blinko。
AI 整合層：透過 OpenAI 兼容接口（可配置自建模型，例如 litellm 作為閘道）進行摘要、關鍵字分析及語意搜尋。

喺我哋嘅實際環境中，Blinko 容器 blinkospace/blinko:1.8.8 被指派靜態 IPv4 172.21.0.78，位於外部 Docker 網絡 cf_network（該網絡由cloudflare-tunnel或其他服務共用），容器名稱 blinko，確保重啟後 IP 不變。資料庫則共用另一台 PostgreSQL 實體（pg-main），Blinko 透過內部網絡連接 pg-main:5432/blinko，唔會直接暴露到公網。

部署¶

部署 Blinko 好簡單，使用 Docker Compose 即可。以下係實際節選嘅 docker-compose.yml：

services:
  blinko:
    image: blinkospace/blinko:1.8.8
    container_name: blinko
    restart: always
    networks:
      cf_network:
        ipv4_address: 172.21.0.78
    environment:
      NODE_ENV: production
      NEXTAUTH_URL: https://memo.benhoweb.com
      NEXT_PUBLIC_BASE_URL: https://memo.benhoweb.com
      NEXTAUTH_SECRET: ${BLINKO_NEXTAUTH_SECRET}
      DATABASE_URL: postgresql://${BLINKO_DB_USER}:${BLINKO_DB_PASSWORD}@pg-main:5432/blinko
      TZ: Asia/Hong_Kong
    volumes:
      - blinko-data:/app/.blinko
    logging:
      options:
        max-size: "10m"
        max-file: "3"
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://localhost:1111/').then(r=>{if(r.ok)process.exit(0);process.exit(1)}).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s

volumes:
  blinko-data:

networks:
  cf_network:
    external: true

部署步驟：

準備 .env 檔，設定 BLINKO_NEXTAUTH_SECRET（可用 openssl rand -base64 32 產生）、BLINKO_DB_USER、BLINKO_DB_PASSWORD。
確保 pg-main 已建立名為 blinko 嘅資料庫。
確認 cf_network 已經存在（否則用 docker network create cf_network 建立）。
執行 docker compose up -d。

Blinko 容器預設監聽 1111 埠（healthcheck 亦以此為準），但喺 Compose 冇對外映射埠，因為係透過 cloudflare-tunnel 嘅 cloudflared 容器接入同一個 cf_network，再由 Tunnel 將 memo.benhoweb.com 流量轉發至 http://blinko:1111，實現 HTTPS 訪問，無需直接開放公網埠。

配置¶

環境變數關鍵項目：

NODE_ENV=production：啟用生產模式。
NEXTAUTH_URL 同 NEXT_PUBLIC_BASE_URL：必須設定為對外嘅完整網址 https://memo.benhoweb.com，否則 OAuth 回調同 API 路徑會出錯。
NEXTAUTH_SECRET：NextAuth 用嚟加密 session，一定要保持機密。
DATABASE_URL：PostgreSQL 連接字串，建議使用專用帳號，唔好用 superuser。
TZ=Asia/Hong_Kong：令時間顯示符合香港時區。

Blinko 介面入面可以設定 AI 模型，揀「OpenAI 兼容」provider，填入 API Base URL（例如自建 https://ai.example.com/v1）以及 API Key。如果使用 litellm 做統一閘道，就可以將不同模型（如 GPT、Claude、本地模型）統一成一個 endpoint 畀 Blinko 用。

維運與監控¶

日常維運要留意以下幾點：

日誌：Compose 已設定 max-size: 10m 同 max-file: 3，避免日誌塞爆磁碟。可用 docker logs -f blinko 查看即時日誌。
健康檢查：內建 healthcheck 每 30 秒打一次 http://localhost:1111/，連續失敗 5 次會標記 unhealthy。建議用 docker ps 監察狀態。
備份：blinko-data volume 包含資料庫備份同附件。除咗備份 volume，亦建議喺 pg-main 定期 pg_dump blinko。可以將備份檔案同步去另一隻磁碟或 rclone 等工具做異地備份。
升級：升級前先備份 volume，然後拉新鏡像，docker compose up -d。留意 Changelog，尤其係資料庫 migration 有冇 breaking change。
網絡：因為用固定 IP，要確保 cf_network 冇 IP 衝突。若重建網絡，記得更新 Compose 入面嘅 IP。

監控方面可以將 Blinko 加入 Uptime Kuma 或 prometheus（透過 blackbox exporter 探測 HTTPS），配合 grafana 做儀表板，確保服務穩定。

常見問題¶

Q1：登入後出現 502 / 504？
通常係 NEXTAUTH_URL 冇設定，或者 Cloudflare Tunnel 指向錯嘅服務名／埠。確認容器名稱係 blinko，且 NEXT_PUBLIC_BASE_URL 同實際對外網址一致。

Q2：AI 功能冇反應？
檢查 API Base URL 是否可達，同埋模型名稱是否符合 provider 要求。如果用到 litellm，確認 /v1 路徑正確，以及 API Key 有效。

Q3：容器啟動失敗，顯示資料庫連線錯誤？
先確認 pg-main 是否運行中、blinko 資料庫是否存在、用戶權限是否足夠。可以喺 Blinko 容器內部用 nc -zv pg-main 5432 測試連線。

Q4：圖片上傳失敗？
檢查 blinko-data volume 是否可寫入，磁碟空間是否足夠。亦要留意 Nginx 或 Tunnel 有冇 request body size 限制。

Q5：如何更新 Blinko？
docker compose pull blinko && docker compose up -d。建議先備份。

來源¶

自動生成（2026-08-19 容器覆蓋率補完第二批）

Blinko¶

概述¶

架構¶

部署¶

配置¶

維運與監控¶

常見問題¶

相關鏈接¶

來源¶