Update README [skip ci]

This commit is contained in:
Tindy X 2021-09-30 13:08:13 +08:00
parent cea6d5fe88
commit beb1070c24
No known key found for this signature in database
GPG Key ID: C6AD413169968D58
2 changed files with 9 additions and 146 deletions

View File

@ -2,7 +2,7 @@
在各种订阅格式之间进行转换的实用程序.
[![Build Status](https://travis-ci.com/tindy2013/subconverter.svg?branch=master)](https://travis-ci.com/tindy2013/subconverter)
[![Build Status](https://github.com/tindy2013/subconverter/actions/workflows/build.yml/badge.svg)](https://github.com/tindy2013/subconverter/actions)
[![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)

153
README.md
View File

@ -2,7 +2,7 @@
Utility to convert between various proxy subscription formats.
[![Build Status](https://travis-ci.com/tindy2013/subconverter.svg?branch=master)](https://travis-ci.com/tindy2013/subconverter)
[![Build Status](https://github.com/tindy2013/subconverter/actions/workflows/build.yml/badge.svg)](https://github.com/tindy2013/subconverter/actions)
[![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)
@ -16,13 +16,7 @@ Utility to convert between various proxy subscription formats.
- [Quick Usage](#quick-usage)
- [Access Interface](#access-interface)
- [Description](#description)
- [Quick Conversion](#quick-conversion)
- [Advanced Usage](#advanced-usage)
- [Read Before Continue](#read-before-continue)
- [Advanced Details](#advanced-details)
- [Profiles](#profiles)
- [Configuration File](#configuration-file)
- [External Configuration File](#external-configuration-file)
- [Auto Upload](#auto-upload)
## Supported Types
@ -70,13 +64,13 @@ http://127.0.0.1:25500/sub?target=%TARGET%&url=%URL%&config=%CONFIG%
### Description
| Argument | Needed | Example | Explanation |
| ------- | :----: | :------ | ----------- |
| 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`. |
| Argument | Required | Example | Description |
| -------- | :------: | :------ | ----------- |
| 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. |
If you need to merge two or more subscription, you should connect them with '|' before the URLEncode process.
If you need to merge two or more subscription, you should join them with '|' before the URLEncode process.
Example:
@ -97,142 +91,11 @@ http://127.0.0.1:25500/sub?target=clash&url=https%3A%2F%2Fdler.cloud%2Fsubscribe
Finally subscribe this link in Clash and you are done!
```
### Quick Conversion
When the Surge configuration file has already meet your requirements, but you also need a same Clash configuration with the same groups and rules, you can use the following method:
```txt
http://127.0.0.1:25500/surge2clash?link=url_to_Surge_subscription
```
Here `url_to_Surge_subscription` **does not need to be URLEncoded** and no other configuration is needed.
---
## Advanced Usage
> 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.
### 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)
Subconverter only guaranteed to work with default configurations.
### Advanced Details
#### Access Interface
```txt
http://127.0.0.1:25500/sub?target=%TARGET%&url=%URL%&emoji=%EMOJI%····
```
#### Description
| Argument | Needed | Example | Explanation |
| -------- | :----: | :--------------- | :------------------------ |
| 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, data URIs, 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`** |
| filename | No | MySS | Set the file name while downloading. Can be used as a profile name in Clash for Windows. |
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".
First find all needed arguments:
target=surge, ver=4, tfo=true, udp=true, emoji=true, exclude=(流量|官网)
url=https://dler.cloud/subscribe/ABCDE?clash=vmess
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
Then merge everything into a single URL:
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
Finally subscribe this link in Surge and you are done!
```
### Profiles
> After preparing all the arguments for the subscription link, it may be too long and hard to remember. Now you can consider setting up a profile.
For now **only local profiles are allowed.**
#### Interface for Profiles
```txt
http://127.0.0.1:25500/getprofile?name=%NAME%&token=%TOKEN%
```
#### Description
| Argument | Needed | Example | Explanation |
| -------- | :----: | :--------------- | :------------------------ |
| name | Yes | profiles/formyairport.ini | The path to the profile. (relative to the `pref` configuration) |
| token | Yes | passwd | The access token for authorization. (Please check `api_access_token` in the `[common] section` in `pref` configuration. |
Notice that arguments in the profile **does not require URLEncode**.
Create a new text file **only in the same directory or a sub-directory** of the `pref` configuration (a sub-directory named `profiles` is recommended) and name it, for example `formyairport.ini`, then fill the arguments to the file according to the [example profile](https://github.com/tindy2013/subconverter/blob/master/base/profiles/example_profile.ini), then you are good to go.
<details>
<summary>Example:</summary>
Using the same example in [Advanced Usage](#advanced-usage), the content of `formyairport.ini` should be:
```txt
[Profile]
url=https://dler.cloud/subscribe/ABCDE?clash=vmess
target=surge
surge_ver=4
tfo=true
udp=true
emoji=true
exclude=(流量|官网)
```
After saving it to the `profile` directory, you can access `http://127.0.0.1:25500/getprofile?name=profiles/formyairport.ini&token=passwd` to read this profile.
</details>
### Configuration File
> Check comments inside [pref.example.ini](https://github.com/tindy2013/subconverter/blob/master/base/pref.example.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.example.ini](https://github.com/tindy2013/subconverter/blob/master/base/pref.example.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.
Please refer to [中文文档](https://github.com/tindy2013/subconverter/blob/master/README-cn.md#%E8%BF%9B%E9%98%B6%E7%94%A8%E6%B3%95).
## Auto Upload