在云服务器上用 Docker 部署 OpenList:从安装到 Nginx 反向代理与 HTTPS 的完整实践
一、为什么要自建网盘索引服务
把多个网盘、对象存储和本地目录统一挂到一个 Web 入口,是很多个人开发者管理文件的常见需求。OpenList 是一个支持多存储聚合的文件列表程序:它本身不存文件,只负责把不同存储的目录结构统一展示出来,并提供预览、下载、WebDAV 等能力。
本文记录一次完整的部署过程:一台 2 核 2G 的 Linux 云服务器(Debian 12),用 Docker 运行 OpenList,再用 Nginx 做反向代理并签发 HTTPS 证书。整个过程不需要改任何业务代码,适合第一次在云服务器上部署自托管服务的同学参考。
二、准备工作
- 一台已开放 80、443 端口的云服务器,安全组中放行这两个端口
- 一个解析到该服务器公网 IP 的域名,例如 pan.example.com
- 已安装 Docker 与 Docker Compose
先确认 Docker 正常:docker version 和 docker compose version。
三、用 Docker Compose 启动 OpenList
新建目录并写入 docker-compose.yml:
services:
openlist:
image: openlistteam/openlist:latest
container_name: openlist
restart: unless-stopped
ports:
- "127.0.0.1:5244:5244"
volumes:
- ./data:/opt/openlist/data
environment:
- TZ=Asia/Shanghai
- UMASK=022
注意端口映射前面加了 127.0.0.1:,表示服务只监听本机回环地址,不直接暴露到公网,后续所有外部访问都走 Nginx。这一条是很容易被忽略的安全细节:管理类服务尽量不要裸奔在公网端口上。
启动:mkdir -p openlist && cd openlist,然后 docker compose up -d,再用 docker compose logs -f --tail=50 查看日志。首次启动时日志里会输出初始管理员密码,务必保存下来,登录后第一时间修改。如果错过了,可以执行 docker exec -it openlist ./openlist admin random 重置。
四、添加存储时的三个坑
- 令牌不要在 OpenList 之外手动刷新。很多网盘的 refresh_token 是轮换制的:一旦你在别处用同一个 refresh_token 换了新令牌,OpenList 里保存的旧令牌就会失效,存储会突然掉线。需要新令牌时,让 OpenList 自己刷新,再从它的数据库里读取结果,不要在外部脚本里抢刷。
- 挂载路径要规划好。建议按用途划分一级目录,例如 /音乐、/影视、/备份,后续做权限控制和分享时更清晰。
- 驱动参数填错先看状态码。存储添加后显示异常时,先看驱动返回的错误信息,多数是回调地址、令牌范围或目录 ID 填错,逐项对照官方文档排查比反复重装有效得多。
五、Nginx 反向代理配置
新建站点配置 /etc/nginx/sites-available/openlist:
server {
listen 80;
server_name pan.example.com;
client_max_body_size 0;
location / {
proxy_pass http://127.0.0.1:5244;
proxy_set_header Host $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_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
几个关键点:client_max_body_size 0; 不限制上传体积,否则大文件上传会在 Nginx 这一层被截断;WebSocket 相关的两行不能少,否则部分实时功能会连接失败;X-Forwarded-Proto 要透传,后端生成下载直链时才不会把 https 写成 http。
启用并重载:ln -s /etc/nginx/sites-available/openlist /etc/nginx/sites-enabled/ 然后 nginx -t && systemctl reload nginx。
六、签发 HTTPS 证书
用 Certbot 一条命令完成签发和自动改写配置:apt install -y certbot python3-certbot-nginx,然后 certbot --nginx -d pan.example.com。Certbot 会自动配置 443 监听和 HTTP 跳转,并写入定时续期任务。可以用 certbot renew --dry-run 验证自动续期是否正常,这一步建议部署当天就做,不要等证书快过期了才发现续期是坏的。
七、上线后的检查清单
- 管理员密码已修改,初始密码不再可用
- OpenList 端口只监听 127.0.0.1,公网只能通过域名访问
- HTTPS 正常,HTTP 自动跳转
- 大文件上传、下载各测一次
- ./data 目录纳入定期备份(里面是配置和存储令牌,丢了要全部重配)
- 容器设置了 restart: unless-stopped,服务器重启后能自启
八、小结
这次部署真正花时间的不是命令本身,而是三个容易踩的细节:端口只监听本机、令牌不在外部抢刷、证书续期提前验证。把这三点处理好,一个自托管网盘入口就可以长期稳定运行,后续迁移服务器时也只需要搬运 docker-compose.yml 和 data 目录即可。