一、OpenList 是什么

OpenList 是 AList 的社区开源分支，用 Gin + SolidJS 写成，AGPL-3.0 协议。AList 原项目被商业公司收购后，社区出于治理与信任考虑 fork 出了 OpenList，用法、配置、数据目录与 AList V3 基本兼容，老的 AList 用户把 data 目录拷过来就能迁移。

它能做的事：

• 挂载 40+ 种存储：本地磁盘、阿里云盘、OneDrive、Google Drive、115、天翼云盘、S3、FTP/SFTP、WebDAV 等；

• 统一成一个网页文件列表，支持在线预览视频、音频、图片、PDF、Office、epub；

• 把挂载的内容再以 WebDAV / S3 / FTP 的方式对外提供，等于自建一个网盘中转层；

• 支持离线下载（aria2）、缩略图（ffmpeg）、目录加密（元信息密码）、多用户与权限。

版本信息：本文基于 v4.2.x（2026 年 9 月最新稳定版为 v4.2.6）编写，Docker 镜像为 openlistteam/openlist，默认 Web 端口 5244，S3 端口 5246，WebDAV 根路径 /dav。

v4.1.0 之后的版本在 Docker 部署时建议显式指定 user: "UID:GID"，否则挂载目录可能出现写入权限问题。用 1Panel 应用商店安装时，镜像里已经处理好了，一般不用操心。

二、整体架构与前置准备

先明确流量是怎么走的，后面排错才不会瞎猜：

用户浏览器 ──HTTPS(443)──▶ OpenResty（1Panel，宿主机）
                              │  反代 + SSL 卸载 + 强制跳转
                              ▼
                      http://127.0.0.1:5244 ──▶ OpenList 容器
                                                    │
                                                    ▼
                                        各类网盘 / 本地磁盘 / S3

关键设计：OpenList 的 5244 端口只监听在 127.0.0.1，公网唯一入口是 OpenResty 的 443。这样既不用为 OpenList 单独配证书，也不会把管理后端裸奔在公网。

前置清单

端口规划建议：

先确认系统版本与防火墙状态：

lsb_release -a
sudo ufw status
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

云厂商机器还要在安全组里放行 80/443，这是最常见的一次性踩坑点：系统防火墙开了，云控制台没开，证书申请照样失败。

三、安装 1Panel

用官方一键脚本，全程自动（会自动安装 Docker 与 Docker Compose）：

bash -c "$(curl -sSL https://resource.fit2cloud.com/1panel/package/v2/quick_start.sh)"

安装完成后终端会输出三样东西，务必复制保存：

• 面板访问地址（http://<IP>:<端口>/<安全入口>）

• 初始用户名

• 初始密码

安装完立刻做三件加固的事：

1. 改掉默认用户名和密码：面板设置 → 用户 → 修改用户名/密码。

2. 修改面板端口与安全入口：面板设置 → 安全，改端口并开启入口地址（避免被全网扫描器直接撞面板登录页）。

3. 开启两步验证（若版本支持）：面板设置 → 安全 → MFA，用 Authenticator App 绑定。

1Panel 的面板端口建议不要保留默认。改完端口记得在系统防火墙放行新端口，否则会把自己锁在门外。

四、安装 OpenResty 与 OpenList

4.1 安装 OpenResty

左侧菜单 应用商店 → 搜索 OpenResty → 安装，参数全部保持默认即可（1Panel 的 OpenResty 默认使用 host 网络，能直接反代到 127.0.0.1）。

第一次进入「网站」菜单时，如果还没装 OpenResty，1Panel 会主动提示安装，按提示一键装完就行。

4.2 安装 OpenList

应用商店 → 搜索 openlist → 点击卡片 → 安装。安装参数说明：

点「确认」后等 1～2 分钟，镜像拉取并启动完成。装完可以在「已安装」里看到 OpenList，状态应为「已启动」。

为什么要关掉端口外部访问？ 勾选后 Docker 会把 0.0.0.0:5244 映射到公网，任何人都可能直接撞你的登录页；关掉后只绑定 127.0.0.1:5244，公网唯一入口是带证书的 OpenResty，安全性和整洁度都更好。万一已经勾了，去「容器 → 编辑 compose 文件」把端口改成 127.0.0.1:5244:5244 再重启即可。

