最新 OpenWrt Passwall/Passwall2 安装教程

在 OpenWrt 系统中，Passwall 与 Passwall2 是备受推崇的网络代理工具，能助力软路由实现高效稳定的魔法上网。本文将基于官方最新资源，为你详细拆解完整安装流程，若遇到 Passwall 损坏或无法使用的情况，也可选择 OpenClash 等同类工具作为替代。

更新一键安装代码：在本文页末↓↓↓

一、核心准备与前置说明

1. 官方资源地址

Passwall GitHub 仓库：https://github.com/Openwrt-Passwall/openwrt-passwall
Passwall2 最新发布页：https://github.com/Openwrt-Passwall/openwrt-passwall2/releases
官方安装教程参考：https://github.com/moetayuko/openwrt-passwall-build
增加X86架构run格式安装包；下载地址：https://github.com/AUK9527/Are-u-ok/tree/main/x86

2. 工具与环境要求

已刷入 OpenWrt 系统的软路由
登录工具：软路由自带终端（如有），或 MobaXterm、WindTerm 等远程连接工具
网络环境：确保软路由能正常访问互联网

3. 特别注意

Passwall 25.3.9 及以上版本适配 Sing-box 1.12.0 + 时，需依赖 Geoview 生成规则集（Sing-box 1.12.0 已移除 Geo 功能），未安装 Geoview 将无法使用 Sing-box 分流功能，安装流程会自动处理相关依赖，无需额外操作。

二、详细安装步骤

第一步：登录软路由后台终端

若软路由配备实体终端，可直接本地登录；
无实体终端时，打开 MobaXterm 或 WindTerm，输入软路由的 IP 地址、用户名和密码，建立 SSH 连接后进入终端界面。

第二步：添加 opkg 密钥（验证软件完整性）

在终端中依次执行以下命令，下载并添加官方密钥：

wget -O passwall.pub https://master.dl.sourceforge.net/project/openwrt-passwall-build/passwall.pub
opkg-key add passwall.pub

该步骤用于验证后续安装包的安全性，避免恶意软件植入。

第三步：添加 opkg 软件源（二选一即可）

软件源用于获取 Passwall 相关安装包，根据软路由系统版本选择对应命令：

选项 1：稳定版源（推荐正式版 OpenWrt 系统）

read release arch << EOF
$(. /etc/openwrt_release ; echo ${DISTRIB_RELEASE%.*} $DISTRIB_ARCH)
EOF
for feed in passwall_luci passwall_packages passwall2; do
  echo "src/gz $feed https://master.dl.sourceforge.net/project/openwrt-passwall-build/releases/packages-$release/$arch/$feed" >> /etc/opkg/customfeeds.conf
done

选项 2：快照版源（适用于 OpenWrt 快照版系统）

read arch << EOF
$(. /etc/openwrt_release ; echo $DISTRIB_ARCH)
EOF
for feed in passwall_luci passwall_packages passwall2; do
  echo "src/gz $feed https://master.dl.sourceforge.net/project/openwrt-passwall-build/snapshots/packages/$arch/$feed" >> /etc/opkg/customfeeds.conf
done

第四步：安装 Passwall（核心组件）

添加源后，执行以下命令更新软件列表并安装 Passwall：

opkg update
opkg install luci-app-passwall

opkg update 用于同步最新软件包信息，确保安装的是当前最新版本。

第五步：安装 Passwall2（可选，增强版功能）

若需要使用 Passwall2 的进阶功能，继续执行：

opkg update
opkg install luci-app-passwall2

Passwall2 兼容更多代理协议（如 Hysteria、TUIC 等），且优化了分流逻辑，推荐追求高性能的用户安装。

第六步：安装中文语言包（解决英文界面问题）

若安装后界面为英文，执行以下命令安装中文包：

# Passwall 中文包
opkg install luci-i18n-passwall-zh-cn
# Passwall2 中文包
opkg install luci-i18n-passwall2-zh-cn

安装完成后，刷新软路由管理界面即可切换为中文。

第七步：故障排除与重启（可选）

若 Passwall 版本过旧、功能异常或安装后无法正常显示，可重启软路由；
若无需重启整机，也可执行以下命令重启 Web 服务：

