OpenList Docker 部署与升级完全指南

type

status

date

slug

summary

版本说明

从 v4.1.0 版本之后（不包含 v4.1.0），OpenList 镜像进行了重要调整：

移除了 PUID 和 PGID 环境变量

新增了 专用用户 openlist（UID 1001）和组 openlist（GID 1001）

OpenList 服务使用该用户运行

💡

权限处理要点 您需要手动处理映射目录的权限，确保容器内的 openlist(1001) 用户有权限访问映射的目录。也可以通过 --user UID:GID 参数指定运行用户。

Docker CLI 部署

准备工作：配置目录权限

在启动容器前，需要先创建数据目录并配置正确的权限：

💡

为什么是 1001:1001？ 从 v4.1.0 之后的版本，OpenList 容器内使用专用的 openlist 用户（UID 1001）和组（GID 1001）运行服务。手动配置权限可以确保容器有正确的文件访问权限。

快速启动

配置好权限后，运行以下命令启动 OpenList：

参数说明

参数	说明
`-v $PWD/openlist:/opt/openlist/data`	数据持久化目录映射
`-p 5244:5244`	端口映射（宿主机:容器）
`-e UMASK=022`	文件权限掩码
`--restart=unless-stopped`	容器自动重启策略

⚠️

注意新版本不再使用 PUID 和 PGID 环境变量。权限需要通过手动配置目录所有权来实现，或使用 --user 参数指定运行用户。

Docker Compose 部署

准备工作：配置目录权限

同样需要先配置权限：

创建配置文件

创建 docker-compose.yml 文件：

启动服务

权限配置

方法一：修改目录权限

方法二：使用自定义用户

在 Docker 命令中添加 --user 参数：

或在 docker-compose.yml 中添加：

升级 OpenList

Docker CLI 升级

Docker Compose 升级

一键升级脚本

创建 `upgrade.sh` 脚本：

赋予执行权限并运行：

初始配置

获取初始密码

首次启动后，查看日志获取初始管理员密码：

查找类似以下内容：

访问管理界面

打开浏览器访问：`http://服务器IP:5244`

用户名：admin

密码：日志中显示的初始密码

🔐

安全建议 首次登录后请立即修改管理员密码！在管理界面的"设置" → "用户"中修改。

常见问题

1. 权限错误

问题：容器无法写入数据目录

解决：

2. 端口冲突

问题：5244 端口已被占用

解决：修改端口映射

3. 容器无法启动

问题：容器启动后立即退出

解决：

4. 升级后数据丢失

问题：升级后配置和数据不见了

原因：数据卷映射路径错误

解决：确保使用相同的数据卷路径 -v $PWD/openlist:/opt/openlist/data

进阶配置

使用外部数据库

编辑 $PWD/openlist/config.json：

配置反向代理

Nginx 配置示例：

总结

通过本教程，您已经学会了：

✅ 使用 Docker CLI 和 Docker Compose 部署 OpenList ✅ 正确配置文件权限 ✅ 升级 OpenList 到最新版本 ✅ 处理常见问题 ✅ 进行进阶配置

OpenList 提供了强大的文件管理功能，结合 Docker 部署让维护更加便捷。祝您使用愉快！🎉

版本说明

Docker CLI 部署

准备工作：配置目录权限

快速启动

参数说明

Docker Compose 部署

准备工作：配置目录权限

创建配置文件

启动服务

权限配置

方法一：修改目录权限

方法二：使用自定义用户

升级 OpenList

Docker CLI 升级

Docker Compose 升级

一键升级脚本

初始配置

获取初始密码

访问管理界面

常见问题

1. 权限错误

2. 端口冲突

3. 容器无法启动

4. 升级后数据丢失

进阶配置

使用外部数据库

配置反向代理

相关资源

总结

Orz