Homepage¶

概述¶

Homepage 係一套開源、自承辦嘅導航儀表板，用嚟將分散喺內網嘅服務集中喺一個網頁入口。本實例部署喺 Oracle Cloud Infrastructure (OCI) 香港區 always-free VM，採用 Docker Compose 管理，一律匯聚咗 68 個運行中容器嘅狀態，包括可用性、CPU／記憶體使用率同個別服務嘅快捷連結。使用者只要開啟 https://homepage.benhoweb.com，就唔使再記低每個服務嘅 IP、port 或路徑，達到真正單一入口嘅效果。

架構¶

Homepage 容器行喺 OCI 彈性 VM 上，歸入外部 bridge network cf_network，固定 IPv4 地址為 172.21.0.26。同一網絡亦連住 cloudflared（Cloudflare Tunnel），將公網 HTTPS 流量轉發到容器嘅 3000 port。呢個設計令 Homepage 唔需要對公網暴露任何 port，大幅減少攻擊面。

主要組件： - homepage container：鏡像 ghcr.io/gethomepage/homepage:latest - 配置目錄：/home/opc/homepage/config，掛載到 /app/config - Docker Socket：唯讀掛載 /var/run/docker.sock，用嚟讀取容器狀態 - 時區：TZ=Asia/Hong_Kong，確保時間顯示正確

部署（Docker Compose 片段）¶

喺 /home/opc/homepage/ 建立 docker-compose.yml。因為 cf_network 係由多個服務共用嘅外部網絡，必須聲明為 external: true。

version: '3'

networks:
  cf_network:
    external: true

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    environment:
      - TZ=Asia/Hong_Kong
      - HOMEPAGE_ALLOWED_HOSTS=${HOMEPAGE_DOMAIN:-homepage.benhoweb.com}
    volumes:
      - /usr/share/zoneinfo:/usr/share/zoneinfo:ro
      - /home/opc/homepage/config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "127.0.0.1:3000:3000"   # 只反綁本機，公網走 Tunnel
    restart: unless-stopped
    networks:
      cf_network:
        ipv4_address: 172.21.0.26

啟動指令：

cd /home/opc/homepage
export HOMEPAGE_DOMAIN=homepage.benhoweb.com
docker compose up -d
docker compose ps

配置與環境變數¶

重要環境變數： - TZ：必須設為 Asia/Hong_Kong，否則所有時間會以 UTC 顯示，造成排程同日誌誤判。 - HOMEPAGE_ALLOWED_HOSTS：控制 HTTP Host header 驗證。當你加入新網址，一定要補上呢個值，否則會出現 400 invalid hostname。 - HOMEPAGE_DOCKER_HOST：一般唔需要設定，Homepage 預設使用 /var/run/docker.sock；如果行 rootless Docker，就要改為 unix:///run/user/1000/docker.sock。

配置文件全部放喺 /home/opc/homepage/config，掛載到容器 /app/config。常用檔案： - settings.yml：語言、主題、佈局。 - services.yaml：定義 68 個容器嘅群組、圖標、URL 同 Docker 名稱，例如 homepage。 - bookmarks.yaml：常用書籤。 - widgets.yaml：頂部 widget，例如 CPU／RAM、天氣、時間。

每次修改 YAML 後，可以用以下方式重新載入，或者直接 restart 容器：

docker exec homepage pkill -HUP node

維運與監控¶

日常檢查指令：

# 睇 logs
docker logs --tail=200 -f homepage

# 檢查容器狀態
docker ps | grep homepage

# 直接喺內網 curl，測試唔經 Tunnel 嘅連線
curl -H 'Host: homepage.benhoweb.com' http://172.21.0.26:3000

# 重啟服務
docker restart homepage

Homepage 本身極輕量，一般只用唔夠 50 MB RAM。如果發現頁面載入慢，多數係因為同時監察 68 個服務嘅狀態，可以喺 services.yaml 設定 siteMonitor: false，或者調低 refreshInterval 去減低網絡負載。

備份配置目錄係最重要嘅維運動作：

mkdir -p /home/opc/backup
tar czf /home/opc/backup/homepage_config_$(date +%F).tgz /home/opc/homepage/config

常見問題¶

公網開啟後顯示 400 Bad Request：多數係 HOMEPAGE_ALLOWED_HOSTS 冇包含正確域名，尤其用咗 Cloudflare Tunnel 之後 Host header 會變成真實網址，一定要將 homepage.benhoweb.com 加入白名單。
睇唔到容器狀態，只剩一頁空白／只有 Homepage 一個：檢查 /var/run/docker.sock 是否正確掛載；如果係 rootless Docker，要用 HOMEPAGE_DOCKER_HOST 指去正確 socket 路徑。
Cloudflare Tunnel 連唔到 Homepage：確認 cloudflared 同 homepage 都喺 cf_network，而且 tunnel 嘅 target 係 172.21.0.26:3000，唔好用 localhost，因為容器各自有獨立 network namespace。
改完 services.yaml 之後無反應：先檢查 YAML 語法，再用 docker compose exec homepage cat /app/config/services.yaml 確認檔案有正確掛載入容器。

Homepage¶

概述¶

架構¶

部署（Docker Compose 片段）¶

配置與環境變數¶

維運與監控¶

常見問題¶

相關鏈接¶