Use Docker

WARNING

It is highly recommended to deploy OpenList in an isolated environment using Docker. Otherwise, without security measures like SELinux or AppArmor, if your password is exposed, and hackers may gain access to all the files on your server.

WARNING

强烈建议使用 Docker 在隔离环境中部署 OpenList。否则，如果没有正确配置像 SELinux 或 AppArmor 这样的安全措施，假如您的密码暴露，黑客将可以访问您服务器上的所有文件。

Install ​

安装 ​

Docker CLI ​

Install Docker. And run the command below:

安装好 Docker 后，执行以下命令：

bash
docker run -d --restart=unless-stopped -v /etc/openlist:/opt/openlist/data -p 5244:5244 -e PUID=0 -e PGID=0 -e UMASK=022 --name="openlist" openlistteam/openlist:latest

Docker Compose ​

Create docker-compose.yml file.

创建 docker-compose.yml 文件。

bash
mkdir -p /opt/openlist
vim docker-compose.yml

Write the content below. Then save and exit.

写入以下内容，然后保存并退出：

yaml
# docker-compose.yml
services:
  openlist:
    image: 'openlistteam/openlist:latest'
    container_name: openlist
    volumes:
      - './data:/opt/openlist/data'
    ports:
      - '5244:5244'
    environment:
      - PUID=0
      - PGID=0
      - UMASK=022
    restart: unless-stopped

Run commands in the same path of docker-compose.yml file:

在 docker-compose.yml 相同目录下执行：

bash
docker compose pull
docker compose up -d

Env ​

环境变量 ​

NameDefaultDesc
PUID0User UID
PGID0User GID
UMASK022https://en.wikipedia.org/wiki/Umask
TZUTCDefault is the UTC time zone. If you want to specify a time zone, you can set this variable, for example: Asia/Shanghai.
RUN_ARIA2Whether to run ARIA2 concurrently, default is true if aria2 is pre-installed, otherwise it is false.
OPENLIST_ADMIN_PASSWORDSet the password of admin by environment variable
名称默认值说明
PUID0运行身份 UID
PGID0运行身份 GID
UMASK022https://en.wikipedia.org/wiki/Umask
TZUTC默认为 UTC 时区，如果你想指定时区，则可以设置此变量，例如：Asia/Shanghai
RUN_ARIA2是否同时运行 ARIA2，当镜像含有 aria2 环境时默认为 true，否则为 false
OPENLIST_ADMIN_PASSWORD通过环境变量指定管理员密码

Additionally, OpenList supports passing configuration through environment variables. The OpenList in the Docker image runs by default with the --no-prefix flag, so you don’t need to add the OPENLIST_ prefix.

You can view all available environment variables online in Go Packages.

此外，OpenList 支持将 配置 通过环境变量的方式传入。Docker 镜像中的 OpenList 默认使用 --no-prefix 参数运行，因此您无需添加 OPENLIST_ 前缀。

您可以在 Go Packages 中在线查看所有可以使用的环境变量。

https://pkg.go.dev/github.com/OpenListTeam/OpenList/v4/internal/conf#Config

Image Versions ​

镜像版本 ​

  • Stable version: openlistteam/openlist:latest or openlistteam/openlist:v*.*.*

    • Latest image version tag, please refer to https://hub.docker.com/r/openlistteam/openlist/tags

    • Some PaaS platforms do not support images larger than 100MB. Please use the lightweight image lite, for example: openlistteam/openlist:latest-lite. Otherwise, you may encounter the following error: Pod ephemeral local storage usage exceeds the total limit of containers 100Mi.

  • Dev version: openlistteam/openlist:beta

Pre-installed environment image suffix:

SuffixDesc
aioAn image that includes all of the following pre-installed environments.
ffmpegPre-installed FFmpeg image for generating thumbnail for local storage
aria2Pre-installed aria2 image for offline downloading.

You can append a suffix using the - symbol after any of the mirror tags to switch to an image with the corresponding environment. For example, openlistteam/openlist:latest-aio openlistteam/openlist:latest-aria2 openlistteam/openlist:latest-ffmpeg.

If the thumbnail generation function still does not work when using the pre-installed ffmpeg, please confirm:

  • You are using local storage
  • Switched to grid view
  • The thumbnail switch in local storage driver settings is enabled
  • The configuration path for the thumbnail cache folder in local storage is correct, for example, data/thumbnail

When using a pre-installed aria2 mirror, you might see errors like the following in the OpenList logs:

