Vikunja¶

Overview¶

Vikunja 是一套開源、可自架的任務管理與待辦事項系統。它提供清單、看板、甘特圖、日曆、標籤、篩選器、提醒、團隊協作、API 等功能，常用作 Todoist、Trello、Microsoft To Do 等的自架替代方案。由於資料存放在自己控制的伺服器，適合重視私隱、資料主權及長期成本的用戶。Vikunja 以 Go 編寫後端，前端多為 Vue 生態，官方提供 Docker 映像，方便在 docker 環境部署。此條目描述在 oracle-cloud 上自架 Vikunja 的實例，並以 cloudflare-tunnel 將 task.benhoweb.com 發佈到互聯網。應用容器名為 vikunja_app，資料庫使用外部 postgres 容器 pg-main，持久化檔案放在 /home/opc/vikunja/files。整體設計符合低成本、可備份、可升級的個人或小型團隊需求。

Architecture¶

此部署由四個主要層次組成：

邊緣層：Cloudflare DNS 與 Cloudflare Tunnel。用戶瀏覽 https://task.benhoweb.com/，TLS 由 Cloudflare 處理，Tunnel 將請求轉到內部 Docker 網絡。
應用層：vikunja_app 容器執行 Vikunja。它預設監聽 3456 連接埠，但 compose 檔未對外開放連接埠，只連上 cf_network，因此只能由同一網絡的 Tunnel 容器或反向代理存取。
資料層：PostgreSQL 容器 pg-main，內有 vikunja 資料庫及用戶。應用透過 VIKUNJA_DATABASE_* 環境變數連接。附件、背景等檔案則存於 /home/opc/vikunja/files。
網絡層：cf_network 是外部建立的 Docker bridge network，子網通常為 172.21.0.0/16。vikunja_app 固定使用 172.21.0.10，令 Cloudflare Tunnel 設定穩定，不會因容器重建而改變目標 IP。

請求流程：瀏覽器 → Cloudflare Edge → Tunnel → cf_network → 172.21.0.10:3456 → Vikunja → pg-main:5432。此架構不需在 Oracle Cloud 安全清單開放 3456，亦避免直接暴露來源 IP。

Deployment¶

前置條件包括：Oracle Cloud 執行個體（ARM Ampere A1 或 AMD 均可）、已安裝 docker 與 Docker Compose、已建立 cf_network、已運行 pg-main PostgreSQL、已設定 Cloudflare Tunnel，以及 .env 檔內的 VIKUNJA_DATABASE_PASSWORD。建議先建立目錄：

mkdir -p /home/opc/vikunja/files
cd /home/opc/vikunja
nano .env

.env 內容示例：

VIKUNJA_DATABASE_PASSWORD=請使用高強度密碼

建立外部網絡（若未存在）：

docker network create --driver bridge --subnet 172.21.0.0/16 cf_network

將以下 compose 存為 docker-compose.yml：

services:
  vikunja_app:
    image: vikunja/vikunja:latest
    container_name: vikunja_app
    environment:
      TZ: Asia/Hong_Kong
      VIKUNJA_DATABASE_HOST: pg-main
      VIKUNJA_DATABASE_PORT: 5432
      VIKUNJA_DATABASE_PASSWORD: ${VIKUNJA_DATABASE_PASSWORD}
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_DATABASE: vikunja
      VIKUNJA_SERVICE_PUBLICURL: https://task.benhoweb.com/ # 必須與你的 Cloudflare 二級網域完全一致
    volumes:
      - /home/opc/vikunja/files:/app/vikunja/files
    networks:
      cf_network:
        ipv4_address: 172.21.0.10
    restart: unless-stopped

networks:
  cf_network:
    external: true

啟動：

docker compose up -d
docker compose logs -f vikunja_app

之後在 Cloudflare Tunnel 新增 Public Hostname：task.benhoweb.com → http://172.21.0.10:3456。首次開啟網址時，註冊第一個帳戶；Vikunja 通常會將首個用戶設為管理員，實際行為依版本而定。若已關閉註冊，可用容器內 CLI 建立管理員。

Configuration¶

