OpenList 自建 - 这篇文章属于一个选集。

Part 1: 本文

Part 2: 把自建网盘挂载成 Windows 本地磁盘：WinFsp + Rclone + WebDAV 教程

引言
#

我有一台 2核2G 的 Debian 小鸡，平时跑着几个自建服务。前阵子想在上面搭一套离线下载——手机丢个磁力链，回家文件已经在网盘里等着了。

市面上现成的方案不少，但要么闭源不敢用，要么配置繁琐劝退。最后选了 OpenList 做文件管理前端，qBittorrent 和 Aria2 当下载引擎，用 Docker Compose 把它们捆一起。搭完之后顺手写了个一键部署脚本——以后换服务器、或者别人要用，一条命令就完事。

这篇文章就是脚本的"说明书"，把每一步在干什么、为什么这么写、三个最容易踩的坑（权限对齐、端口对接、HTTPS 配置）说清楚。最前面是一键命令，喜欢直接动手的可以先跑再看文。

快速开始（一分钟部署）
#

如果你不想一步步敲命令，直接执行以下命令即可：

curl -fsSL https://olist.upgyc.top/deploy_zh.sh | bash

带参数的非交互模式（适合自动化）：

curl -fsSL https://olist.upgyc.top/deploy_zh.sh | bash -s -- \
  --domain example.com \
  --email admin@example.com \
  --aria2 \
  -y

脚本支持的完整 CLI 参数：

参数	说明	默认值
`--domain`	OpenList 域名	无（交互询问）
`--qbit-domain`	qBittorrent 域名	无
`--email`	Let’s Encrypt 通知邮箱	无（有域名时必填）
`--base-dir`	部署根目录	`/opt/openlist`
`--bt-port`	BT/PT 监听端口	`62973`
`--aria2`	安装 Aria2	交互询问
`--no-aria2`	不安装 Aria2	—
`--aria2-bt-port`	Aria2 BT 端口	`62974`
`--timezone`	时区	`Asia/Shanghai`
`--puid`	容器 UID	`1001`
`--pgid`	容器 GID	`1001`
`-y` / `--non-interactive`	跳过确认直接执行	—
`-h` / `--help`	显示帮助	—

脚本可以安全重复运行，已完成的步骤会自动跳过。如果中途某个关键步骤失败，修复问题后重新运行即可。

脚本内部怎么做的
#

脚本虽然长（1000+ 行），但思路不复杂。它本质上就是按顺序跑了一组检查步骤，每步有明确的成功/失败判定，最后打印一份汇总报告。

几个值得提的设计点：

管道模式兼容。 curl | bash 这个用法下，stdin 被管道占用，脚本里的 read 会直接读到 EOF 然后跳过所有交互。脚本的处理方式是——如果检测到 stdin 不是终端（[ ! -t 0 ]），就把 read 重定向到 /dev/tty。这样做到了同一份脚本既能 curl | bash 交互运行，也能 bash deploy.sh -y 全自动跑，不需要维护两个版本。

Smart bind。 有域名时，OpenList 的 5244、qBittorrent WebUI 的 8080、Aria2 RPC 的 6800 都绑 127.0.0.1，不直接暴露公网，流量走 Nginx 代理 + HTTPS。没域名时绑 0.0.0.0，直接 IP 访问。这个切换是脚本根据你有没有提供 --domain 参数自动判断的。

前置检查。 跑部署之前先过一遍：是不是 root、系统是不是 Debian/Ubuntu、磁盘够不够 3GB（不足直接拒绝）、内存够不够 1.5GB（不足自动建 Swap）。这些检查能拦住大部分"跑一半挂掉"的情况。

config.json 自动生成。 OpenList 的配置文件不是交互式生成的——脚本用随机 jwt_secret 直接写出完整的 config.json，site_url 根据有无域名自动填 http://IP:5244 或 https://域名。这样做的好处是脚本可以完全无交互运行。

权限一杆子插到底。 脚本里凡是创建目录的地方，紧跟着就是 chown ${PUID}:${PGID}。部署完成后还有一个专门的权限验证步骤，逐个目录检查 owner，哪个不对当场标出来。这是针对"下载成功文件不落地"这个最高频问题设计的。

