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

156 lines
6.0 KiB
Markdown

# luci-app-substore
**English** | [简体中文](README.md)
Native **OpenWrt / ImmortalWrt** LuCI application for managing airport / proxy
subscriptions. Parse nodes from a subscription, filter, deduplicate, rename and
group them, then re-emit them in a format your client can consume.
## Features
**Subscription management**
- Add / edit / delete / update multiple subscription sources
- Manual update plus per-subscription timed (cron) updates
- Status overview: node count, last update time, error message
- Remaining traffic & remaining duration per subscription, parsed from the
`subscription-userinfo` response header (shown on the edit page only)
- **Subscription proxy**: download the subscription through an
`http://` / `https://` / `socks4` / `socks5` / `socks5h` proxy — useful when the
source is unreachable directly
- **Combination subscription**: merge an arbitrary subset of existing subscriptions
(optionally with keyword include / exclude and dedup rules) into one combination that
has its own name, token and subscription link; combinations are recomputed automatically
when a source updates
**Input parsing**
- Subscription formats: URI lists, Base64, JSON, Clash YAML, sing-box JSON,
V2Ray / Xray JSON, Surge / Surfboard / Loon / Quantumult X configs, and LAN
subscription links
- Node protocols: `vmess` / `vless` / `trojan` / `shadowsocks` / `ssr` / `hysteria2` /
`tuic` / `socks` (and more)
**Node processing**
- Browse nodes, filter by protocol, keyword search, sort
- Per-subscription rules applied on every update:
- keyword include / exclude (comma-separated, multi-keyword)
- deduplication
**Network probing** (Nodes page)
- Ping (ICMP latency), TCPing (connect latency), URL test (HTTP latency)
- Parallel probing, success count and average latency
**Conversion & output**
- Protocol conversion: any node type → any other type
- SSR (`ssr://`) input is re-emitted losslessly to SSR-capable clients only — Mihomo /
Clash.Meta, Stash, Loon, Egern, Shadowrocket — and dropped for the rest (sing-box,
V2Ray/Xray, Surge family), since SSR is not convertible to/from other protocols
- 13 output formats (all implemented): Plain JSON, Stash, Clash.Meta / Mihomo YAML,
Surfboard, Surge, Surge Mac, Loon, Egern, Shadowrocket, Quantumult X, sing-box,
V2Ray / Xray, V2Ray URI
**Subscription links**
- Per-subscription random token → public download endpoint
`/substore/download?token=<token>&target=<format>` that Passwall / OpenClash and
other clients can pull directly
**LuCI web UI & i18n**
- English by default, 简体中文 auto-selected when the runtime language is `zh-cn`
## Installation
> The version in the package name must match `PKG_VERSION` / `PKG_RELEASE` in the
> [Makefile](Makefile) (currently `2.1.3-r6`).
opkg (OpenWrt / ImmortalWrt 24.10 and earlier):
```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
```
Then open LuCI: **Services → Subscriptions**.
## Usage
1. **Add a subscription** — paste the subscription URL; optionally set up a
per-subscription cron schedule, rules, or a download proxy.
2. **Update** — fetch, parse and filter the nodes.
3. **Browse nodes** — filter, sort, and probe latency.
4. **Export** — pick one of the 13 output formats, or copy the subscription link
to feed a downstream client (Passwall / OpenClash / …).
## Project layout
```
.
├── Makefile # OpenWrt package definition
├── LICENSE # GPL-2.0-or-later
├── root/ # install payload
│ ├── etc/
│ │ ├── config/substore # UCI placeholder
│ │ └── uci-defaults/99-substore
│ ├── usr/
│ │ ├── bin/substore-cron.sh # per-subscription cron runner
│ │ ├── lib/lua/luci/
│ │ │ ├── controller/admin/substore.lua # routes / actions
│ │ │ └── view/substore/*.htm # templates
│ │ └── share/
│ │ ├── luci/menu.d/luci-app-substore.json
│ │ └── substore/*.lua # core logic (no luci.* dependency)
├── po/zh-cn/substore.po # 简体中文 translations
├── docs/ # design & guides
└── tests/ # self-contained Lua 5.1 unit tests
```
## Documentation
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — architecture design
- [docs/PLAN.md](docs/PLAN.md) — staged development plan
- [docs/BUILD.md](docs/BUILD.md) — building from an OpenWrt SDK/source tree
- [docs/INSTALL.md](docs/INSTALL.md) — installation
- [docs/SECURITY.md](docs/SECURITY.md) — security model
- [docs/TESTING.md](docs/TESTING.md) — testing
- [docs/UCODE_MIGRATION.md](docs/UCODE_MIGRATION.md) — `.htm` → `.ut` (ucode) migration notes
- [CHANGELOG.md](CHANGELOG.md) — changelog
## Building
Place the package under an OpenWrt / ImmortalWrt SDK or source tree matching the
target firmware, then:
```bash
cp -r luci-app-substore <openwrt-tree>/package/
make package/luci-app-substore/compile V=s
```
The `.ipk` (or `.apk` on apk builds) is produced under `bin/packages/.../`.
## Development & testing
The core is plain Lua 5.1 with no `luci.*` dependency, so it is unit-testable
without a device. Each file under `tests/` is self-contained:
```bash
lua5.1 tests/run_tests.lua # or any single test file
for f in tests/*.lua; do lua5.1 "$f" || exit 1; done
```
Target-device verification is required for the LuCI UI and cron behaviour — see
[docs/TESTING.md](docs/TESTING.md).
## Security
SSRF protection (private / reserved / link-local ranges rejected), protocol
whitelisting, response size & timeout limits, command-injection defence
(whitelisted parsing + shell quoting), token-based access control on the public
download endpoint, and no credentials in logs. See
[docs/SECURITY.md](docs/SECURITY.md).
## License
[GPL-2.0-or-later](LICENSE) — see the [LICENSE](LICENSE) file.