OpenList¶

概述¶

OpenList 是一個以 Alist 為基礎的分支項目，目標是打造一個開放、輕量且易於自託管的列表前端。Alist 本身是一個支援多種儲存後端的檔案列表程式，而 OpenList 在此之上進一步強化了與第三方服務的整合能力，特別適合用於建立個人雲端入口或團隊共享資源目錄。

OpenList 與 Alist 最大的分別在於其「開放列表」定位：它不單止是檔案瀏覽器，更可以聚合不同來源的連結、文件和媒體資源，以統一介面向使用者呈現。對於需要快速搭建內部工具入口、文件中心或媒體庫的場景，OpenList 提供了一個比傳統靜態頁面更具互動性的選擇。

本條目基於 benhoweb 的實際部署環境撰寫，該實例運行於 Oracle Cloud Infrastructure（OCI）的 Always Free 運算執行個體上，使用 Docker Compose 管理，並接入 Cloudflare Tunnel 作對外發布。

架構¶

OpenList 採用單一容器架構，官方鏡像為 openlistteam/openlist:latest。此鏡像已包含執行階段所需的所有相依元件，無需額外安裝 Nginx 或 PHP-FPM。容器內部監聽既定連接埠，並透過 Docker 網絡對外提供服務。

在 benhoweb 的環境中，容器的 container_name 設為 openlist，使用者及群組 ID 指定為 0:0（即根使用者），確保容器內有足夠權限寫入掛載的資料目錄。資料目錄 /opt/openlist/data 被綁定掛載至容器內的 /opt/openlist/data，用於存放設定檔、資料庫及其他狀態資料。

此實例接入了一個外部 Docker 網絡 cf_network（external: true），該網絡同時連接 Cloudflare Tunnel 容器，使 OpenList 可以經由 Tunnel 安全地對外提供 HTTPS 訪問，而無需直接暴露公網連接埠。此架構既提升了安全性，亦簡化了 TLS 憑證管理。

部署¶

以下是 OpenList 的 Docker Compose 部署定義（節選）：

services:
  openlist:
    image: openlistteam/openlist:latest
    container_name: openlist
    user: '0:0'
    environment:
      - UMASK=022
      - TZ=Asia/Hong_Kong
    volumes:
      - /home/opc/openlist/data:/opt/openlist/data
    networks:
      cf_network:
        ipv4_address: 172.21.0.55
    restart: unless-stopped

networks:
  cf_network:
    external: true

部署步驟如下：

建立資料目錄：mkdir -p /home/opc/openlist/data
將上述 Compose 內容儲存為 docker-compose.yml
執行 docker compose up -d 啟動服務

注意 networks.cf_network.external 設為 true，因此需要預先建立該網絡（docker network create cf_network）。同時，ipv4_address 被指定為 172.21.0.55，該 IP 必須在 cf_network 的子網範圍內，否則容器啟動時會報錯。

配置¶

OpenList 的設定檔儲存在掛載的 /opt/openlist/data 目錄內。首次啟動後，容器會生成預設配置，管理員可以透過 Web 介面或直接編輯設定檔進行調整。

環境變數方面：

UMASK=022：設定容器內建立檔案的權限遮罩，使新檔案具備 644（rw-r--r--）、目錄具備 755（rwxr-xr-x）的預設權限，避免因權限過寬或過窄導致存取問題。
TZ=Asia/Hong_Kong：指定時區為香港時間，確保日誌時間戳及排程任務（如備份）的執行時間符合本地習慣。

預設的管理員帳號和密碼會在首次啟動時輸出至容器日誌，可透過 docker logs openlist 查看。強烈建議首次登入後立即變更密碼，並啟用雙重認證（如適用）。

維運與監控¶

日常維運主要圍繞以下幾個面向：

日誌查詢：使用 docker logs -f openlist 即時查看應用日誌，排查存取錯誤或異常行為。
資料備份：定期備份 /home/opc/openlist/data 目錄。可使用 tar 打包整個目錄，並同步至 OCI Object Storage 或遠端伺服器。
更新升級：當官方發布新版本時，執行 docker compose pull 拉取最新鏡像，然後 docker compose up -d 重建容器。由於資料目錄獨立於容器，升級過程不會影響既有資料。
健康監控：可善用 OCI 的 Monitoring 服務，對執行個體的 CPU、記憶體及磁碟 IO 設定告警。同時，由於 OpenList 經由 Cloudflare Tunnel 發布，可以在 Cloudflare 儀表板設定 Availability 監控，確保外部存取正常。

若容器因不明原因停止，restart: unless-stopped 策略會自動嘗試重新啟動。如持續失敗，需檢查 cf_network 是否存在，以及掛載目錄的權限是否正確。

常見問題¶

問：容器啟動後立即退出，日誌顯示「network cf_network not found」。

答：表示 cf_network Docker 網絡尚未建立。請先執行 docker network create cf_network，或檢查 Compose 檔案中的 external: true 設定是否正確。

問：無法寫入資料目錄，或 Web 介面顯示唯讀錯誤。

答：由於 Compose 中設定了 user: '0:0'，容器以根使用者執行，理論上不會有權限問題。但若宿主機目錄掛載時有 SELinux 或 AppArmor 限制，可能需要調整安全策略。

問：如何變更 OpenList 的監聽連接埠？

答：OpenList 預設在容器內部連接埠 5244 上監聽。如需變更，可在 Compose 中加入 ports 對映，或修改容器內的環境變數。注意要同時更新 Cloudflare Tunnel 的服務設定。

問：升級新版本後功能異常，如何回滾？

答：在執行 docker compose pull 之前，先記錄當前鏡像的 digest（docker images --digests）。若升級後出現問題，可以使用 docker compose up -d --no-deps 配合指定舊版標籤或 digest 重新部署。

來源¶

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

OpenList¶

概述¶

架構¶

部署¶

配置¶

維運與監控¶

常見問題¶

相關鏈接¶

來源¶