密码自动提取 + 汇总报告。 脚本最后会从容器日志里捞 OpenList 初始密码、qBittorrent 临时密码和 Aria2 RPC 密钥，汇总打印成一个表格，连带访问地址、端口清单、OpenList 后台配置说明、SSL 证书到期时间等一起输出。这份东西就是部署完毕后你唯一需要看的地方。

下面按手动部署的顺序，把每一步的细节展开。即使你用一键脚本，看懂这些也能在出问题时知道该查哪里。

架构概览
#

互联网 → VPS (Debian 12, 2C2G)
  ├── Nginx (反向代理 + HTTPS 终结)
  │   ├── 域名A → OpenList (5244)
  │   └── 域名B → qBittorrent WebUI (8080)  [可选]
  ├── certbot (Let's Encrypt 证书自动续期)
  ├── OpenList (Docker 容器)
  │   └── 文件管理 + 离线下载调度
  ├── qBittorrent (Docker 容器)
  │   └── BT/PT 下载引擎
  └── Aria2 (Docker 容器) [可选]
      └── HTTP/FTP/BT/磁力链接全能下载器

共享目录:
  /opt/openlist/temp/qBittorrent → OpenList 和 qBittorrent 共享
  /opt/openlist/temp/aria2        → OpenList 和 Aria2 共享

目录结构总览：

/opt/openlist/
├── docker-compose.yml
├── config/
│   ├── openlist/          # OpenList 数据（配置、数据库等）
│   ├── qbittorrent/       # qBittorrent 配置
│   │   └── qBittorrent/
│   │       └── qBittorrent.conf
│   └── aria2/             # Aria2 配置（可选）
│       └── aria2.conf
└── temp/
    ├── qBittorrent/       # qBittorrent 离线下载共享目录
    └── aria2/             # Aria2 离线下载共享目录（可选）

端口清单：

端口	协议	公网	用途
你的SSH端口	TCP	✅	SSH 远程连接
80	TCP	✅	HTTP（重定向到 HTTPS / 证书申请）
443	TCP	✅	HTTPS（Nginx 代理）
5244	TCP	❌	OpenList（仅本地，走 Nginx 代理）
8080	TCP	❌	qBittorrent WebUI（仅本地）
62973	TCP+UDP	✅	BT/PT 数据传输（qBittorrent）
6800	TCP	❌	Aria2 RPC（仅本地）
62974	TCP+UDP	✅	Aria2 BT 数据传输（可选）

前置准备
#

以下两件事脚本帮不了你，部署前务必先搞定：

1. DNS 解析

在域名后台添加 A 记录指向服务器 IP。本文约定：

OpenList 面板 → pan.example.com
qBittorrent WebUI → qb.example.com（可选）

不配域名也行，直接用 http://IP:5244 访问，可以跳过所有 Nginx 和证书步骤。

2. 云安全组（防火墙）

在云厂商控制台放行以下端口：SSH 端口、80、443、62973（TCP+UDP）。如果装了 Aria2，还需放行 62974（TCP+UDP）。本文不再配置 UFW，请务必在安全组层面操作。

第一步：系统初始化
#

# 系统更新（建议在 tmux/screen 里跑，防止 SSH 断开导致更新中断）
apt update && apt upgrade -y

# 装好必备工具
apt install -y curl wget vim git unzip net-tools gpg

# 设置时区
timedatectl set-timezone Asia/Shanghai

# 2GB 内存属于紧巴巴的水平，加 2GB Swap 防 OOM
dd if=/dev/zero of=/swapfile bs=1M count=2048
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab
echo 'vm.swappiness=10' >> /etc/sysctl.conf
sysctl -p

第二步：安装 Docker
#

# 清理旧版本（如果有）
for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do
    apt remove -y $pkg 2>/dev/null || true
done

# 添加 Docker 官方 APT 源
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | \
    gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
    > /etc/apt/sources.list.d/docker.list

# 安装 Docker 全家桶
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 验证安装
docker --version
docker compose version

第三步：创建目录结构并预置配置
#

# 一键创建目录
mkdir -p /opt/openlist/config/openlist
mkdir -p /opt/openlist/config/qbittorrent/qBittorrent
mkdir -p /opt/openlist/temp/qBittorrent

# 如果装了 Aria2
mkdir -p /opt/openlist/config/aria2
mkdir -p /opt/openlist/temp/aria2

# 预置 qBittorrent 配置（修复 Unauthorized + 指定 BT 端口）
cat > /opt/openlist/config/qbittorrent/qBittorrent/qBittorrent.conf << 'EOF'
[Preferences]
WebUI\HostHeaderValidation=false
WebUI\CSRFProtection=false
WebUI\LocalHostAuth=false

[BitTorrent]
Session\Port=62973
EOF

# 统一权限：两个容器内都使用 UID 1001（可通过 --puid/--pgid 自定义）
chown -R 1001:1001 /opt/openlist
chmod -R 755 /opt/openlist

权限说明（必读！踩坑重灾区）
#

核心原则就一条：所有容器内都跑着同一个 UID，相关目录 owner 必须也是这个 UID（默认 1001）。

qBittorrent / Aria2 (UID 1001)
  │  写入文件到 /opt/openlist/data/temp/<下载器>/<uuid>/
  │  → 要求: temp 目录 owner=1001
  ▼
OpenList (UID 1001)
  │  读取临时文件，移动到最终存储
  │  → 要求: 最终存储目录 owner=1001  ← 最容易漏掉！
  ▼
用户正常访问 ✓

以下目录的 owner 必须全是 1001：

共享临时目录 temp/qBittorrent（和 temp/aria2）
qBittorrent 配置目录（和 Aria2 配置目录）
OpenList 中挂载的本地存储目录（🔥 最高频遗漏项）

# 一键修复
chown -R 1001:1001 /opt/openlist

# 如果有额外挂载的存储目录（如 /mnt/data），也必须：
chown -R 1001:1001 /mnt/data

部署后快速自查：

# 检查关键目录 owner
stat -c '%u %n' /opt/openlist/temp/qBittorrent
stat -c '%u %n' /opt/openlist/config/qbittorrent

# 找出所有不是 UID 1001 的文件（应该没有输出）
find /opt/openlist -not -user 1001 -ls

# 有外部挂载也必须检查
find /你的存储目录 -not -user 1001 -ls

⚠️ 权限错误是「下载成功但文件不写入网盘」的罪魁祸首。部署完第一时间执行自查。

第四步：编写 docker-compose.yml
#

2核2G 优化要点：为每个容器设置内存上限，防止下载器内存泄漏把整个系统拖垮。

基础版（qBittorrent）
#

cat > /opt/openlist/docker-compose.yml << 'EOF'
services:
  openlist:
    image: openlistteam/openlist:latest
    container_name: openlist
    volumes:
      - /opt/openlist/config/openlist:/opt/openlist/data
      - /opt/openlist/temp/qBittorrent:/opt/openlist/data/temp/qBittorrent
      - /opt/openlist/temp/aria2:/opt/openlist/data/temp/aria2
    ports:
      - "127.0.0.1:5244:5244"
    environment:
      - PUID=1001
      - PGID=1001
      - UMASK=022
    restart: unless-stopped
    mem_limit: 512m
    networks:
      openlist_net:
        aliases:
          - openlist

  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=1001
      - PGID=1001
      - WEBUI_PORT=8080
      - BT_PORT=62973
      - TZ=Asia/Shanghai
    volumes:
      - /opt/openlist/config/qbittorrent:/config
      - /opt/openlist/temp/qBittorrent:/opt/openlist/data/temp/qBittorrent
    ports:
      - "127.0.0.1:8080:8080"
      - "62973:62973"
      - "62973:62973/udp"
    restart: unless-stopped
    mem_limit: 1g
    networks:
      openlist_net:
        aliases:
          - qbittorrent

networks:
  openlist_net:
    name: openlist_net
EOF

完整版（qBittorrent + Aria2）
#

在基础版的 services: 块内追加 Aria2 服务定义：

  aria2:
    image: p3terx/aria2-pro:latest
    container_name: aria2
    environment:
      - PUID=1001
      - PGID=1001
      - UMASK_SET=022
      - RPC_SECRET=your_rpc_secret_here    # 改成随机字符串
      - RPC_PORT=6800
      - LISTEN_PORT=62974
      - TZ=Asia/Shanghai
      - DISK_CACHE=64M
      - UPDATE_TRACKERS=true
    volumes:
      - /opt/openlist/config/aria2:/config
      - /opt/openlist/temp/aria2:/opt/openlist/data/temp/aria2
      - /opt/openlist/temp/aria2:/downloads
    ports:
      - "127.0.0.1:6800:6800"
      - "62974:62974"
      - "62974:62974/udp"
    restart: unless-stopped
    mem_limit: 512m
    networks:
      openlist_net:
        aliases:
          - aria2

# 验证语法
cd /opt/openlist
docker compose config --quiet

关键说明：

OpenList 的 5244、qBittorrent WebUI 的 8080、Aria2 RPC 的 6800 都绑定 127.0.0.1，不直接暴露公网，由 Nginx 代理更安全
BT 端口 62973（和 Aria2 的 62974）绑定 0.0.0.0，需要公网可达，DHT/PT 才能正常工作
所有容器必须在同一网络 openlist_net，OpenList 通过容器名访问下载器（qbittorrent:8080、aria2:6800）
mem_limit：OpenList 512MB，qBittorrent 1GB，Aria2 512MB，合计不超过物理内存
Aria2 的 RPC_SECRET 务必改成随机字符串，这是 OpenList 连接 Aria2 的凭证

如果不配域名，把 127.0.0.1:5244:5244、127.0.0.1:8080:8080、127.0.0.1:6800:6800 改成 5244:5244、8080:8080、6800:6800（即绑定 0.0.0.0），直接 IP 访问即可。

第五步：启动容器并获取初始密码
#

cd /opt/openlist
docker compose up -d

# 等容器启动后获取密码
sleep 10

# OpenList 初始密码
docker logs openlist 2>&1 | grep -i "initial password"
# 输出类似：Admin initial password: aB3xYz12

# qBittorrent 临时密码
docker logs qbittorrent 2>&1 | grep -i "temporary password"
# 输出类似：A temporary password is provided for this session: RXdMg5sDD

# Aria2 RPC 密钥（如果装了）
docker logs aria2 2>&1 | grep -i "rpc.secret"
# 或直接查看配置文件
cat /opt/openlist/config/aria2/aria2.conf | grep rpc-secret

⚠️ 拿到密码立刻记下来！ qBittorrent 每次重建容器临时密码都会变。OpenList 的密码登录后可在后台修改。Aria2 的 RPC 密钥在配置文件中是固定的，不会随重启变化。

如果 grep "initial password" 没输出，试试更宽泛的搜索：docker logs openlist 2>&1 | grep -i password。

浏览器打开 http://服务器IP:5244 登录 OpenList，qBittorrent WebUI 在 http://服务器IP:8080（用户名 admin，密码为上方获取的临时密码）。

第六步：Nginx 反向代理 + HTTPS
#

没配域名的同学可以跳过这一步。

6.1 安装并配置反向代理
#

# 安装
apt install -y nginx certbot python3-certbot-nginx

# OpenList 反向代理配置（先 HTTP，certbot 会自动加 HTTPS）
cat > /etc/nginx/sites-available/openlist << 'NGINX_EOF'
server {
    listen 80;
    server_name pan.example.com;    # 改成你的域名

    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    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 100m;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        proxy_connect_timeout 60s;
    }
}
NGINX_EOF

