开启 3 天免费试用
注册即可免费体验全部高级功能。
*仅限新用户；每位用户只能获得一次试用。
HomeProxy 安装教程：OpenWrt 部署、验证与回滚
Kevin Wu
2026年10月14日· 8 分钟阅读
完成 HomeProxy 安装后，OpenWrt 类固件的 LuCI 里会多出一个界面，它负责生成 sing-box 客户端配置，并把路由器流量导入其中。请从固件自己的官方软件源安装，只让一台测试客户端经由一个你有权使用的节点出网，并确认停止服务后网络恢复直连。本文依据文末列出的官方来源整理，未完成完整端到端实测。
关键要点
- HomeProxy 是 LuCI 应用，真正承担代理工作的是底层的 sing-box。
- 项目没有打标签的发行版，安装时要固定固件和软件包版本。
- 先只代理列表里的一台客户端，因为 DNS 改动会影响所有向路由器查询 DNS 的设备。
- 服务停止后，应清除它添加的路由规则、防火墙链和 dnsmasq 配置。
本文覆盖哪一种 HomeProxy 安装环境？
项目将 HomeProxy 描述为面向 ARM64 与 AMD64 设备、基于 sing-box 的现代 ImmortalWrt 代理平台。仓库里的 README 只是一份简短的待办清单，并不是安装手册，而且没有打标签的发行版。因此本文以提交 98a6ad9 的代码为准，只介绍其中确实存在的选项。［1］
软件包定义声明了四个依赖：sing-box、firewall4、kmod-nft-tproxy 和 ucode-mod-digest。它还列出了升级时作为配置保留的文件，包括 /etc/config/homeproxy 以及直连、代理域名列表。［2］
本文基线是 ImmortalWrt 24.10.6，这是一款基于 OpenWrt 的固件：其 LuCI 软件源提供 luci-app-homeproxy 版本 26.236.50592~9b8ee64，packages 软件源提供 sing-box 1.12.25-r1。［3］［4］ 原版 OpenWrt 没有官方的 HomeProxy 发行包，所以本文不涉及从来路不明的镜像安装构建产物。
开始之前，先想清楚自己是否真的要在路由器上运行网关。自建服务的责任划分指南说明了自己维护这条路径要承担哪些工作；在把路由器交给它之前，也值得先对比自己维护服务器与使用托管 VPN 服务的差别。如果 HomeProxy 不合适，另一类插件可参考 OpenClash 安装与恢复流程，普通隧道方案则见 OpenWrt WireGuard 客户端配置步骤。
HomeProxy 会改动路由器上的哪些内容？
选定主节点后启动服务时，init 脚本会生成 /var/run/homeproxy/sing-box-c.json，并对它执行 sing-box check。检查失败则中止启动，原因写入 /var/run/homeproxy/homeproxy.log。［5］
同一个脚本会改动路由器的三个层面：写入一个 dnsmasq 配置目录并重启 dnsmasq，添加策略路由规则（TProxy 默认使用表 100 和标记 101），并带着 HomeProxy 的链重新加载 firewall4。此外，WAN 接口上线时服务也会重新加载。［5］
| 层面 | 随服务启用的内容 | 停止流程会清除的内容 |
|---|---|---|
| 代理进程 | 由生成的 JSON 启动的 sing-box 客户端 | 生成的 JSON 和客户端日志 |
| DNS | Global 模式下 dnsmasq 转发到 127.0.0.1#5333 | HomeProxy 的 dnsmasq 目录，随后重启 dnsmasq |
| 路由 | 表 100 中的 ip rule 与本地路由 | IPv4 和 IPv6 的同一组规则与路由 |
| 防火墙 | inet fw4 中的 homeproxy_* 链和集合 | 清空并删除这些链和集合 |
DNS 这一行决定了测试怎么规划。在 Global、Bypass mainland China 和 Custom routing 模式下，脚本会让 dnsmasq 停用原有上游，把查询转发到本机 sing-box 的 DNS 端口。所以受影响的是所有向路由器查询 DNS 的客户端，而不只是你列入代理名单的那一台。［5］
步骤 1：核对固件、架构和存储空间
使用你拥有或有权管理的路由器，准备一台接在已知 LAN 口上的有线客户端，并确认该型号有文档记载的恢复方法。安装前记录固件版本、CPU 架构和剩余空间。
cat /etc/openwrt_release
uname -m
opkg print-architecture
df -h /overlay /tmp
把架构与准备使用的软件包索引对照。LuCI 软件包与架构无关，但 sing-box 和内核模块按目标平台分别构建，所以同一版本下，AMD64 路由器和 aarch64_cortex-a53 路由器需要不同的二进制文件。［3］［4］
如果固件不是 ImmortalWrt 24.10.6，又无法确认有匹配的官方软件源，就停在这里。混用其他版本的软件包可能破坏内核模块依赖，本文也没有验证基线以外的兼容性。
步骤 2：备份后完成 HomeProxy 安装
在 LuCI 中打开 System → Backup / Flash Firmware（即备份与刷写固件页面），把配置备份下载到另一台设备。同时记下当前的 DNS 转发服务器和测试客户端的 LAN 地址。整个过程保持有线管理会话不断开。
在路由器上刷新软件包列表，再从官方软件源安装 LuCI 应用。软件包列表保存在内存中的 /tmp/opkg-lists，重启后会丢失，所以之后每次安装前都要重新执行 opkg update。［6］
opkg update
opkg list-installed | grep -E 'homeproxy|sing-box'
opkg install luci-app-homeproxy
安装会自动拉取声明的依赖。请阅读事务输出：如果 opkg 报告依赖或内核模块冲突，就停下来按固件文档解决，不要强制安装。［2］［6］ 安装完成后刷新 LuCI，应用会出现在 Services → HomeProxy 下，包含 Client Settings、Node Settings、Server Settings 和 Service Status 四个页面（简体中文界面分别显示为“客户端设置”“节点设置”“服务器设置”“服务状态”）。［1］
不要为了让安装通过而升级路由器上的全部软件包。opkg 文档明确不建议批量升级，因为这可能让设备在软件层面变砖。［6］
步骤 3：导入一个获授权的节点
打开 Services → HomeProxy → Node Settings。在 Nodes（节点）标签页中，可以手动添加节点：选择 Type（类型），填写 Address（地址）和 Port（端口）；也可以通过 Import share links（导入分享链接）粘贴分享链接，完成 HomeProxy 节点导入。导入对话框列出的支持格式为 Hysteria、Shadowsocks、Trojan、VMess（v2rayN 格式）和 VLESS 链接。［7］
只使用你自己运行或获准使用的节点。保持 Allow insecure（允许不安全连接）关闭：关闭证书校验只是掩盖不匹配，并没有解决问题。不要把订阅地址或分享链接贴到公开论坛或截图里，它们本身就相当于凭证。
HomeProxy 会根据这些字段生成 sing-box 配置。遇到不确定的协议参数时，请查阅路由器上已安装版本对应的 sing-box 文档中相应的 outbound 说明，不要凭猜测填值。［8］
步骤 4：为一台客户端选择 HomeProxy 路由模式
打开 Client Settings → Routing Settings（路由设置）。把 Main node（主节点）设为刚导入的节点；只要它还停在 Disable（禁用），客户端服务就不会启动。［5］［9］ Main UDP node（主 UDP 节点）保持默认，即沿用主节点。
Routing mode（路由模式）提供 GFWList、Bypass mainland China（默认值，中文界面为“大陆白名单”）、Only proxy mainland China、Custom routing 和 Global（全局）。［9］ 第一次做有边界的测试时，Global 的预期最简单：列表中客户端的流量应从节点出去。Proxy mode（代理模式）保持默认的 Redirect TCP + TProxy UDP；只有安装了 ip-full 和 kmod-tun 后才会出现 Tun 选项。［9］
| 设置 | 首次测试取值 | 原因 |
|---|---|---|
| Main node | 刚导入的节点 | 客户端服务启动的前提 |
| Routing mode | Global | 每台客户端只有一个明确预期 |
| Proxy mode | Redirect TCP + TProxy UDP | 软件包默认值，无需额外模块 |
| IPv6 support | 按你计划的覆盖范围 | 启用后会添加 IPv6 规则 |
| Proxy filter mode | Proxy listed only | 只拦截一台客户端 |
接着打开 Access Control（访问控制）标签页，选择 LAN IP Policy（LAN IP 策略），把 Proxy filter mode（代理过滤模式）设为 Proxy listed only（中文界面为“仅允许列表内”）。在 Proxy IPv4 IP-s 中添加测试客户端的地址（测试 IPv6 时再填 Proxy IPv6 IP-s），管理电脑不要加入列表。［9］ 保存并应用后，确认 Service Status 显示客户端正在运行。
步骤 5：验证客户端出口、DNS 和 IPv6
在测试客户端上逐条单独检查，然后在不在列表中的客户端上重复关键检查。下表是预期现象，实际结果请自己记录。
| 检查方法 | 预期现象 | 失败时处理 |
|---|---|---|
| 在列表内客户端打开 IP 检测页 | 显示节点的公网地址 | 查看 homeproxy.log 和节点字段 |
| 在列表外客户端打开同一页面 | 显示平时的运营商地址 | 重新检查 Proxy filter mode 和列表 |
| 在两台客户端上解析域名 | 应答经由路由器返回 | 停止服务并对比 dnsmasq |
| 在列表内客户端访问仅 IPv6 站点 | 与 IPv6 support 的选择一致 | 缩小范围或关闭 IPv6 support |
| 从有线客户端访问 LuCI | 管理仍然正常 | 立即停止服务 |
检查出口时，可以在每台客户端上比对对外显示的公网地址。列表内客户端的地址变了，只能说明它的网页流量到达了节点；DNS 和 IPv6 仍需单独检查。
路由器状态也要看。服务运行期间，ip rule show 应能看到 HomeProxy 的标记规则，nft list ruleset | grep homeproxy 应能看到它的链。［5］ 启用 IPv6 support 时，脚本会添加对应的 IPv6 规则；如果客户端有 IPv6，而测试显示 IPv6 走的是直连，请在扩大列表前把这一限制记录下来。
步骤 6：停止服务并确认恢复直连
通过 init 脚本停止 HomeProxy；如果试用到此结束，再关闭开机自启。这只影响路由器上的 HomeProxy。
/etc/init.d/homeproxy stop
/etc/init.d/homeproxy disable
ip rule show
nft list ruleset | grep homeproxy
停止流程会删除它的策略路由规则和路由，清空并删除 homeproxy_* 链与集合，移除它的 dnsmasq 目录并重启 dnsmasq。［5］ 因此，两条检查命令都不应再显示 HomeProxy 相关条目。测试客户端上的 IP 检测页应重新显示平时的地址，域名解析也应回到原来的转发服务器。
任何时候一旦失去管理访问，先用有线客户端停止服务，再恢复步骤 2 的配置备份。不要一上来就清空整个防火墙或恢复出厂设置。
如何安全地升级或卸载 HomeProxy？
只在同一固件版本的软件源内升级，先执行 opkg update，升级后核对已安装版本。软件包把 /etc/config/homeproxy、证书、规则集以及直连和代理列表标记为配置文件，按设计会在升级后保留；但仍应保留自己的备份。［2］［6］
卸载时，先停止并禁用服务，完成上面的恢复检查，再移除应用。opkg remove --autoremove luci-app-homeproxy 会一并移除仅作为其依赖安装的软件包；确认前请查看它列出的清单，因为 sing-box 可能还被其他组件使用。［6］ 试用期间泄露过的节点凭证应当吊销，而不只是删除本地副本。
总结
- 项目没有打标签的发行版，请固定固件、LuCI 软件包和 sing-box 的版本。
- 从固件官方软件源安装，遇到依赖冲突就停下。
- 用 Global 模式只代理列表中的一台客户端，并清楚 DNS 改动会影响路由器的所有客户端。
- 分别验证出口、DNS、IPv6 和管理访问，再证明停止服务能恢复直连。
常见问题
HomeProxy 和 sing-box 是同一个东西吗？
不是。HomeProxy 是 LuCI 应用，负责写入 sing-box 配置、路由规则和 dnsmasq 设置；sing-box 则是另一个独立的代理程序，真正承载流量。
原版 OpenWrt 能安装 HomeProxy 吗？
项目不提供打标签的发行包，原版 OpenWrt 的软件源里也没有它。本文覆盖的是 ImmortalWrt 24.10.6，它的官方 LuCI 软件源提供了这个软件包。
为什么没加入列表的客户端 DNS 也变了？
在 Global 等模式下，HomeProxy 会把 dnsmasq 指向本机 sing-box 的 DNS 端口。所有向路由器查询 DNS 的设备都会经过这条路径，即使它们的流量并没有走代理。
应该先用哪种路由模式？
先用 Global 配合 Proxy listed only，一台客户端只有一个清晰的预期。等首次测试和回滚都成功后，再考虑换成其他模式。
需要使用 Tun 模式吗？
首次测试不需要。默认的 Redirect TCP + TProxy UDP 模式不依赖额外模块，而且只有安装 ip-full 和 kmod-tun 之后才会出现 Tun 选项。
服务启动不了该怎么办？
先确认 Main node 没有设为 Disable，再查看 /var/run/homeproxy/homeproxy.log。sing-box 配置检查失败会中止启动，并把原因记录在这个日志里。
卸载应用会自动恢复原来的网络吗？
真正清除规则和 dnsmasq 改动的是停止服务这一步。请先停止服务，确认路由器上没有 HomeProxy 规则，再测试客户端，最后才移除软件包。
免责声明: 本文仅供一般信息参考，不构成法律、技术或其他专业建议。我们不保证内容的准确性、完整性或时效性。请只在你拥有或获授权使用的网络、路由器和代理节点上操作。
来源:
- ImmortalWrt — HomeProxy repository (commit 98a6ad9) — https://github.com/immortalwrt/homeproxy/tree/98a6ad9e71484528008ff435694fd107591f3a1d
- HomeProxy — package definition (Makefile) — https://github.com/immortalwrt/homeproxy/blob/98a6ad9e71484528008ff435694fd107591f3a1d/Makefile
- ImmortalWrt — 24.10.6 LuCI feed (aarch64_cortex-a53) — https://downloads.immortalwrt.org/releases/24.10.6/packages/aarch64_cortex-a53/luci/
- ImmortalWrt — 24.10.6 packages feed (aarch64_cortex-a53) — https://downloads.immortalwrt.org/releases/24.10.6/packages/aarch64_cortex-a53/packages/
- HomeProxy — service init script — https://github.com/immortalwrt/homeproxy/blob/98a6ad9e71484528008ff435694fd107591f3a1d/root/etc/init.d/homeproxy
- OpenWrt — opkg package manager — https://openwrt.org/docs/guide-user/additional-software/opkg
- HomeProxy — node settings view — https://github.com/immortalwrt/homeproxy/blob/98a6ad9e71484528008ff435694fd107591f3a1d/htdocs/luci-static/resources/view/homeproxy/node.js
- sing-box — Configuration — https://sing-box.sagernet.org/configuration/
- HomeProxy — client settings view — https://github.com/immortalwrt/homeproxy/blob/98a6ad9e71484528008ff435694fd107591f3a1d/htdocs/luci-static/resources/view/homeproxy/client.js
Sources checked 2026 年 10 月 14 日。
延伸阅读:
