# OpenWrt单网口旁路由 \+ 群晖qBittorrent 综合配置手册

# OpenWrt 单网口旁路由 \+ 群晖 qBittorrent 综合配置手册

> 复制下面全部内容，粘贴到记事本，文件另存为：`OpenWrt_群晖QB配置手册.md`，编码选择 **UTF\-8**
> 
> 

```markdown
# OpenWrt单网口旁路由 + 群晖qBittorrent 综合配置手册
## 模块一 OpenWrt单网口旁路由（关闭DHCP+彻底关闭DNS劫持）
### 一、适用场景
- 设备：单网口软路由、无独立WAN口、单口复用
- 模式：纯旁路由模式，**主路由负责拨号、PPPoE、DHCP分配IP**
- 需求：关闭OpenWrt DHCP、关闭DNS 53端口劫持，不篡改终端DNS请求
- 核心原则：**全程不新建、不配置WAN接口**，防止单网口断后台

### 二、前置风险提示
1. OpenWrt关闭DHCP后，内网设备无法自动获取IP，IP分配全部交给上层主路由DHCP。
2. 单网口设备不要随意修改接口、新建WAN，极易丢失后台访问。
3. DNS劫持来源两类：防火墙53端口DNAT规则 / AdGuardHome/SmartDNS等插件强制拦截DNS。

### 三、核心配置步骤（LuCI图形界面 + SSH）
#### 步骤1 LAN接口基础配置（旁路由核心）
网络 → 接口 → LAN → 编辑
1. 常规设置
- IPv4地址：同网段静态IP（例：主路由`192.168.1.1`，旁路由`192.168.1.2`，避免IP冲突）
- 子网掩码：`255.255.255.0`
- IPv4网关：填写**主路由IP**
- DNS服务器：填写**主路由IP**
2. DHCP服务器选项卡：勾选【忽略此接口】，关闭LAN口DHCP分发
3. 物理设置：单网口建议拆除多余桥接，仅绑定eth0
保存&应用。

#### 步骤2 SSH命令永久关闭DHCP
```bash
uci set dhcp.lan.ignore="1"
uci commit dhcp
/etc/init.d/dnsmasq restart
```

校验命令：

```bash
uci show dhcp.lan
```

输出含 `dhcp.lan.ignore='1'` 代表 DHCP 关闭成功。

#### 步骤 3 清除 DNS 劫持

1. 图形界面：网络 → 防火墙 → 端口转发，**删除所有目标端口 53 的 DNAT 规则**，保存应用。

2. SSH 查看 53 端口劫持规则：

```bash
iptables -t nat -L PREROUTING --line-numbers | grep dpt:53
```

删除规则（行号替换为你查到的数字）

```bash
iptables -t nat -D PREROUTING 1
```

重复执行直到无输出。
3\. 插件设置（AdGuardHome / SmartDNS）：关闭「拦截 53 端口、强制劫持 DNS」。

#### 步骤 4 防火墙必要设置

网络 → 防火墙

- LAN 区域转发：接受

- **开启 IP 动态伪装（MASQ）**，否则流量无法转发

- 不新增 WAN 区域

### 四、DNS 劫持有效性测试

Windows CMD 执行（设备网关设旁路由 IP，DNS 手动填 \[223\.5\.5\.5\]\(223\.5\.5\.5\)）

```cmd
nslookup baidu.com 223.5.5.5
```

✅正常：服务器 =`223.5.5.5`
❌劫持：服务器显示旁路由内网 IP

OpenWrt 内 SSH 测试：

```bash
nslookup baidu.com 223.5.5.5
```

### 五、核对清单

* [ ] LAN DHCP 已忽略关闭

* [ ] 防火墙无 53 端口 DNAT 劫持规则

* [ ] DNS 插件劫持关闭

* [ ] LAN 防火墙 MASQ 开启

* [ ] 没有新建 WAN 接口

---

## 模块二 群晖 NAS qBittorrent 配置（Docker 部署）

> 环境：群晖 DSM，Docker 安装 qBittorrent，配合旁路由做流量出口，配套目录权限、文件整理、防踩坑设置
> 
> 

### 一、前置准备

1. 群晖存储空间：新建共享文件夹，示例命名`qb-download`

    - 子目录建议：`incomplete`（临时未完成）、`complete`（完成文件）

2. 权限：给 Docker 的 qb 容器读写权限，**不要用 root 直接跑**，设置 PUID/PGID（群晖用户 UID）

3. 网络模式：推荐`bridge`桥接模式；如需走旁路由，容器网关指定为 OpenWrt 旁路由 IP。

### 二、Docker 容器环境变量（常用模板）

```Plain Text
PUID=1026
PGID=100
TZ=Asia/Shanghai
WEBUI_PORT=8080
```

端口映射：

- 8080:8080 Web 管理面板

- 50681:50681/TCP\+UDP BT 监听端口（自行选用）

挂载目录：

- `/volume1/qb-download/complete` → `/downloads`

- `/volume1/qb-download/incomplete` → `/incomplete`

- `/volume1/docker/qb/config` → `/config`

### 三、qBittorrent WebUI 核心参数配置

打开 WebUI → 选项

1. **连接**

    - 监听端口固定，启用 UPnP/NAT\-PMP（有公网 IP 推荐开启）

    - 限制全局连接数，防止占满内网带宽

2. **下载**

    - ✅ 启用：未完成文件保存到单独目录（incomplete）

    - 完成后自动移动到`complete`目录

    - 预分配磁盘空间：按需开启（大文件推荐）

3. **BitTorrent**

    - DHT、PEX、本地对等发现：按需开启（私种关闭 DHT/PEX）

4. **高级**

    - 不要开启不必要的代理；如需走旁路由，**全局网关在 Docker 层面设置，不要在 qb 内单独配置代理**

### 四、配套：文件名清理 / 刮削脚本（Tinymediamanager）

> 需求：自动清理文件名特殊字符、目录监听、媒体库刮削
> 
> 

1. TinyMediaManager 用于媒体元数据刮削，自动匹配电影 / 剧集海报、简介

2. 文件名清洗脚本：正则过滤特殊符号，清理种子下载带来的杂乱文件名，避免 Emby/Jellyfin 识别失败

3. 注意：脚本运行用户 UID 必须和 qb 下载文件 UID 一致，防止权限报错。

### 五、权限 \& 避坑重点

1. 权限大坑：qb 下载文件归属 PUID 用户，**群晖文件管理器看不到 / 无法删除，就是 PUID 不匹配**

2. 旁路由联动：

    - 群晖本身网关可保留主路由；仅 Docker 容器单独指定网关走 OpenWrt 旁路由

    - 注意：DNS 设置，群晖 / 容器 DNS 不要被劫持，使用公共 DNS（\[223\.5\.5\.5\]\(223\.5\.5\.5\)）

3. 端口：群晖防火墙放行 qb 监听端口；路由器端口映射（有公网 IP）

4. 硬盘：开启 SSD 缓存，大流量下载注意硬盘休眠策略，避免频繁启停损坏硬盘

### 六、备份建议

1. qBittorrent：备份 `/config` 整个目录（包含配置、种子列表）

2. 定期导出 torrent 种子文件做异地备份

---

## 附录 A：故障排查小节

### 1\. qBittorrent 无速度 / Tracker 连接失败

1. DNS 问题：容器内 DNS 被劫持。在 Docker 容器配置内手动指定 DNS 为`223.5.5.5`，不要自动获取。

2. 端口不通：

    - 检查群晖防火墙放行 BT 监听端口 TCP/UDP

    - 公网环境：主路由端口映射，确认 UPnP 正常

3. 私种站点：关闭 DHT、PEX；核对站点密钥、passkey，检查种子是否过期

4. 网关错误：容器网关没有正确指向旁路由 IP；检查 OpenWrt 防火墙 MASQ 是否开启

### 2\. 群晖文件权限报错（无法删除、看不到文件）

- 根源：PUID/PGID 和群晖本地用户 ID 不一致

- 解决：在容器环境变量修改 PUID，与你群晖登录用户 UID 保持一致；重建容器，不要直接修改已下载文件权限。

> 获取群晖 UID：SSH 登录群晖，执行 `id 你的用户名`
> 
> 

### 3\. OpenWrt 旁路由故障

1. 无法访问 OpenWrt 后台：检查电脑 IP 网段；单网口不要新建 WAN，修改 LAN IP 后需要用新 IP 访问

2. 设备网关指向旁路由但无法上网：LAN 区域 IP 动态伪装 \(MASQ\) 未开启；检查主路由与旁路由网段一致

3. DNS 劫持复现：重启防火墙后 53 端口 DNAT 规则恢复，回到 LuCI 防火墙端口转发页面删除持久化规则；检查 AdGuardHome/SmartDNS 插件劫持开关

### 4\. TinyMediaManager 刮削识别失败

1. 文件名残留特殊符号，正则清洗脚本未执行，媒体库无法识别剧集 / 电影

2. 文件权限：脚本运行用户没有读取 complete 目录权限

3. 网络：TMM 的 DNS 被劫持，无法访问元数据站点，使用公共 DNS

## 附录 B：定期自动备份脚本（群晖任务计划程序）

> 用途：自动备份 qb 的 config 目录和种子，保存到群晖另一存储目录，可设置定时任务（每日凌晨执行）
> 使用方法：群晖控制面板 → 任务计划程序 → 新增【用户定义的脚本】，填入下面脚本，修改路径为你实际路径
> 
> 

```bash
#!/bin/bash
# qBittorrent配置备份脚本
BACKUP_SRC="/volume1/docker/qb/config"
BACKUP_DST="/volume1/backup/qb_backup"
TMP_NAME="qb_backup_$(date +%Y%m%d_%H%M%S).tar.gz"