ln -sf /etc/nginx/sites-available/openlist /etc/nginx/sites-enabled/openlist
rm -f /etc/nginx/sites-enabled/default
nginx -t && systemctl reload nginx

6.2 申请 Let’s Encrypt 证书
#

certbot --nginx -d pan.example.com --non-interactive --agree-tos -m you@example.com

Certbot 会自动修改 Nginx 配置加入 HTTPS 并设置 80→443 重定向。证书有效期 90 天，certbot 安装后会自动创建 systemd timer 每日检查续期：

# 查看定时任务
systemctl status certbot.timer

# 测试续期（不会真正续期）
certbot renew --dry-run

6.3 （可选）为 qBittorrent WebUI 也配域名
#

cat > /etc/nginx/sites-available/qbittorrent << 'QBIT_NGINX_EOF'
server {
    listen 80;
    server_name qb.example.com;    # 改成你的域名

    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    location / {
        proxy_pass http://127.0.0.1:8080;
        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 100m;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        proxy_connect_timeout 60s;
    }
}
QBIT_NGINX_EOF

ln -sf /etc/nginx/sites-available/qbittorrent /etc/nginx/sites-enabled/qbittorrent
nginx -t && systemctl reload nginx
certbot --nginx -d qb.example.com --non-interactive --agree-tos -m you@example.com

