PassWall2 OpenWrt 安装与基础配置指南
简答：PassWall2 OpenWrt 安装前先确认固件版本、CPU 架构和包管理器：OpenWrt 24.10 及更早通常使用 opkg，25.12 及更新版本使用 apk。再从官方 Releases 选择对应 IPK 或 APK，安装依赖、重启 LuCI，最后导入已有节点或订阅并检查日志；排查完成后应能看到 PassWall2 菜单并确认核心正常运行。
定义：PassWall2 是运行在 OpenWrt 路由器上的 LuCI 图形管理应用，本身不是节点或代理服务，必须配合可用的节点、订阅和对应代理核心使用。
先看这张表：你的 OpenWrt 应该安装哪一种包
PassWall2 的安装包不是通用文件。先在路由器 SSH 终端执行检查命令，再决定下载 .ipk 还是 .apk。OpenWrt 官方文档说明，25.12 及更新版本使用 apk，24.10 及更早版本使用 opkg；PassWall2 项目也要求按路由器的包管理器选择安装格式。
| 检查项目 | 执行方式 | 如何判断 |
|---|---|---|
| OpenWrt 版本 | cat /etc/openwrt_release | 重点查看 DISTRIB_RELEASE 与 DISTRIB_ARCH |
| 包管理器 | opkg --version 或 apk --version | 能正常返回版本的命令就是当前使用的包管理器 |
| CPU 架构 | ubus call system board | 记录 board_name、target 和 architecture，下载时不要凭路由器型号猜架构 |
| 可用空间 | df -h | 确认 overlay 和临时目录仍有足够空间，避免安装到一半失败 |
| 网络与时间 | ping -c 3 github.com、date | 下载前确认路由器能联网，系统时间明显错误时先校正时间 |
截至 2026-10-26，PassWall2 官方 Releases 页面显示的最新发布版本为 26.10.20-1，发布于 2026 年 10 月 20 日。版本会继续变化，下载前应重新打开官方 Releases 列表核对版本和文件名。
从官方 Releases 选择 PassWall2 安装包
- 打开PassWall2 官方 Releases 页面，进入需要安装的版本，展开 Assets。
- 使用 opkg 的固件选择带
_all.ipk结尾的主程序包，例如luci-app-passwall2_版本号_all.ipk。 - 使用 apk 的固件选择对应的
.apk主程序包，例如luci-app-passwall2-版本号-r1.apk。 - 需要中文界面时，再选择同一版本的
luci-i18n-passwall2-zh-cn语言包。语言包不是主程序，不能替代主程序安装。 - 如果页面提供 SHA-256 值，下载后应在电脑上核对文件摘要。Linux 或 macOS 可执行
sha256sum 文件名；Windows PowerShell 中执行Get-FileHash .\文件名 -Algorithm SHA256。
官方项目 README 将 PassWall2 定义为 OpenWrt 的 LuCI 应用，并明确区分 IPK 与 APK 安装方式；主程序、语言包和代理核心是不同组件，不能把“看到 LuCI 菜单”误认为所有核心已经安装。
opkg 路线：OpenWrt 24.10 及更早版本
以下命令在路由器 SSH 终端执行。先把从 Releases 下载的 IPK 文件上传到路由器的临时目录，例如 /tmp。也可以使用 LuCI 的软件包上传入口，但手动上传时要确认文件没有被浏览器重命名。
- 进入文件目录并确认文件名：
cd /tmp && ls -l luci-app-passwall2*.ipk。 - 先更新系统软件列表：
opkg update。 - 安装主程序和中文语言包：
opkg install ./luci-app-passwall2_版本号_all.ipk ./luci-i18n-passwall2-zh-cn_版本号_all.ipk。文件名要替换成实际下载名称。 - 若提示缺少
xray-core、sing-box、dnsmasq-full或防火墙模块，不要随意下载其他固件的同名包。先检查 OpenWrt 版本、架构和 PassWall2 软件源是否匹配，再根据错误信息补依赖。 - 安装完成后重启 LuCI 后端：
/etc/init.d/rpcd restart。退出浏览器后重新登录 LuCI，通常在“服务”菜单中查找 PassWall2。
官方 README 提到，IPK 安装遇到依赖缺失时需要配置 PassWall 软件源；如果主程序能安装但核心无法启动，问题通常不在 LuCI 菜单本身，而在核心包、架构或运行时依赖。
apk 路线：OpenWrt 25.12 及更新版本
OpenWrt 官方文档说明，25.12 已从 opkg 转向 apk。先确认你的固件确实能执行 apk，不要因为文件扩展名相似就把 APK 包安装到旧版 opkg 固件上。
- 将 APK 文件上传到路由器，例如保存到
/tmp，然后执行cd /tmp && ls -l luci-app-passwall2*.apk。 - 优先使用已经配置并带签名的软件源安装。先执行
apk update，再执行apk add luci-app-passwall2；如果软件源中没有该包，再回到官方 Releases 选择本地 APK。 - 安装本地 APK 时，官方 PassWall2 README 给出的方式是
apk add --allow-untrusted ./luci-app-passwall2-版本号-r1.apk。这个参数会绕过本地包的签名验证，只适合你已从官方发布页下载并核对文件摘要的情况。 - 安装中文语言包时，使用同一版本的
luci-i18n-passwall2-zh-cn-版本号.apk，不要混用不同版本。 - 安装完成后执行
/etc/init.d/rpcd restart，重新登录 LuCI，在“服务”中检查 PassWall2。
OpenWrt 官方 apk 文档明确说明，--allow-untrusted 用于安装自行构建或来自外部软件源的包，但会降低签名校验保护。因此，能使用可信软件源时优先使用软件源；必须本地安装时，至少核对来源、版本和 SHA-256。
依赖怎么判断：不要一次性盲装所有核心
PassWall2 只是管理界面，实际转发还需要代理核心和系统组件。不同协议、固件版本与防火墙版本所需依赖可能不同，建议按照“先基础组件、再核心、最后配置”的顺序安装。
| 组件 | 作用 | 排查重点 |
|---|---|---|
dnsmasq-full | 提供更完整的 DNS 能力，部分透明代理和分流配置会依赖它 | 安装前确认系统如何替换原有 dnsmasq，避免重复服务抢占 DNS 端口 |
kmod-nft-tproxy | 为较新的 fw4/nftables 路线提供透明代理相关内核模块 | 必须与当前 OpenWrt 内核版本匹配，不能跨固件版本硬装 |
kmod-nft-socket | 配合 nftables socket 匹配等透明代理场景 | 安装失败时先检查固件版本与内核版本，而不是只看包名 |
xray-core、sing-box | 实际处理对应协议和节点连接 | 核心未安装、路径错误或配置不兼容都会导致“菜单存在但无法启动” |
| 地理数据与测速组件 | 用于分流、域名分类或节点测试 | 属于按功能选择的组件，不需要为了显示菜单全部安装 |
PassWall2 官方发布页会列出随版本发布的核心组件版本。例如 26.10.20-1 页面列出了 sing-box、xray-core、geoview 等包的版本，但这些版本会随 Release 变化，本文不把它们写死为长期安装命令。
安装后第一次配置：导入订阅或单个节点
- 在浏览器打开路由器 LuCI 地址，登录后进入“服务”→“PassWall2”。如果没有菜单，先执行
/etc/init.d/rpcd restart，然后强制刷新页面。 - 进入节点或节点列表相关页面，选择添加节点、导入配置或订阅管理入口。不同版本的菜单文字可能变化，但应先完成节点数据导入，再选择代理核心。
- 使用订阅链接时，只填写你已确认来源可信的订阅地址；不要把含有 token 的完整链接粘贴到公开日志、工单或截图中。
- 选择与节点协议匹配的核心，例如节点需要 Xray 或 sing-box 时，先确认对应核心已经安装并能被 PassWall2 找到。
- 保存后运行节点测试。测试失败时先分别检查域名解析、TCP 连接、TLS/SNI 和核心日志，不要直接修改多个选项。
- 在主开关或运行设置中启用后，使用一台局域网设备访问普通网站和需要代理的目标进行对照测试。若只有部分域名异常，优先检查 DNS 与分流规则；若所有流量都异常，先停用透明代理并回到单节点测试。
PassWall2 本身不提供节点、订阅或线路。本文只说明客户端侧的安装与配置方法，订阅内容、节点可用性和服务状态需要由其提供方或用户自行核验。
常见安装失败：按现象定位，不要反复重装
| 现象 | 优先检查 | 处理顺序 |
|---|---|---|
| 提示架构不匹配 | ubus call system board 与下载包所属架构 | 删除错误包，重新从 Releases 选择匹配架构和固件版本的文件 |
| 依赖无法满足 | 软件源、OpenWrt 版本、内核版本和磁盘空间 | 先执行 opkg update 或 apk update，再根据完整报错处理，不要混用其他版本包 |
| 安装成功但 LuCI 没菜单 | rpcd、浏览器缓存和安装包名称 | 执行 /etc/init.d/rpcd restart，退出登录后重新打开 LuCI |
| 菜单有但核心启动失败 | 核心是否安装、路径是否正确、配置格式是否匹配 | 在 PassWall2 日志页面查看启动日志；SSH 中可用 logread | grep -i passwall 辅助筛选 |
| 启用后设备无法上网 | DNS 端口冲突、透明代理模块和分流配置 | 先关闭 PassWall2 恢复直连，再逐项检查 DNS、核心和规则 |
日志优先从 LuCI 的 PassWall2 日志页面查看；若页面打不开或信息不足，再通过 SSH 执行 logread。排障时不要输出包含订阅 token、Cookie 或完整认证链接的日志内容。
最后核对：2026-10-26 安装前自查清单
- 已确认 OpenWrt 版本和 CPU 架构。
- 已确认使用 opkg 还是 apk，没有混装 IPK 与 APK。
- 已从官方 Releases选择对应版本，并核对文件名与摘要。
- 已准备足够的可用空间，并确认路由器能正常联网。
- 已根据实际功能安装 dnsmasq-full、防火墙模块和代理核心，没有盲目安装全部组件。
- 已重启 rpcd，并在 LuCI 的“服务”菜单看到 PassWall2。
- 已先测试单个节点，再启用分流或透明代理。
如果你的目标只是让 OpenWrt 路由器运行 PassWall2，最稳妥的路径是：先识别包管理器，再从官方发布页下载匹配文件，优先使用签名软件源，安装后查看日志，最后才配置订阅和分流。
参考资料
本文依据以下公开资料整理：PassWall2 官方项目说明、PassWall2 官方 Releases、OpenWrt 官方软件包管理文档以及OpenWrt 官方 apk 文档。本站是第三方使用指南，不是 PassWall2 或 OpenWrt 官方站点。
常见问题
PassWall2 OpenWrt 应该下载 IPK 还是 APK？
先执行 opkg --version 和 apk --version。OpenWrt 24.10 及更早版本通常使用 opkg，对应 IPK；OpenWrt 25.12 及更新版本使用 apk，对应 APK。最终以路由器实际可用的包管理器和官方发布页文件为准。
PassWall2 安装后 LuCI 里没有菜单怎么办？
先确认主程序确实安装成功，再通过 SSH 执行 /etc/init.d/rpcd restart，退出 LuCI 后重新登录并清理浏览器缓存。如果仍没有菜单，检查安装包架构、OpenWrt 版本和系统日志。
安装 PassWall2 后还需要安装 Xray 或 sing-box 吗？
如果要实际处理节点连接，通常还需要与节点协议匹配的代理核心。PassWall2 主要是 LuCI 管理界面，不等于代理核心，也不提供节点或订阅。请根据配置页面提示和官方发布包选择所需核心。
apk 安装时为什么要使用 --allow-untrusted？
本地 APK 不一定来自已配置的签名软件源，因此官方 README 提供了该参数作为本地安装方式。但它会绕过签名验证，使用前应确认下载地址来自官方发布页，并核对 SHA-256；能使用可信软件源时优先使用软件源。
PassWall2 启用后局域网设备无法上网，先查哪里？
先关闭 PassWall2 恢复直连，再按 DNS 端口冲突、dnsmasq-full、透明代理内核模块、代理核心日志和分流规则的顺序检查。不要同时修改 DNS、核心和规则，否则难以判断具体故障点。
相关阅读
参考资料
- PassWall2 官方项目说明
- PassWall2 官方 Releases 发布列表
- OpenWrt 官方软件包管理文档（openwrt.org）
- OpenWrt 官方 apk 软件包文档（openwrt.org）