五、初始化：设置管理员密码

OpenList 首次启动会随机生成一个 admin 密码，正式使用前必须自己设一个。

方式一：容器终端（最省事）

左侧 容器 → 找到 OpenList 容器 → 终端 → 连接，执行：

# 手动设置密码（推荐）
./openlist admin set 'Your_Strong_Password_123'
​
# 或者让它生成随机密码
./openlist admin random

方式二：宿主机用 docker exec

docker ps --format '{{.Names}}\t{{.Image}}' | grep -i openlist
docker exec -it 1Panel-openlist-xxxx sh -c "./openlist admin set 'Your_Strong_Password_123'"

如果提示找不到可执行文件，先定位一下：

docker exec -it 1Panel-openlist-xxxx sh -c "find / -maxdepth 3 -name openlist -type f"

然后用绝对路径执行，比如 /opt/openlist/openlist admin set '密码'。

方式三：直接看初始日志（仅用于临时登录）

docker logs 1Panel-openlist-xxxx 2>&1 | grep -i -E 'password|admin'

密码里如果包含 $、!、单引号这类字符，一定要用单引号包住，否则会被 shell 解释掉。设完密码后回到容器列表确认状态正常，然后访问 http://<服务器IP>:5244（此时只有内网能开）验证一次，用户名是 admin。

六、用 OpenResty 做反向代理

6.1 面板可视化创建

网站 → 创建网站 → 类型选 反向代理：

• 主域名：openlist.example.com

• 代理地址：http://127.0.0.1:5244

• 其他保持默认 → 确认

记得提前把域名解析到服务器（A 记录，纯 IPv6 机器用 AAAA 记录）。

6.2 补齐关键请求头（重点）

这是全文最容易翻车的一步。1Panel 生成的默认反代头不够用，必须补齐下面几条：

在「网站 → 设置 → 反向代理 → 编辑」里填好，或者直接在「配置文件」里改成下面这段（推荐，一次到位）：

location ^~ / {
    proxy_pass http://127.0.0.1:5244;
​
    # —— 基础转发头 ——
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Forwarded-Port $server_port;
​
    # —— 视频拖动 / 断点续传，必须加 ——
    proxy_set_header Range $http_range;
    proxy_set_header If-Range $http_if_range;
​
    proxy_redirect off;
    proxy_http_version 1.1;
​
    # —— 大文件上传 ——
    client_max_body_size 20000m;
    proxy_request_buffering off;
​
    # —— 可选：流式传输，看视频/下大文件更稳 ——
    proxy_buffering off;
}

改完点保存，1Panel 会自动校验并重载 OpenResty。等价的命令行操作：

docker exec -it 1Panel-openresty-xxxx openresty -t
docker exec -it 1Panel-openresty-xxxx openresty -s reload

坑：页面白屏 / js、css 404。 如果你的站点配置里存在类似 location ~ .*\.(js|css)?$ 或 location ~ .*\.(gif|jpg|png)$ 的静态资源拦截规则（某些面板模板会自带），OpenList 的前端资源会被拦掉导致白屏。解决办法是直接删除或注释掉这几段 location，让所有请求都走反代。

七、申请 SSL 证书并开启 HTTPS

7.1 创建 ACME 账户

网站 → 证书 → ACME 账户 → 创建账户：

• 邮箱：填真实邮箱（Let's Encrypt 到期提醒会用）

• 类型：Let's Encrypt

• 密钥算法：EC 256（比 RSA 2048 更短更快，兼容性也没问题）

7.2 选择验证方式

DNS 验证需要先在 证书 → DNS 账户 里添加服务商 API 密钥。以阿里云为例，去 RAM 控制台创建一个「只授权 DNS 修改权限」的子账号 AccessKey，填进去即可，不要直接用主账号 AK。

7.3 申请证书

证书 → 申请证书：

• 主域名：openlist.example.com

• 其他域名：可以填 *.example.com（仅 DNS 验证支持）

• ACME 账户：选刚才创建的

• 验证方式：HTTP 或 DNS

• 勾选「自动续签」

点确认后等 1～2 分钟，日志出现「申请证书成功」即可。

7.4 站点启用 HTTPS