/etc/init.d/uhttpd restart

三、替代方案说明

若 Passwall 安装失败、持续报错或无法满足需求，可选择 OpenClash 等同类代理工具，核心安装逻辑类似：

添加对应工具的 opkg 源或下载离线安装包；
执行安装命令并配置中文包；
按照工具官方文档完成代理节点设置，即可实现魔法上网。

四、注意事项

本教程仅适用于合法的网络访问需求，请勿用于违反国家法律法规的行为；
确保软路由的 OpenWrt 系统版本与软件源匹配，否则可能导致安装失败；
若遇到 "网页解析失败" 等下载问题，检查网络连接或更换时间段重试，必要时手动访问 GitHub 仓库下载离线安装包（ipk 格式），通过opkg install 本地包路径命令安装。
如若侵权请联系博主删除

PassWall与PassWall2一键安装命令;请使用SSH工具或者路由终端安装 2026-03-29

一键安装/更新passwall：【点击进入】

cat >/usr/bin/passwall-update.sh <<'EOF'
#!/bin/sh
set -e

KEY_URL="https://master.dl.sourceforge.net/project/openwrt-passwall-build/passwall.pub"
GH_API="https://api.github.com/repos/Openwrt-Passwall/openwrt-passwall/releases/latest"
LOCKDIR="/tmp/passwall-update.lock"

if ! mkdir "$LOCKDIR" 2>/dev/null; then
  echo "==> Another update task is already running"
  exit 1
fi
trap 'rmdir "$LOCKDIR"' EXIT INT TERM

# 读取系统信息
. /etc/openwrt_release
ARCH="$DISTRIB_ARCH"
REL_RAW="$DISTRIB_RELEASE"

# 判断 release / snapshot 源
case "$REL_RAW" in
  *SNAPSHOT*)
    FEED_BASE="https://master.dl.sourceforge.net/project/openwrt-passwall-build/snapshots/packages/$ARCH"
    ;;
  *)
    RELEASE="${REL_RAW%.*}"
    FEED_BASE="https://master.dl.sourceforge.net/project/openwrt-passwall-build/releases/packages-$RELEASE/$ARCH"
    ;;
esac

echo "==> System release: $REL_RAW"
echo "==> Arch: $ARCH"
echo "==> Feed base: $FEED_BASE"

# GitHub 最新版本（仅显示参考）
GH_LATEST="$(wget -qO- "$GH_API" 2>/dev/null | sed -n 's/.*"tag_name":[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)"
[ -n "$GH_LATEST" ] && echo "==> GitHub latest release: $GH_LATEST"

# 确保文件存在
touch /etc/opkg/customfeeds.conf

# 清理旧的 passwall 源，避免重复追加
sed -i '\|openwrt-passwall-build|d' /etc/opkg/customfeeds.conf
sed -i '/^src\/gz passwall_luci /d' /etc/opkg/customfeeds.conf
sed -i '/^src\/gz passwall_packages /d' /etc/opkg/customfeeds.conf
sed -i '/^src\/gz passwall2 /d' /etc/opkg/customfeeds.conf

# 导入 key
cd /tmp
rm -f passwall.pub
wget -qO passwall.pub "$KEY_URL"
opkg-key add /tmp/passwall.pub >/dev/null 2>&1 || true

# 重写软件源
for feed in passwall_luci passwall_packages passwall2; do
  echo "src/gz $feed $FEED_BASE/$feed" >> /etc/opkg/customfeeds.conf
done

echo "==> Refresh package index"
opkg update

OLD_VER="$(opkg status luci-app-passwall 2>/dev/null | sed -n 's/^Version: //p')"
echo "==> Current installed version: ${OLD_VER:-not installed}"

echo "==> Install / upgrade PassWall"
opkg install luci-app-passwall luci-i18n-passwall-zh-cn

NEW_VER="$(opkg status luci-app-passwall 2>/dev/null | sed -n 's/^Version: //p')"
echo "==> Installed version after update: ${NEW_VER:-unknown}"

