OpenList 用 Docker 部署：把数据目录和公网入口先管好

OpenList 的 Docker 部署很短：一个镜像、一个数据目录、一个 5244 端口。短不代表可以随便跑。

文件列表服务通常连接本地磁盘、WebDAV、S3 或网盘。容器删了数据没丢是一回事，服务直接裸露到公网、管理员账号没改密码是另一回事。先把持久化和入口边界定下来，后面更新才不会慌。

用 Compose 起一个最小实例

官方文档在 v4.1.0 之后使用 /opt/openlist/data 作为容器内数据目录。下面用 bind mount，备份和迁移时能直接看见数据在哪：

services:
  openlist:
    image: openlistteam/openlist:latest
    container_name: openlist
    user: "1000:1000" # 换成宿主机实际 UID:GID
    ports:
      - "127.0.0.1:5244:5244"
    volumes:
      - ./data:/opt/openlist/data
    environment:
      UMASK: "022"
    restart: unless-stopped

启动：

Terminal window
mkdir -p openlist && cd openlist
# 将 compose 内容保存为 compose.yml
docker compose up -d
docker compose logs -f openlist

这里把端口绑定到 127.0.0.1，意味着它只接受本机反向代理的请求。要在内网直接访问，可以改成 <LAN_IP>:5244:5244；只有确定需要让公网直接访问时，才写成 5244:5244。这不是格式差异，是暴露范围差异。

user: "1000:1000" 也别照抄。先在宿主机执行：

Terminal window
id -u
id -g

再把输出填进去。否则容器可能以 root 在 ./data 写文件，后面换运行账户或迁移数据时容易遇到权限问题。

第一次打开后，先做这些

  1. 设置或核验管理员密码，不要沿用初始化凭据。
  2. 只添加你确实要用的存储，并给每个存储账号最小权限。
  3. 如果服务经公网访问，启用 HTTPS 和强认证。
  4. 备份 data/，它是实例恢复时最重要的目录。

目录加密、隐藏目录等功能可以在 OpenList 里配置，但不要把文件名伪装当作安全边界。真正需要隔离的内容，用独立账号、权限和网络入口做限制。

经 Nginx 反代时，保留真实 Host

如果用了 Nginx Proxy Manager、1Panel 或自己写 Nginx，反代目标就是 http://127.0.0.1:5244。手写 Nginx 可以参考：

server {
    listen 443 ssl http2;
    server_name files.your-domain.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;
    }
}

client_max_body_size 0 适合文件上传场景，否则大文件可能先被 Nginx 拒绝。反代上的 TLS 证书和 OpenList 的登录策略是两层事：有 HTTPS 不等于所有文件都能公开浏览。

更新前备份，更新后读日志

不要因为看到 latest 就直接重建。先确认数据目录完整，再拉镜像：

Terminal window
cd /path/to/openlist
cp -a data "data-backup-$(date +%F)"
docker compose pull
docker compose up -d
docker compose logs --tail=100 openlist

然后实际登录一次，检查存储挂载、文件列表和上传下载各跑一遍。docker compose up -d 成功只说明容器启动了，不说明外部存储授权和反代都正常。

出问题时按这个顺序看

现象先查什么
页面打不开docker compose ps、5244 监听地址、反代目标
重启后配置没了./data:/opt/openlist/data 是否真的挂载成功
容器不断重启docker compose logs openlist，再看目录权限
上传大文件失败反代的 client_max_body_size、磁盘空间、后端存储配额
访问外部存储失败存储凭据、回调地址、容器 DNS 与网络连通性

OpenList 容器并不复杂。复杂的是它接上的存储和谁能访问它。数据目录能恢复、端口不乱开、反代日志看得懂，部署就已经过了最容易出事的部分。

参考