Alist¶
概述¶
Alist 係一個多雲端儲存聚合網關，將本地磁碟、物件儲存、WebDAV 及各大雲端硬碟（例如 S3、阿里雲盤、OneDrive）統一收斂成單一 API 入口。喺 benhoweb.com 基礎設施入面，我哋採用 alist-custom:lrcfix 版本，主要係因為原版 image 未能滿足 LRC 歌詞修正嘅需求；lrcfix 版本加入咗歌詞字串正規化同時間軸偏移修正，令到透過 WebDAV 串流音樂時，播放器可以正確顯示歌詞。
Alist 喺成個生態系統擔當「儲存網關」角色。對內，佢連接唔同 storage driver；對外，佢提供 RESTful API 同 WebDAV 介面。標準 WebDAV 端點設於 https://alist.benhoweb.com/dav，下游服務包括 Rclone（伺服器間同步）同 Nextcloud（用戶檔案管理）。
架構¶
系統結構如下：
- 上游儲存端：本地檔案系統掛載至
/opt/docker/alist/data以外嘅目錄，經由 Alist storage driver 接入；雲端儲存則透過 API 或 S3 協定連接。 - Alist 核心容器：容器名
alist，內部預設監聽5244端口。容器無直接對外發布端口，所有外部流量經 Cloudflare Tunnel 轉發至http://alist:5244，減少攻擊面。 - 資料庫：Alist 本身支援 SQLite 或 PostgreSQL。喺我哋環境入面使用 PostgreSQL 16 儲存檔案元資料、帳戶設定及掛載快照，連接字串由 Infisical 注入，避免密碼硬編碼喺 Compose 檔案。
- 公網入口：Cloudflare Tunnel 終止 TLS，並將
alist.benhoweb.com流量轉發到容器網絡cf_network內嘅固定 IP172.21.0.43:5244。 - 下游消費端：
- Rclone 以
webdavremote 指向/dav，用於 nightly backup。 - Nextcloud 用「External storage」掛載同一 WebDAV 端點，整合用戶檔案。
- 內部工具直接調用 Alist API（端口僅限容器網絡內存取）。
cf_network 係外部 overlay network，IP 分配已鎖定，避免容器重建後 IP 漂移影響 Tunnel 配置。Tunnel 本身由獨立 daemon 管理，Alist 容器唔需要知道 Tunnel 存在。
部署（Docker Compose 片段）¶
採用 Docker Compose v3.8，容器以固定 IP 接入 cf_network，所有敏感值以環境變數注入：
version: '3.8'
services:
alist:
image: alist-custom:lrcfix-20260805
container_name: alist
environment:
- TZ=Asia/Hong_Kong
- PUID=0
- PGID=0
- UMASK=022
- DB_DSN=${ALIST_DB_DSN} # PostgreSQL 連接字串，由 Infisical 注入
- JWT_SECRET=${ALIST_JWT_SECRET}
volumes:
- /opt/docker/alist/data:/opt/alist/data
networks:
cf_network:
ipv4_address: 172.21.0.43
restart: unless-stopped
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
networks:
cf_network:
external: true
啟動流程：
docker compose pull
docker compose up -d
docker compose logs -f alist
首次啟動後，Alist 會自動初始化資料庫架構。管理員帳號透過 docker exec -it alist ./alist admin random 生成臨時密碼，之後登入 https://alist.benhoweb.com 修改。
配置與環境變數¶
| 變數 | 用途 |
|---|---|
TZ=Asia/Hong_Kong |
設定時區，確保日誌時間戳同排程任務同香港時間一致。 |
PUID=0 / PGID=0 |
以 root 身份運行，方便讀取 NFS/SMB 掛載點。若你 host 上嘅儲存目錄權限收緊，可以改用專屬 UID。 |
UMASK=022 |
預設檔案權限 755/644，避免 Alist 建立嘅暫存檔案被其他容器意外讀寫。 |
DB_DSN |
PostgreSQL 連接字串，格式：postgres://user:pass@postgres:5432/alist?sslmode=disable。 |
JWT_SECRET |
Alist API 簽發 Token 用，必須由 Infisical 管理並定期輪換。 |
Volume /opt/docker/alist/data 存放 Alist 自身設定檔、SQLite fallback 資料及暫存快取。若改用 PostgreSQL，則大部分資料庫內容唔會寫入呢個目錄，但備份依然要覆蓋成個資料夾，確保唔會遺失 config.json 附帶嘅 storage driver 秘密（例如雲端硬碟 refresh token）。
維運與監控¶
日常維運項目：
- 容器狀態：
docker ps | grep alist，確認 Restart 次數無持續上升。 - 健康檢查：用
curl -I https://alist.benhoweb.com/dav應該要收到200/401而非502。 - WebDAV 實測：
rclone lsd alist:測試讀取；rclone copy /tmp/test.bin alist:/測試寫入。 - PostgreSQL 連線數：使用
SELECT count(*) FROM pg_stat_activity;監察有無 connection leak。 - 日誌：
docker logs alist --since 1h | grep -i error。留意context deadline exceeded通常係某個雲端盤 upstream 超時，唔一定係 Alist 本身問題。 - 磁碟空間：
df -h /opt/docker/alist/data，特別係 lrcfix 歌詞索引快取，體積增長速度快，建議保留 space 監控。 - Infisical 輪換：每個月輪換一次 JWT_SECRET 同
DB_DSN，操作後docker compose up -d重建容器。 - Tunnel 健康：如果
alist.benhoweb.com回應 502，第一時間檢查cloudflared隧道狀態，而唔好淨係重啟 Alist。
常見問題¶
Q1：WebDAV 連線失敗，但 HTTPS 網頁正常。
通常係路徑問題。Rclone 盤設定 /dav 經常有尾斜線混淆，應設為 /dav/。另外 Alist 要求 WebDAV 請求包含正確認證 header，檢查設定有無漏咗 vendor（Rclone 選 other）。
Q2：某個雲端盤突然變成唯讀。
先登入 Alist 後台檢查對應 storage driver 是否仍然「有效」。如果係 refresh token 過期，喺 Infisical 更新 token，再喺 Alist 後台重新儲存，唔需要重啟容器。
Q3：容器重啟後 IP 變成 172.21.0.x 其他位址。
確認 Compose 網絡定義有無用 external: true，並確保無第二個容器佔用 .43。檢查：docker network inspect cf_network --format '{{json .Containers}}'。
Q4：LRC 歌詞修正無生效。
查 lrcfix 版本日誌：docker logs alist 2>&1 | grep lrcfix。如果歌詞來源係本機檔案，確保 .lrc 檔案編碼為 UTF-8；Big5 編碼歌詞要轉換後先放上掛載點。