if [ -n "$NEW_VER" ] && [ "$OLD_VER" != "$NEW_VER" ]; then
  echo "==> Version changed, restarting related services"
  /etc/init.d/firewall restart >/dev/null 2>&1 || true
  /etc/init.d/passwall restart >/dev/null 2>&1 || true
  /etc/init.d/uhttpd restart >/dev/null 2>&1 || true
else
  echo "==> No version change, skip service restart"
fi

echo "==> Done"
EOF

chmod +x /usr/bin/passwall-update.sh
/usr/bin/passwall-update.sh

一键安装/更新PassWall2：【点击进入】

cat >/usr/bin/passwall2-update.sh <<'EOF'
#!/bin/sh
set -e

KEY_URL="https://master.dl.sourceforge.net/project/openwrt-passwall-build/passwall.pub"
GH_API="https://api.github.com/repos/Openwrt-Passwall/openwrt-passwall2/releases/latest"
LOCKDIR="/tmp/passwall2-update.lock"

if ! mkdir "$LOCKDIR" 2>/dev/null; then
  echo "==> Another update task is already running"
  exit 1
fi
trap 'rmdir "$LOCKDIR"' EXIT INT TERM

# 读取系统信息
. /etc/openwrt_release
ARCH="$DISTRIB_ARCH"
REL_RAW="$DISTRIB_RELEASE"

# 判断 release / snapshot 源
case "$REL_RAW" in
  *SNAPSHOT*)
    FEED_BASE="https://master.dl.sourceforge.net/project/openwrt-passwall-build/snapshots/packages/$ARCH"
    ;;
  *)
    RELEASE="${REL_RAW%.*}"
    FEED_BASE="https://master.dl.sourceforge.net/project/openwrt-passwall-build/releases/packages-$RELEASE/$ARCH"
    ;;
esac

echo "==> System release: $REL_RAW"
echo "==> Arch: $ARCH"
echo "==> Feed base: $FEED_BASE"

# GitHub 最新版本（仅显示参考）
GH_LATEST="$(wget -qO- "$GH_API" 2>/dev/null | sed -n 's/.*"tag_name":[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)"
[ -n "$GH_LATEST" ] && echo "==> GitHub latest PassWall2 release: $GH_LATEST"

# 确保 customfeeds.conf 存在
touch /etc/opkg/customfeeds.conf

# 清理旧的 passwall 源，避免重复追加
sed -i '\|openwrt-passwall-build|d' /etc/opkg/customfeeds.conf
sed -i '/^src\/gz passwall_luci /d' /etc/opkg/customfeeds.conf
sed -i '/^src\/gz passwall_packages /d' /etc/opkg/customfeeds.conf
sed -i '/^src\/gz passwall2 /d' /etc/opkg/customfeeds.conf

# 导入 key
cd /tmp
rm -f passwall.pub
wget -qO passwall.pub "$KEY_URL"
opkg-key add /tmp/passwall.pub >/dev/null 2>&1 || true

# 重写软件源
for feed in passwall_luci passwall_packages passwall2; do
  echo "src/gz $feed $FEED_BASE/$feed" >> /etc/opkg/customfeeds.conf
done

echo "==> Refresh package index"
opkg update

OLD_VER="$(opkg status luci-app-passwall2 2>/dev/null | sed -n 's/^Version: //p')"
echo "==> Current installed version: ${OLD_VER:-not installed}"

echo "==> Install / upgrade PassWall2"
opkg install luci-app-passwall2 luci-i18n-passwall2-zh-cn

NEW_VER="$(opkg status luci-app-passwall2 2>/dev/null | sed -n 's/^Version: //p')"
echo "==> Installed version after update: ${NEW_VER:-unknown}"

if [ -n "$NEW_VER" ] && [ "$OLD_VER" != "$NEW_VER" ]; then
  echo "==> Version changed, restarting related services"
  /etc/init.d/firewall restart >/dev/null 2>&1 || true
  /etc/init.d/passwall2 restart >/dev/null 2>&1 || true
  /etc/init.d/uhttpd restart >/dev/null 2>&1 || true
else
  echo "==> No version change, skip service restart"
fi

echo "==> Done"
EOF

chmod +x /usr/bin/passwall2-update.sh
/usr/bin/passwall2-update.sh