回到 网站 → 设置 → HTTPS：

• 启用 HTTPS：开

• SSL 选项：选择已有证书 → 选中刚才申请的

• （或）Acme 账户：选中账户后由面板自动申请

• HTTP 选项：访问 HTTP 自动跳转到 HTTPS

• 支持协议：勾选 HTTP/2（有性能收益）

保存后，访问 https://openlist.example.com，地址栏出现小锁，HTTP 访问会自动 301 到 HTTPS。

验证一下证书信息：

echo | openssl s_client -connect openlist.example.com:443 -servername openlist.example.com 2>/dev/null \
  | openssl x509 -noout -issuer -dates

Let's Encrypt 单证书有效期 90 天，1Panel 的自动续签会在到期前自动完成，只要「自动续签」勾了就不用管。如果续签失败，面板会发邮件提醒，通常是 80 端口被占或 DNS API 失效。

八、OpenList 侧的收尾设置

反代和证书都通了，还有一步必须做：告诉 OpenList 它对外叫什么名字。

管理后台 → 设置 → 站点：

• 站点 URL：填 https://openlist.example.com

• 保存后重启 OpenList 容器才会生效（设置项里也可以点重启）

这一步不做的话，OpenList 生成的分享链接、直链、WebDAV 地址都会是 http://127.0.0.1:5244/...，外面根本打不开。

其他建议顺手调整的全局设置（设置 → 全局）：

• 隐藏文件：填常见垃圾文件规则，如 /.__thumb\n/.DS_Store\n/Thumbs.db\n/@eaDir

• 直链签名（sign all）：对外分享建议开启，防止直链被滥用

• 包下载 / 批量下载：家里带宽够就开着，方便整目录打包

• 预览设置：按需要开启 office/pdf 预览（需要后端服务支持）

WebDAV 地址此时为：https://openlist.example.com/dav，用 admin 账号密码即可连接。

九、OpenList 日常管理操作手册

9.1 密码与账号

# 改管理员密码（容器终端内执行）
./openlist admin set 'New_Password'

# 生成随机密码
./openlist admin random

# 忘记密码 / 2FA 设备丢失（按实际版本命令为准）
./openlist cancel2FA

日常建议：

• 不要长期使用 admin 做日常访问，新建普通用户只给只读权限；

• 后台 用户 → 编辑 里可以限制该用户「允许访问的路径」，比如只允许看 /媒体库；

• 开启两步验证（个人设置里绑定 TOTP）。

9.2 存储管理

管理 → 存储 → 添加：

常用操作：

• 刷新缓存：存储列表右侧「重新加载」，网盘内容变了但页面没变就用它；

• 禁用：临时下架某个挂载，不用删配置；

• 删除：会连带删除该存储下的索引数据，注意先确认。

网盘类驱动最常出的问题是刷新令牌过期。症状是挂载还在、打开报 401/获取失败，解决方法是重新获取 refresh_token 填回去。

9.3 用户与权限

• 用户 → 新建：填用户名密码，选择角色（管理员 / 普通用户）；

• 权限粒度靠「允许的路径」控制，多个路径用换行分隔；

• WebDAV 客户端建议用一个只读专用账号，避免客户端把主账号密码同步到多处。

9.4 目录加密（元信息）

给某个目录加密码：管理 → 元信息 → 添加，路径填 /媒体库/私密，勾选「密码」并填写，保存后访问该目录就需要输入密码。

同一个界面还能设置：隐藏子目录、只读、上传白名单、自定义 header/说明文案。

9.5 备份与迁移

方式一：内置备份（推荐日常用）

管理 → 备份 & 恢复：

• 点「备份」导出数据（不含索引），可以填加密密码；

• 恢复时选择文件、勾选「覆盖」即可还原用户信息与存储配置。

方式二：直接备份 data 目录（迁移必备）

OpenList 的全部状态都在数据目录里，1Panel 安装的默认位置是：

/opt/1panel/apps/openlist/openlist/data

核心文件是 data.db（SQLite：用户、存储、设置），以及索引目录。官方提醒：如果存在 data.db-shm 和 data.db-wal，必须一起备份，最好先停容器让 WAL 合并回主库。

一个可直接用的备份脚本：

