mirror of
https://github.com/kiddin9/op-packages.git
synced 2026-11-16 21:43:33 +08:00
144 lines
5.8 KiB
Markdown
144 lines
5.8 KiB
Markdown
# luci-app-substore
|
||
|
||
**简体中文** | [English](README.en.md)
|
||
|
||
原生 **OpenWrt / ImmortalWrt** LuCI 应用,用于管理机场 / 代理订阅:解析订阅节点、
|
||
筛选、去重、重命名与分组,再转换为客户端可用的配置格式输出。
|
||
|
||
参考 [Sub-Store](https://github.com/sub-store-org/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](Makefile) 的 `PKG_VERSION` / `PKG_RELEASE` 保持一致
|
||
> (当前 `2.1.3-r6`)。
|
||
|
||
opkg(OpenWrt / ImmortalWrt 24.10 及更早):
|
||
|
||
```bash
|
||
opkg install luci-app-substore-2.1.3-r6.ipk
|
||
```
|
||
|
||
apk(OpenWrt / ImmortalWrt 25.12+):
|
||
|
||
```bash
|
||
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 单元测试
|
||
```
|
||
|
||
## 文档
|
||
|
||
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — 架构设计
|
||
- [docs/PLAN.md](docs/PLAN.md) — 分阶段开发计划
|
||
- [docs/BUILD.md](docs/BUILD.md) — 从 OpenWrt SDK / 源码树构建
|
||
- [docs/INSTALL.md](docs/INSTALL.md) — 安装
|
||
- [docs/SECURITY.md](docs/SECURITY.md) — 安全模型
|
||
- [docs/TESTING.md](docs/TESTING.md) — 测试
|
||
- [docs/UCODE_MIGRATION.md](docs/UCODE_MIGRATION.md) — `.htm` → `.ut`(ucode)迁移说明
|
||
- [CHANGELOG.md](CHANGELOG.md) — 更新日志
|
||
|
||
## 构建
|
||
|
||
将本包放入与目标固件版本匹配的 OpenWrt / ImmortalWrt SDK 或源码树:
|
||
|
||
```bash
|
||
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/` 下每个测试文件自包含:
|
||
|
||
```bash
|
||
lua5.1 tests/run_tests.lua # 或任意单个测试文件
|
||
for f in tests/*.lua; do lua5.1 "$f" || exit 1; done
|
||
```
|
||
|
||
LuCI 界面与 cron 行为仍需在目标设备上验证 —— 见 [docs/TESTING.md](docs/TESTING.md)。
|
||
|
||
## 安全
|
||
|
||
SSRF 防护(拒绝内网 / 保留 / 链路本地地址)、协议白名单、响应体大小与超时限制、
|
||
命令注入防护(白名单解析 + shell 引用)、公开下载端点基于 token 的访问控制、日志不含凭据。
|
||
详见 [docs/SECURITY.md](docs/SECURITY.md)。
|
||
|
||
## 许可证
|
||
|
||
[GPL-2.0-or-later](LICENSE) —— 见 [LICENSE](LICENSE) 文件。 |