第七步：在 OpenList 后台绑定下载器
#

7.1 绑定 qBittorrent
#

登录 OpenList → 管理后台 → 设置 → qBittorrent
填写 qBittorrent URL：http://admin:你的qBit密码@qbittorrent:8080/
点击「设置 qBittorrent」，无报错即对接成功

字段	值	说明
qBittorrent URL	`http://admin:你的qBit密码@qbittorrent:8080/`	用容器名不要用 IP
做种时间	`0`	0 = 下载完立即删除（单位：分钟）

⚠️ URL 格式要求：http://用户名:密码@容器名:8080/。结尾 / 不能省。用户名默认 admin，密码是第五步获取的临时密码。务必用容器名 qbittorrent，不是 IP！

7.2 绑定 Aria2
#

登录 OpenList → 管理后台 → 设置 → 其他 → Aria2
填写以下信息：

字段	值	说明
Aria2 RPC URL	`http://aria2:6800/jsonrpc`	容器名 `aria2`，端口 `6800`
RPC 密钥	第五步获取的密钥	即 `RPC_SECRET` 的值

保存后，在 OpenList 前端右下角 → 离线下载 → 就可以在 qBittorrent 和 Aria2 之间切换选择了

第八步：常见配置问题排查
#

8.1 qBittorrent Unauthorized（401）
#

