openwrt插件库

一、什么是 OpenWrt 插件库

OpenWrt 是一个“最小可用”的路由器系统：官方固件里只打包了内核、网络栈、防火墙、DHCP/DNS 以及 LuCI 基础界面这些核心组件，其余功能全部以软件包（package）的形式按需安装。存放这些软件包的地方就是软件源（feed / repository），而玩家平时说的“插件库”，通常指的是三类东西：

• 官方软件源：OpenWrt 官方发布的 feeds，包含 LuCI 界面、大部分内核模块与常用工具，可以通过 opkg 或 apk 直接安装。
• 第三方插件源：由社区或厂商维护的额外软件源，提供官方源里没有的插件，例如各种代理内核面板、去广告组件、Docker 管理界面、下载器等。
• 插件包合集仓库：GitHub 上的“插件库”项目，里面存放的是已经编译好的 .ipk / .apk 安装包或一键安装脚本，适合不想自己编译固件的用户。

理解这三者的区别非常重要：“插件库”只是存放安装包的仓库，真正让插件生效的是路由器上的包管理器和内核模块版本匹配。很多人从网上下载一个 ipk 装上却报错，根本原因不是插件库有问题，而是插件依赖的内核模块版本（kmod，跟随内核版本号）和自己固件的内核版本不一致。

二、适用场景

• 软路由（x86_64、N100、J4125 等）刷了 OpenWrt 或 iStoreOS，需要补装插件实现科学上网、内网穿透、下载、家庭 NAS 等功能。
• 硬路由（ARM 平台）移植了 OpenWrt，想通过第三方源安装官方源没有的插件。
• 系统升级后插件丢失，需要重新从插件库安装或从备份中恢复。
• 需要给多台设备批量部署同一套插件，希望通过命令行的方式自动化安装。

三、前置条件

• 路由器已刷好 OpenWrt / iStoreOS / ImmortalWrt 等衍生固件，并且能正常上网。
• 已开启 SSH：LuCI 界面路径为 系统 → 管理权 → SSH 访问，确认 Dropbear 实例 已启用并放行 LAN 口访问。
• 确认设备架构，避免下载错误的安装包。命令行查看：

# 查看 CPU 架构与包管理器类型
uname -m
cat /etc/openwrt_release
opkg print-architecture 2>/dev/null || echo "当前系统使用 apk 包管理器"

• 确认 overlay 剩余空间充足（插件体积从几十 KB 到几十 MB 不等，Docker、Clash 内核这类插件很占空间）：

df -h /overlay
df -h /tmp

四、常用插件库清单

下面是目前社区里使用最广泛、更新相对活跃的插件库与项目地址，可直接在浏览器中打开查看说明与适配的固件版本：

1、iStoreOS 插件库：

https://github.com/AUK9527/Are-u-ok/tree/main

2、PassWall 项目：

https://github.com/xiaorouji/openwrt-passwall

3、OpenClash 项目：

https://github.com/vernesong/OpenClash

4、iStore 软件包目录：

https://github.com/AUK9527/Are-u-ok/tree/main/apps

5、ImmortalWrt 源码与软件源（衍生固件，软件包兼容性最好）：

https://github.com/immortalwrt/immortalwrt

6、iStore 应用商店本体（iStoreOS 内置，普通 OpenWrt 可尝试安装）：

https://github.com/linkease/istore

需要提醒的是：这些项目大多提供的是已编译好的安装包，下载前必须确认三件事——CPU 架构（x86_64 / aarch64_cortex-a53 等）、内核版本（决定 kmod 依赖）、以及固件是 opkg 还是 apk 体系。三者中任意一项不匹配，安装都会失败。

五、分步操作：图形界面安装插件（推荐新手）

1. 浏览器登录 LuCI，地址通常是 http://192.168.1.1（iStoreOS 默认 http://192.168.100.1）。
2. 如果固件集成了 iStore，直接在菜单 iStore 应用商店 中搜索插件名，点击“安装”即可，商店会自动处理依赖与架构匹配问题。
3. 如果使用原生 LuCI，进入 系统 → 软件包（System → Software），先点击“更新列表”（Update lists）刷新软件源索引。
4. 在“过滤器”输入框中搜索关键字，例如 openclash、passwall、adguard，在结果列表中点击对应条目右侧的“安装”。
5. LuCI 会弹出依赖确认窗口，列出需要一并安装的依赖包，确认后点击“安装”，等待进度条完成。
6. 安装完成后刷新浏览器（Ctrl+F5），在顶部菜单或 服务 菜单下即可看到新插件的页面。

六、分步操作：命令行添加第三方软件源

