Skip to content

Docker Compose 部署 Alist 完整教程 1

Alist Docker Compose 部署教程

本教程基于 AList 3.x（最新正式版），使用 Docker Compose 在 Linux/Windows 的 Docker 环境下实现快速、可持续的部署。
参考文档：

  • AList 主页（中文）[1]
  • 官方安装指南[6]
  • V3 版本说明[9]
  • GitHub 仓库[3]

1️⃣ 前置准备

步骤 说明 参考
1. 安装 Docker 若尚未安装，请先安装 Docker Engine（Desktop 或 Engine）
2. 安装 Docker Compose 版本 ≥ 1.29 或使用 docker compose 插件
3. 建立工作目录 建立一个专用于 Alist 的目录，例如 ~/alist 

mkdir -p ~/alist
cd ~/alist`

2️⃣ 写入 docker‑compose.yml

将以下内容复制到 ~/alist/docker-compose.yml（如已提供的文件）。

重要：锁定镜像版本，防止意外更新导致兼容性问题。

YAML

services:
  alist:
    image: xhofe/alist:v3.40.0      # 关键：锁定安全版本【3】
    container_name: alist
    volumes:
      - ./alist:/opt/alist/data      # 持久化文件与配置
    ports:
      - 5244:5244                    # 访问端口，支持自定义
    environment:
      - PUID=0                       # 运行用户（根）  建议非 root 运行时更改
      - PGID=0                       # 运行组
      - UMASK=022                    # 文件权限
    restart: unless-stopped

注意

  • ./alist 目录是宿主机的相对路径，用来保存 Alist 的数据库与配置。
  • 端口 5244 是默认端口，若已有同端口占用，可自行修改。
  • PUID / PGID 需要根据宿主机的用户 ID 与组 ID 设置；最安全做法是使用非 root 用户。

3️⃣ 启动 Alist

BASH

cd ~/alist
docker compose up -d

-d 代表后台执行。
第一时间可以查看日志验证启动成功：

BASH

docker compose logs -f alist   # 持续查看日志

当日志中出现 Listening on http://0.0.0.0:5244 时，即表示服务已上线。

4️⃣ 访问 & 账号初始化

  1. 浏览器访问

    TEXT

    http://<宿主机IP>:5244

第一次访问会弹出账号创建页面，默认邮箱为空，记得设置强密码。
  1. API 交互
    Alist 提供 RESTful 接口，可在后续脚本或工具中使用。参考官方 API 文档（在 docs/api）【9】。

5️⃣ 常用维护操作

操作 命令 说明
查看服务状态 docker compose ps
重启服务 docker compose restart alist
停止服务 docker compose down
清理旧镜像 docker image prune -a

6️⃣ 生产环境推荐配置

目标 推荐做法 说明
HTTPS 通过 Nginx 或 Caddy 反向代理，使用 Let’s Encrypt 自动证书 与 Alist 本身没有 HTTPS，需代理实现安全访问
备份 定期备份 ./alist/data 目录 保证配置与数据库不丢失
防火墙 仅开放 5244（或自定义端口） 防止外网直接访问
监控 使用 Prometheus + Grafana 监控 Docker 观察容器健康状态
版本控制 将 docker-compose.yml 保存在 Git 仓库 配合 CI/CD 自动升级

7️⃣ 常见问题排查

问题 解决思路
镜像拉取失败 检查网络、使用镜像镜像源（如阿里云 registry.cn-hangzhou.aliyuncs.com）
docker pull registry.cn-hangzhou.aliyuncs.com/xhofe/alist:v3.40.0
权限错误 确认宿主机 ./alist 目录的属主与 PUID/PGID 匹配
端口冲突 改 docker-compose.yml 中的 ports 部分，映射到其它空余端口
数据不保留 确保 ./alist 挂载路径存在且可写，容器内写入 /opt/alist/data

8️⃣ 下一步探索

  • 多存储插件：Alist 支持 S3、WebDAV、SMB 等，可在后台管理页面配置。
  • 文件分享：使用 Alist 提供的分享链接、二维码等功能。
  • API 自动化：结合 Cron、CI/CD 实现文件同步与自动部署。

祝你使用愉快 🚀

参考链接

  1. AList 主页（中文）https://alistgo.com/zh/
  2. 官方安装指南https://alistgo.com/zh/guide/install/
  3. GitHub 仓库（镜像信息）https://github.com/AlistGo/alist
  4. V3 版本说明https://alist-go.pages.dev/zh/guide/
  5. 多存储与功能介绍https://zhuanlan.zhihu.com/p/662035279