diff --git a/docs/document/command.md b/docs/document/command.md index 6abcb2ed..a5c3d76d 100644 --- a/docs/document/command.md +++ b/docs/document/command.md @@ -8,7 +8,7 @@ Xray 使用 Go 风格的命令及参数 您可以运行 `xray help` 来获得所有 xray 最基础的用法, 以及可用的命令及说明。 -``` +```bash Xray is a platform for building proxies. Usage: @@ -38,11 +38,11 @@ Use "xray help " for more information about a command. 使用方法: -``` - xray run [-c config.json] [-confdir dir] +```bash +xray run [-c config.json] [-confdir dir] ``` -``` +```bash Run Xray with config, the default command. The -config=file, -c=file flags set the config files for @@ -59,15 +59,53 @@ without launching the server. The -dump flag tells Xray to print the merged config. ``` -`-config=` / `-c=` 用于指定使用的配置文件的位置,支持多文件配置。 -`-confdir=` 用于指定一个包含多个配置文件的文件夹。 -`-format=` 用于指定使用的配置文件的格式。 -`-test` 用于测试配置文件的合法性。 -`-dump` 用于显示多文件配置文件合并之后的效果。 +- `-config=` / `-c=` 用于指定使用的配置文件的位置。 +- `-confdir=` 用于指定一个含多个配置文件的文件夹,该目录下的所有配置文件会[自动合并](/config/features/multiple.md)。 +- `-format=` 用于指定使用的配置文件的格式。 +- `-test` 用于测试配置文件的合法性。 +- `-dump` 用于显示多文件配置文件合并之后的效果。 + ::: tip 配置文件除了默认的 JSON 格式外,也可以使用 TOML 和 YAML。在不指定格式的前提下会通过文件扩展名识别。 ::: +:::: tip +`-config=` / `-c=` 不仅支持本地文件路径,也支持标准输入和远程地址。 + +::: details 展开查看 `-config` 支持的形式与示例 +`-config=` 可重复使用,以指定多个配置源。例如: + +```bash +xray run -config base.json -config routing.json -config outbounds.yaml +``` + +Xray 会按参数顺序读取这些配置文件,并[自动合并](/config/features/multiple.md)为最终配置。 + +除了常见的本地文件绝对路径、相对路径外,还支持以下形式: + +- `stdin:`:从标准输入读取配置内容。适合配合管道、重定向或由上层程序动态生成配置时使用。输入完成后,调用者必须关闭标准输入流,否则 Xray 会继续等待输入结束。 +- 以 `http://` 或 `https://` 开头的 URL:从远程地址下载配置内容。协议名前缀必须使用小写。**此方式存在安全风险,除非你明确知道自己在做什么,否则不要轻易使用。** +- `http+unix://`:通过 Unix Domain Socket 发起 HTTP 请求并读取配置,格式形如 `http+unix:///path/to/socket.sock/api/endpoint`。适合配置由本机某个仅监听 Unix Socket 的服务动态提供时使用。 + +示例: + +```bash +# 从本地文件读取 +xray run -config ./config.json + +# 从标准输入读取 +cat config.json | xray run -config stdin: + +# 从远程地址读取 +xray run -config https://example.com/xray/config.json + +# 通过 Unix Domain Socket 对应的 HTTP 接口读取 +xray run -config http+unix:///run/xray-config.sock/config.json +``` + +::: +:::: + ::: tip 当 `-config` 没有指定时,Xray 将先后尝试从以下路径加载 `config.json` : @@ -75,8 +113,8 @@ The -dump flag tells Xray to print the merged config. - [环境变量](../config/features/env.md#资源文件路径)中 `Xray.location.asset` 所指定的路径 ::: -``` - xray run -dump +```bash +xray run -dump ``` 用以输出多文件配置融合之后的结果。 @@ -87,8 +125,8 @@ The -dump flag tells Xray to print the merged config. 使用方法: -``` - xray version +```bash +xray version ``` ### xray api @@ -97,11 +135,11 @@ The -dump flag tells Xray to print the merged config. 使用方法: -``` +```bash xray api [arguments] ``` -``` +```bash restartlogger Restart the logger stats Get statistics statsquery Query statistics @@ -118,7 +156,7 @@ xray api [arguments] 使用方法: -``` +```bash xray convert [arguments] The commands are: @@ -173,11 +211,11 @@ xray help convert json 使用方法: -``` +```bash xray tls [arguments] ``` -``` +```bash cert Generate TLS certificates ping Ping the domain with TLS handshake certChainHash Calculate TLS certificates hash. @@ -189,7 +227,7 @@ xray tls [arguments] 使用方法: -``` +```bash xray uuid [-i "example"] ``` @@ -199,7 +237,7 @@ xray uuid [-i "example"] 使用方法: -``` +```bash xray x25519 [-i "(base64.RawURLEncoding)" --std-encoding ] ``` @@ -209,7 +247,7 @@ xray x25519 [-i "(base64.RawURLEncoding)" --std-encoding ] 使用方法: -``` +```bash xray wg [-i "(base64.StdEncoding)"] ``` @@ -226,7 +264,7 @@ xray wg [-i "(base64.StdEncoding)"] 使用方法: -``` +```bash xray mldsa65 [-i "seed (base64.StdEncoding)"] ``` @@ -236,7 +274,7 @@ xray mldsa65 [-i "seed (base64.StdEncoding)"] 使用方法: -``` +```bash xray mlkem768 [-i "seed (base64.StdEncoding)"] ``` @@ -246,6 +284,6 @@ xray mlkem768 [-i "seed (base64.StdEncoding)"] 使用方法: -``` +```bash xray vlessenc ``` diff --git a/docs/en/document/command.md b/docs/en/document/command.md index f1faa7f5..1489d2d7 100644 --- a/docs/en/document/command.md +++ b/docs/en/document/command.md @@ -8,7 +8,7 @@ Xray uses Go-style commands and parameters. You can run `xray help` to get the most basic usage of Xray, as well as available commands and descriptions. -``` +```bash Xray is a platform for building proxies. Usage: @@ -38,11 +38,11 @@ Specify one or more configuration files and run. Usage: -``` - xray run [-c config.json] [-confdir dir] +```bash +xray run [-c config.json] [-confdir dir] ``` -``` +```bash Run Xray with config, the default command. The -config=file, -c=file flags set the config files for @@ -59,16 +59,53 @@ without launching the server. The -dump flag tells Xray to print the merged config. ``` -`-config=` / `-c=` are used to specify the location of the configuration file(s) to use. Supports multi-file configuration. -`-confdir=` is used to specify a folder containing multiple configuration files. -`-format=` is used to specify the format of the configuration files. -`-test` is used to test the validity of the configuration files. -`-dump` is used to display the result after merging multiple configuration files. +- `-config=` / `-c=` are used to specify the location of the configuration file(s) to use. +- `-confdir=` is used to specify a folder containing multiple configuration files. All configuration files in that directory will be [merged automatically](/en/config/features/multiple.md). +- `-format=` is used to specify the format of the configuration files. +- `-test` is used to test the validity of the configuration files. +- `-dump` is used to display the result after merging multiple configuration files. ::: tip In addition to the default JSON format, configuration files can also use TOML and YAML. If no format is specified, it will be identified by the file extension. ::: +:::: tip +`-config=` / `-c=` supports not only local file paths, but also standard input and remote URLs. + +::: details Expand to view supported `-config` forms and examples +`-config=` can be repeated to specify multiple configuration sources. For example: + +```bash +xray run -config base.json -config routing.json -config outbounds.yaml +``` + +Xray reads these configuration files in argument order and [merges them automatically](/en/config/features/multiple.md) into the final configuration. + +In addition to common local absolute and relative file paths, the following forms are also supported: + +- `stdin:`: Read configuration content from standard input. This is useful when piping, redirecting, or generating configuration dynamically from another program. After the input is complete, the caller must close the standard input stream, otherwise Xray will continue waiting for the end of input. +- URLs starting with `http://` or `https://`: Download configuration content from a remote address. The protocol prefix must be lowercase. **This method carries security risks. Do not use it unless you clearly know what you are doing.** +- `http+unix://`: Read configuration over an HTTP request sent through a Unix Domain Socket, in a form such as `http+unix:///path/to/socket.sock/api/endpoint`. This is useful when configuration is provided dynamically by a local service that only listens on a Unix socket. + +Examples: + +```bash +# Read from a local file +xray run -config ./config.json + +# Read from standard input +cat config.json | xray run -config stdin: + +# Read from a remote URL +xray run -config https://example.com/xray/config.json + +# Read through an HTTP endpoint on a Unix Domain Socket +xray run -config http+unix:///run/xray-config.sock/config.json +``` + +::: +:::: + ::: tip When `-config` is not specified, Xray will attempt to load `config.json` from the following paths in order: @@ -76,8 +113,8 @@ When `-config` is not specified, Xray will attempt to load `config.json` from th - The path specified by `Xray.location.asset` in [Environment Variables](../config/features/env.md#resource-file-path) ::: -``` - xray run -dump +```bash +xray run -dump ``` Used to output the result after merging multi-file configurations. @@ -88,8 +125,8 @@ Output Xray version, Golang version, and other information. Usage: -``` - xray version +```bash +xray version ``` ### xray api @@ -98,11 +135,11 @@ Call Xray's gRPC API. Needs to be enabled in the configuration file. Usage: -``` +```bash xray api [arguments] ``` -``` +```bash restartlogger Restart the logger stats Get statistics statsquery Query statistics @@ -119,7 +156,7 @@ Convert configuration files to protobuf or convert typedMessage to JSON. Usage: -``` +```bash xray convert [arguments] The commands are: @@ -174,11 +211,11 @@ Some tools related to TLS. Usage: -``` +```bash xray tls [arguments] ``` -``` +```bash cert Generate TLS certificates ping Ping the domain with TLS handshake certChainHash Calculate TLS certificates hash. @@ -190,7 +227,7 @@ Generate UUID. Usage: -``` +```bash xray uuid [-i "example"] ``` @@ -200,7 +237,7 @@ Generate x25519 key pair. Usage: -``` +```bash xray x25519 [-i "(base64.RawURLEncoding)" --std-encoding ] ``` @@ -210,7 +247,7 @@ Generate WireGuard curve25519 key pair. Usage: -``` +```bash xray wg [-i "(base64.StdEncoding)"] ``` @@ -227,7 +264,7 @@ Generate MLDSA-65 post-quantum signature key pair for REALITY. Usage: -``` +```bash xray mldsa65 [-i "seed (base64.StdEncoding)"] ``` @@ -237,7 +274,7 @@ Generate ML-KEM-768 post-quantum key exchange key pair for VLESS Encryption. Usage: -``` +```bash xray mlkem768 [-i "seed (base64.StdEncoding)"] ``` @@ -247,6 +284,6 @@ Generate encryption/decryption option content that can be directly used for VLES Usage: -``` +```bash xray vlessenc ``` diff --git a/docs/ru/document/command.md b/docs/ru/document/command.md index 70bf85ae..a7bf7a45 100644 --- a/docs/ru/document/command.md +++ b/docs/ru/document/command.md @@ -8,7 +8,7 @@ Xray использует команды и аргументы в стиле Go. Вы можете запустить `xray help`, чтобы получить список всех базовых команд Xray, а также их описание и примеры использования. -``` +```bash Xray is a platform for building proxies. Usage: @@ -38,11 +38,11 @@ Use "xray help " for more information about a command. Использование: -``` - xray run [-c config.json] [-confdir dir] +```bash +xray run [-c config.json] [-confdir dir] ``` -``` +```bash Run Xray with config, the default command. The -config=file, -c=file flags set the config files for @@ -59,16 +59,53 @@ without launching the server. The -dump flag tells Xray to print the merged config. ``` -`-config=` / `-c=`: Указывает путь к файлу конфигурации, поддерживается использование нескольких файлов. -`-confdir=`: Указывает путь к папке, содержащей несколько файлов конфигурации. -`-format=`: Задает формат файлов конфигурации. -`-test`: Проверяет корректность файлов конфигурации. -`-dump`: Выводит объединенный результат слияния нескольких файлов конфигурации. +- `-config=` / `-c=`: Указывает расположение используемого файла конфигурации. +- `-confdir=`: Указывает путь к папке, содержащей несколько файлов конфигурации. Все файлы конфигурации в этом каталоге будут [объединены автоматически](/ru/config/features/multiple.md). +- `-format=`: Задает формат файлов конфигурации. +- `-test`: Проверяет корректность файлов конфигурации. +- `-dump`: Выводит объединенный результат слияния нескольких файлов конфигурации. ::: tip Помимо формата JSON по умолчанию, файлы конфигурации также могут быть в формате TOML или YAML. Если формат не указан явно, он определяется по расширению файла. ::: +:::: tip +`-config=` / `-c=` поддерживает не только локальные пути к файлам, но и стандартный ввод, а также удаленные адреса. + +::: details Разверните, чтобы посмотреть поддерживаемые формы `-config` и примеры +`-config=` можно указывать несколько раз, чтобы задать несколько источников конфигурации. Например: + +```bash +xray run -config base.json -config routing.json -config outbounds.yaml +``` + +Xray прочитает эти файлы конфигурации в порядке аргументов и [автоматически объединит их](/ru/config/features/multiple.md) в итоговую конфигурацию. + +Помимо обычных абсолютных и относительных путей к локальным файлам, поддерживаются и следующие формы: + +- `stdin:`: Чтение содержимого конфигурации из стандартного ввода. Это удобно при использовании конвейеров, перенаправления или когда конфигурация динамически генерируется другой программой. После завершения ввода вызывающая сторона должна закрыть поток стандартного ввода, иначе Xray продолжит ждать окончания ввода. +- URL, начинающиеся с `http://` или `https://`: Загрузка содержимого конфигурации с удаленного адреса. Префикс протокола должен быть записан строчными буквами. **Этот способ связан с рисками безопасности. Не используйте его, если вы не вполне понимаете, что делаете.** +- `http+unix://`: Чтение конфигурации через HTTP-запрос, отправленный через Unix Domain Socket, в формате вроде `http+unix:///path/to/socket.sock/api/endpoint`. Это удобно, если конфигурация динамически выдается локальным сервисом, который слушает только Unix-сокет. + +Примеры: + +```bash +# Чтение из локального файла +xray run -config ./config.json + +# Чтение из стандартного ввода +cat config.json | xray run -config stdin: + +# Чтение с удаленного адреса +xray run -config https://example.com/xray/config.json + +# Чтение через HTTP-эндпоинт на Unix Domain Socket +xray run -config http+unix:///run/xray-config.sock/config.json +``` + +::: +:::: + ::: tip Когда `-config` не указан, Xray последовательно попытается загрузить `config.json` из следующих путей: @@ -76,8 +113,8 @@ The -dump flag tells Xray to print the merged config. - Путь, указанный в переменной окружения `Xray.location.asset` в [переменных окружения](../config/features/env.md#Путь-к-файлам-ресурсов) ::: -``` - xray run -dump +```bash +xray run -dump ``` Выводит результат слияния нескольких файлов конфигурации. @@ -88,8 +125,8 @@ The -dump flag tells Xray to print the merged config. Использование: -``` - xray version +```bash +xray version ``` ### xray api @@ -98,11 +135,11 @@ The -dump flag tells Xray to print the merged config. Использование: -``` +```bash xray api [arguments] ``` -``` +```bash restartlogger Restart the logger stats Get statistics statsquery Query statistics @@ -119,7 +156,7 @@ Convert config to protobuf, or convert typedMessage to JSON usage: -``` +```bash xray convert [arguments] The commands are: @@ -174,11 +211,11 @@ xray help convert json Использование: -``` +```bash xray tls [arguments] ``` -``` +```bash cert Generate TLS certificates ping Ping the domain with TLS handshake certChainHash Calculate TLS certificates hash. @@ -190,7 +227,7 @@ xray tls [arguments] Использование: -``` +```bash xray uuid [-i "example"] ``` @@ -200,7 +237,7 @@ xray uuid [-i "example"] Использование: -``` +```bash xray x25519 [-i "(base64.RawURLEncoding)" --std-encoding ] ``` @@ -210,7 +247,7 @@ xray x25519 [-i "(base64.RawURLEncoding)" --std-encoding ] Использование: -``` +```bash xray wg [-i "(base64.StdEncoding)"] ``` @@ -227,7 +264,7 @@ xray wg [-i "(base64.StdEncoding)"] Использование: -``` +```bash xray mldsa65 [-i "seed (base64.StdEncoding)"] ``` @@ -237,7 +274,7 @@ xray mldsa65 [-i "seed (base64.StdEncoding)"] Использование: -``` +```bash xray mlkem768 [-i "seed (base64.StdEncoding)"] ``` @@ -247,6 +284,6 @@ xray mlkem768 [-i "seed (base64.StdEncoding)"] Использование: -``` +```bash xray vlessenc ```