主要設定集中於環境變數。TZ: Asia/Hong_Kong 確保日曆與提醒使用香港時區。VIKUNJA_DATABASE_HOST: pg-main 指向 PostgreSQL 容器；PORT、TYPE、USER、DATABASE 分別為 5432、postgres、vikunja、vikunja。密碼不寫死在 compose，而由 .env 的 VIKUNJA_DATABASE_PASSWORD 注入，降低洩漏風險。

VIKUNJA_SERVICE_PUBLICURL 必須是 https://task.benhoweb.com/，並與 Cloudflare 二級網域完全一致。若不一致，可能導致登入回呼、API 連結、電郵連結、WebAuthn、前端資源路徑或分享連結出錯。volumes 將主機 /home/opc/vikunja/files 掛載到容器 /app/vikunja/files，用於保存附件、頭像、背景等。此目錄必須定時備份，並確保容器用戶有讀寫權限。

cf_network 使用 external: true，表示網絡由 compose 以外管理，適合多個服務共用，例如 cloudflare-tunnel、postgres、litellm 或 Uptime Kuma。固定 IP 172.21.0.10 可簡化 Tunnel 設定，但同一網絡內不可與其他容器衝突。若更改子網，必須同步更新所有服務及 Tunnel 目標。

Operations¶

日常運維包括：

狀態檢查：docker compose ps、docker compose logs -f vikunja_app。
更新：先備份，再 docker compose pull、docker compose up -d。Vikunja 容器啟動時通常會自動執行資料庫遷移；跨版本升級前應查閱官方 release notes。
備份：資料庫用 docker exec pg-main pg_dump -U vikunja vikunja > vikunja.sql；檔案用 tar czf vikunja-files.tar.gz /home/opc/vikunja/files。兩者應一併備份，並上傳到 OCI Object Storage 或異地儲存。
還原：先停 vikunja_app，還原資料庫與檔案，再啟動容器。
監測：可用 Uptime Kuma 檢查 https://task.benhoweb.com/ 或 API 端點；亦可觀察容器 CPU、記憶體與磁碟。
安全：Oracle Cloud 安全清單只開放必要連接埠；不要對外開放 3456；啟用 Cloudflare Access、強密碼、兩步驗證；定期更新映像。
故障排查：若 502，檢查 Tunnel 目標與 cf_network；若資料庫連線失敗，檢查 pg-main、密碼及網絡別名；若上載失敗，檢查 volume 權限與磁碟空間；若連結錯誤，檢查 PUBLICURL。

FAQ¶

Vikunja 與 Todoist、Trello 有何分別？
Vikunja 是開源軟件，可自架，資料由自己控制；功能與介面則針對任務、清單、看板與協作。

為何要使用 external cf_network 與固定 IP？
Cloudflare Tunnel 容器需要穩定目標。固定 172.21.0.10 可避免容器重建後 IP 改變，減少斷線。

可以不用 PostgreSQL 嗎？
可以。Vikunja 支援 SQLite、MySQL、PostgreSQL；此部署選 PostgreSQL，較適合多人及長期使用。

資料實際存放在哪裡？
結構化資料在 pg-main 的 PostgreSQL；附件等檔案在 /home/opc/vikunja/files。兩者都要備份。

如何更新 Vikunja？
先備份，再 docker compose pull && docker compose up -d。如遇到資料庫遷移問題，應回看日誌及官方升級指引。

為何 VIKUNJA_SERVICE_PUBLICURL 要完全一致？
因為 Vikunja 會用它產生對外連結、處理跨域、登入及 API 請求。錯配會造成重定向或功能異常。

可以開放 3456 給公眾嗎？
不建議。應經 Cloudflare Tunnel 或反向代理，並加上驗證與防火牆規則。

忘記密碼怎麼辦？
若已設定郵件，可用重設功能；否則可透過 Vikunja CLI 或資料庫管理員重設。實際指令依版本而異。

docker
docker-compose
oracle-cloud
cloudflare-tunnel
postgres
litellm
Uptime Kuma
Nginx
反向代理
備份與還原

Source¶

Coverage auto (container scan)