Alist

Overview

Alist 係一套開放原始碼嘅檔案列表工具，以網頁介面為主軸，將多種唔同類型嘅儲存空間聚合喺同一個入口。使用者可以透過瀏覽器瀏覽、搜尋、預覽及分享檔案，亦可以啟用 WebDAV 服務，令桌面電腦嘅檔案管理員、流動應用程式或第三方工具，都可以用標準 WebDAV 協定存取同一批檔案。

本百科頁描述嘅係部署喺 Oracle Cloud 上嘅自托管 Alist 服務。佢使用 Docker Compose 管理，映像名稱係 alist-custom:lrcfix-20260805，即係以官方 Alist 為基礎，再加入 LRC 歌詞修正功能嘅自訂映像；適合用於音樂庫、影片字幕或需要同步顯示歌詞嘅多媒體檔案管理場景。

Alist 本身支援本地磁碟、S3 物件儲存、OneDrive、Google Drive、阿里雲盤、FTP、WebDAV 等多種儲存後端，所以喺 Oracle Cloud 上部署一個實例，就可以集中管理分散喺唔同供應商嘅檔案。由於係自托管服務，所有配置、帳號資料同檔案索引都掌握喺管理員自己手中。

Architecture

呢套 Alist 部署採取單一容器架構，所有服務都執行喺名為 alist 嘅 Docker Container 入面。容器命名固定，方便其他容器或反向代理透過 Docker DNS 或指定 IP 存取。資料目錄採用 Bind Mount，將 Host 上嘅 /opt/docker/alist/data 對應到容器內嘅 /opt/alist/data，令容器重建或者升級之後，配置、SQLite 資料庫同日誌仍然可以保留。

網絡方面，容器加入咗外部 Docker Network cf_network，並指定 ipv4_address: 172.21.0.43。呢個做法係為咗令容器喺 Docker Network 內有固定 IP，方便 Cloudflare Tunnel、Nginx Reverse Proxy 或者其他容器以穩定嘅位址連接 Alist。外部網絡必須預先建立，否則 Docker Compose 會因為找不到 cf_network 而拒絕啟動。

容器內設定咗 TZ=Asia/Hong_Kong，確保日誌、WebUI 嘅時間顯示同香港時間一致。PUID=0 同 PGID=0 表示容器主程序以 root 身份執行，主要係為咗避免因 Host 目錄權限不足而導致讀寫失敗。UMASK=022 則令新建立嘅檔案預設具有 755 目錄權限同 644 檔案權限，方便同一 Host 上其他服務讀取。

Oracle Cloud 方面，VM 嘅 Security List 同 firewall 需要按實際用途開放連接埠。如果 Alist 只透過 Cloudflare Tunnel 對外提供服務，就唔需要直接開放 5244 連接埠。若果想以 IP 直連方式存取，就必須喺 Oracle Cloud Console 同 VM 內嘅 iptables/firewalld 一併放行。

Deployment

部署前需要確認 Host 已經安裝 Docker Engine 同 Docker Compose Plugin。首先建立資料目錄：

mkdir -p /opt/docker/alist/data

然後建立 docker-compose.yml，內容如下：

version: '3.8'

services:
  alist:
    image: alist-custom:lrcfix-20260805
    container_name: alist
    environment:
      - TZ=Asia/Hong_Kong
      - PUID=0
      - PGID=0
      - UMASK=022
    volumes:
      # 左側為 Host 路徑，請根據你實際存放 Docker 資料的習慣修改
      - /opt/docker/alist/data:/opt/alist/data
    networks:
      cf_network:
        ipv4_address: 172.21.0.43
    restart: unless-stopped

networks:
  cf_network:
    external: true

啟動服務：

docker compose up -d

檢查容器狀態：

docker compose ps

如果未建立 cf_network，需要先手動建立：

docker network create -d bridge --subnet=172.21.0.0/24 cf_network

建立時要確保 IP Range 包含 172.21.0.43，而且無其他容器佔用呢個位址。若果 cf_network 已經存在，可以用 docker network inspect cf_network 檢查目前配置。

Configuration

Alist 嘅主要配置並唔係完全透過環境變數控制，而係由容器內嘅 /opt/alist/data 目錄保存。該目錄包含 SQLite 資料庫、config.json 設定檔同 log 目錄。第一次啟動之後，管理員可以登入網頁後台，加入各種儲存驅動器、設定分享連結、配置 WebDAV 使用者及修改介面主題。