# 创建备份目录
mkdir -p ${BACKUP_DST}
# 打包备份
tar -zcf ${BACKUP_DST}/${TMP_NAME} ${BACKUP_SRC}
# 保留最近7天备份，删除旧备份
find ${BACKUP_DST} -name "qb_backup_*.tar.gz" -mtime +7 -delete
```

> 注意事项：
> 
> 1. 修改脚本内路径为你真实的存储路径
> 
> 2. 任务运行用户选择和 qb 相同 UID 的用户，避免权限报错
> 
> 3. 建议备份目录放在不同硬盘 / 存储池，防止单盘损坏丢失
> 
> 

## 附录 C：整体网络拓扑

```Plain Text
光猫 → 主路由（拨号+DHCP）
        ↓
├─ 群晖NAS（Docker qBittorrent）
└─ 单网口OpenWrt旁路由（不拨号、无WAN，关闭DHCP+关闭DNS劫持）
```

```Plain Text
## 📝 保存操作步骤
1. 全选上面所有文本，复制
2. 电脑桌面右键 → 新建 → 文本文档
3. 粘贴内容进去
4. 文件 → 另存为
   - 文件名：`OpenWrt_群晖QB配置手册.md`
   - 编码：**UTF-8**
5. 保存完成，可用Typora、VS Code等软件打开查看。

如果你后续还要新增其他配置（比如飞牛OS、Audiobookshelf），我可以继续追加到这份文档里。
```

> （注：部分内容由豆包工作 AI 生成）