第三步已经预置了修复配置，正常情况下不会遇到此问题。

如果仍然 401，先确认预置配置是否生效：

grep WebUI /opt/openlist/config/qbittorrent/qBittorrent/qBittorrent.conf

应该包含三项 false。如果没有，手动追加后重启：

cat >> /opt/openlist/config/qbittorrent/qBittorrent/qBittorrent.conf << 'EOF'
WebUI\HostHeaderValidation=false
WebUI\CSRFProtection=false
WebUI\LocalHostAuth=false
EOF
cd /opt/openlist && docker compose restart qbittorrent

替代方案：登录 qBittorrent WebUI → 工具 → 选项 → Web UI，勾选「对本地主机上的客户端跳过身份验证」，并在 IP 子网白名单中添加 172.16.0.0/12（Docker 默认网络范围）。之后 OpenList 可以直接用 http://qbittorrent:8080/（无需密码），更加省事。

8.2 修改默认密码
#

8.3 BT 端口不可达
#

检查云安全组是否放行 62973 TCP+UDP（以及 Aria2 的 62974），然后验证端口监听：

ss -tunlp | grep -E "62973|62974"

8.4 Aria2 连接失败
#

常见原因：

RPC 密钥不匹配：检查 docker logs aria2 2>&1 | grep -i secret 和 OpenList 后台填写的密钥是否一致
容器网络不通：确认 Aria2 和 OpenList 都在 openlist_net 网络中
端口冲突：如果 Aria2 BT 端口和 qBittorrent 的相同，脚本会自动 +1 调整

# 验证 Aria2 RPC 是否正常
curl http://127.0.0.1:6800/jsonrpc -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"1","method":"aria2.getVersion","params":["token:你的密钥"]}'

第九步：临时文件清理说明
#

下载完成后，文件是否在服务器上保留取决于你在新建下载任务时选择的 删除策略：

删除策略	行为
下载成功后删除	传输到目标存储后自动清理临时文件 ✅ 推荐
下载失败后删除	成功的保留，失败的删除
总是删除	无论成败都删
从不删除	永久保留在 `temp/` 目录
下载流直接上传	不落盘，直接流式传输（仅对 HTTP 下载有效，BT 任务不适用）

如果之前一直选「从不删除」，/opt/openlist/temp/ 下面可能堆积了大量历史文件。可以随时重启容器触发清理：

docker restart openlist

OpenList 启动时会自动清空 temp 目录（前提是没有未完成的传输任务）。

第十步：验证离线下载
#

用一条测试磁力链验证整套流程是否跑通：

在 OpenList 前端进入任意文件夹
点击右下角 离线下载 → 选择 qBittorrent 或 Aria2
粘贴测试磁力链（Ubuntu 官方镜像）：

magnet:?xt=urn:btih:ZQHXPTJLDGTJGEMRJGMBMG5MZGFDJ5BX&dn=ubuntu-24.04-live-server-amd64.iso