環境變數方面，TZ 控制時區；PUID 同 PGID 決定容器內檔案操作嘅使用者身份；UMASK 控制新檔案權限。呢套部署使用 PUID=0 同 PGID=0，即係 root。呢個設定可以有效避免權限問題，但需要注意安全風險。如果 Host 上已有專用使用者，可以將 PUID/PGID 改為該使用者嘅 UID/GID，然後將 /opt/docker/alist/data 嘅 owner 一併調整。

首次使用時，需要設定管理員密碼。可以執行：

docker exec -it alist ./alist admin set YOUR_PASSWORD

若果想由系統隨機產生密碼，則執行：

docker exec -it alist ./alist admin random

之後喺瀏覽器開啟 http://<server_ip>:5244，登入後就可以開始新增儲存後端。Alist 支援非常多類型嘅雲端硬碟同物件儲存，例如 S3、OneDrive、Google Drive、阿里雲盤、FTP 等等。每個後端都可以獨立設定掛載路徑、快取時間同存取權限。

網絡配置方面，由於容器使用固定 IP 172.21.0.43，如果同一 cf_network 上仲有其他容器要連接 Alist，可以直接使用 http://172.21.0.43:5244 作為 Target。對外則建議交由 Cloudflare Tunnel 或 Nginx 等反向代理處理 HTTPS 終止，避免喺 Alist 容器內直接處理 TLS 證書。

Operations

日常操作主要透過 docker compose 完成。

停止服務：

docker compose down

啟動服務：

docker compose up -d

重啟服務：

docker compose restart alist

查看日誌：

docker logs -f alist

查看容器詳細狀態：

docker inspect alist

備份好重要，因為 Alist 嘅儲存後端配置同帳號資料全部記錄喺 SQLite 資料庫入面。建議定期停機備份整個 /opt/docker/alist/data 目錄：

docker stop alist
tar -czf alist-backup-$(date +%Y%m%d).tar.gz /opt/docker/alist/data
docker start alist

如果容器報錯或者無法啟動，可以檢查 docker compose config 確認 YAML 格式，再用 docker logs alist 睇錯誤訊息。常見問題包括 cf_network 未建立、IP 位址衝突、資料目錄權限不足，以及自訂映像本身嘅執行環境有缺漏。

升級方面，如果 alist-custom:lrcfix-20260805 有新版映像，可以先備份資料，再拉取新映像並重新建立容器：

docker compose pull
docker compose up -d

對於自訂映像，可能需要在本地重新 Build，並沿用同一個 Tag 或更新 Tag 後再修改 docker-compose.yml。

FAQ

問：點解要部署喺 Oracle Cloud？
Oracle Cloud 提供 Always Free 嘅 ARM VM，有足夠資源運行 Alist。自托管方式令檔案索引同帳號資料唔需要依賴第三方服務，管理員可以完全控制。

問：172.21.0.43 係咪永遠固定？
只要 cf_network 冇被刪除，而且無其他容器搶佔同一個 IP，Docker Compose 每次重建容器都會按照配置分配同一個 IP。若果網絡重建，就需要確保新 subnet 包含呢個位址。

問：點樣透過互聯網安全存取 Alist？
建議使用 Cloudflare Tunnel，將 cf_network 上嘅 Alist 服務以 http://172.21.0.43:5244 作為 upstream，再由 Cloudflare 提供 HTTPS 同存取控制。Oracle Cloud 嘅 Security List 只需要開放 Cloudflare Tunnel 所需連線即可。

問：PUID/PGID 設做 0 會唔會有問題？
任何以 root 執行嘅服務都有潛在風險。如果 Host 環境本身已有防火牆同最低權限原則，可以建立專用使用者並修改 /opt/docker/alist/data 嘅 owner，然後將 PUID/PGID 改做該使用者嘅 ID。

問：點樣更新管理員密碼？
喺 Host 上執行：

docker exec -it alist ./alist admin set NEW_PASSWORD

更新後立即生效，無需要重啟容器。

Related Links

• docker
• litellm
• oracle-cloud
• cloudflare-tunnel
• WebDAV
• proxy

Source

Coverage auto (container scan)