ERRO[2022-11-20 12:05:19] error [unaligned 64-bit atomic operation] while run task  [download http://xxx.com/xxx.png to [/ftp](/)]

The solution is, if the CPU architecture is 64-bit, you can try to manually pull a 64-bit image or rebuild the container. If the CPU architecture is 32-bit, there is currently no available solution.

  • 稳定版：openlistteam/openlist:latest or openlistteam/openlist:v*.*.*

    • 最新镜像版本 Tag，请参阅：https://hub.docker.com/r/openlistteam/openlist/tags

    • 部分容器运行平台不支持大于 100M 的镜像，请使用精简版镜像 lite，如：openlistteam/openlist:latest-lite，否则可能出现Pod ephemeral local storage usage exceeds the total limit of containers 100Mi.

  • 开发版：openlistteam/openlist:beta

预装环境镜像后缀:

后缀说明
aio同时包含下列所有预装环境的镜像
ffmpeg预装 ffmpeg 的镜像，用于本地存储缩略图
aria2预装 aria2 的镜像，用于离线下载

你可以在上述任意镜像标签后面，使用 - 符号附加后缀以切换到附带环境的镜像。如 openlistteam/openlist:latest-aio openlistteam/openlist:latest-aria2 openlistteam/openlist:latest-ffmpeg。

如果使用预装 ffmpeg 镜像缩略图功能仍无法使用，请确认:

  • 使用的是本地存储
  • 切换到网格视图
  • 本地存储的缩略图开关开启
  • 本地存储的缩略图缓存文件夹配置路径正确，例如 data/thumbnail

当使用预装 aria2 镜像时，可能会在 OpenList 的日志中看到类似错误：

ERRO[2022-11-20 12:05:19] error [unaligned 64-bit atomic operation] while run task  [download http://xxx.com/xxx.png to [/ftp](/)]

解决方法是，如果是 CPU 架构是 64 位，可以尝试手动拉取 64 位镜像或重新构建容器。 如果是 CPU 架构是 32 位，目前尚无可用方案。

See the admin’s info ​

查看管理员信息 ​

First run ​

首次运行 ​

bash
docker log openlist

You will see the admin password in the log.

你将在日志中看到密码。

INFO[2025-06-30 12:17:09] username: admin
INFO[2025-06-30 12:17:09] password: xYZabHGf

Not first run ​

非首次运行 ​

You can randomly generate or manually set

bash
# Randomly generate password
docker exec -it openlist ./openlist admin random

# Manually set password to `NEW_PASSWORD` (replace this)
docker exec -it openlist ./openlist admin set NEW_PASSWORD

您可以重新生成或手动设置密码。

bash
# 重新随机生成密码
docker exec -it openlist ./openlist admin random

# 手动设置密码为 `NEW_PASSWORD`（替换为您要设置的密码）
docker exec -it openlist ./openlist admin set NEW_PASSWORD

Update ​

更新 ​

Watchtower ​

If you find it troublesome, you can complete the update with a single line using Watchtower.

如果嫌麻烦，可以使用 Watchtower 一键更新。

bash
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower openlist --cleanup --run-once

If the container name is not named openlist, please replace it to the actual one.

如果您的容器名不是 openlist，请替换为实际的名称。

Docker CLI ​

bash
# View the container (find the ID of the OpenList container)
docker ps -a

# Stop running OpenList container instance, otherwise it cannot be deleted (this time the ID of the OpenList container is d429749a6e69, it is different for each installation)
docker stop ID

# Delete the OpenList container (the data is still there as long as you don't delete it manually)
docker rm ID

# Pull the latest image of OpenList
docker pull openlistteam/openlist:latest

# Enter the installation command
docker run -d --restart=unless-stopped -v /etc/openlist:/opt/openlist/data -p 5244:5244 -e PUID=0 -e PGID=0 -e UMASK=022 --name="openlist" openlistteam/openlist:latest
bash
# 查看容器（查找 OpenList 容器的 ID）
docker ps -a

# 停止运行中的 OpenList 容器实例，否则无法删除（此时 OpenList 容器的 ID 为 d429749a6e69，每次安装时不同）
docker stop ID

# 删除 OpenList 容器（只要不手动删除数据，数据仍然保留）
docker rm ID

# 拉取 OpenList 的最新镜像
docker pull openlistteam/openlist:latest

# 输入安装命令
docker run -d --restart=unless-stopped -v /etc/openlist:/opt/openlist/data -p 5244:5244 -e PUID=0 -e PGID=0 -e UMASK=022 --name="openlist" openlistteam/openlist:latest
docker

Docker Compose ​

Enter the same path of docker-compose.yml file and run:

进入 docker-compose.yml 相同目录，然后运行：

bash
docker compose pull
docker compose down
docker compose up -d

Contributors

Edit this page on GitHub

Last updated: