HomeProxy 介绍和使用指南

软件介绍

HomeProxy 是 ImmortalWrt 团队的官方代理插件，和 OpenClash、PassWall 放在一起，就是 OpenWrt 生态里三大代理插件的新面孔。它的定位在 GitHub 描述里写得很直白：“为 ARM64/AMD64 设计的现代 ImmortalWrt 代理平台（powered by sing-box）”——内核直接用 sing-box，不碰 Clash 那套配置体系，也不像 PassWall 那样多内核可切换，而是一条路走到底：sing-box 内核 + 内置国内/GFW 资源列表 + DNS 国内外分流。

插件把代理做进网关层：路由器一开，整个局域网里的设备连上 WiFi 就自动被接管，手机、电脑都不用单独配代理。和 OpenClash 侧重"策略组精细分流"、PassWall 侧重"规则简单直接"不同，HomeProxy 的开箱即用程度是三者里最高的——装上、导入订阅、选主节点，默认的"大陆白名单"路由模式加上默认 DNS 就能跑，大部分设置项都带着贴心的默认值。我这次写文的测试环境是 OpenWrt 24.10.7 x86_64 虚拟机，下文所有界面描述和运行状态，都来自这台机器上的真实中文界面和实拍截图。

身世：从个人仓库走进 ImmortalWrt 组织

HomeProxy 的作者是 lxiaya，ImmortalWrt 团队的维护者之一。仓库最开始挂在他个人名下（lxiaya/openwrt-homeproxy），README 第一句就是"The modern ImmortalWrt proxy platform for ARM64/AMD64 (powered by sing-box)"，项目从设计之初就是奔着 ImmortalWrt 生态去的。最早一批第三方 fork 出现在 2023 年 10 月，说明仓库在那之前就建好了，到今天已经维护了三四年。现在项目挂在 ImmortalWrt 官方组织下（immortalwrt/homeproxy），协议 GPL-2.0；截止到本文更新时间，Stars 约 1061，最近一次更新在 2026 年 8 月初，属于活跃项目。

HomeProxy 出现的时间点很有意思：那几年 OpenWrt 的代理插件要么绑死 Clash 配置、要么绑死 xray，而 sing-box 正在快速成为新一代多协议内核。HomeProxy 押注 sing-box，把"内核 + 资源列表 + DNS 分流"打包成一个整体，是 ImmortalWrt 团队对"现代代理插件应该长什么样"的答案。和 OpenClash（mihomo 内核，vernesong/OpenClash）、PassWall（xray 等多内核，Openwrt-Passwall/openwrt-passwall）相比，三者的内核路线完全不同，文末有专门的对比表。

先过一遍术语：

• 节点：机场分配的一台代理服务器，里面装着协议、地址、端口、密码等连接信息，一条订阅通常包含几十个。
• 订阅：机场发放的链接，把全部节点信息打包在里面，插件更新订阅时自动拉取。
• 内核：承担流量转发的底层程序。HomeProxy 是控制界面，sing-box 是执行转发的引擎，opkg 装插件时自动带上。
• 资源列表：分流规则的数据源。HomeProxy 内置国内 IPv4 库、国内 IPv6 库、国内域名列表、GFW 域名列表四份，状态页一键更新。
• 大陆白名单：大陆 IP 和国内域名走直连、其余流量走代理的路由模式，是 HomeProxy 的默认选项。
• TProxy：Linux 的透明代理技术，能接管 UDP 流量（游戏、语音），Redirect 模式管不了 UDP。
• Redirect：iptables/nftables 的端口重定向，只对 TCP 生效，配合 TProxy 补上 UDP 那一半。
• DoH/DoQ/DoT：三种加密 DNS 传输方式，分别走 HTTPS、QUIC、TLS 协议，比明文 DNS 难被污染和偷看。
• GFW：教程语境里指被墙域名名单，命中名单的域名才走代理。

优点和缺点

优点：

• 开箱即用：默认大陆白名单 + 默认国内外 DNS，导入订阅选完节点就能跑，不用懂策略组
• 资源列表一体化：国内/GFW 域名和 IP 列表内置在状态页，点一下"检查更新"就行，不用自己找规则集
• DNS 国内外分流：DNS 服务器和国内 DNS 服务器分开填，默认谷歌 8.8.8.8 + 阿里 223.5.5.5，支持 DoH/DoQ/DoT
• UDP 原生支持：默认代理模式就是 Redirect TCP + TProxy UDP，游戏和语音流量不用额外折腾
• 官方组织维护：挂在 ImmortalWrt 组织下，跟着固件生态一起更新，版本节奏稳定

缺点：

• 面向新平台：官方明确限定 ARM64/AMD64，老架构设备（mips、老 armv7 路由）不在支持范围
• 配置项偏整合：资源列表、DNS 都走内置方案，想完全自定义规则集不如 OpenClash 灵活
• 教程资料少：教程数量不如 OpenClash、PassWall 多，冷门问题主要靠 GitHub Issues 翻答案

谁适合 HomeProxy： 刚入软路由、想要"装上就能用"的玩家；一直在用 ImmortalWrt 固件、想让插件和固件同生态的；以及游戏、语音这类 UDP 流量多的用户。谁不适合： 老架构路由器（官方不支持）、重度自定义规则玩家（规则体系比 OpenClash 简单）。

sing-box 内核意味着什么

HomeProxy 界面只是壳，真正干活的是 sing-box 内核。sing-box 是社区里新一代的单二进制多协议代理内核：SS、VMess、Trojan、VLESS、Hysteria 2、Tuic 这些协议都在一个程序里实现，配置用 JSON 描述。HomeProxy 做的就是把 LuCI 里的中文设置翻译成 sing-box 的 JSON 配置——用户全程不碰 JSON，主节点、DNS、路由模式这些选项在界面里点完，插件自动生成内核配置并拉起进程。

选 sing-box 的连带好处是新协议跟进快：Clash 系内核的协议支持要看维护方节奏，sing-box 这边新协议基本是发布即支持。坏处也有——想高度自定义时，界面选项覆盖不到的部分就不好办了，这也是它和 OpenClash 的分水岭：OpenClash 把 Clash 配置全文开放给你改，HomeProxy 走"界面生成配置"路线。

下载安装

安装前先确认两件事：路由器的 CPU 架构和固件类型。HomeProxy 官方只支持 **ARM64（aarch64）和 AMD64（x86_64）**两种架构，在 LuCI 的"系统 → 软件包"页面能看到 CPU 架构；固件是 ImmortalWrt 最省心，官方 OpenWrt 也能装，但插件默认面向 ImmortalWrt 的包管理器和防火墙组件（firewall4、nftables 那套）。下面两种安装方式按我实测的 x86_64 写，架构后缀换成 aarch64 就是 ARM 设备的对应包。

我这次的环境是 OpenWrt 24.10.7 x86_64 虚拟机，安装结果如下表，写文时用的版本都在这：

opkg update
opkg install luci-app-homeproxy

opkg install /tmp/luci-app-homeproxy.apk

安装报错排查

• opkg 装不上先 opkg update：软件源索引过期是最常见原因，报"Unknown package"或 404 基本都是这个，先更新列表再装
• 依赖冲突：把已经装着的 OpenClash、PassWall 之类的代理插件先卸载再装 HomeProxy，别让两套代理组件在系统里抢资源
• 内核模块加载失败：TProxy 报错时检查固件内核版本和 opkg 源是否匹配，官方 OpenWrt 固件混用 ImmortalWrt 软件源最容易出这种问题，换成同一家固件的软件源就好
• 安装后自检三步：① 菜单里出现 服务 → HomeProxy；② 已安装列表里有 sing-box；③ 打开插件首页状态徽章不是一片空白（未运行是正常的，选完主节点才运行）

使用教程

界面一览：四个标签页

装好后打开 服务 → HomeProxy，页面顶部是四个标签：客户端设置、节点设置、服务器设置、服务状态。打开默认落在"客户端设置"页，页面上方有运行状态徽章，显示 HomeProxy (sing-box v1.12.22) 加运行状态——未运行（红色）或运行中，括号里的版本号跟着实际装的 sing-box 内核走。客户端设置页里还分了路由设置和访问控制两个子分区，日常配置基本都在这一页完成。四个标签的分工先记牢：

• 客户端设置：主节点、DNS、路由模式、代理模式，日常用的 80% 操作都在这里
• 节点设置：导入订阅、管理节点列表
• 服务器设置：把路由器变成代理服务端时才用，纯客户端用户不用管
• 服务状态：连接检查、资源列表更新、三段日志，排错的主战场

图注：HomeProxy 默认的客户端设置页，从上到下依次是主节点、主 UDP 节点、DNS 服务器、国内 DNS 服务器、路由模式、路由端口、代理模式和 IPv6 支持，状态徽章显示"未运行"。

第一步：导入订阅

点顶部节点设置标签，页面里有两个子标签：节点和订阅。订阅列表页有"导入分享链接"按钮，把机场发给你的订阅链接粘贴进去，保存后点更新，插件就会拉取订阅里的全部节点。首次添加订阅后，节点列表从"尚无任何配置"变成机场下发的节点列表，之后想刷新节点，回到这里点更新就行。订阅失效的常见表现是更新报错或节点列表一直不变，去机场面板确认链接还能用，删掉重新导入一次即可。

图注：节点设置页的"节点/订阅"子标签，节点表格列出名称、应用、类型、地址、端口五列，未添加任何配置时显示"尚无任何配置"。

第二步：管理节点

节点列表按名称、应用、类型、地址、端口五列展示，一眼看清每个节点用的协议、服务器地址和端口。想单独加一个节点，用页面上的导入分享链接按钮，粘贴单节点链接（比如 ss://、vless://、trojan:// 这类），插件解析后直接进列表。节点管理页的操作主要就两个：导入和查看——具体把哪个节点设为生效节点，要到"客户端设置"页的主节点里选，不在节点列表页操作。看到某个节点类型识别异常（列表里类型列是空的或乱码），通常是链接格式旧或机场给的协议太新，换订阅源或换节点试试。

第三步：客户端设置（主节点、DNS、路由、代理模式）

回到客户端设置页，从上到下依次设置：

• 主节点：默认"禁用"。改成某个节点后，路由器才开始走代理。这一步是 HomeProxy 的"总开关"，主节点选好并保存应用，状态徽章就从"未运行"变"运行中"
• 主 UDP 节点：默认"保持与主节点一致"。需要 UDP 流量（游戏、语音）走单独线路时在这里指定；没有特殊需求保持默认
• DNS 服务器：默认谷歌公共 DNS 8.8.8.8，负责解析走代理的域名。界面提示支持 UDP、TCP、DoH、DoQ、DoT，不指定传输方式时走 TCP 协议
• 国内 DNS 服务器：默认阿里云公共 DNS 223.5.5.5，负责解析国内域名，和国外 DNS 分开，互不污染
• 路由模式：默认大陆白名单——大陆 IP 和国内域名直连，其余流量走代理，适合绝大多数家庭场景
• 路由端口：默认仅常用端口（绕过 P2P 流量），BT 下载这类 P2P 流量不经过代理；多个端口用逗号隔开
• 代理模式：默认 Redirect TCP + TProxy UDP，TCP 走 Redirect、UDP 走 TProxy，两层都接管
• IPv6 支持：勾选后 IPv6 流量也走代理，前提是固件 WAN6 能正常拿到 IPv6 地址

每个设置项旁边都有中文说明，改完点保存并应用才生效。最省心的组合就是全默认值 + 主节点选机场节点，这也是我日常的使用方式——除了主节点，其余设置我都没动过。

第四步：服务状态检查

点顶部服务状态标签，这一页是排错和日常巡检的核心，分三块：

• 连接检查：内置百度和谷歌两个检查目标，分别对应国内直连和国外代理链路。点"检查"，通过/失败一目了然——百度通了说明国内直连正常，谷歌通了说明代理链路正常，两个一起查就能定位问题出在国内段还是国外段
• 资源管理：四份分流列表——国内 IPv4 库、国内 IPv6 库、国内域名列表、GFW 域名列表，各自带版本号和"检查更新"按钮。版本号是日期+序号格式（我机器上显示 20260424052559 这种），定期点一下更新，分流规则就跟上最新变化
• 日志区：HomeProxy 日志、sing-box 客户端日志、sing-box 服务端日志三段，每 5 秒自动刷新，各有"清空日志"按钮

图注：服务状态页自上而下是连接检查（百度/谷歌）、资源管理（四份列表带版本号）、三段日志（HomeProxy 日志、sing-box 客户端/服务端日志），日志每 5 秒刷新。

第五步：日志排错

出问题时先看连接检查，再翻日志，比瞎猜快得多：

• HomeProxy 日志：插件自身运行状态，比如资源列表更新失败、配置生成报错，问题在插件层就看它
• sing-box 客户端日志：代理客户端运行日志，节点连不上、握手超时、协议报错都在这，级别默认警告，想看得更细可以把级别往下调
• sing-box 服务端日志：把路由器当代理服务端时才有内容，纯客户端使用基本用不到

我在 26.151 上遇到过"主节点选了但上不了网"的情况：连接检查里百度通、谷歌不通，sing-box 客户端日志刷出节点握手超时——换另一个节点立刻恢复。日志区是判断"是节点问题还是配置问题"最直接的工具。

服务器设置标签（服务端模式）

顶部四个标签里平时基本用不到的，就是服务器设置：它把路由器反过来变成一台代理服务器，让其他设备（手机、电脑、甚至另一台路由器）把代理指向这台路由器来上网。服务状态页里第三段 sing-box 服务端日志就是为这个模式准备的。只有自建代理服务、或者想让家里路由器给外出设备当跳板时才需要碰它，纯客户端使用直接忽略这个标签，不影响任何功能。

深入配置（进阶篇）

资源列表更新

资源管理里的四份列表决定了分流规则的边界：国内 IPv4/IPv6 库覆盖国内 IP 段，国内域名列表覆盖常见国内站点域名（这些直连），GFW 域名列表覆盖被墙域名（这些走代理）。默认配置下这套列表已经能覆盖绝大多数场景，但列表会随网络环境变化，建议每个月在状态页点一次"检查更新"。更新失败时看 HomeProxy 日志里的具体报错，一般是网络问题，稍后再试即可。

DNS 国内外分流

HomeProxy 的 DNS 设计是"国外 DNS 管代理域名、国内 DNS 管直连域名"：走代理的域名交给 DNS 服务器（默认 8.8.8.8）在代理侧解析，避开 DNS 污染；国内域名交给国内 DNS 服务器（默认 223.5.5.5）解析，延迟低。这个分流默认就生效，不用像 OpenClash 那样单独调 DNS 策略。想换加密 DNS，两个字段都支持 DoH、DoQ、DoT，按协议格式填 URL 就行——DoH 用 https:// 开头、DoQ 用 quic://、DoT 用 tls://。

代理模式：Redirect 与 TProxy

代理模式默认 Redirect TCP + TProxy UDP，这是 HomeProxy 推荐的组合：TCP 用 Redirect（端口重定向，兼容性好、性能高），UDP 用 TProxy（透明代理，能接管 UDP 流量）。为什么 UDP 要单独用 TProxy？因为 Redirect 只能重定向 TCP，游戏、语音这类 UDP 流量必须靠 TProxy 才能接管。想玩主机游戏、开语音的，保持默认模式别动；确认不需要 UDP 代理的，可以只留 Redirect TCP，省一点内核开销。

路由模式与路由端口

路由模式默认大陆白名单，理解成"国内直连 + 国外代理"就行，这是国内家庭网络最合适的默认值。路由端口默认仅常用端口（绕过 P2P 流量），意思是只代理常用服务端口，BT 下载的流量直接放行——别为了省事改成全部端口，否则 BT 流量全走代理，机场流量翻倍、路由器 CPU 也吃紧。想精细控制，就在路由端口里用逗号列出想要代理的端口范围。

访问控制与 IPv6

客户端设置页下方的访问控制子分区，用来按设备控制代理策略：某些设备强制走代理、某些设备绕过代理，都在这里按设备（IP 或 MAC）指定，适合"给电视盒子开代理、给打印机保持直连"这类场景。IPv6 支持勾选框在客户端设置页底部，勾选后 IPv6 流量同样进代理链路；前提是 WAN6 正常获取到地址，没配好 IPv6 就先别勾，不影响 IPv4 使用。

旁路由部署

HomeProxy 走透明代理，旁路由部署不需要在插件里做任何额外设置：主路由正常拨号，旁路由（跑 HomeProxy 的这台）接在主路由下，然后把需要走代理的设备网关和 DNS 手动指到旁路由的 IP，流量就自动进代理。想在整网层面生效，把主路由的 DHCP 下发的网关和 DNS 改成旁路由 IP 即可，改完记得让设备重新获取一次 IP（重启设备或断开重连 WiFi）。

更新与维护

HomeProxy 更新跟着 ImmortalWrt 软件源走，SSH 执行 opkg update && opkg upgrade luci-app-homeproxy 就能升到源里最新的版本；想追 GitHub Releases 的新包，下载对应架构的安装包手动装（见下载安装的方案二）。升级完回插件页面看一眼状态徽章和资源列表版本，如果 sing-box 版本号变了，说明内核也一起升了，不需要额外操作。

配置备份只涉及一个文件：/etc/config/homeproxy。SSH 执行 cp /etc/config/homeproxy /tmp/homeproxy.bak 就能留一份，大版本升级前备份一次，出问题直接拷回去恢复。

从 OpenClash 或 PassWall 迁移

换插件的完整流程走一遍大概十分钟：

1. 在旧插件（OpenClash/PassWall）里停用服务，避免新旧两套代理同时抢端口
2. 卸载旧插件，再按上文方案一安装 HomeProxy
3. 导入订阅、选主节点，客户端设置其余保持默认
4. 保存应用后去服务状态页跑一次连接检查，百度、谷歌都通过就迁移完成
5. 最后重启一次防火墙，把旧插件留下的端口规则清干净

迁移后 DNS 和分流规则都交给 HomeProxy 内置方案，旧插件里配过的自定义规则不会带过来，需要的话在 HomeProxy 的访问控制和路由端口里重新配。

和 OpenClash、PassWall 的对比

OpenWrt 三大代理插件，内核路线完全不同，选型看这张表就够（版本为截止到本文更新时间的实测/发布版本）：

我的取舍：第一次接触 OpenWrt 代理、想装完就用的，选 HomeProxy，默认值靠谱，导入订阅选完主节点就能跑，资源列表和 DNS 都不用管；追求策略组级别的精细分流、一个域名指定一条线路的，选 OpenClash（详见本站 OpenClash 介绍和使用指南）；用惯了 PassWall 那套规则逻辑、想继续老牌稳定的，维持 PassWall（详见本站 PassWall 介绍和使用指南）。三个插件都开源活跃，差别主要在内核路线、学习成本和玩法上限，没有明显痛点就不用换。想在电脑端体验同款 sing-box 内核配置思路的，可以看本站 v2rayA 使用教程。

切换插件提醒： 装新插件前先把旧插件的服务停掉，装完切换后建议重启一次防火墙，端口规则才会干净刷新。同一台路由器不要同时运行两个代理插件，端口冲突会让全家断网。

常见问题

常见问题（FAQ）

1. HomeProxy 和 OpenClash、PassWall 能同时装吗？

能装但别同时运行。三个插件都接管透明代理和 DNS，同时开启会抢端口、规则打架，表现就是全家上不了网。想换插件，先停旧的、再装新的。

2. 装好后状态一直显示"未运行"？

绝大多数情况是主节点还没选。去客户端设置页把主节点从"禁用"改成具体节点，保存并应用，状态才会变"运行中"。订阅没更新导致节点列表为空，也会卡在未运行。

3. 需要单独下载 sing-box 内核吗？