#!/usr/bin/env bash
# /opt/1panel/apps/openlist/openlist/backup_openlist.sh
set -euo pipefail

DATA_DIR="/opt/1panel/apps/openlist/openlist/data"
BACKUP_DIR="/opt/backup/openlist"
KEEP_DAYS=7

mkdir -p "$BACKUP_DIR"
STAMP=$(date +%F-%H%M)
tar -czf "$BACKUP_DIR/openlist-$STAMP.tar.gz" -C "$DATA_DIR" .
find "$BACKUP_DIR" -name "openlist-*.tar.gz" -mtime +"$KEEP_DAYS" -delete
echo "[$(date)] backup done: $BACKUP_DIR/openlist-$STAMP.tar.gz"

挂个定时任务（每天凌晨 4 点）：

sudo chmod +x /opt/1panel/apps/openlist/openlist/backup_openlist.sh
(crontab -l 2>/dev/null; echo "0 4 * * * bash /opt/1panel/apps/openlist/openlist/backup_openlist.sh >> /var/log/openlist-backup.log 2>&1") | crontab -

迁移时把备份包拷到新机器，停掉新 OpenList，解压覆盖 data 目录，再启动即可——这也是 AList V3 迁移到 OpenList 的标准做法。

9.6 版本升级

1Panel 升级（推荐）：应用商店 → 已安装 → OpenList → 升级 → 选目标版本 → 确认。面板会自动拉新镜像并重建容器，data 目录挂载卷不受影响。

手动升级（compose 部署）：

cd /opt/1panel/apps/openlist/openlist
docker compose pull
docker compose up -d
docker image prune -f

升级前两件事：备份 data 目录；看一下 release notes 里有没有 breaking changes（4.2.x 有过驱动字段规范化这类改动）。

9.7 日志与状态检查

# 实时看容器日志
docker logs -f --tail 200 1Panel-openlist-xxxx

# 容器内服务端口是否活着
docker exec 1Panel-openlist-xxxx sh -c "wget -qO- http://127.0.0.1:5244/api/me || echo 'no response'"

# 站点健康
curl -I https://openlist.example.com

后台 管理 → 任务 可以看离线下载、复制、上传任务的执行情况与失败原因。

9.8 命令速查表

外部常用命令：

docker restart 1Panel-openlist-xxxx     # 重启
docker logs -f 1Panel-openlist-xxxx     # 看日志
docker exec -it 1Panel-openlist-xxxx sh # 进容器

十、常见问题排查

特殊环境补充：

• 纯 IPv6 机器：域名加 AAAA 记录即可对外服务；证书申请建议用 DNS 验证，避免 ACME 机构回连 IPv4 失败；OpenList 容器在 1Panel 的容器网络里默认只有 IPv4，访问外部网盘走宿主机 NAT 出口，一般没问题，若某个网盘 API 连不上，检查宿主机 IPv6 出口与 DNS 解析。

• 80 端口被运营商封掉：只能用 DNS 验证签证书，访问时记得手动带 https://（HTTP 跳转用不了）。

十一、安全加固清单

收尾前对照检查一遍：

• 1Panel 面板端口已改、已设安全入口、已开两步验证

• OpenList 的 5244 未对外暴露（只监听 127.0.0.1）

• 站点已强制 HTTP → HTTPS，证书自动续签已开

• admin 密码是强密码，日常使用建了只读用户

• 对外分享的目录开启直链签名

• 私密目录用元信息加了访问密码

• data 目录有定时备份，备份文件不在同一块盘上

• 防火墙只放行 80/443（和面板端口）

写在最后

整套流程跑下来其实只有四个环节：装 1Panel → 应用商店装 OpenList → OpenResty 反代 + 补齐请求头 → 签证书开 HTTPS。真正的坑集中在「反代头信息」和「站点 URL」这两处，把它们处理好，后面的 WebDAV 挂载、播放器直连、多用户分享都会顺理成章。

日常运维记住两句话就够了：升级前先备份 data 目录，出问题先看 docker logs。

参考链接

• OpenList 官方文档：https://doc.oplist.org/

• OpenList GitHub：https://github.com/OpenListTeam/OpenList

• 1Panel 官方文档 - OpenList 应用：https://1panel.cn/docs/v2/user_manual/appstore/openlist/