Raspberry Pi ImmortalWrt 快速安装指南
本文介绍 ImmortalWrt 的基本安装与配置流程，适合作为首次部署的入口。
验收结果：LuCI 可以访问；连接树莓派 Wi-Fi 的设备可以联网；已确认系统使用的包管理器；配置备份已保存到另一台设备。
| 预计时间 | 难度 | 适用设备 | 推荐网络模式 |
|---|---|---|---|
| 30–60 分钟 | 入门 | Raspberry Pi 4B / 400 / CM4 | 上级路由器接入 |
安装流程
安装分为六个阶段：
- 确认硬件和网络角色
- 下载并烧录正确的固件
- 完成首次登录和安全设置
- 让基础网络先通过验证
- 再安装 OpenClash 和导入规则
- 最后创建备份
网络、DNS 和 OpenClash 配置应分阶段修改。每完成一个阶段均应先验证结果；出现故障时，优先检查最近的改动。
准备清单
开始前准备：
- Raspberry Pi 4B、400 或 CM4
- 8 GB 或更大的可靠 SD 卡；读卡器
- 稳定的 5V 电源
- 一台电脑
- 一根网线
- 一个现有路由器；首次安装建议使用上级路由器接入方案
- 如果要让树莓派直接拨号：运营商提供的 PPPoE 账号和密码
会覆盖数据：向 SD 卡写入新镜像会覆盖卡上的原有分区。先确认目标磁盘，再点击写入。
选择网络角色
根据实际网络环境选择对应方案：
| 网络环境 | 配置方案 | 注意事项 |
|---|---|---|
| 已有路由器负责拨号，树莓派只提供 Wi-Fi 和代理 | 上级路由器 LAN 接入 | 无需填写 PPPoE 账号 |
| 光猫桥接，树莓派负责直接拨号 | PPPoE 拨号 | 不使用上级 LAN 方案中的网关设置 |
| 有线设备也需要接入树莓派 LAN | 增加 USB 网卡或使用支持 VLAN 的交换机 | 一个物理接口不应同时配置为 LAN 和 WAN |
本教程默认走第一条：上级路由器继续负责互联网接入，树莓派的以太网口作为 WAN，无线作为 LAN。
下载固件
- 打开 ImmortalWrt Firmware Selector。
- 搜索与你设备对应的 Raspberry Pi 型号。
- 确认目标平台为
bcm27xx / bcm2711，架构通常为aarch64_cortex-a72。 - 第一次安装下载磁盘镜像，常见扩展名是
.img.gz。
EXT4 与 SQUASHFS
| 类型 | 特点 | 适合谁 |
|---|---|---|
| SQUASHFS | 只读系统层加可写 overlay，支持恢复出厂，系统结构更接近常见 OpenWrt 路由器 | 第一次安装、希望出错后容易恢复的人 |
| EXT4 | 根文件系统直接可写，后续从电脑扩展分区更直观，但没有 SQUASHFS 的只读系统层 | 清楚自己为什么需要 EXT4 的人 |
将新的 .img 写入 SD 卡时，两种文件系统都会覆盖目标介质。配置能否保留通常取决于 sysupgrade 选项和备份流程，不能仅根据 EXT4 或 SQUASHFS 判断。
首次部署建议选择 SQUASHFS。需要扩容时可查阅存储扩容指南。
烧录并首次启动
推荐用 balenaEtcher 直接写入 .img.gz：
- 选择下载的镜像。
- 选择 SD 卡。再次核对容量，避免选到电脑硬盘。
- 点击写入并等待校验完成。
- Windows 提示需要格式化磁盘时选择取消。Windows 默认不识别 Linux 分区，此提示不代表烧录失败。
- 将 SD 卡插入树莓派，连接网线和电源，等待 2–5 分钟。
需要 Windows、macOS 的逐步说明时，打开固件烧录手册。
完成首次登录
优先用网线把电脑与树莓派直接连接，或者连接固件提供的默认无线网络。不同镜像的无线默认状态可能不同，因此有线更容易排查。
- 浏览器打开
http://192.168.1.1。 - 使用
root登录；密码以镜像说明为准，部分镜像首次为空。 - 立即进入
系统 -> 管理权设置强密码。 - 进入
系统 -> 系统，确认时区和时间正确。
如果 192.168.1.1 与家中现有路由器地址冲突，先保持电脑与上级路由器断开，只连接树莓派完成管理地址调整。
首次登录验收
- LuCI 页面能稳定打开
- 修改密码后可以重新登录
- 刷新页面不会跳到另一台路由器的后台
以上三项全部通过后再安装插件。
配置基础网络
按照前面选择的角色进入对应文档：
- 默认路线：上级路由器 LAN 接入
- 拨号路线：PPPoE 拨号
配置后先做四项验证：
# 1. 查看接口地址
ip addr show
# 2. 应该能看到默认路由
ip route show
# 3. 验证纯 IP 连通性
ping -c 3 1.1.1.1
# 4. 验证 DNS
nslookup openwrt.org
再让手机连接树莓派 Wi-Fi，依次检查：
- 手机获得了树莓派 LAN 网段的地址
- 可以打开 LuCI 管理地址
- 可以打开普通网站
路由器本机可以联网但客户端无法联网时，检查 DHCP、
lan -> wan转发和 WAN 防火墙区域。IP 连通但域名无法解析时，检查 DNS 配置。
确认系统版本和包管理器
OpenWrt 25.12 起使用 apk；24.10 及更早版本使用 opkg。先检查，再复制命令：
. /etc/openwrt_release
echo "$DISTRIB_RELEASE"
# 也可以直接确认命令是否存在
command -v apk || command -v opkg
对应关系：
# OpenWrt 25.12 及更新版本
apk update
apk add <package-name>
# OpenWrt 24.10 及更早版本
opkg update
opkg install <package-name>
apk 系统不能使用 opkg update。也不建议通过 apk upgrade 或 opkg upgrade 批量升级全部系统包；完整系统升级应使用与设备匹配的固件，并提前备份。
官方参考：OpenWrt 软件包管理。
配置 OpenClash
基础网络通过验证后，继续阅读 OpenClash 配置手册。
主流程只有四步：
- 按系统版本安装 OpenClash
- 从仓库选择 YAML 模板
- 把
这里填写你的订阅链接替换成自己的订阅地址 - 导入、启用并验证规则
推荐从 config_linkedin_auto.yaml 开始。多机场用户使用 config_multi-airport_linkedin.yaml；只有 GitHub SSH 22 端口确实被阻断时，才使用带 ssh22_redir 的版本。
OpenClash 验收
- OpenClash 状态显示正在运行
- 国内网站可以打开
- 需要代理的网站可以打开
- 关闭 OpenClash 后，基础网络仍然正常
关闭 OpenClash 后再次验证网络，可以区分基础网络故障与代理配置故障。
创建第一份备份
进入 系统 -> 备份与升级：
- 点击生成备份。
- 下载
.tar.gz文件到电脑。 - 确认文件不是空文件，并用日期命名，例如
raspi-router-2026-08-10.tar.gz。 - 记录当前固件版本和已安装的重要插件。
完整恢复流程见备份与恢复。
故障排查
| 现象 | 检查项目 | 暂不调整 |
|---|---|---|
打不开 192.168.1.1 | 电脑地址、网线、地址冲突 | OpenClash |
路由器不能 ping 通 1.1.1.1 | WAN 地址、默认路由、拨号状态 | DNS |
| IP 能通，域名打不开 | DNS 配置 | 重新烧录 |
| 路由器能上网，客户端不能 | DHCP、防火墙区域、LAN 到 WAN 转发 | 订阅链接 |
| 开启 OpenClash 后才断网 | OpenClash 日志、配置文件与 DNS 模式 | WAN 物理连接 |
每次只修改一类设置，并在修改后重复相同的验证步骤。
验收检查表
- 能进入 LuCI，管理员密码已修改
- 树莓派有正确的 WAN 地址和默认路由
- 路由器的 IP 与 DNS 测试都通过
- 客户端连接树莓派 Wi-Fi 后可以上网
- 已确认使用
apk还是opkg - OpenClash 开关前后基础网络都可判断
- 第一份备份已经下载到电脑
以上项目全部完成后，可继续阅读系统维护与故障排查。