Skip to content

Commit

Permalink
add en
Browse files Browse the repository at this point in the history
  • Loading branch information
@xishang0128
xishang0128 committed Sep 21, 2024
1 parent 44d13cf commit cbc1598
Show file tree
Hide file tree
Showing 20 changed files with 1,080 additions and 108 deletions.
219 changes: 118 additions & 101 deletions docs/api/index.en.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,231 +3,248 @@ hide:
- navigation
# - toc
---

# API

## Request Example

curl example: `curl -H 'Authorization: Bearer ${secret}' http://${controller-api}/version`
Curl example: `curl -H 'Authorization: Bearer ${secret}' http://${controller-api}/configs?force=true -d '{"path": "", "payload": ""}' -X PUT`

This request includes the header `'Authorization: Bearer ${secret}'`, where:

This request includes the `'Authorization: Bearer ${secret}'` header, where:
- `${secret}` is the API key set in the configuration file [api](../config/general.md#external-control-api)
- `${controller-api}` is the API listening address set in the configuration file [api](../config/general.md#external-control-api)
- `?force=true` is a parameter that needs to be included in certain requests
- `'{"path": "", "payload": ""}'` is the data for the resource to be updated

- `${secret}` is the [api](../config/general.md#api) secret set in the configuration file.
- `${controller-api}` is the [api](../config/general.md#api) listening address set in the configuration file.
In most cases, the data passed is `'{"path": "", "payload": ""}'`, which can include a new configuration file path.

## Logs

### `/logs`

Request Method: `GET`
Request method: `GET`

- Obtain real-time logs.
- Retrieve real-time logs.

## Traffic Information

### `/traffic`

Request Method: `GET`
Request method: `GET`

- Obtain real-time traffic, measured in kbps.
- Retrieve real-time traffic, measured in kbps.

## Memory Information

### `/memory`

Request Method: `GET`
Request method: `GET`

- Obtain real-time memory usage, measured in kb.
- Retrieve real-time memory usage, measured in kb.

## Version Information

### `/version`

Request Method: `GET`
Request method: `GET`

- Get Clash version.
- Retrieve the Clash version.

## Cache

### `/cache/fakeip/flush`

Request Method: `POST`
Request method: `POST`

- Clear fake-IP cache
- Clear the fake IP cache.

## Runtime Configuration
## Running Configuration

### `/configs`

Request Method: `GET`
Request method: `GET`

- Get basic configuration.
- Retrieve basic configuration.

Request Method: `PUT`
Request method: `PUT`

- Reload basic configuration.
- URL must include `?force=true` to force execution and must send data.
- curl example: `curl "${controller-api}/configs?force=true" -X PUT -d '{"path": "", "payload": ""}'`
- Reload basic configuration; data must be sent, and the URL must include `?force=true` to enforce execution.

Request Method: `PATCH`
Request method: `PATCH`

- Update basic configuration by providing the configuration to be modified in JSON format.
- curl example: `curl ${controller-api}/configs -X PATCH -d '{"mixed-port": 7890}'`
- Update basic configuration; data must be sent in the format `'{"mixed-port": 7890}'`, modified as needed for the configuration items to be updated.

### `/configs/geo`

Request Method: `POST`
Request method: `POST`

- Update GEO database.
- Must send data, as it automatically reloads the configuration after the update.
- curl example: `curl "${controller-api}/configs" -X POST -d '{"path": "", "payload": ""}'`
- Update the GEO database; data must be sent.

### `/restart`

Request Method: `POST`
Request method: `POST`

- Restart the kernel.
- Must send data.
- curl example: `curl "${controller-api}/restart " -X POST -d '{"path": "", "payload": ""}'`
- Restart the kernel; data must be sent.

## Update
## Updates

### `/upgrade/`
### `/upgrade`

Request Method: `POST`
Request method: `POST`

- Update the kernel.
- Must send data, as it automatically reloads the configuration after the update.
- curl example: `curl "${controller-api}/upgrade" -X POST -d '{"path": "", "payload": ""}'`
- Update the kernel; data must be sent.

### `/upgrade/ui`

Request Method: `POST`
Request method: `POST`

- Update the panel; external-ui must be set.
- curl example: `curl "${controller-api}/upgrade/ui" -X POST`
- Update the panel; [external-ui](../config/general.md#external-user-interface) must be set.

## Proxies
### `/upgrade/geo`

### `/proxies`
Request method: `POST`

Request Method: `GET`
- Update the GEO database; data must be sent.

- Get proxy information.
## Policy Groups

### `/proxies/:name`
### `/group`

Request Method: `GET`
Request method: `GET`

- Get specific proxy information.
- Retrieve policy group information.

Request Method: `PUT`
### `/group/group_name`

- Select a specific proxy.
Request method: `GET`

### `/proxies/:name/delay`
- Retrieve specific policy group information.

Request Method: `GET`
### `/group/group_name/delay`

- Get delay test information for a specific proxy.
Request method: `GET`

## Rules
- Test nodes/policy groups within a specified policy group and return new delay information; the URL must include `?url=xxx&timeout=5000`, modified as needed.

### `/rules`
## Proxies

Request Method: `GET`
### `/proxies`

- Get rule information.
Request method: `GET`

## Connections
- Retrieve proxy information.

### `/connections`
### `/proxies/proxies_name`

Request Method: `GET`
Request method: `GET`

- Get connection information.
- Retrieve specific proxy information.

Request Method: `DELETE`
Request method: `PUT`

- Close all connections.
- Select a specific proxy; data must be included in the format `'{"name":"Japan"}'`.

### `/connections/:id`
### `/proxies/proxies_name/delay`

Request Method: `DELETE`
Request method: `GET`

- Close a specific connection.
- Test a specified proxy and return new delay information; the URL must include `?url=xxx&timeout=5000`, modified as needed.

## Proxy Providers
## Proxy Sets

### `/providers/proxies`

Request Method: `GET`
Request method: `GET`

- Retrieve all information for all proxy sets.

### `/providers/proxies/providers_name`

Request method: `GET`

- Retrieve information for a specific proxy set.

Request method: `PUT`

- Get information for all proxies in all Proxy Providers.
- Update the proxy set.

### `/providers/proxies/:name`
### `/providers/proxies/providers_name/healthcheck`

Request Method: `GET`
Request method: `GET`

- Get information for proxies in a specific Proxy Providers.
- Trigger a health check for a specific proxy set.

Request Method: `PUT`
### `/providers/proxies/providers_name/proxies_name/healthcheck`

- Update Proxy Providers.
- Test a specified proxy within the proxy set and return new delay information; the URL must include `?url=xxx&timeout=5000`, modified as needed.

### `/providers/proxies/:name/healthcheck`
## Rules

### `/rules`

Request Method: `GET`
Request method: `GET`

- Trigger health check for a specific Proxy Providers.
- Retrieve rule information.

## Rule Providers
## Rule Sets

### `/providers/rules`

Request Method: `GET`
Request method: `GET`

- Get information for all Rule Providers.
- Retrieve all information for all rule sets.

### `/providers/rules/:name`
### `/providers/rules/providers_name`

Request Method: `PUT`
Request method: `PUT`

- Update Rule Providers.
- Update the rule set.

## Domain Query
## Connections

### `/dns/query`
### `/connections`

Request method: `GET`

- Retrieve connection information.

Request Method: `GET`
Request method: `DELETE`

- Get DNS query data for a specified name and type.
- Close all connections.

### `/connections/:id`

Parameters:
Request method: `DELETE`

- Close a specific connection.

## Domain Query

### `/dns/query`

- `name` (required): The domain name to query.
- `type` (optional): The DNS record type to query (e.g., A, MX, CNAME, etc.).
Request method: `GET`

Example: `GET /dns/query?name=example.com&type=A`
- Retrieve DNS query data for a specified name and type; the URL must include `?name=example.com&type=A`, modified as needed.

## DEBUG

`/debug` requires the core to start with [debug log level](../config/general.md#_5)
`/debug` requires the kernel to be started with the [log level](../config/general.md#log-level) set to `debug`.

### `/debug/gc`

Request Method: `PUT`
Request method: `PUT`

- Perform a manual GC.
- curl example: `curl "${controller-api}/debug/gc" -X PUT`
- Perform active garbage collection.

### `/debug/pprof`

Open `http://${controller-api}/debug/pprof` in a browser to view raw DEBUG information, including:
Open in a browser `http://${controller-api}/debug/pprof` to view raw DEBUG information, where:

- `allocs` shows the memory allocation for each function call, including the size and number of allocations on the stack and heap. This report helps identify memory leaks and frequent memory allocations in the code.
- `heap` report provides detailed information about the program's use of memory on the heap, including the size, quantity, and address of allocated memory blocks, sorted by size. This report is useful for finding places where memory usage is too high. You can view object sizes in the heap report to identify areas of excessive memory usage.
- `allocs` indicates memory allocation for each function call, including the size of memory allocated on the stack and heap, as well as the number of allocations. This report is primarily to help identify memory leaks and frequent memory requests in the code.
- The `heap` report provides detailed information about memory usage on the heap, including the size, number, and address of allocated memory blocks, sorted by size. This report is mainly to locate areas of excessive memory usage; we can check object sizes in the heap report to find areas of high memory consumption.

#### Install [Graphviz](https://graphviz.org/download/) to view graphical debug information
#### Install [Graphviz](https://graphviz.org/download/) to view graphical debug information.

##### View Graphical Heap Report

Expand All @@ -243,8 +260,8 @@ go tool pprof -http=:8080 http://127.0.0.1:xxxx/debug/pprof/heap
go tool pprof -http=:8080 http://127.0.0.1:xxxx/debug/pprof/allocs
```

[Example output](../assets/image/api/allocs.svg)
[Sample output](../assets/image/api/allocs.svg)

##### Submit Output Report

Access `http://${controller-api}/debug/pprof/heap?raw=true` in your browser to download the file and submit any issues you encounter by uploading it to [issues](https://github.com/MetaCubeX/Clash.Meta/issues).
Access `http://${controller-api}/debug/pprof/heap?raw=true` in a browser to download this file, and upload it to [issues](https://github.com/MetaCubeX/Clash.Meta/issues) to report any problems you encounter.
16 changes: 16 additions & 0 deletions docs/config/dns/hosts.en.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# hosts

```{.yaml linenums="1"}
hosts:
'*.clash.dev': 127.0.0.1
'alpha.clash.dev': '::1'
test.com: [1.1.1.1, 2.2.2.2]
baidu.com: google.com
```

Keys support [domain wildcards](../../handbook/syntax.md#domain-wildcards).

Values support strings/arrays; domain redirection does not support arrays.

!!! note
A complete domain takes precedence over domains using wildcards, for example: foo.example.com > *.example.com > .example.com.
Loading

0 comments on commit cbc1598

Please sign in to comment.