从零搭建你的网盘聚合神器：OpenList Docker Compose 部署全指南

前言

如果你是一个囤积松鼠，手握阿里云盘、百度网盘、Google Drive、OneDrive 等多个云盘账号，你一定有过在不同 App 之间来回切换的烦恼。

AList 是一款备受推崇的文件列表程序，它能将几十种网盘挂载到本地，像管理本地文件夹一样管理云端文件。而 OpenList 是基于 AList 源码的社区维护版本，旨在保持开源的纯粹性，去除商业化干扰。

今天这篇教程，将手把手教你使用 Docker Compose 部署 OpenList，并重点解决新版本中常见的权限报错问题。

为什么选择 Docker Compose？

相比于直接在物理机上运行二进制文件，Docker Compose 拥有以下优势：

配置即代码：所有配置写在一个文件里，迁移方便。
环境隔离：不会污染宿主机环境。
易于维护：升级、重启、日志查看只需一行命令。

准备工作

一台安装了 Docker 和 Docker Compose 的服务器（Linux/macOS/Windows 均可）。
SSH 连接工具。

第一步：创建项目目录

为了保持文件系统整洁，我们先创建一个存放配置文件的目录：

# 创建目录
mkdir -p ~/docker/openlist

# 进入目录
cd ~/docker/openlist

第二步：编写 docker-compose.yml

在目录下创建一个名为 docker-compose.yml 的文件。

vim docker-compose.yml
# 或者使用 nano docker-compose.yml

填入以下内容：

version: '3.8'

services:
  openlist:
    # 镜像地址，OpenList 官方镜像
    image: openlistteam/openlist:latest
    container_name: openlist
    # 容器崩溃或重启后自动重新启动
    restart: always
    ports:
      # 宿主机端口:容器端口
      - "5244:5244"
    volumes:
      # 挂载数据目录，持久化保存数据库和配置
      - ./data:/opt/openlist/data
    environment:
      # 设置特定用户 ID 运行（可选，配合下文权限设置）
      - PUID=1001
      - PGID=1001
      # 设置文件权限掩码
      - UMASK=022
      # 设置时区
      - TZ=Asia/Shanghai

第三步：解决“权限拒绝”报错（关键步骤！）

OpenList（以及新版 AList）为了安全性，默认不再使用 root 用户运行容器，而是使用 UID 为 1001 的普通用户。

如果你直接启动容器，Docker 会自动以 root 身份创建 ./data 目录，导致容器内的 1001 用户无法写入，从而出现如下报错并不断重启：

Error: Current user does not have write and/or execute permissions for the ./data directory...

解决方案（推荐）

我们在启动前，手动创建数据目录并修改其归属权：

# 1. 确保在 docker-compose.yml 同级目录下
# 2. 手动创建数据文件夹
mkdir -p data

# 3. 将文件夹的所有权交给 UID 1001 (OpenList 默认运行用户)
sudo chown -R 1001:1001 ./data

# 4. 赋予读写执行权限（双重保险）
sudo chmod -R 775 ./data

注意：即使你是在 Windows 的 Docker Desktop 上运行，通常不需要执行 chown，因为 Windows 的文件挂载机制不同。但在 Linux 上这一步是必须的。

第四步：启动服务

配置完成且权限修正后，执行启动命令：

docker compose up -d

等待几秒钟，查看容器状态：

docker compose ps

如果状态是 Up，说明启动成功。

第五步：初始化管理员密码

容器启动后，默认并没有显示密码。我们需要进入容器设置一个新密码。

执行以下命令（将 your_password 替换为你想要设置的密码）：

docker exec -it openlist ./openlist admin set your_password

看到输出 admin users setting success 即表示成功。

第六步：访问与使用

打开浏览器，访问：

http://你的服务器IP:5244

用户名：admin
密码：你刚才设置的密码

登录后，点击底部的“管理”，你就可以开始添加各种云盘账号了（阿里云盘、百度网盘、123网盘等）。

进阶配置：Nginx 反向代理（可选）

如果你想通过域名（如 pan.example.com）访问，而不是 IP:5244，可以使用 Nginx 进行反向代理。

在你的 Nginx 配置文件（server 块）中添加以下内容：

location / {
    proxy_pass http://127.0.0.1:5244;
    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;
    
    # 禁止客户端缓存，避免刷新不及时
    add_header Cache-Control no-cache;
}

常见问题与维护

1. 如何更新 OpenList？

使用 Docker Compose 更新非常简单：

# 拉取最新镜像
docker compose pull

# 重新创建容器（自动更新）
docker compose up -d

# 删除旧的无用镜像（可选）
docker image prune

2. 挂载的网盘下载速度慢？

OpenList 自身不存储文件，它只是做一个“链接转发”。

302 重定向模式：如果你在管理后台将网盘策略设置为 302 重定向，用户下载文件时会直接从云盘官方服务器下载，速度取决于用户本地带宽和云盘自身的限制（如百度网盘非会员限速），不消耗你的服务器流量。
本地代理模式：如果你开启了代理，流量会经过你的服务器中转。

结语

至此，一个私有的、支持多网盘聚合的 OpenList 就搭建完成了。无论是用来挂载阿里云盘看高清电影，还是挂载 Google Drive 同步工作文档，它都能完美胜任。

如果在部署过程中遇到问题，欢迎在评论区留言交流！