观察任务状态变化：Downloading metadata → 有速度 → 完成。一气呵成即表示配置成功 ✅

第十一步：性能调优（2核2G 必备）
#

设置项	位置	建议值
磁盘缓存	高级	64 MB
文件池大小	高级	40
全局最大连接数	连接	200
每种子最大连接数	连接	50
全局上传通道数	连接	4
全局下载通道数	连接	8

Docker 资源限制（OpenList 512MB / qBittorrent 1GB / Aria2 512MB）已在第四步配置，无需额外操作。

第十二步：部署后全面验证
#

部署完毕，逐项过一遍确认一切正常：

# 容器状态（都应该显示 Up）
docker ps --format "table {{.Names}}\t{{.Status}}"

# 端口监听
ss -tlnp | grep -E "5244|8080|62973|6800"

# 权限检查（最关键！owner 必须全是 1001）
stat -c '%u %n' /opt/openlist/config/openlist
stat -c '%u %n' /opt/openlist/temp/qBittorrent
stat -c '%u %n' /opt/openlist/config/qbittorrent
stat -c '%u %n' /opt/openlist/config/qbittorrent/qBittorrent/qBittorrent.conf
# 如果装了 Aria2
stat -c '%u %n' /opt/openlist/temp/aria2
stat -c '%u %n' /opt/openlist/config/aria2

# 找出所有非 UID 1001 的文件（应该没有输出）
find /opt/openlist -not -user 1001 -ls

# HTTP 可达
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:80/

# HTTPS 可达（配了域名的）
curl -s -o /dev/null -w "%{http_code}\n" https://你的域名/

第十三步：日常维护速查
#

# 容器管理
cd /opt/openlist
docker compose ps          # 查看状态
docker compose restart     # 重启
docker compose down && docker compose up -d  # 重建
docker compose pull && docker compose up -d  # 更新镜像

# 查看日志
docker logs -f openlist
docker logs -f qbittorrent
docker logs -f aria2       # 如果装了

# Nginx
nginx -t                  # 测试配置
systemctl reload nginx    # 重载
systemctl status nginx    # 状态

# 证书
certbot renew --dry-run   # 测试续期
systemctl status certbot.timer  # 自动续期状态

快速排障
#

现象	可能原因	解决
无法访问 OpenList	Nginx 未启动	`systemctl restart nginx`
qBittorrent not ready	容器未在同一网络/URL 配置错误	检查 docker network；确认 URL 用容器名
torrent parse timeout	qBittorrent 版本过低	确保使用 `lscr.io/linuxserver/qbittorrent:latest`
Unauthorized (401)	预置配置未生效	`grep WebUI .../qBittorrent.conf` 检查三项配置，见第八步
Aria2 连接失败	RPC 密钥不匹配或网络不通	验证密钥一致性，检查容器网络
下载成功但文件未写入	目录 owner 不是 1001	`find /opt/openlist -not -user 1001 -ls`，然后 `chown -R 1001:1001 /opt/openlist`
下载速度为 0	BT 端口不可达	检查云安全组是否放行 62973 TCP+UDP（Aria2 还需 62974）
内存不足	qBittorrent 占内存过多	按第十一步限制资源
SSL 证书过期	certbot timer 未运行	`systemctl status certbot.timer`
Aria2 下载无速度	DHT 端口未放行	检查安全组 UDP 端口 62974

一键部署命令
#

# 中文版
curl -fsSL https://olist.upgyc.top/deploy_zh.sh | bash

# 英文版
curl -fsSL https://olist.upgyc.top/deploy.sh | bash

# 非交互模式示例
curl -fsSL https://olist.upgyc.top/deploy_zh.sh | bash -s -- \
  --domain pan.example.com \
  --email admin@example.com \
  --aria2 \
  -y

脚本托管在 openlist-deploy 仓库，欢迎提 Issue 和 PR。

速查卡
#

路径
#

项目	路径
部署根目录	`/opt/openlist/`
docker-compose	`/opt/openlist/docker-compose.yml`
OpenList 配置	`/opt/openlist/config/openlist/`
qBittorrent 配置	`/opt/openlist/config/qbittorrent/qBittorrent/qBittorrent.conf`
Aria2 配置	`/opt/openlist/config/aria2/`
qBittorrent 共享下载目录	`/opt/openlist/temp/qBittorrent/`
Aria2 共享下载目录	`/opt/openlist/temp/aria2/`