当插件不在官方源里时，可以手动添加第三方源，或者直接用 wget 下载 ipk 安装。以下是以 x86_64 平台为例的通用流程：

# 1) 备份原有源配置
cp /etc/opkg/distfeeds.conf /etc/opkg/distfeeds.conf.bak

# 2) 追加第三方源（把下面的 URL 换成插件库实际提供的地址）
echo "src/gz custompkg https://example.com/openwrt/packages/x86_64/base" >> /etc/opkg/customfeeds.conf

# 3) 刷新索引
opkg update

# 4) 安装插件（名称以软件源中的实际包名为准）
opkg install luci-app-passwall

如果是用 apk 体系的新版本 OpenWrt，对应的命令是：

apk update
apk add luci-app-passwall

对于只拿到单个安装包的场景，可以这样做：

cd /tmp
wget -O plugin.ipk https://example.com/path/to/plugin.ipk
opkg install plugin.ipk

OpenClash、PassWall 这类插件还需要额外下载 Clash / sing-box 内核文件，内核与插件版本必须对应，否则插件界面能打开但无法启动。安装内核后一般执行：

/etc/init.d/openclash enable
/etc/init.d/openclash start
/etc/init.d/openclash status

七、验证方法

• 确认包已安装：opkg list-installed | grep -i clash（apk 系统用 apk info | grep -i clash）。
• 确认服务脚本存在并可用：ls /etc/init.d/ | grep -i clash，再执行 /etc/init.d/clash status。
• 确认进程在运行：ps w | grep -i clash | grep -v grep。
• 确认端口监听正常：netstat -lntp | grep -E "7890|9090"（具体端口以插件配置为准）。
• 确认界面入口出现：重新登录 LuCI，检查 服务 菜单下是否出现新插件；若没有，清理浏览器缓存或重启 web 服务 /etc/init.d/uhttpd restart。
• 确认空间与日志无异常：logread | tail -50，查看是否有依赖缺失或内核模块加载失败的报错。

八、常见问题

1. opkg update 报 SSL 证书错误或下载失败
多由时间不同步或 DNS 解析异常引起。先执行 date 检查系统时间，再执行 ntpd -q -p pool.ntp.org 同步时间；若域名解析不通，可在 网络 → DHCP/DNS 中把上游 DNS 改为 223.5.5.5 或 1.1.1.1 后重试。

2. 安装时提示 cannot install package xxx 或依赖 kmod 无法满足
这是最典型的问题：插件的内核模块依赖与固件内核版本不一致。解决办法是使用与固件同版本号（同 hash）的插件包，或者更换为提供该插件的固件（如 iStoreOS、ImmortalWrt）。强行加 --force-depends 安装通常能装上但运行会崩溃，不建议。

3. 提示空间不足 No space left on device
使用 df -h /overlay 查看剩余空间；卸载不用的插件 opkg remove 包名，清理缓存 rm -rf /tmp/opkg-lists/*，或给 x86 软路由扩容 overlay 分区。

4. 安装成功但 LuCI 菜单里看不到插件
先重启 web 服务 /etc/init.d/uhttpd restart 并强制刷新浏览器；仍不显示则检查是否有权限或语言包问题，可尝试 opkg install luci-i18n-包名-zh-cn 安装中文语言包。

5. 提示包已存在冲突 conflicts with installed package
常见于同时安装两套同类插件（如 OpenClash 与 PassWall 的 DNS 劫持组件）。先卸载冲突包，再安装目标插件，避免同时启用两个会修改防火墙规则的插件。

6. 升级固件后插件全部消失
sysupgrade 默认不保留已安装的第三方包，只保留配置文件。升级后重新安装，或提前把 ipk 与内核文件放在 U 盘或 /root 目录下以便快速恢复。

7. 插件能启动但无法出网
排查顺序：确认防火墙转发与 NAT 规则未被覆盖 → 检查 DNS 是否被劫持到未启动的端口 → 查看插件日志（logread -e clash）确认订阅拉取是否成功。

8. 第三方源是否安全
第三方软件源本质上是把安装包交给对方。建议只使用社区长期维护、star 数较高、能看到源码的项目；上线前先在虚拟环境或备用设备上测试，避免在承载生产网络的路由器上直接试装未知来源的包。

九、小结

OpenWrt 插件库的核心逻辑并不复杂：官方源解决“基础功能”，第三方插件库解决“特色功能”，而安装能否成功取决于架构、内核版本和存储空间三个条件。新手优先用 iStore 这类带依赖解析的应用商店进入插件生态；进阶用户则建议掌握 opkg/apk 与自定义软件源的用法，这样即使固件升级或换机器，也能在几分钟内把常用插件重新部署起来。