zykhs/opensurge-for-qnap repository overview

⁠OpenSurge for QNAP - 测试镜像

OpenSurge for QNAP 是面向 QNAP Container Station / Docker 的单容器 IPv4 透明代理网关。它使用 QNET、TUN 和 Linux policy routing，让局域网设备按需经过 Mihomo 代理。

⁠拉取

docker pull zykhs/opensurge-for-qnap:test

:test 是滚动更新的多架构测试标签，Docker 会按主机架构选择 amd64 或 arm64。它不适合生产环境；需要可复现部署时，请在 Docker Hub 查看并固定具体 digest。

架构标签也可单独使用：

zykhs/opensurge-for-qnap:test-amd64
zykhs/opensurge-for-qnap:test-arm64

⁠QNAP 使用方法

镜像只包含 OpenSurge 程序，不包含 QNAP 的 QNET 网络、固定 IP、设备权限和持久化挂载配置。推荐从 GitHub 下载部署文件，或按下面的 Container Station 手动设置逐项配置。

先从 GitHub 仓库下载部署文件，进入 deploy/qnap 目录：

https://github.com/zyk1172/OpenSurge-for-QNAP/tree/master/deploy/qnap⁠

复制并编辑环境文件：

cp .env.example .env

至少确认以下配置（按你的实际网络修改）：

OPENSURGE_IMAGE=zykhs/opensurge-for-qnap:test
OPENSURGE_IP=192.168.2.241
OPENSURGE_SUBNET=192.168.2.0/24
OPENSURGE_GATEWAY=192.168.2.1
OPENSURGE_PARENT_INTERFACE=br0
OPENSURGE_DATA_PATH=/share/Container/opensurge

其中：

• OPENSURGE_IP：OpenSurge 的固定局域网 IPv4；
• OPENSURGE_SUBNET：局域网 CIDR；
• OPENSURGE_GATEWAY：上游主路由 IPv4；
• OPENSURGE_PARENT_INTERFACE：QNAP 创建 QNET 时使用的网卡或 Virtual Switch；
• OPENSURGE_DATA_PATH：持久化目录，升级和重建时不要删除。

不知道 QNET 父接口时先运行：

sh ./preflight.sh --list-interfaces
sh ./preflight.sh

预检通过后启动：

docker compose up -d

打开 http://192.168.2.241:8080（请替换为你的⁠ OPENSURGE_IP）。首次创建管理员账户所需的一次性 bootstrap token 可从容器日志中获取：

docker logs opensurge

之后在 Web 的“代理与规则源”中导入 HTTPS Mihomo 订阅或本地 YAML 配置，再启动网关。

⁠Container Station 手动设置

如果不使用 Compose，在 Container Station 图形界面创建容器时，不能只填写镜像名。不同 QTS / Container Station 版本的字段名称可能略有不同，但以下值必须等价配置。

⁠1. 创建或选择 QNET 网络

在 Container Station 的网络设置中创建 QNET 网络（如果界面允许在创建容器时直接配置，也按同样的参数填写）：

• 网络类型 / 驱动：QNET；
• 网络名称：opensurge-qnet；
• 父接口：QNAP 实际联网的物理网卡或 Virtual Switch；先用 preflight.sh 确认，不要猜测；
• IPv4 子网：OPENSURGE_SUBNET，例如 192.168.2.0/24；
• IPv4 网关：OPENSURGE_GATEWAY，例如 192.168.2.1；
• 容器 IPv4：固定为 OPENSURGE_IP，例如 192.168.2.241；
• 容器内接口：通常为 eth0，不要因为宿主接口叫 br0 或 eth1 就改成同名。

⁠2. 容器基本设置

• 镜像：zykhs/opensurge-for-qnap:test；
• 容器名称：opensurge；
• 重启策略：unless-stopped；
• 网络：连接上面的 opensurge-qnet，并使用固定容器 IPv4；
• Web：容器监听 8080，通过 QNET IP 的 http://OPENSURGE_IP:8080 访问；不要使用 host network；
• 持久化挂载：/share/Container/opensurge:/data（左侧路径可按实际磁盘修改，但必须是 NAS 上的持久化目录）；
• 设备映射：/dev/net/tun:/dev/net/tun；
• Capabilities：NET_ADMIN、NET_RAW；
• 安全选项：no-new-privileges:true；
• 不要启用 privileged: true，不要挂载 Docker Socket。