常用命令速记
#

cd /opt/openlist
docker compose ps                    # 容器状态
docker compose restart               # 重启
docker compose down && docker compose up -d  # 重建
docker compose pull && docker compose up -d  # 更新

# 密码
docker logs openlist | grep -i password
docker logs qbittorrent | grep -i password
docker logs aria2 | grep -i secret   # Aria2 RPC 密钥

# Nginx
nginx -t && systemctl reload nginx

# 证书
certbot renew --dry-run
systemctl status certbot.timer

OpenList 下载器连接配置
#

qBittorrent：

URL:  http://admin:你的密码@qbittorrent:8080/

Aria2：

RPC URL:   http://aria2:6800/jsonrpc
RPC 密钥:  见 Aria2 配置文件或启动日志

qBittorrent 用户名默认 admin，密码是第五步获取的临时密码
务必使用容器名（qbittorrent / aria2），不是 IP
qBittorrent URL 结尾 / 必加；Aria2 URL 带 /jsonrpc 路径

权限检查（下载成功但文件不落地？就查这个）
#

stat -c '%u %n' /opt/openlist/temp/qBittorrent    # 必须输出 1001
stat -c '%u %n' /opt/openlist/temp/aria2           # 必须输出 1001（如果装了）
stat -c '%u %n' /opt/openlist/config/qbittorrent   # 必须输出 1001
find /opt/openlist -not -user 1001 -ls              # 不应有输出
chown -R 1001:1001 /opt/openlist                    # 一键修复

排查顺序
#

docker logs openlist / docker logs qbittorrent / docker logs aria2 看日志
nginx -t 检查 Nginx 配置
Unauthorized → grep WebUI /opt/openlist/config/qbittorrent/qBittorrent/qBittorrent.conf
qBittorrent not ready / Aria2 连接失败 → 检查 docker network、URL 配置
下载速度为 0 → 检查云安全组 62973/62974 端口
下载成功但文件未写入 → find /opt/openlist -not -user 1001 -ls

结语
#

OpenList + qBittorrent + Aria2 的组合本身并不复杂，真正的坑都在细节里：权限对不齐、端口没放开、URL 写错格式。记住三条铁律基本不会翻车：

所有目录 owner = 容器 UID（默认 1001）
qBittorrent/Aria2 端口里外一致，URL 用容器名不用 IP
Aria2 的 RPC 密钥务必和 OpenList 后台填写的一致

遇到问题先看 docker logs——容器日志能解决 90% 的疑问。如果还有坑，欢迎到 GitHub 仓库提 Issue 交流 🚀

服务端跑起来了？ 下一步把 OpenList 挂载为 Windows 本地磁盘，文件管理不用再开浏览器，直接拖拽就能用。

OpenList 自建 - 这篇文章属于一个选集。

Part 1: 本文

Part 2: 把自建网盘挂载成 Windows 本地磁盘：WinFsp + Rclone + WebDAV 教程

引言#

快速开始（一分钟部署）#

脚本内部怎么做的#

架构概览#

前置准备#

第一步：系统初始化#

第二步：安装 Docker#

第三步：创建目录结构并预置配置#

权限说明（必读！踩坑重灾区）#

第四步：编写 docker-compose.yml#

基础版（qBittorrent）#

完整版（qBittorrent + Aria2）#

第五步：启动容器并获取初始密码#

第六步：Nginx 反向代理 + HTTPS#

6.1 安装并配置反向代理#

6.2 申请 Let’s Encrypt 证书#

6.3 （可选）为 qBittorrent WebUI 也配域名#

第七步：在 OpenList 后台绑定下载器#

7.1 绑定 qBittorrent#

7.2 绑定 Aria2#

第八步：常见配置问题排查#

8.1 qBittorrent Unauthorized（401）#

8.2 修改默认密码#

8.3 BT 端口不可达#

8.4 Aria2 连接失败#

第九步：临时文件清理说明#

第十步：验证离线下载#

第十一步：性能调优（2核2G 必备）#

第十二步：部署后全面验证#

第十三步：日常维护速查#

快速排障#

一键部署命令#

速查卡#

路径#

常用命令速记#

OpenList 下载器连接配置#

权限检查（下载成功但文件不落地？就查这个）#

排查顺序#

结语#

相关文章