不需要。opkg 安装 luci-app-homeproxy 时，依赖会自动带上 sing-box 和 firewall4、kmod-nft-tproxy 等组件，装完即可用，这是 HomeProxy 对比 PassWall 少折腾的地方。

4. HomeProxy 支持哪些协议？

支持范围跟着 sing-box 内核走：Shadowsocks、VMess、Trojan、VLESS、Hysteria 2、Tuic 这些 sing-box 支持的协议都能用。具体某个协议能不能跑，看节点导入后列表里的类型列有没有正常识别。

5. DNS 服务器和国内 DNS 服务器分别填什么？

默认**谷歌 8.8.8.8（国外）+ 阿里 223.5.5.5（国内）**就能正常用。想要加密 DNS，两个字段都支持 DoH、DoQ、DoT，按协议格式填 URL 即可。

6. 代理模式"Redirect TCP + TProxy UDP"是什么意思？

TCP 流量走 Redirect 重定向，UDP 流量走 TProxy 透明代理，两者配合把 TCP 和 UDP 都接管进代理链路。保持默认即可；确认不需要 UDP 代理时可只留 Redirect TCP。

7. UDP 游戏流量不通怎么办？

先检查主 UDP 节点有没有单独设置（默认跟着主节点），再确认代理模式里含 TProxy UDP。都正常还不行，看 sing-box 客户端日志里 UDP 相关报错，通常是节点对 UDP 支持不好，换节点试试。

8. 资源管理里四份列表各是干什么的？

国内 IPv4 库和国内 IPv6 库是直连的国内 IP 段，国内域名列表是直连的国内站点域名，GFW 域名列表是走代理的被墙域名。四份一起决定了"国内直连、国外代理"的分流边界，定期点检查更新就行。

9. 路由端口"仅常用端口（绕过 P2P 流量）“要改吗？

不用改。默认值把 BT 下载这类 P2P 流量放行，避免机场流量和路由器 CPU 被下载吃满。改成全部端口后 BT 会全走代理，一般不划算。

10. 订阅更新后节点列表没变化？

先确认订阅链接还能访问（机场面板里测试），再到节点设置 → 订阅页手动点更新，看 HomeProxy 日志有没有更新失败报错。订阅失效是最常见原因。

11. IPv6 支持要勾选吗？

固件 WAN6 正常拿到 IPv6 地址再勾，勾了之后 IPv6 流量也走代理。IPv6 没配好就先别勾，不影响 IPv4 上网。

12. HomeProxy 能把路由器当代理服务端用吗？

可以。顶部服务器设置标签就是配服务端的，服务状态页里也有独立的 sing-box 服务端日志。把路由器变成代理服务端，可以让其他设备把代理指向这台路由器。

13. 想从 OpenClash/PassWall 换过来，配置会丢吗？

配置不会自动迁移，需要重新导入订阅、重选主节点。好在 HomeProxy 主要设置就集中在客户端设置一页，重新配一遍十分钟以内，路由模式和 DNS 都保持默认即可。

14. 插件升级会丢配置吗？

HomeProxy 的配置存在 OpenWrt 的 UCI 配置文件里（/etc/config/homeproxy），opkg 升级插件不会动这个文件，升级后配置都在。保险起见，大版本升级前可以备份一份 /etc/config/homeproxy 文件。

15. HomeProxy 日志一直提示"日志文件不存在”？

这是正常状态：插件还没产生过日志（比如从未运行成功过）时，日志文件还没生成，界面就提示这个。选好主节点、跑起来之后再看，日志就会出现了。

16. 连接检查里百度和谷歌都失败？

两个目标同时失败，先看主节点是否选中并保存应用，再看 sing-box 客户端日志有没有报错。如果节点状态正常、日志干净，多半是机场节点整体不可用，换个节点或回机场面板看看线路状态。

17. 改了设置但好像没生效？

HomeProxy 每个设置项改完都要点保存并应用才会写进配置并重启相关服务，只点"保存"不会生效。改了路由模式、代理模式这类底层设置后如果还是老行为，去防火墙页面重启一次防火墙，规则就会重新加载。