# 如何在 OpenWrt 上安装 VilaNet？

安装与路由器匹配的两个软件包，然后在 LuCI 中打开 **网络 > VilaNet**，登录并连接。请先备份路由器，并在下载任何文件前确认其软件包管理器和 CPU 架构。

> **需要完整图文参考？** 请打开[内容更丰富的 VilaNet OpenWrt 指南](https://openwrt.vilavpn.com/)，查看不同软件包的安装步骤、架构选择、截图和高级故障排除。本页继续作为多语言安全入门指南。

{% hint style="warning" %}
更改路由器可能会中断网络中所有设备的连接。开始前，请保留路由器配置副本，并确保可以通过本地网络访问 LuCI 或 SSH。
{% endhint %}

## 所需条件

- 受支持的 OpenWrt 或 iStoreOS 路由器
- 使用 `opkg` 的 OpenWrt 24.x，或使用 `apk` 的 OpenWrt 25.x
- 已设置路由器 root 密码
- LuCI 和 SSH 管理员访问权限
- 有效的 VilaVPN 账户
- 当前的 [VilaNet OpenWrt 版本](https://github.com/vilavpn/vilanet-openwrt/releases/tag/v1.0.33)

本指南目前验证过的公开版本是 **v1.0.33**。

## 备份路由器

在 LuCI 中打开 **系统 > 备份/升级**，然后创建配置备份。将压缩包存放在路由器以外的位置。

还请记录：

- 路由器型号
- OpenWrt 版本
- CPU 架构
- 路由器使用 `opkg` 还是 `apk`

在 SSH 会话中，以下命令会显示相关详细信息：

```sh
cat /etc/openwrt_release
command -v opkg || command -v apk
opkg print-architecture 2>/dev/null || apk --print-arch
```

`opkg print-architecture` 可能返回多行。请使用优先级数字最高的具体架构；核心软件包应忽略 `all` 和 `noarch`。例如，当 `aarch64_cortex-a53` 的优先级更高时，应选择它而不是 `all`。

## 选择安装方式

| 路由器 | 文件 | 安装方式 |
|---|---|---|
| iStoreOS | `vilanet-istore-install_1.0.33.run` | **iStore > 手动安装** |
| OpenWrt 24.x | `vilanet-core_1.0.33_<arch>.ipk` 和 `luci-app-vilanet_1.0.33_all.ipk` | `opkg install` |
| OpenWrt 25.x | `vilanet-core_1.0.33_<arch>.apk` 和 `luci-app-vilanet_1.0.33_noarch.apk` | `apk add` |

将 `<arch>` 替换为路由器报告的架构。不要只根据路由器的营销名称来猜测。

## 验证 OpenWrt 25 下载文件

OpenWrt 25 软件包使用 `--allow-untrusted` 安装，因为它们是本地发布文件，而不是来自路由器所配置的软件源。将文件复制到路由器或安装之前，**务必**验证其 SHA-256 值。

| 文件 | v1.0.33 的预期 SHA-256 |
|---|---|
| `vilanet-core_1.0.33_aarch64_cortex-a53.apk` | `b66dba97bc2c8d3c18eca3556e087651fc9d8ec6d84ebed2ac1d4ab65b03a982` |
| `vilanet-core_1.0.33_aarch64_generic.apk` | `5479c84c8b1373150dd4afd5a337e7e4cfbbcf7109b8c2861e40f979784677b8` |
| `vilanet-core_1.0.33_arm_arm926ej-s.apk` | `5c8c211f9aa9708bab10cdfc80d3171d6f6d6453d0f836927b199f938c5e4569` |
| `vilanet-core_1.0.33_arm_cortex-a7_neon-vfpv4.apk` | `de7425cc9c23cb5f981f78344b75822a11c7624a7033a044bf8eb701415a4d7e` |
| `vilanet-core_1.0.33_mipsel_24kc.apk` | `643ff91ca501ef7605146bf3c9e2490a5177ecfdfc5bc9613e48ac4a8b22867d` |
| `vilanet-core_1.0.33_x86_64.apk` | `f22fa045b777677a647da808110eb00af8ad661bafeb07b48aae13e7ff6187c4` |
| `luci-app-vilanet_1.0.33_noarch.apk` | `201782ccebba81d170ed7193ca75aee8e46fe9d542fa4992dc7222960dc04502` |

在 macOS 上运行 `shasum -a 256 <filename>`。在 Linux 或路由器上运行 `sha256sum <filename>`。如果任何一个值不同，请勿安装这些文件。

## 在 iStoreOS 上安装

1. 从当前版本下载 `vilanet-istore-install_1.0.33.run`。
2. 打开 iStoreOS Web 界面。
3. 前往 **iStore > 手动安装**。
4. 上传 `.run` 安装程序。
5. 离开页面前检查安装结果。
6. 打开 **网络 > VilaNet**。

## 在 OpenWrt 24.x 上安装

下载匹配的核心 IPK 和不依赖架构的 LuCI IPK。将它们复制到路由器：

```sh
scp -O vilanet-core_1.0.33_<arch>.ipk root@<router>:/tmp/
scp -O luci-app-vilanet_1.0.33_all.ipk root@<router>:/tmp/
```

通过 SSH 安装两个软件包：

```sh
opkg install /tmp/vilanet-core_1.0.33_<arch>.ipk \
  /tmp/luci-app-vilanet_1.0.33_all.ipk
/etc/init.d/vilanet enable
vilanet version
```

## 在 OpenWrt 25.x 上安装

下载匹配的核心 APK 和 noarch LuCI APK。将它们复制到路由器：

```sh
scp -O vilanet-core_1.0.33_<arch>.apk root@<router>:/tmp/
scp -O luci-app-vilanet_1.0.33_noarch.apk root@<router>:/tmp/
```

通过 SSH 安装两个软件包：

```sh
apk add --allow-untrusted --force-non-repository \
  /tmp/vilanet-core_1.0.33_<arch>.apk \
  /tmp/luci-app-vilanet_1.0.33_noarch.apk
/etc/init.d/vilanet enable
vilanet version
```

## 登录并连接

1. 安装后刷新 LuCI。
2. 打开 **网络 > VilaNet**。
3. 在**概览**中输入 VilaVPN 账户的电子邮件地址和密码。
4. 选择**登录**。
5. 打开**服务器节点**并选择一个位置，或者在有自动选项时保留**自动选择**。
6. 返回**概览**并选择**连接**。

![在真实 OpenWrt LuCI 界面中使用虚构示例地址的 VilaNet 登录表单](/assets/openwrt/openwrt-vilanet-login-en-24.10.2.png)

这张真实的 LuCI 截图使用保留的示例地址 `you@example.com`，密码字段为空。为了让登录控件在手机上清晰可读，宽幅路由器页面经过裁剪；没有重建任何界面元素。

实体路由器屏幕截图和局域网流量检查仍是发布证据门槛；仅显示“已连接”绝不能证明隧道可用。

## 确认工作正常

先检查路由器：

```sh
vilanet version
vilanet status --json
/etc/init.d/vilanet status
logread | grep vilanet
```

然后使用连接到路由器的设备：

1. 打开一个普通 HTTPS 网站。
2. 返回**网络 > VilaNet > 概览**。
3. 确认服务仍在运行，连接状态仍为**已连接**。

仅显示“已连接”还不够。路由器状态和局域网设备的流量都必须正常。

## 如果没有 VilaNet 菜单

1. 强制刷新 LuCI 页面。
2. 通过 SSH 运行 `/etc/init.d/rpcd restart`。
3. 重新打开 LuCI 并检查**网络 > VilaNet**。
4. 确认核心软件包和 LuCI 软件包都已安装。

## 如果 VilaNet 启动后又停止

重新安装前保留证据：

```sh
vilanet version
vilanet status --json
/etc/init.d/vilanet status
logread | grep vilanet
```

联系支持时，请提供路由器型号、OpenWrt 版本、软件包管理器和经过脱敏的输出。不要发送密码或原始订阅数据。

## 不受支持的旧安装程序

旧的 `vilanet-test-*.tar.gz` 手动复制方法已经停用。请使用官方版本中当前的 IPK、APK 或 iStoreOS 安装程序。

## 后续步骤

更改路由模式、升级软件包或移除 VilaNet 前，请阅读[恢复与回滚](/zh-cn/routers/recovery-and-rollback/)。