Skip to content

Docker Compose 部署 Alist 完整教程

本文将详细介绍如何使用 Docker Compose 快速部署 Alist，一个支持多种存储的开源网盘聚合工具。

一、Alist 简介

Alist 是一款开源跨平台网盘聚合与文件管理工具，基于 Gin+Solidjs 开发，支持网页浏览与 WebDAV 协议。它可将本地磁盘、阿里云盘、OneDrive、Google Drive、百度网盘等多种存储统一到一个界面，实现跨平台文件统一管理与高效访问。

核心优势

  • 统一管理：在一个界面操作多个网盘与本地存储，减少切换成本

  • 高效便捷：WebDAV 挂载与在线预览显著提升文件处理速度

  • 安全可控：多重权限与加密方式保障数据安全与隐私

  • 开源免费：AGPL-3.0 协议，可自由使用与定制

  • 多端兼容：支持 Windows、macOS、Linux、Docker、路由器（OpenWrt）等

二、部署前准备

1. 环境要求

  • 已安装 Docker 和 Docker Compose

  • 系统内存：至少 512MB（建议 1GB 以上）

  • 磁盘空间：根据存储需求而定

2. 环境检查

在终端中执行以下命令，确认 Docker 环境正常：

bash

# 检查 Docker 版本
docker --version

# 检查 Docker Compose 版本
docker-compose --version

若未安装，请参考 Docker 官方文档进行安装。

3. 创建项目目录

建议创建独立的目录来管理 Alist 配置和数据：


bash

# 创建项目目录
mkdir -p /opt/docker/alist
cd /opt/docker/alist

三、Docker Compose 配置

1. 编写 docker-compose.yml

创建 docker-compose.yml 文件，内容如下：

yaml

#version: '3.3'
services:
  alist:
    image: xhofe/alist:v3.40.0 # 关键：锁定安全版本
    container_name: alist
    volumes:
      - ./alist:/opt/alist/data
    ports:
      - 5244:5244
    environment:
      - PUID=0
      - PGID=0
      - UMASK=022
      - TZ=Asia/Shanghai
    restart: unless-stopped

2. 配置参数说明

  • image: xhofe/alist:v3.40.0 - 使用固定的稳定版本，避免自动更新导致的不兼容问题

  • volumes: ./alist:/opt/alist/data - 数据持久化挂载，确保配置和数据安全

  • ports: 5244:5244 - 端口映射，前者为主机端口，可自定义修改

  • environment:

    • PUID=0 和 PGID=0 - 以 root 权限运行，确保文件访问权限

    • UMASK=022 - 控制新创建文件的默认权限

    • TZ=Asia/Shanghai - 设置容器时区

  • restart: unless-stopped - 自动重启策略，确保服务高可用

四、部署与启动

1. 启动 Alist 服务

在 docker-compose.yml 文件所在目录执行：

bash

# 后台启动服务
docker-compose up -d

2. 检查服务状态

bash

# 查看容器运行状态
docker ps

# 查看服务日志
docker logs alist

当看到容器正常运行时，表示 Alist 已成功启动。

五、初始配置

1. 获取管理员密码

Alist 启动后，需要获取或设置管理员密码：


bash

# 查看管理员信息（适用于 v3.25.0 及以上版本）
docker exec -it alist ./alist admin

对于更新的版本，可以使用以下命令：


bash

# 生成随机密码
docker exec -it alist ./alist admin random

# 或手动设置密码
docker exec -it alist ./alist admin set 你的新密码

2. 访问管理界面

  1. 打开浏览器，访问 http://localhost:5244（如修改了端口，请使用实际端口）

  2. 输入前面获取的用户名（一般为 admin）和密码

  3. 成功登录后进入 Alist 管理后台

3. 添加存储策略

在管理面板中，可以添加多种存储方式：

  1. 进入 存储 → 添加

  2. 选择存储类型（支持阿里云盘、OneDrive、Google Drive 等 20+ 种存储服务）

  3. 根据指引配置相应参数

  4. 保存并启用存储

六、功能使用

1. WebDAV 访问

Alist 支持 WebDAV 协议，可以通过客户端连接：

  • WebDAV 地址：http://你的IP:5244/dav

  • 用户名/密码：与 Web 端相同

2. 文件预览

支持 PDF、Office、视频、音频、图片、代码等多种格式的在线预览，无需下载即可查看。

3. 外网访问配置

方案一：直接暴露端口

确保服务器安全组开放 5244 端口，通过 http://<公网IP>:5244 访问。

方案二：Nginx 反向代理（推荐）

配置 Nginx 反向代理并添加 SSL 证书：


nginx

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;

    location / {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Range $http_range;
        proxy_set_header If-Range $http_if_range;
        proxy_redirect off;
        proxy_pass http://127.0.0.1:5244;
        client_max_body_size 20000m;
    }
}

七、维护与管理

1. 服务停止与启动


bash

# 停止服务
docker-compose down

# 启动服务
docker-compose up -d

# 重启服务
docker-compose restart

2. 数据备份

定期备份 ./alist 目录，该目录包含所有配置信息和本地存储数据：


bash

# 备份数据
tar -czf alist-backup-$(date +%Y%m%d).tar.gz ./alist

3. 版本更新

如需更新到新版本，建议按以下步骤操作：


bash

# 停止当前服务
docker-compose down

# 修改 docker-compose.yml 中的镜像版本
# 将 image: xhofe/alist:v3.40.0 更新为目标版本

# 重新拉取镜像并启动
docker-compose pull
docker-compose up -d

注意：更新前请确保已备份数据，版本跨度较大时建议查阅更新日志。

八、常见问题排查

问题现象 解决方法
端口冲突 修改 docker-compose.yml 中的端口映射，如 - 5255:5244
时区错误 确保环境变量中设置了 TZ=Asia/Shanghai
密码丢失 使用 docker exec -it alist ./alist admin random 重置
权限不足 检查挂载目录权限，确保容器有读写权限
无法上传大文件 检查磁盘空间和 Web 服务器客户端上传大小限制

九、安全建议

  1. 定期更新：关注 Alist 版本更新，及时修复安全漏洞

  2. 强密码策略：设置复杂的管理员密码并定期更换

  3. 网络安全：如对外提供服务，建议使用 Nginx 反向代理并配置 SSL 加密

  4. 权限控制：根据实际需要配置适当的访问权限

  5. 日志监控：定期检查系统日志，发现异常访问行为

通过以上步骤，您已经成功使用 Docker Compose 部署了 Alist，并可以开始统一管理您的各种云存储和本地文件。如有更多高级需求，可参考 Alist 官方文档进一步探索。