Update README

Clean up files.
This commit is contained in:
Tindy X
2020-02-05 23:06:28 +08:00
parent 9c992ff2c3
commit 84a1b73f45
7 changed files with 147 additions and 1347 deletions

View File

@@ -3,17 +3,21 @@
在各种订阅格式之间进行转换的实用程序. 在各种订阅格式之间进行转换的实用程序.
[![Build Status](https://travis-ci.com/tindy2013/subconverter.svg?branch=master)](https://travis-ci.com/tindy2013/subconverter) [![Build Status](https://travis-ci.com/tindy2013/subconverter.svg?branch=master)](https://travis-ci.com/tindy2013/subconverter)
[![GitHub tag (latest SemVer)](https://img.shields.io/github/tag/tindy2013/subconverter.svg)](https://github.com/tindy2013/subconverter/tags)
[![GitHub release](https://img.shields.io/github/release/tindy2013/subconverter.svg)](https://github.com/tindy2013/subconverter/releases)
[![GitHub license](https://img.shields.io/github/license/tindy2013/subconverter.svg)](https://github.com/tindy2013/subconverter/blob/master/LICENSE)
- [支持类型](#支持类型) - [subconverter](#subconverter)
- [简易用法](#简易用法) - [支持类型](#支持类型)
- [调用地址](#调用地址) - [简易用法](#简易用法)
- [调用说明](#调用说明) - [调用地址](#调用地址)
- [进阶用法](#进阶用法) - [调用说明](#调用说明)
- [阅前提示](#阅前提示) - [进阶用法](#进阶用法)
- [进阶地址](#进阶地址) - [阅前提示](#阅前提示)
- [配置文件](#配置文件) - [进阶地址](#进阶地址)
- [外部配置](#外部配置) - [配置文件](#配置文件)
- [自动上传](#自动上传) - [外部配置](#外部配置)
- [自动上传](#自动上传)
## 支持类型 ## 支持类型

356
README.md
View File

@@ -3,268 +3,178 @@
Utility to convert between various subscription format. Utility to convert between various subscription format.
[![Build Status](https://travis-ci.com/tindy2013/subconverter.svg?branch=master)](https://travis-ci.com/tindy2013/subconverter) [![Build Status](https://travis-ci.com/tindy2013/subconverter.svg?branch=master)](https://travis-ci.com/tindy2013/subconverter)
[![GitHub tag (latest SemVer)](https://img.shields.io/github/tag/tindy2013/subconverter.svg)](https://github.com/tindy2013/subconverter/tags)
[![GitHub release](https://img.shields.io/github/release/tindy2013/subconverter.svg)](https://github.com/tindy2013/subconverter/releases)
[![GitHub license](https://img.shields.io/github/license/tindy2013/subconverter.svg)](https://github.com/tindy2013/subconverter/blob/master/LICENSE)
[中文文档](./README-cn.md) [Docker README](https://github.com/tindy2013/subconverter/blob/master/README-docker.md)
- [subconverter](#subconverter) - [subconverter](#subconverter)
- [Support Type](#support-type) - [Supported Types](#supported-types)
- [Usage](#usage) - [Quick Usage](#quick-usage)
- [Old interface](#old-interface) - [Access Interface](#access-interface)
- [**Recommended reading**](#recommended-reading) - [Description](#description)
- [pref.ini](#prefini) - [Advanced Usage](#advanced-usage)
- [common](#common) - [Read Before Continue](#read-before-continue)
- [api_mode](#api_mode) - [Advanced Details](#advanced-details)
- [default_url](#default_url) - [Configuration File](#configuration-file)
- [exclud_remarks](#exclud_remarks) - [External Configuration File](#external-configuration-file)
- [include_remarks](#include_remarks) - [Auto Upload](#auto-upload)
- [clash_rule_base](#clash_rule_base)
- [surge_rule_base](#surge_rule_base)
- [surfboard_rule_base](#surfboard_rule_base)
- [rename_node](#rename_node)
- [managed_config](#managed_config)
- [emojis](#emojis)
- [ruleset](#ruleset)
- [clash_proxy_group](#clash_proxy_group)
- [server](#server)
- [listen](#listen)
- [port](#port)
- [advanced](#advanced)
- [gist](#gist)
## Supported Types
| Type | As Source | As Target | Target Name |
| ------------ | :---------: | :-----------: | ----------- |
| Clash | ✔ | ✔ | clash |
| ClashR | ✔ | ✔ | clashr |
| Quantumult | ✔ | ✔ | quan |
| Quantumult X | ✔ | ✔ | quanx |
| SS (SIP002) | ✔ | ✔ | ss |
| SS Android | ✔ | ✔ | sssub |
| SSD | ✔ | ✔ | ssd |
| SSR | ✔ | ✔ | ssr |
| Surfboard | ✔ | ✔ | surfboard |
| Surge 2 | ✔ | ✔ | surge&ver=2 |
| Surge 3 | ✔ | ✔ | surge&ver=3 |
| Surge 4 | ✔ | ✔ | surge&ver=4 |
| V2Ray | ✔ | ✔ | v2ray |
## Support Type **Notice**Shadowrocket users should use `ss`, `ssr` or `v2ray` as target.
| Type | As Source Type | As Target Type | Parameters | ---
| ------------ | :------------: | :------------: | ----------- |
| clash | ✔ | ✔ | clash |
| clashr | ✔ | ✔ | clashr |
| surge2 | ✔ | ✔ | surge?ver=2 |
| surge3 | ✔ | ✔ | surge?ver=3 |
| surge4 | ✔ | ✔ | surge?ver=4 |
| quantumult | ✔ | ✔ | quan |
| quantumult X | ✔ | ✔ | quanx |
| surfboard | ✔ | ✔ | surfboard |
| ss | ✔ | ✔ | ss |
| ssr | ✔ | ✔ | ssr |
| ssd | ✔ | ✔ | ssd |
| v2ray | ✔ | ✔ | v2ray |
## Quick Usage
> Using default groups and rulesets configuration directly, without changing any settings
## Usage ### Access Interface
``` ```TXT
http://127.0.0.1:25500/sub?target=clash&url=%URL_ENCODED_LINKS% http://127.0.0.1:25500/sub?target=%TARGET%&url=%URL%&config=%CONFIG%
http://127.0.0.1:25500/sub?target=surge&ver=4&url=%URL_ENCODED_LINKS%
http://127.0.0.1:25500/sub?target=v2ray&url=%URL_ENCODED_LINKS%
``` ```
#### Old interface ### Description
``` | Argument | Needed | Example | Explanation |
http://127.0.0.1:25500/clash?url=%URL_ENCODED_LINKS% | ------- | :----: | :------ | ----------- |
| target | Yes | clash | Target subscription type. Acquire from Target Name in [Supported Types](#Supported_Types). |
| url | Yes | https%3A%2F%2Fwww.xxx.com | Subscription to convert. Supports URLs and file paths. Process with [URLEncode](https://www.urlencoder.org/) first. |
| config | No | https%3A%2F%2Fwww.xxx.com | External configuration file path. Supports URLs and file paths. Process with [URLEncode](https://www.urlencoder.org/) first. More examples can be found in [this](https://github.com/lzdnico/subconverteriniexample) repository. Default is to load configurations from `pref.ini`. |
If you need to merge two or more subscription, you should connect them with '|' before the URLEncode process.
Example:
```TXT
You have 2 subscriptions and you want to merge them and generate a Clash subscription:
1. https://dler.cloud/subscribe/ABCDE?clash=vmess
2. https://rich.cloud/subscribe/ABCDE?clash=vmess
First use '|' to separate 2 subscriptions:
https://dler.cloud/subscribe/ABCDE?clash=vmess|https://rich.cloud/subscribe/ABCDE?clash=vmess
Then process it with URLEncode to get %URL%:
https%3A%2F%2Fdler.cloud%2Fsubscribe%2FABCDE%3Fclash%3Dvmess%7Chttps%3A%2F%2Frich.cloud%2Fsubscribe%2FABCDE%3Fclash%3Dvmess
Then fill %TARGET% and %URL% in Access Interface with actual values:
http://127.0.0.1:25500/sub?target=clash&url=https%3A%2F%2Fdler.cloud%2Fsubscribe%2FABCDE%3Fclash%3Dvmess%7Chttps%3A%2F%2Frich.cloud%2Fsubscribe%2FABCDE%3Fclash%3Dvmess
Finally subscribe this link in Clash and you are done!
``` ```
If you have multiple subscriptions, use '|' to separate the links before url encode. <br> ---
e.g. <br> ## Advanced Usage
> I have the following two subscriptions: <br>
`https://dler.cloud/subscribe/ABCDE?clash=vmess`
`https://rich.cloud/subscribe/ABCDE?clash=vmess`
<br> <br>
separated by '|': <br>
`https://dler.cloud/subscribe/ABCDE?clash=vmess|https://rich.cloud/subscribe/ABCDE?clash=vmess`
<br> <br>
after url encode: <br>
`https%3A//dler.cloud/subscribe/ABCDE%3Fclash%3Dvmess%7Chttps%3A//rich.cloud/subscribe/ABCDE%3Fclash%3Dvmess`
<br> <br>
add to the back of the link: <br>
`http://127.0.0.1:25500/sub?target=clash&url=https%3A//dler.cloud/subscribe/ABCDE%3Fclash%3Dvmess%7Chttps%3A//rich.cloud/subscribe/ABCDE%3Fclash%3Dvmess `
<br> <br>
&nbsp;&nbsp;&#127830; Edible &#127830;
<br> <br>
> If you are not satisfied with the default groups and rulesets, you can try out advanced usage.
> Customize more settings in Access Interface and `pref.ini` to satisfy various needs.
- Want to learn more postures? Come to [pref.ini](./pref.ini). ### Read Before Continue
It is strongly recommended to read the following articles before continuing:
1. Related to `pref.ini`: [INI file](https://en.wikipedia.org/wiki/INI_file)
1. Related to `Clash` configurations: [YAML Syntax](https://en.wikipedia.org/wiki/YAML#Syntax)
1. Often needed: [Learn Regular Expression](https://github.com/ziishaned/learn-regex/blob/master/README.md)
1. When you want to write an ISSUE: [How To Ask Questions The Smart Way](http://www.catb.org/~esr/faqs/smart-questions.html)
## **Recommended reading** Subconverter only guaranteed to work with default configurations.
> - [&#128220; Regular Expression &#128220;](https://en.wikipedia.org/wiki/Regular_expression) ### Advanced Details
> - [&#128221; yaml syntax introduction &#128221;](https://en.wikipedia.org/wiki/YAML)
> - [&#10068; Wisdom to ask questions &#10068;](http://www.catb.org/~esr/faqs/smart-questions.html)
#### Access Interface
```txt
## pref.ini http://127.0.0.1:25500/sub?target=%TARGET%&url=%URL%&emoji=%EMOJI%····
### common
#### api_mode
> API mode, set to true to prevent loading local subscriptions or serving local files directly.
When the value is `false`, `pref.ini` is read every time the configuration is updated. When it is `true`, it is read only at startup.
#### default_url
> Default URLs, used when no URL is provided in request, use "|" to separate multiple subscription links, supports local files/URL.
This usage:
```ini
default_url=https://dler.cloud/subscribe/ABCDE?clash=vmess
``` ```
`http://127.0.0.1:25500/clash` #### Description
equivalent to: | Argument | Needed | Example | Explanation |
<br> | -------- | :----: | :--------------- | :------------------------ |
`http://127.0.0.1:25500/sub?target=clash&url=https%3A//dler.cloud/subscribe/ABCDE%3Fclash%3Dvmess` | target | Yes | quan | Target subscription type. Acquire from Target Name in [Supported Types](#Supported_Types). |
| url | No | https%3A%2F%2Fwww.xxx.com | Subscription to convert. Supports URLs and file paths. Process with [URLEncode](https://www.urlencoder.org/) first. **Not needed ONLY WHEN YOU HAVE SET `default_urls` IN `pref.ini`. |
| config | No | https%3A%2F%2Fwww.xxx.com | External configuration file path. Supports URLs and file paths. Process with [URLEncode](https://www.urlencoder.org/) first. More examples can be found in [this](https://github.com/lzdnico/subconverteriniexample) repository. Default is to load configurations from `pref.ini`. |
| upload | No | true / false | Upload generated configuration to `Gist repository`. `gistconf.ini` must be filled before uploading. Default is `false`. |
| upload_path | No | MySS.yaml | File name when uploaded to `Gist`. Process with [URLEncode](https://www.urlencoder.org/) first. |
| emoji | No | true / false | Adding Emoji to node remarks. Default is `true`. |
| group | No | MySS | Set a custom group for generated configuration. Often needed in SSD/SSR subscription. |
| tfo | No | true / false | Enable TCP Fast Open for all nodes. Default is `false`. |
| udp | No | true / false | Enable UDP for all nodes. Default is `false`. |
| scv | No | true / false | Enable Skip Cert Verify for all nodes. Default is `false`. |
| list | No | true / false | Generate Surge Node List or Clash Proxy Provider. Default is `false`. |
| sort | No | true / false | Sort nodes in alphabetical order. Default is `false`. |
| include | No | See `include_remarks` | Exclude nodes which remarks match the following patterns. Supports regular expression. Process with [URLEncode](https://www.urlencoder.org/) first. **WILL OVERRIDE THE SAME SETTING IN `pref.ini`** |
| exclude | No | See `exclude_remarks` | Only include nodes which remarks match the following patterns. Supports regular expression. Process with [URLEncode](https://www.urlencoder.org/) first. **WILL OVERRIDE THE SAME SETTING IN `pref.ini`** |
Example:
```TXT
You have the following subscription: `https://dler.cloud/subscribe/ABCDE?clash=vmess`, and you want to convert it to Surge 4 subscription, set UDP and TFO to enabled,
add Emoji to node remarks and filter out unused nodes named "剩余流量1024G" and "官网地址dler.cloud".
#### exclud_remarks First find all needed arguments:
target=surge, ver=4, tfo=true, udp=true, emoji=true, exclude=(流量|官网)
url=https://dler.cloud/subscribe/ABCDE?clash=vmess
> Exclude nodes which remarks match the following patterns. Supports regular expression. Then process any argument that requires URLEncode:
exclude=%28%E6%B5%81%E9%87%8F%7C%E5%AE%98%E7%BD%91%29
url=https%3A%2F%2Fdler.cloud%2Fsubscribe%2FABCDE%3Fclash%3Dvmess
e.g. Then merge everything into a single URL:
```ini http://127.0.0.1:25500/sub?surge&ver=4&tfo=true&udp=true&emoji=true&exclude=%28%E6%B5%81%E9%87%8F%7C%E5%AE%98%E7%BD%91%29&url=https%3A%2F%2Fdler.cloud%2Fsubscribe%2FABCDE%3Fclash%3Dvmess
exclude_remarks=(Traffic|Time|Official Website|Products)
Finally subscribe this link in Surge and you are done!
```
### Configuration File
> Check comments inside [pref.ini](https://github.com/tindy2013/subconverter/blob/master/base/pref.ini) for more information.
### External Configuration File
> Most settings works the same as the ones with the same name inside `pref.ini`, you can check [the example configuration file](https://github.com/tindy2013/subconverter/blob/master/base/config/example_external_config.ini) and comments inside [pref.ini](https://github.com/tindy2013/subconverter/blob/master/base/pref.ini) for more information.
Any setting defined in the external configuration file will **override** the ones from `pref.ini`.
For example, if you have the following lines inside the external configuration file:
```
emoji=(流量|时间|应急),🏳️‍🌈
emoji=阿根廷,🇦🇷
``` ```
Then instead of the Emojis defined in `pref.ini`, the program will only use the newly defined ones.
## Auto Upload
#### include_remarks > Upload Gist automatically
> Only include nodes which remarks match the following patterns. Supports regular expression. Add a [Personal Access Token](https://github.com/settings/tokens/new) into [gistconf.ini](./gistconf.ini) in the root directory, then add `&upload=true` to the local subscription link, then when you access this link, the program will automatically update the content to Gist repository.
e.g. Example:
```ini
include_remarks=(?<=美).*(BGP|GIA|IPLC)
```
#### clash_rule_base
> Clash config base used by the generator, supports local `files`/`URL`.
e.g.
```ini
clash_rule_base=clash.yaml
clash_rule_base=https://raw.githubusercontent.com/ConnersHua/Profiles/master/Clash/Pro.yaml
```
#### surge_rule_base
> Surge config base used by the generator, supports local `files`/`URL`.
#### surfboard_rule_base
> Surfboard config base used by the generator, supports local `files`/`URL`.
#### rename_node
> Rename remarks with the following patterns. Supports regular expression.
e.g.
```ini
rename_node=中国@中
rename_node=深圳@深
```
### managed_config
> Append a '#!MANAGED-CONFIG' info to Surge configurations.
### emojis
> Rule to add emojis. Supports regular expression.
e.g.
```ini
rule=(流量|时间|应急),⌛time
rule=(美|美国|United States),🇺🇸
```
### ruleset
> Enable generating rules with rulesets.
e.g.
<img src="./doc/imgs/Snipaste_2019-11-18_14-11-52.png">
```ini ```ini
ruleset=🌹 YouTube, https://raw.githubusercontent.com/ConnersHua/Profiles/master/Surge/Media/YouTube.list [common]
;uncomment the following line and enter your token to enable upload function
token = xxxxxxxxxxxxxxxxxxxxxxxx(Your Personal Access Token)
``` ```
effect chart:
<img src="./doc/imgs/Snipaste_2019-11-18_14-15-54.png">
### clash_proxy_group
> Generate Clash Proxy Group with the following patterns. Node filterting rule supports regular expression.
e.g.
```ini
custom_proxy_group=🇺🇸US`url-test`(United States|United States|United States)`http://www.gstatic.com/generate_204`300
```
effect chart:
<img src="./doc/imgs/Snipaste_2019-11-18_14-47-30.png">
The ssr/v2 subscription does not have a group name by default. You can use this method to add a group name.
```ini
custom_proxy_group=g1`select`!!GROUPID=0
custom_proxy_group=g2`select`!!GROUPID=1
custom_proxy_group=v2ray`select`!!GROUP=V2RayProvider
```
### server
#### listen
> Address to bind on for Web Server.
#### port
> Port to bind on for Web Server.
### advanced
> No description required.
## gist
> Automatically upload gist.
Add personal access token in [gistconf.ini](./gistconf.ini), add `upload=true` after the link will automatically upload gist after updating.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.1 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 435 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 946 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 7.5 KiB

File diff suppressed because it is too large Load Diff