Files
op-packages/luci-app-substore/README.md
T

5.8 KiB
Raw Blame History

luci-app-substore

简体中文 | English

原生 OpenWrt / ImmortalWrt LuCI 应用,用于管理机场 / 代理订阅:解析订阅节点、 筛选、去重、重命名与分组,再转换为客户端可用的配置格式输出。

参考 Sub-Store 的功能与用户体验, 独立设计与实现:不使用 Docker,不依赖外部云端服务,资源占用友好,适配低配置路由器。

功能特性

订阅管理

  • 新增 / 编辑 / 删除 / 更新多个订阅源
  • 手动更新 + 按订阅的定时(cron)更新
  • 状态总览:节点数、最近更新时间、错误信息
  • 每个订阅的剩余流量 / 剩余时长,从 subscription-userinfo 响应头解析(仅在编辑页显示)
  • 订阅代理:通过 http:// / https:// / socks4 / socks5 / socks5h 代理下载订阅, 用于订阅源直连失败时
  • 组合订阅:勾选任意子集的现有订阅(可叠加关键词包含 / 排除、去重规则)合并成一个组合, 拥有独立名称、token 与订阅链接;源订阅更新后组合自动重算

输入解析

  • 订阅格式:URI 列表、Base64、JSON、Clash YAML、sing-box JSON、V2Ray / Xray JSON、 Surge / Surfboard / Loon / Quantumult X 配置、局域网订阅链接
  • 节点协议:vmess / vless / trojan / shadowsocks / ssr / hysteria2 / tuic / socks(及更多)

节点处理

  • 浏览节点,按协议筛选、关键词搜索、排序
  • 每次更新时生效的按订阅规则:
    • 关键词包含 / 排除(逗号分隔,支持多关键词)
    • 去重

网络探测(节点页)

  • Ping(ICMP 延迟)、TCPing(连接延迟)、URL 测试(HTTP 延迟)
  • 并行探测,显示成功数与平均延迟

转换与输出

  • 协议转换:任意协议 → 任意协议
  • SSR(ssr://)订阅源支持:仅能原样输出到支持它的客户端(Mihomo / Clash.Meta、Stash、 Loon、Egern、Shadowrocket),对其余目标(sing-box、V2Ray/Xray、Surge 家族)丢弃;SSR 不能与 vmess/vless 等其它协议互转(协议不兼容)
  • 13 种输出格式(全部实现):Plain JSON、Stash、Clash.Meta / Mihomo YAML、Surfboard、 Surge、Surge Mac、Loon、Egern、Shadowrocket、Quantumult X、sing-box、V2Ray / Xray、 V2Ray URI

订阅链接

  • 每个订阅独立随机 token → 公开下载端点 /substore/download?token=<token>&target=<format>,Passwall / OpenClash 等客户端可直接拉取

LuCI 界面与国际化

  • 默认英文,运行时语言为 zh-cn 时自动显示简体中文

安装

包名中的版本号必须与 Makefile 的 PKG_VERSION / PKG_RELEASE 保持一致 (当前 2.1.3-r6)。

opkg(OpenWrt / ImmortalWrt 24.10 及更早):

opkg install luci-app-substore-2.1.3-r6.ipk

apk(OpenWrt / ImmortalWrt 25.12+):

apk add --allow-untrusted luci-app-substore-2.1.3-r6.apk

然后在 LuCI 菜单打开:服务 → 订阅。

使用方法

  1. 添加订阅 —— 粘贴订阅 URL;可选的按订阅 cron 定时、规则或下载代理。
  2. 更新 —— 下载、解析并过滤节点。
  3. 浏览节点 —— 筛选、排序、探测延迟。
  4. 导出 —— 任选 13 种格式之一,或复制订阅链接供下游客户端(Passwall / OpenClash / …)使用。

目录结构

.
├── Makefile                      # OpenWrt 包定义
├── LICENSE                       # GPL-2.0-or-later
├── root/                         # 安装内容
│   ├── etc/
│   │   ├── config/substore       # UCI 占位
│   │   └── uci-defaults/99-substore
│   ├── usr/
│   │   ├── bin/substore-cron.sh  # 按订阅 cron 执行脚本
│   │   ├── lib/lua/luci/
│   │   │   ├── controller/admin/substore.lua   # 路由 / 动作
│   │   │   └── view/substore/*.htm             # 模板
│   │   └── share/
│   │       ├── luci/menu.d/luci-app-substore.json
│   │       └── substore/*.lua    # 核心逻辑(不依赖 luci.*)
├── po/zh-cn/substore.po          # 简体中文翻译
├── docs/                         # 设计与指南
└── tests/                        # 自包含 Lua 5.1 单元测试

文档

构建

将本包放入与目标固件版本匹配的 OpenWrt / ImmortalWrt SDK 或源码树:

cp -r luci-app-substore <openwrt-tree>/package/
make package/luci-app-substore/compile V=s

.ipk(或 apk 构建下的 .apk)生成于 bin/packages/.../ 下。

开发与测试

核心逻辑为纯 Lua 5.1,不依赖 luci.*,无需设备即可单元测试。tests/ 下每个测试文件自包含:

lua5.1 tests/run_tests.lua          # 或任意单个测试文件
for f in tests/*.lua; do lua5.1 "$f" || exit 1; done

LuCI 界面与 cron 行为仍需在目标设备上验证 —— 见 docs/TESTING.md。

安全

SSRF 防护(拒绝内网 / 保留 / 链路本地地址)、协议白名单、响应体大小与超时限制、 命令注入防护(白名单解析 + shell 引用)、公开下载端点基于 token 的访问控制、日志不含凭据。 详见 docs/SECURITY.md。

许可证

GPL-2.0-or-later —— 见 LICENSE 文件。