OpenList 基础部署：用 Docker 建立自己的文件入口

OpenList 可以把不同存储整理成一个文件浏览入口。这次先部署服务、登录后台，再挂载一个本地测试目录，完成“能看到并下载自己的文件”这个最小目标。

本文环境是 Ubuntu 服务器、Docker Engine 和 Docker Compose 插件。你需要 SSH 登录权限和 sudo 权限。本文不展开网盘授权、域名和公开访问配置。

命令已对照官方文档整理，本内容包没有在实际服务器上运行部署测试。镜像和界面更新后，请同时查看官方说明。

一、检查前置环境

先按 Docker 官方 Ubuntu 安装说明安装 Docker Engine 与 Compose 插件，然后在服务器终端运行：

sudo docker version
sudo docker compose version

两条命令都应显示版本信息。第一条如果提示无法连接 daemon，先处理 Docker 服务；第二条如果不认识 compose，先补齐插件。

本教程后面的 Bash 命令在服务器执行。SSH 隧道命令在你的 Windows 电脑执行。

二、准备独立的数据目录

在服务器执行：

sudo mkdir -p /opt/sy-openlist/data /opt/sy-openlist/files
sudo chown 1001:1001 /opt/sy-openlist/data
printf 'OpenList test file\n' | sudo tee /opt/sy-openlist/files/hello.txt
sudo chmod 755 /opt/sy-openlist/files
sudo chmod 644 /opt/sy-openlist/files/hello.txt
cd /opt/sy-openlist

data 保存应用配置与数据库，files 保存测试文件。官方当前镜像默认使用 UID 1001 的用户，因此持久化目录需要匹配访问权限。OpenList 官方 Docker 部署说明

这里只调整新建的专用目录。不要照搬目录路径去修改已有业务文件的归属。

三、创建 Compose 文件

继续在服务器粘贴整段命令：

sudo tee /opt/sy-openlist/compose.yaml > /dev/null <<'YAML'
services:
  openlist:
    image: openlistteam/openlist:latest
    container_name: sy-openlist
    restart: unless-stopped
    ports:
      - "127.0.0.1:5244:5244"
    volumes:
      - ./data:/opt/openlist/data
      - ./files:/mnt/files:ro
    environment:
      TZ: Asia/Shanghai
      UMASK: "022"
YAML

这里把端口绑定到服务器的本地回环地址，使用 SSH 隧道访问。Docker 官方说明了这种绑定方式与公开发布端口的差别；使用旧版本 Docker 时，也要留意其文档中的网络暴露提示。Docker 端口发布说明

latest 用于初次体验；它会随发布变化。准备长期运行时，先确认实际版本，再固定对应版本标签或镜像摘要，便于复现和回退。

四、启动并确认状态

cd /opt/sy-openlist
sudo docker compose config
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=80 openlist

config 用来检查配置格式，ps 应显示容器处于运行状态。首次初始化时，日志会给出管理员初始密码。把密码保存在自己的密码管理工具中，不要把含密码的日志发到公开群聊。

如果日志已经没有初始密码，可以按照官方命令为这个容器重新生成：

sudo docker exec -it sy-openlist ./openlist admin random

这会更改管理员密码，只在需要重置时使用。

五、在 Windows 上打开 SSH 隧道

在电脑上新开 PowerShell，把用户名和地址换成自己的真实登录信息。示例 IP 不是可连接服务器：

ssh -L 5244:127.0.0.1:5244 ubuntu@203.0.113.10

SSH 使用其他端口时，加上 -p 实际端口。保持这个终端连接，然后在电脑浏览器打开 http://127.0.0.1:5244。

这里浏览器的 127.0.0.1 指你的电脑；隧道把请求转发到服务器上的服务。如果本机 5244 已占用，把命令左侧端口改成 15244，再访问本机的 15244。

六、挂载测试文件并验收

用管理员账号登录，进入管理界面中的存储设置，新增本地存储。站内挂载路径可填 /demo，驱动的根文件夹路径填容器里的 /mnt/files。某些界面会把该字段写成“根文件夹 ID”，实际填写的是目录路径。官方本地存储说明

保存后返回文件页面，打开 demo 目录，下载 hello.txt。下载到的内容应与前面创建的测试文本一致。

这里的挂载是只读的，便于验证浏览和下载。暂时不要添加整个服务器根目录，也不要把无关业务目录暴露给文件服务。

七、备份和常见问题

对本教程这种轻量测试实例，可以先停止容器，再归档配置目录：

cd /opt/sy-openlist
sudo docker compose stop
sudo tar -czf /opt/sy-openlist-backup-$(date +%Y%m%d-%H%M%S).tar.gz data compose.yaml
sudo docker compose start

如果归档失败，也要重新启动服务并检查错误。此归档包含配置和 Compose 文件，不包含 files 中的文件或外部网盘内容；需要把备份另存到服务器之外，并测试恢复。

容器不断重启，先看日志和目录权限；页面打不开，先看容器状态和隧道；目录为空，核对宿主机 files 与容器 /mnt/files 的对应关系。

完成标准是：容器运行、后台可登录、hello.txt 可下载、配置能持久保存。准备增加网盘或公开访问时，再按对应官方文档处理授权、访问控制和 HTTPS。