Vikunja¶

概述¶

Vikunja 係一款開源、可自託管嘅任務管理／看板工具，支援 Kanban、List、Gantt 等視圖，適合個人同團隊協作。本站以 Docker Compose 方式部署喺 Oracle Cloud Infrastructure（OCI）VM 上，使用外部 PostgreSQL 實例 pg-main 儲存資料，並透過 Cloudflare Tunnel 對外提供 HTTPS 服務，網址為 https://task.benhoweb.com/。呢個部署方案兼顧靈活性同安全性，且所有敏感設定均透過環境變數管理。

架構¶

整體架構如下：

VM：OCI 上的 Linux 主機，IP 為私有地址（例如 10.0.0.10），運行 Docker Engine 及 Docker Compose。
應用容器：vikunja_app，使用官方鏡像 vikunja/vikunja:latest，固定容器 IP 172.21.0.10 於外部 Docker network cf_network。
資料庫：PostgreSQL 服務 pg-main，可以係同一台 VM 或另一台主機，Vikunja 透過 Docker network 或主機網絡連接；本部署假設 pg-main 亦在同一個 cf_network 內可連。
外部訪問：Cloudflare Tunnel 將 task.benhoweb.com 嘅 HTTPS 流量轉發至容器嘅 3450 端口（Vikunja 預設端口）。
持久化儲存：只保留 /app/vikunja/files（用戶上傳附件），資料庫則全部放入 PostgreSQL。

部署（Docker Compose 片段）¶

以下係精簡但可用嘅 docker-compose.yml，請將敏感值放入同目錄下嘅 .env 檔案：

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_USER: vikunja
      VIKUNJA_DATABASE_PASSWORD: ${VIKUNJA_DATABASE_PASSWORD}
      VIKUNJA_DATABASE_DATABASE: vikunja
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_SERVICE_PUBLICURL: https://task.benhoweb.com/
    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 network 存在：docker network create cf_network --subnet 172.21.0.0/24（如果未建立）。
將以上內容儲存為 /home/opc/vikunja/docker-compose.yml。
喺同一目錄建立 .env，內容至少包括：VIKUNJA_DATABASE_PASSWORD=你的強密碼。
執行 docker compose up -d。

配置與環境變數¶

Vikunja 支援以環境變數覆蓋設定檔，以下係本部署關鍵項目：

VIKUNJA_DATABASE_TYPE：固定為 postgres。
VIKUNJA_DATABASE_HOST：指向 PostgreSQL 主機名 pg-main，若唔同網絡請用 IP 或 FQDN。
VIKUNJA_DATABASE_PORT：PostgreSQL 預設 5432。
VIKUNJA_DATABASE_USER／VIKUNJA_DATABASE_DATABASE：建議設定對應專用帳號及資料庫，唔好用 postgres 超級用戶。
VIKUNJA_SERVICE_PUBLICURL：必須與 Cloudflare 網域完全一致，結尾斜線可保留，否則會影響連結產生。
TZ：設為 Asia/Hong_Kong，確保時間顯示正確。

另外，生產環境建議加入：

VIKUNJA_SERVICE_JWTSECRET：用於簽署 JWT，請設為長隨機字串。
VIKUNJA_SERVICE_ENABLEREGISTRATION：若只邀請成員，可設為 false。

維運與監控¶

日常維運注意以下幾點：

查看日誌：docker logs -f vikunja_app；若發現 database connection error，先確認 pg-main 是否可達。
檢查連接：docker exec vikunja_app ping pg-main 或 nc -vz pg-main 5432。
備份資料庫：PostgreSQL 備份可使用 pg_dump：
```
pg_dump -h pg-main -U vikunja -d vikunja -F c -f /backup/vikunja.dump
```
還原用 pg_restore --clean -h pg-main -U vikunja -d vikunja /backup/vikunja.dump。
備份檔案：直接 rsync /home/opc/vikunja/files 到異地。
更新鏡像：先 docker compose pull，再 docker compose up -d，留意官方 changelog，通常無需手動 migrate。
監控端口：容器對外只透過 Cloudflare Tunnel，主機毋須開放 3450 埠；若需本機測試，用 curl http://127.0.0.1:3450。
資源限制：建議喺 compose 中加入 deploy.resources.limits（如 memory: 512M），避免 OOM。

常見問題¶

Q1：登入後網頁顯示「404 Not Found」或樣式錯亂。
檢查 VIKUNJA_SERVICE_PUBLICURL 是否同 Cloudflare 網域完全一致，包括斜線同協議。變更後需要 docker compose restart vikunja_app。

Q2：無法連接 PostgreSQL。
確認 pg-main 服務正常，且用戶 vikunja 有權限訪問 vikunja 資料庫；若 pg-main 使用另一個 Docker network，要將兩個 network 連通或改用主機 IP。

Q3：上傳檔案後無法下載。
檢查 files volume 權限，容器內用戶 UID 通常係 1000，宿主要 chown -R 1000:1000 /home/opc/vikunja/files。

Q4：Cloudflare Tunnel 無法連到容器。
確認 tunnel 嘅 service 指向 http://localhost:3450 或 http://172.21.0.10:3450，並且 cf_network 已建立、容器 IP 未被佔用。

Q5：點樣徹底重置？
先備份 database dump 同 files，然後 docker compose down -v（會刪除容器及 unnamed volumes），再重新部署。

Vikunja¶

概述¶

架構¶

部署（Docker Compose 片段）¶

配置與環境變數¶

維運與監控¶

常見問題¶

相關鏈接¶