环境变量至少填写：

TZ=Asia/Shanghai
OPENSURGE_ROLE=gateway
OPENSURGE_WEB_ADDR=0.0.0.0:8080
OPENSURGE_SEED_LAN_IP=192.168.2.241
OPENSURGE_SEED_LAN_CIDR=192.168.2.0/24
OPENSURGE_SEED_UPSTREAM_GATEWAY=192.168.2.1
OPENSURGE_CONTAINER_INTERFACE=eth0

其中 IP、网段、上游网关和父接口必须替换成你的真实网络值。Web UID/GID 可按 NAS 文件权限需要设置，通常为 OPENSURGE_WEB_UID=1000、OPENSURGE_WEB_GID=100。

⁠3. IPv4 转发和 IPv6 设置

当前产品数据面为 IPv4-only，IPv6 保持关闭。Container Station 如果提供 sysctl 设置，请逐项填写：

net.ipv4.ip_forward=1
net.ipv4.conf.all.rp_filter=0
net.ipv4.conf.default.rp_filter=0
net.ipv6.conf.all.disable_ipv6=1
net.ipv6.conf.default.disable_ipv6=1
net.ipv6.conf.eth0.disable_ipv6=1

不要重新启用 IPv6，也不要用全局网络模式替代 QNET。

⁠4. 可选 Host Takeover 设置

只有在确实需要让 QNAP NAS 宿主机自身也使用 OpenSurge 时才启用。Compose 用户直接使用：

docker compose -f docker-compose.yml -f docker-compose.host-takeover.yml up -d

如果在 Container Station 手动配置，还要额外增加：

• Capability：SYS_ADMIN；
• 只读挂载：/proc/1/ns/net:/run/opensurge/host-netns:ro；
• 环境变量：OPENSURGE_HOST_NETNS_PATH=/run/opensurge/host-netns。

然后在 Web 中开启“让 NAS 使用 OpenSurge”。启用前必须确认持久化配置中的 upstream_gateway 是有效且非空的上游路由 IPv4；不能留空，否则会出现 “QNAP fallback gateway is invalid” 错误。

Host Takeover 不使用 privileged: true，不挂载 Docker Socket，也不修改 QTS 默认网关；异常时 OpenSurge 会尝试回退到 QTS 原路径。

⁠先测试一台客户端

不要一开始就修改全家的 DHCP。先选一台手机、电脑或电视，将它的网络设置改为：

IPv4 网关 = OpenSurge IP
DNS       = OpenSurge IP

例如：

IPv4 网关 = 192.168.2.241
DNS       = 192.168.2.241

确认 DNS、DIRECT、PROXY、TCP、视频和下载等实际场景正常后，再逐步扩大使用范围。

⁠更新

保留同一个 /data 持久化目录，只更新镜像：

docker compose pull
docker compose up -d

不管是升级还是重建，都不要删除 /share/Container/opensurge，其中保存账户、配置、订阅和恢复状态。

⁠当前限制

• 当前数据面为 IPv4-only，不接管 IPv6；
• 不自动修改主路由 DHCP 或 QTS“网络与虚拟交换机”；
• 修改 QNET 父接口、OpenSurge 固定 IP、网段或主路由地址后，需要重建容器；
• ARM64 已提供镜像，但不同 QNAP ARM 型号的 QNET、TUN 和内核策略路由能力可能不同；
• 这是测试版，升级前请备份 /data，并先在非生产设备上验证。

⁠排查

docker ps --filter name=opensurge
docker logs --tail 200 opensurge
docker inspect --format '{{json .State.Health}}' opensurge
docker exec opensurge ip -br addr
docker exec opensurge ip route
docker exec opensurge ip rule

⁠来源与许可证

• GitHub：https://github.com/zyk1172/OpenSurge-for-QNAP⁠
• GitHub 测试发布：https://github.com/zyk1172/OpenSurge-for-QNAP/releases/tag/qnap-test-latest⁠
• 许可证：GPL-3.0-only

这是 OpenSurge for QNAP 的测试镜像，不代表稳定版或生产可用性。