purgatory/Xray-docs-next
1
0
Fork 0
mirror of https://github.com/XTLS/Xray-docs-next.git synced 2025-04-05 14:23:34 +03:00
Code Issues Projects Releases Packages Wiki Activity

Translate dev into English

Browse source
This commit is contained in:
Kevin Amiri 2023-04-15 13:47:55 +02:00
parent bb959756e1
commit 546df9549b
8 changed files with 473 additions and 477 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

42
docs/en/development/README.md
View file

@ -1,41 +1,41 @@
# 开发指南
# Development Guide
## 编译文档
## Compile Documentation
Xray 支持各种平台, 您可以在多种平台上自行进行交叉编译。
Xray supports multiple platforms, and you can perform cross-compilation on various platforms by yourself.
请点击[编译文档](./intro/compile.md)以查看具体编译相关内容。
Please click [Compile Documentation](./intro/compile.md) to view specific compile-related content.
## 设计思路
## Design Concept
Xray 内核提供了一个平台，在其之上可以进二次开发。
Xray kernel provides a platform for secondary development.
这个章节阐述了 Xray 的设计目标和架构。
This section explains the design goals and architecture of Xray.
请点击[设计思路](./intro/design.md)以了解 Xray 的设计目标和架构。
Please click [Design Principles](./intro/design.md) to learn about the design goals and architecture of Xray.
## 开发规范
## Development Standards
这个章节阐述了获取代码,进行开发,提交 PR 的流程中需要遵循的准则, 以及相关的编码规范。
This section outlines the guidelines to follow when obtaining code, developing, submitting PRs, as well as the relevant coding standards.
请点击[开发规范](./intro/guide.md)查看 Xray 开发中应遵循的准则。
Please click [Development Specification](./intro/guide.md) to view the guidelines that should be followed during Xray development.
## 协议详解
## Protocol Details
Xray 用到了很多种协议, 您可以通过各种途径获得协议的详细描述。
Xray uses many protocols, and you can obtain a detailed description of each protocol through various means.
### [VLESS 协议](./protocols/vless.md)
### [VLESS Protocol](./protocols/vless.md)
VLESS 是一个无状态的轻量传输协议，可以作为 Xray 客户端和服务器之间的桥梁。
VLESS is a stateless lightweight transport protocol that can serve as a bridge between Xray clients and servers.
### [VMess 协议](./protocols/vmess.md)
### [VMess Protocol](./protocols/vmess.md)
VMess 是一个加密传输协议，可以作为 Xray 客户端和服务器之间的桥梁。
VMess is an encrypted transport protocol that can act as a bridge between Xray clients and servers.
### [Mux.Cool 协议](./protocols/muxcool.md)
### [Mux.Cool Protocol](./protocols/muxcool.md)
Mux.Cool 协议是一个多路复用传输协议，用于在一条已建立的数据流中传输多个各自独立的数据流。
Mux.Cool protocol is a multiplexing transport protocol used to transmit multiple independent data streams within an established data stream.
### [mKCP 协议](./protocols/mkcp.md)
### [mKCP Protocol](./protocols/mkcp.md)
mKCP 是流式传输协议，由 [KCP 协议](https://github.com/skywind3000/kcp)修改而来，可以按顺序传输任意的数据流。
mKCP is a stream transmission protocol modified from the [KCP protocol](https://github.com/skywind3000/kcp) that can transmit arbitrary data streams in order.

51
docs/en/development/intro/compile.md
View file

@ -1,34 +1,34 @@
# 编译文档
# Compile the document
## 前序工作
## Preparatory Work
Xray 使用 [Golang](https://golang.org/) 作为编程语言，你需要先安装最新版本 Golang 才能够编译。
Xray uses [Golang](https://golang.org/) as its programming language, so you need to install the latest version of Golang first in order to compile.
::: tip TIP
安装 Golang: [golang.org/doc/install](https://golang.org/doc/install)
Install Golang: [golang.org/doc/install](https://golang.org/doc/install)
:::
> 如果你不幸使用 Windows, 请 **务必** 使用 Powershell
If you happen to use Windows, please **make sure** to use Powershell.
## 拉取 Xray 源代码
## Pull Xray source code
```bash
git clone https://github.com/XTLS/Xray-core.git
cd Xray-core && go mod download
```
> 如果你闲的没事干，可以试试 GitHub 官方工具: `gh repo clone XTLS/Xray-core`
If you have free time, you can try GitHub's official tool: `gh repo clone XTLS/Xray-core`
注意：在无法正常访问 Google 的网络环境，依赖无法被正常拉取，需要先设置 `GOPROXY`：
Note: In a network environment where Google cannot be accessed normally, dependencies cannot be pulled normally, and `GOPROXY` needs to be set first:
```bash
go env -w GOPROXY=https://goproxy.io,direct
```
## 构建二进制
## Build Binary
:::warning
本小节的命令需要在 Xray 根目录内运行。
This command needs to be executed within Xray root directory.
:::
### Windows(Powershell):
@ -44,38 +44,37 @@ go build -o xray.exe -trimpath -ldflags "-s -w -buildid=" ./main
CGO_ENABLED=0 go build -o xray -trimpath -ldflags "-s -w -buildid=" ./main
```
运行以上命令会在目录下生成 xray 可执行文件。
Running the above command will generate an xray executable file in the directory.
::: tip
如果需要编译可以进行 debug 的程序,即可以用 dlv 附加到运行的程序进行调试, 请去掉 ldflags 中的 '-w -s' 选项.
If you need to compile a program that can be debugged, i.e., you can use dlv to attach to the running program for debugging, please remove the '-w -s' options from the ldflags.
-w 禁止生成 debug 信息。使用该选项后，将无法使用 gdb 进行调试。
-s 禁用符号表
PS:其实用 vscode 或其他 IDE 调试似乎更方便。
:::
- w option disables the generation of debug information. After using this option, gdb cannot be used for debugging.
- s option disables the symbol table.
PS: Actually, debugging with vscode or other IDEs seems to be more convenient.
## 交叉编译：
## Cross compilation:
这里以在 Windows(Powershell) 环境中，编译到 Linux 服务器为例：
Here, we take the example of compiling to a Linux server in a Windows (Powershell) environment:
```powershell
$env:CGO_ENABLED=0
$env:GOOS="linux"
$env:GOARCH="amd64"
go build -o xray -trimpath -ldflags "-s -w -buildid=" ./main
```
上传到服务器后，记得在服务器终端内执行 `chmod +x xray`
go build -o xray -trimpath -ldflags "-s -w -buildid=" ./main```
After uploading to the server, remember to execute `chmod +x xray` in the server terminal.
::: tip
执行 `go tool dist list` 查看所有支持的系统与架构。
Execute `go tool dist list` to view all supported systems and architectures.
:::
## 可复现构建：
## Reproducible Build:
按照上述步骤，能够编译与 Release 中完全相同的二进制文件。
Following the above steps, it is possible to compile and release an identical binary file as the one in Release.
::: warning
请先确认您使用的 Golang 版本与编译 Release 的一致。
:::
Please confirm that you are using the same Golang version as the one used to compile the release.
:::

46
docs/en/development/intro/design.md
View file

@ -1,43 +1,43 @@
# 设计目标
# Design Objectives
- Xray 内核提供了一个平台，支持必要的网络代理功能，在其之上可以进二次开发，以提供更好的用户体验；
- 以跨平台为首要原则，以减少二次开发的成本；
- Xray Kernel provides a platform that supports essential network proxy functions and can be developed upon to provide a better user experience.
- Cross-platform is the primary principle to reduce the cost of secondary development.
## 架构
## Architecture
![Architecture](./framework.png)
内核分为三层：应用层、代理层和传输层。
The kernel is divided into three layers: the application layer, the proxy layer, and the transport layer.
每一层内包含数个模块，模块间互相独立，同类型的模块可无缝替换。
Each layer contains several modules, which are independent of each other. Modules of the same type can be seamlessly replaced.
### 应用层
### Application Layer
应用层包含一些代理层中常用的功能，这些功能被抽象出来，以便在不同的代理模块中复用。
The application layer contains some commonly used functions in proxy layers, which are abstracted for reuse in different proxy modules.
应用层的模块应为纯软件实现，与硬件或平台相关的技术无关。
The modules at the application layer should be implemented purely in software and should not be dependent on hardware or platform-related technologies.
重要模块列表：
List of Important Modules:
- Dispatcher: 用于把入站代理所接收到的数据，传送给出站代理；
- Router: 路由模块，详见 [路由配置](../../config/routing.md)；
- DNS: 内置的 DNS 服务器模块；
- Proxy Manager: 代理管理器；
- Dispatcher: Used to transfer data received by the inbound agent to the outbound agent;
- Router: Routing module, see [Routing Configuration](../../config/routing.md) for details;
- DNS: Built-in DNS server module;
- Proxy Manager: Proxy manager;
### 代理层
### Proxy Layer
代理层分为两部分：入站代理（Inbound Proxy）和出站代理（Outbound Proxy）。
The proxy layer is divided into two parts: Inbound Proxy and Outbound Proxy.
两部分相互独立，入站代理不依赖于某个特定的出站代理，反之亦然。
The two parts are independent of each other, where the inbound proxy does not rely on a specific outbound proxy, and vice versa.
#### 入站代理
#### Inbound Proxy
- 实现 [proxy.Inbound](https://github.com/xtls/Xray-core/blob/main/proxy/proxy.go) 接口；
- Implement the [proxy.Inbound](https://github.com/xtls/Xray-core/blob/main/proxy/proxy.go) interface;
#### 出站代理
#### Outbound Proxy
- 实现 [proxy.Outbound](https://github.com/xtls/Xray-core/blob/main/proxy/proxy.go) 接口；
- Implement the [proxy.Outbound](https://github.com/xtls/Xray-core/blob/main/proxy/proxy.go) interface;
### 传输层
### Transport Layer
传输层提供一些网络数据传输相关的工具模块。
The transport layer provides a set of tools and modules related to network data transmission.

164
docs/en/development/intro/guide.md
View file

@ -1,131 +1,131 @@
# 开发规范
# Development Standards
## 基本
## Basic
### 版本控制
### Version Control
project X 的代码被托管在 github 上:
Project X's code is hosted on GitHub:
- xray 核心 [xray-core](https://github.com/XTLS/Xray-core)
- 安装脚本 [Xray-install](https://github.com/XTLS/Xray-install)
- 配置模板 [Xray-examples](https://github.com/XTLS/Xray-examples)
- xray 文档 [Xray-docs-next](https://github.com/XTLS/Xray-docs-next)
- Xray Core [xray-core](https://github.com/XTLS/Xray-core)
- Installation script [Xray-install](https://github.com/XTLS/Xray-install)
- Configuration template [Xray-examples](https://github.com/XTLS/Xray-examples)
- Xray documentation [Xray-docs-next](https://github.com/XTLS/Xray-docs-next)
您可以使用 [Git](https://git-scm.com/) 来获取代码。
You can use [Git](https://git-scm.com/) to get the code.
### 分支（Branch）
### Branch
- 本项目的主干分支为 main，
- 本项目的发布主分支同为 main，
- 需要确保 main 在任一时刻都是可编译，且可正常使用的。
- 如果需要开发新的功能，请新建分支进行开发，在开发完成并且经过充分测试后，合并回主干分支。
- 已经合并入主干且没有必要存在的分支，请删除。
- The main branch is the backbone of this project.
- The main branch is also the release branch of this project.
- It is necessary to ensure that main can be compiled and used normally at any time.
- If you need to develop new features, please create a new branch for development. After development and sufficient testing, merge it back to the main branch.
- Please delete branches that have been merged into the main branch and are no longer necessary.
### 发布（Release）
### Release
<Badge text="WIP" type="warning"/>
<Badge text="WIP" type="warning"/> (Note: this is not translatable as it is a technical tag)
- 建立尝鲜版本和稳定版本两个发布通道
- 尝鲜版本，可以为 daily build，主要用于特定情况的测试，尝鲜和获得即时反馈和再改进。
- 稳定版本，为定时更新(比如月更)，合并稳定的修改并发布。
- Create two release channels: one for the beta version and another for the stable version.
- The beta version, also known as the daily build, is mainly used for specific testing, experimentation, and instant feedback and improvement.
- The stable version, updated regularly (e.g. monthly), merges stable modifications and releases them.
### 引用其它项目
### Citing other projects
- Golang
- 产品代码建议使用 Golang 标准库和 [golang.org/x/](https://pkg.go.dev/search?q=golang.org%2Fx) 下的库；
- 如需引用其它项目，请事先创建 issue 讨论；
- 其它
- 不违反双方的协议，且对项目有帮助的工具，都可以使用。
- It is recommended to use the Golang standard library and libraries under [golang.org/x/](https://pkg.go.dev/search?q=golang.org%2Fx) for product code;
- If you need to reference other projects, please create an issue for discussion beforehand;
- Other
- Tools that do not violate the agreement of both parties and are helpful to the project can be used.
## 开发流程
## Development Process
### 写代码之前
### Before Writing Code
发现任何问题，或对项目有任何想法，请创建 [issue](https://github.com/XTLS/Xray-core/issues) 讨论以减少重复劳动和消耗在代码上的时间。
If you encounter any issues or have any ideas for the project, please create an [issue](https://github.com/XTLS/Xray-core/issues) for discussion to reduce redundant work and save time spent on coding.
### 修改代码
### Modify the code
- Golang
- 请参考 [Effective Go](https://golang.org/doc/effective_go.html)；
- 每一次 push 之前，请运行：`go generate core/format.go`；
- 如果需要修改 protobuf，例如增加新配置项，请运行：`go generate core/proto.go`；
- 提交 pull request 之前，建议测试通过：`go test ./...`；
- 提交 pull request 之前，建议新增代码有超过 70% 的代码覆盖率（code coverage）；
- 其它
- 请注意代码的可读性。
- Please refer to [Effective Go](https://golang.org/doc/effective_go.html);
- Run `go generate core/format.go` before each push;
- If you need to modify protobuf, such as adding new configuration items, please run: `go generate core/proto.go`;
- It is recommended to pass the test before submitting a pull request: `go test ./...`;
- It is recommended to have more than 70% code coverage for newly added code before submitting pull requests.
- Other
- Please pay attention to the readability of the code.
### Pull Request
- 提交 PR 之前，请先运行 `git pull https://github.com/xray/xray-core.git` 以确保 merge 可顺利进行；
- 一个 PR 只做一件事，如有对多个 bug 的修复，请对每一个 bug 提交一个 PR；
- 由于 Golang 的特殊需求（Package path），Go 项目的 PR 流程和其它项目有所不同，建议流程如下：
1. 先 Fork 本项目，创建你自己的 `github.com/<your_name>/Xray-core.git` 仓库；
2. 克隆你自己的 Xray 仓库到本地：`git clone https://github.com/<your_name>/Xray-core.git`；
3. 基于 `main` 分支创建新的分支，例如 `git branch issue24 main`；
4. 在新创建的分支上作修改并提交修改(commit)；
5. 在推送(push)修改完成的分支到自己的仓库前，先切换到 `main` 分支，运行 `git pull https://github.com/xray/xray-core.git` 拉取最新的远端代码；
6. 如果上一步拉取得到了新的远端代码，则切换到之前自己创建的分支，运行 `git rebase main` 执行分支合并操作。如遇到文件冲突，则需要解决冲突；
7. 上一步处理完毕后，就可以把自己创建的分支推送到自己的仓库：`git push -u origin your-branch`
8. 最后，把自己仓库的新推送的分支往 `xtls/Xray-core` 的 `main` 分支发 PR 即可；
9. 请在 PR 的标题和正文中，完整表述此次 PR 解决的问题 / 新增的功能 / 代码所做的修改的用意等；
10. 耐心等待开发者的回应。
- Before submitting a PR, please run `git pull https://github.com/xray/xray-core.git` to ensure that the merge can proceed smoothly;
- One PR only does one thing. If there are fixes for multiple bugs, please submit a PR for each bug;
- Due to Golang's special requirements (Package path), the PR process for Go projects is different from other projects. The recommended process is as follows:
1. Fork this project first and create your own `github.com/<your_name>/Xray-core.git` repository;
2. Clone your own Xray repository to your local machine: `git clone https://github.com/<your_name>/Xray-core.git`;
3. Create a new branch based on the `main` branch, for example `git branch issue24 main`;
4. Make changes on the new branch and commit the changes;
5. Before pushing the modified branch to your own repository, switch to the `main` branch, and run `git pull https://github.com/xray/xray-core.git` to pull the latest remote code;
6. If new remote code is obtained in the previous step, switch to the branch you created earlier and run `git rebase main` to perform branch merging. If there is a file conflict, you need to resolve the conflict;
7. After the previous step is completed, you can push the branch you created to your own repository: `git push -u origin your-branch`
8. Finally, send a PR from your new pushed branch in your own repository to the `main` branch of `xtls/Xray-core`;
9. Please fully describe the purpose of this PR, including the problem solved, the new feature added, or the modifications made in the title and body of the PR;
10. Please be patient and wait for the developer's response.
### 对代码的修改
### Modifying Code
#### 功能性问题
#### Functional issue
请提交至少一个测试用例（Test Case）来验证对现有功能的改动。
Please submit at least one test case to verify changes to existing functionality.
#### 性能相关
#### Performance Related
请提交必要的测试数据来证明现有代码的性能缺陷，或是新增代码的性能提升。
Please provide the necessary test data to demonstrate performance issues in existing code or performance improvements in new code.
#### 新功能
#### New Feature
- 如果新增功能对已有功能不影响，请提供可以开启/关闭的开关（如 flag），并使新功能保持默认关闭的状态；
- 大型新功能（比如增加一个新的协议）开发之前，请先提交一个 issue，讨论完毕之后再进行开发。
- If the new feature does not affect the existing functionality, please provide a toggle (such as a flag) that can be turned on/off, and keep the new feature disabled by default.
- For major new features (such as adding a new protocol), please submit an issue for discussion before development.
#### 其它
#### Other
视具体情况而定。
It depends on the specific situation.
## Xray 编码规范
## Xray Coding Guidelines
以下内容适用于 Xray 中的 Golang 代码。
The following content is applicable to Golang code in Xray.
### 代码结构
### Code Structure
```
Xray-core
├── app // 应用模块
│ ├── router // 路由
├── common // 公用代码
├── proxy // 通讯协议
├── app // Application module
│ ├── router // Router
├── common // Common code
├── proxy // Communication protocol
│ ├── blackhole
│ ├── dokodemo-door
│ ├── freedom
│ ├── socks
│ ├── vmess
├── transport // 传输模块
├── transport // Transport module
```
### 编码规范
### Coding Standards
基本与 Golang 官方所推荐做法一致，有一些例外。写在这里以方便大家熟悉 Golang。
Basic practices are consistent with the recommendations of the official Golang, with a few exceptions. Written here to help everyone familiarize themselves with Golang.
#### 命名
#### Naming
- 文件和目录名尽量使用单个英文单词，比如 hello.go；
- 如果实在没办法，则目录使用连接线／文件名使用下划线连接两个（或多个单词），比如 hello-world/hello_again.go；
- 测试代码使用 \_test.go 结尾；
- 类型使用 Pascal 命名法，比如 ConnectionHandler；
- 对缩写不强制小写，即 HTML 不必写成 Html；
- 公开成员变量也使用 Pascal 命名法；
- 私有成员变量使用 [小驼峰式命名法](https://zh.wikipedia.org/wiki/%E9%A7%9D%E5%B3%B0%E5%BC%8F%E5%A4%A7%E5%B0%8F%E5%AF%AB) ，如 `privateAttribute` ；
- 为了方便重构，方法建议全部使用 Pascal 命名法；
- 完全私有的类型放入 `internal` 。
- Use a single English word for file and directory names, such as hello.go;
- If not possible, use a hyphen for directories / underscore for files to connect two (or more) words, such as hello-world/hello_again.go;
- Use \_test.go to name test code files;
- Use PascalCase for types, such as ConnectionHandler;
- Do not force lowercase for abbreviations, i.e. HTML does not need to be written as Html;
- Use PascalCase for public member variables;
- Use camelCase for private member variables, such as `privateAttribute`;
- For easy refactoring, it is recommended to use PascalCase for all methods;
- Place completely private types in `internal`.
#### 内容组织
#### Content Organization
- 一个文件包含一个主要类型，及其相关的私有函数等；
- 测试相关的文件，如 Mock 等工具类，放入 testing 子目录。
- A file contains a main type and its related private functions;
- Testing-related files, such as Mock tools, should be placed in the testing subdirectory.

126
docs/en/development/protocols/mkcp.md
View file

@ -1,92 +1,92 @@
# mKCP 协议
# mKCP Protocol
mKCP 是流式传输协议，由 [KCP 协议](https://github.com/skywind3000/kcp) 修改而来，可以按顺序传输任意的数据流。
mKCP is a stream transfer protocol, modified from the [KCP protocol](https://github.com/skywind3000/kcp), which can transmit any data stream in order.
## 版本
## Version
mKCP 没有版本号，不保证版本之间兼容性。
mKCP has no version number and does not guarantee compatibility between versions.
## 依赖
## Dependencies
### 底层协议
### Underlying Protocol
mKCP 是一个基于 UDP 的协议，所有通讯使用 UDP 传输。
mKCP is a protocol based on UDP, and all communication uses UDP transmission.
### 函数
### Functions
- fnv: [FNV-1a](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) 哈希函数
- 输入参数为任意长度的字符串；
- 输入出一个 32 位无符号整数；
- fnv: [FNV-1a](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) hash function
- Takes a string of arbitrary length as input parameter;
- Outputs a 32-bit unsigned integer.
## 通讯过程
## Communication Process
1. mKCP 将数据流拆成若干个数据包进行发送。一个数据流有一个唯一标识，用以区分不同的数据流。数据流中的每一个数据包都携带了同样的标识。
1. mKCP 没有握手过程，当收到一个数据包时，根据其携带的数据流的标识来判断是否为新的通话，或是正在进行中的通话。
1. 每一个数据包中包含若干个片段（Segment），片段分为三类：数据（Data）、确认（ACK）、心跳（Ping）。每个片段需要单独处理。
1. mKCP splits data streams into several data packets for transmission. Each data stream has a unique identifier to distinguish it from other data streams. Each data packet in the data stream carries the same identifier.
2. mKCP does not have a handshake process. When receiving a data packet, it determines whether it is a new call or an ongoing call based on the identifier of the data stream it carries.
3. Each data packet contains several segments (Segment), which are divided into three types: data (Data), acknowledgment (ACK), and heartbeat (Ping). Each segment needs to be processed separately.
## 数据格式
## Data Format
### 数据包
### Data Packet
| 4 字节 | 2 字节 | L 字节 |
| ---------- | ---------- | -------- |
| 认证信息 A | 数据长度 L | 片段部分 |
| 4 Bytes | 2 Bytes | L Bytes |
| ------- | ---------- | -------- |
| Auth A | Data Len L | Fragment |
其中：
as which:
- 认证信息 A = fnv(片段部分），big endian；
- 片段部分可能包含多个片段；
- Authentication information A = fnv(fragment), big endian;
- The fragment may contain multiple sections.
### 数据片段
### Data snippet
| 2 字节 | 1 字节 | 1 字节 | 4 字节 | 4 字节 | 4 字节 | 2 字节 | Len 字节 |
| --------- | -------- | -------- | --------- | --------- | ---------------- | -------- | -------- |
| 标识 Conv | 指令 Cmd | 选项 Opt | 时间戳 Ts | 序列号 Sn | 未确认序列号 Una | 长度 Len | 数据 |
| 2 bytes | 1 byte | 1 byte | 4 bytes | 4 bytes | 4 bytes | 2 bytes | Len bytes |
| --------- | -------- | -------- | --------- | -------- | -------------- | -------- | --------- |
| Conv flag | Cmd flag | Opt flag | Timestamp | Sequence | Unacknowledged | Len flag | Data |
其中：
as which:
- 标识 Conv: mKCP 数据流的标识
- 指令 Cmd: 常量 0x01
- 选项 Opt: 可选的值有：
- 0x00: 空选项
- 0x01: 对方已发出所有数据
- 时间戳 Ts: 当前片段从远端发送出来时的时间，big endian
- 序列号 Sn: 该数据片段时数据流中的位置，起始片段的序列号为 0，之后每个新片段按顺序加 1
- 未确认序列号 Una: 远端主机正在发送的，且尚未收到确认的最小的 Sn
- Identifier Conv: Identifier for mKCP data stream
- Command Cmd: Constant 0x01
- Option Opt: Optional values include:
- 0x00: Empty option
- 0x01: Opposite party has sent all data
- Timestamp Ts: Time when the current segment was sent from the remote end, big endian
- Sequence Number Sn: The position of the data segment in the data stream, the sequence number of the starting segment is 0, and each new segment is sequentially added by 1
- Unacknowledged Sequence Number Una: The minimum Sn that the remote host is sending and has not yet received confirmation.
### 确认片段
### Confirmation snippet
| 2 字节 | 1 字节 | 1 字节 | 4 字节 | 4 字节 | 4 字节 | 2 字节 | Len \* 4 字节 |
| --------- | -------- | -------- | -------- | ----------------- | --------- | -------- | -------------- |
| 标识 Conv | 指令 Cmd | 选项 Opt | 窗口 Wnd | 下一接收序列号 Sn | 时间戳 Ts | 长度 Len | 已收到的序列号 |
| 2 bytes | 1 byte | 1 byte | 4 bytes | 4 bytes | 4 bytes | 2 bytes | Len * 4 bytes |
| ------- | ------ | ------ | ------- | --------------- | --------- | ------- | ------------------- |
| Conv ID | Cmd | Opt | Wnd | Next Seq Number | Timestamp | Length | Received Seq Number |
其中：
as which:
- 标识 Conv: mKCP 数据流的标识
- 指令 Cmd: 常量 0x00
- 选项 Opt: 同上
- 窗口 Wnd: 远端主机可以接收的最大序列号
- 下一接收序列号 Sn: 远端主机未收到的数据片段中的最小序列号
- 时间戳 Ts: 远端主机最新收到的数据片段的时间戳，可用于计算延迟
- 已收到的序列号: 每个 4 字节，表示此序列号的数据已经确认收到
- Identifier Conv: Identifier of the mKCP data stream
- Command Cmd: Constant 0x00
- Option Opt: Same as above
- Window Wnd: The maximum sequence number that the remote host can receive
- Next receive sequence number Sn: The smallest sequence number of the data segment that the remote host has not received
- Timestamp Ts: The timestamp of the latest received data segment by the remote host, which can be used to calculate the delay
- Received sequence numbers: Each 4 bytes, indicating that the data of this sequence number has been confirmed received.
注释：
as which:
- 远程主机期待收到序列号 [Sn, Wnd) 范围内的数据
- The remote host expects to receive data within the serial number [Sn, Wnd) range.
### 心跳片段
### Heartbeat Fragments
| 2 字节 | 1 字节 | 1 字节 | 4 字节 | 4 字节 | 4 字节 |
| --------- | -------- | -------- | ---------------- | ----------------- | -------- |
| 标识 Conv | 指令 Cmd | 选项 Opt | 未确认序列号 Una | 下一接收序列号 Sn | 延迟 Rto |
| 2 Bytes | 1 Byte | 1 Byte | 4 Bytes | 4 Bytes | 4 Bytes |
| ------- | ------ | ------ | --------------------- | ------------------- | ------- |
| Conv ID | Cmd | Opt | Unacknowledged Seq No | Next Receive Seq No | Rto |
其中：
as which:
- 标识 Conv: mKCP 数据流的标识
- 指令 Cmd: 可选的值有
- 0x02: 远端主机强行终止会话
- 0x03: 正常心跳
- 选项 Opt: 同上
- 未确认序列号 Una: 同数据片段的 Una
- 下一接收序列号 Sn: 同确认片段的 Sn
- 延迟 Rto: 远端主机自己计算出的延迟
- Identifier Conv: Identifier for the mKCP data stream
- Command Cmd: Optional values include:
- 0x02: Remote host forcibly terminates the session
- 0x03: Normal heartbeat
- Option Opt: Same as above
- Unacknowledged sequence number Una: Same as the Una of the data fragment
- Next receive sequence number Sn: Same as the Sn of the acknowledgement fragment
- Delay Rto: Delay calculated by the remote host itself

152
docs/en/development/protocols/muxcool.md
View file

@ -1,119 +1,117 @@
# Mux.Cool 协议
# Mux.Cool Protocol
Mux.Cool 协议是一个多路复用传输协议，用于在一条已建立的数据流中传输多个各自独立的数据流。
Mux.Cool protocol is a multiplexing transport protocol that is used to transmit multiple independent data streams within an established data stream.
## 版本
## Version
当前版本是 1 Beta。
The current version is 1 Beta.
## 依赖
## Dependencies
### 底层协议
### Underlying Protocol
Mux.Cool 必须运行在一个已建立的可靠数据流之上。
Mux.Cool must run on top of a reliable established data stream.
## 通讯过程
## Communication Process
一个 Mux.Cool 连接中可传输若干个子连接，每个子连接有一个独立的 ID 和状态。传输过程由帧（Frame）组成，每一帧用于传输一个特定的子连接的数据。
Within a Mux.Cool connection, multiple sub-connections can be transmitted, each with a unique ID and status. The transmission process consists of frames, with each frame used to transmit data for a specific sub-connection.
### 客户端行为
### Client behavior
当有连接需求时并且没有现有可用的连接时，客户端向服务器发起一个新连接，以下称为“主连接”。
When there is a need for a connection and there are no existing available connections, the client initiates a new connection to the server, referred to as the "main connection".
1. 一个主连接可用于发送若干个子连接。客户端可自主决定主连接可承载的子连接数量。
1. 对于一个新的子连接，客户端必须发送状态`New`以通知服务器建立子连接，然后使用状态`Keep`来传送数据。
1. 当子连接结束时，客户端发送`End`状态来通知服务器关闭子连接。
1. 客户端可自行决定何时关闭主连接，但必须确定服务器也同时保持连接。
1. 客户端可使用 KeepAlive 状态来避免服务器关闭主连接。
1. One main connection can be used to send several sub-connections. The client can decide independently how many sub-connections the main connection can handle.
2. For a new sub-connection, the client must send the `New` status to notify the server to establish the sub-connection, and then use the `Keep` status to transmit data.
3. When the sub-connection ends, the client sends the `End` status to notify the server to close the sub-connection.
4. The client can decide when to close the main connection, but must ensure that the server also maintains the connection.
5. The client can use the KeepAlive status to prevent the server from closing the main connection.
### 服务器端行为
### Server-side behavior
当服务器端接收到新的子连接时，服务器应当按正常的连接来处理。
When a new sub-connection is received on the server side, the server should handle it as a normal connection.
1. 当收到状态`End`时，服务器端可以关闭对目标地址的上行连接。
1. 在服务器的响应中，必须使用与请求相同的 ID 来传输子连接的数据。
1. 服务器不能使用`New`状态。
1. 服务器可使用 KeepAlive 状态来避免客户端关闭主连接。
1. When the status "End" is received, the server can close the upstream connection to the target address.
2. The same ID used in the request must be used to transfer sub-connection data in the server response.
3. The server cannot use the "New" status.
4. The server can use the KeepAlive status to avoid the client closing the main connection.
## 传输格式
## Data Format
Mux.Cool 使用对称传输格式，即客户端和服务器发送和接收相同格式的数据。
Mux.Cool uses symmetric transmission format, where the client and server send and receive data in the same format.
### 帧格式
### Frame Format
| 2 字节 | L 字节 | X 字节 |
| ------------ | ------ | -------- |
| 元数据长度 L | 元数据 | 额外数据 |
| 2 Bytes | L Bytes | X Bytes |
| ----------------- | -------- | --------------- |
| Metadata Length L | Metadata | Additional Data |
### 元数据
### Metadata
元数据有若干种类型。所有类型的元数据都包含 ID 和 Opt 两项，其含义为：
There are several types of metadata. All types of metadata contain two items, ID and Opt, with the following meanings:
- ID: 子连接的唯一标识
- 对于一般 MUX 子链接，ID 由 1 开始累加
- 对于 XUDP，ID 始终为 0
- ID: Unique identifier of the sub-connection
- For general MUX sub-connections, the ID is accumulated starting from 1
- For XUDP, the ID is always 0
- Opt:
- D(0x01): 有额外数据
- D(0x01): Additional data is available
当选项 Opt(D) 开启时，额外数据格式如下：
When option Opt(D) is enabled, the additional data format is as follows:
| 2 字节 | X-2 字节 |
| -------- | -------- |
| 长度 X-2 | 数据 |
| 2 Bytes | X-2 Bytes |
| ---------- | --------- |
| Length X-2 | Data |
### 新建子连接 (New)
### New Sublink (New)
| 2 字节 | 1 字节 | 1 字节 | 1 字节 | 2 字节 | 1 字节 | A 字节 |
| ------ | ------ | -------- | ---------- | ------ | ---------- | ------ |
| ID | 0x01 | 选项 Opt | 网络类型 N | 端口 | 地址类型 T | 地址 A |
| 2 Bytes | 1 Byte | 1 Byte | 1 Byte | 2 Bytes | 1 Byte | A Bytes |
| ------- | ------ | ------ | --------- | ------- | ------ | ------- |
| ID | 0x01 | Option | Network N | Port | Type T | Address |
其中：
where:
- 网络类型 N：
- 0x01：TCP，表示当前子连接的流量应当以 TCP 的方式发送至目标。
- 0x02：UDP，表示当前子连接的流量应当以 UDP 的方式发送至目标。
- 地址类型 T：
- 0x01：IPv4
- 0x02：域名
- 0x03：IPv6
- 地址 A：
- 当 T = 0x01 时，A 为 4 字节 IPv4 地址；
- 当 T = 0x02 时，A 为 1 字节长度（L） + L 字节域名；
- 当 T = 0x03 时，A 为 16 字节 IPv6 地址；
- Network type N:
- 0x01: TCP, indicating that the traffic of the current sub-connection should be sent to the destination in the way of TCP.
- 0x02: UDP, indicating that the traffic of the current sub-connection should be sent to the destination in the way of UDP.
- Address type T:
- 0x01: IPv4
- 0x02: Domain name
- 0x03: IPv6
- Address A:
- When T = 0x01, A is a 4-byte IPv4 address;
- When T = 0x02, A is a 1-byte length (L) + L-byte domain name;
- When T = 0x03, A is a 16-byte IPv6 address;
在新建子连接时，若 Opt(D) 开启，则这一帧所带的数据需要被发往目标主机。
If Opt(D) is enabled when creating a sub-connection, the data carried by this frame needs to be sent to the target host.
### 保持子连接 (Keep)
### Keep sub-connections
| 2 字节 | 1 字节 | 1 字节 |
| ------ | ------ | -------- |
| ID | 0x02 | 选项 Opt |
| 2 Bytes | 1 Byte | 1 Byte |
| ------- | ------ | ------ |
| ID | 0x02 | Option |
在保持子连接时，若 Opt(D) 开启，则这一帧所带的数据需要被发往目标主机。
XUDP 在 Opt(D) 之后加 UDP 地址，格式同新建子链接
If Opt(D) is enabled while maintaining sub-connections, the data carried by this frame needs to be sent to the target host. XUDP adds the UDP address after Opt(D), and the format is the same as creating a new sub-connection.
### 关闭子连接 (End)
### End
| 2 字节 | 1 字节 | 1 字节 |
| ------ | ------ | -------- |
| ID | 0x03 | 选项 Opt |
| 2 Bytes | 1 Byte | 1 Byte |
| ------- | ------ | ------ |
| ID | 0x03 | Option |
在保持子连接时，若 Opt(D) 开启，则这一帧所带的数据需要被发往目标主机。
If Opt(D) is enabled while maintaining sub-connections, the data carried by this frame needs to be sent to the target host.
### 保持连接 (KeepAlive)
### KeepAlive
| 2 字节 | 1 字节 | 1 字节 |
| ------ | ------ | -------- |
| ID | 0x04 | 选项 Opt |
| 2 Bytes | 1 Byte | 1 Byte |
| ------- | ------ | ---------- |
| ID | 0x04 | Option Opt |
在保持连接时:
While staying connected:
- 若 Opt(D) 开启，则这一帧所带的数据必须被丢弃。
- ID 可为随机值。
- If Opt(D) is enabled, the data carried by this frame must be discarded.
- ID can be a random value.
## 应用
## Application
Mux.Cool 协议与底层协议无关，理论上可以使用任何可靠的流式连接来传输 Mux.Cool 的协议数据。
The Mux.Cool protocol is agnostic to the underlying protocol and can theoretically use any reliable streaming connection to transmit Mux.Cool protocol data.
在目标导向的协议如 Shadowsocks 和 VMess 协议中，连接建立时必须包含一个指定的地址。
为了保持兼容性，Mux.Cool 协议指定地址为“v1.mux.cool”。即当主连接的目标地址与之匹配时，则进行 Mux.Cool 方式的转发，否则按传统方式进行转发。（注：这是一个程序内的标记，VMess 和 VLESS 并不会在数据包中发送“v1.mux.cool”地址）
In target-oriented protocols such as Shadowsocks and VMess, a specified address must be included when establishing a connection. To maintain compatibility, the Mux.Cool protocol specifies the address as "v1.mux.cool". When the target address of the main connection matches this address, the Mux.Cool forwarding method is used. Otherwise, forwarding is done in the traditional way. (Note: This is an internal tag in the program, and VMess and VLESS do not send the "v1.mux.cool" address in data packets.)

95
docs/en/development/protocols/vless.md
View file

@ -1,91 +1,90 @@
# VLESS 协议
# VLESS Protocol
VLESS 是一个无状态的轻量传输协议，可以作为 Xray 客户端和服务器之间的桥梁。
VLESS is a stateless lightweight transmission protocol that can be used as a bridge between Xray clients and servers.
## Request & Response
| 1 字节 | 16 字节 | 1 字节 | M 字节 | 1 字节 | 2 字节 | 1 字节 | S 字节 | X 字节 |
| -------- | --------- | -------------- | ----------------- | ------ | ------ | -------- | ------ | -------- |
| 协议版本 | 等价 UUID | 附加信息长度 M | 附加信息 ProtoBuf | 指令 | 端口 | 地址类型 | 地址 | 请求数据 |
| 1 byte | 16 bytes | 1 byte | M bytes | 1 byte | 2 bytes | 1 byte | S bytes | X bytes |
| ---------------- | --------------- | ------------------------------- | ------------------------------- | ----------- | ------- | ------------ | ------- | ------------ |
| Protocol Version | Equivalent UUID | Additional Information Length M | Additional Information ProtoBuf | Instruction | Port | Address Type | Address | Request Data |
| 1 字节 | 1 字节 | N 字节 | Y 字节 |
| ---------------------- | -------------- | ----------------- | -------- |
| 协议版本，与请求的一致 | 附加信息长度 N | 附加信息 ProtoBuf | 响应数据 |
| 1 Byte | 1 Byte | N Bytes | Y Bytes |
| --------------------------------------------- | ---------------------------------- | ---------------------------------- | ------------- |
| Protocol Version, consistent with the request | Length of additional information N | Additional information in ProtoBuf | Response data |
VLESS 早在第二个测试版 ALPHA 2 时就已经是上述结构了（BETA 是第五个测试版）：
VLESS had the aforementioned structure as early as the second alpha test version (ALPHA 2), with BETA being the fifth test version.
> “响应认证”被替换为“协议版本”并移至最前，使 VLESS 可以升级换代，同时消除了生成伪随机数的开销。混淆相关结构被替换为附加信息（ProtoBuf）并前移，赋予协议本身可扩展性，相关开销也极小（[gogo/protobuf](https://github.com/gogo/protobuf)），若无附加信息则无相关开销。
"`Response authentication`" has been replaced with "`Protocol version`" and moved to the front, allowing VLESS to upgrade and eliminate the overhead of generating pseudo-random numbers. The obfuscation-related structure has been replaced with "`Additional information`" (ProtoBuf) and moved forward, giving the protocol itself scalability, with minimal overhead ([gogo/protobuf](https://github.com/gogo/protobuf)). If there is no additional information, there is no relevant overhead.
我一直觉得“响应认证”不是必要的，ALPHA 时为了提升生成随机数的性能，还用 math/rand 替换 crypto/rand，而现在都不需要了。
I have always felt that "Response Authentication" is not necessary. During ALPHA, math/rand was used to improve the performance of generating random numbers instead of crypto/rand, but now it is no longer needed.
“协议版本”不仅能起到“响应认证”的作用，还赋予了 VLESS 无痛升级协议结构的能力，带来无限的可能性。
“协议版本”在测试版本中均为 0，正式版本中为 1，以后若有不兼容的协议结构变更则应升级版本。
The "Protocol Version" not only serves as "Response Authentication", but also gives VLESS the ability to upgrade the protocol structure seamlessly, bringing infinite possibilities. The "Protocol Version" is 0 in the test version and 1 in the official version. If there are any incompatible protocol structural changes in the future, the version should be upgraded.
VLESS 服务端的设计是 switch version，即同时支持所有 VLESS 版本。若需要升级协议版本（可能到不了这一步），推荐的做法是服务端提前一个月支持，一个月后再改客户端。VMess 请求也有协议版本，但它的认证信息在外面，指令部分则高度耦合且有固定加密，导致里面的协议版本毫无意义，服务端也没有进行判断，响应则没有协议版本。Trojan 的协议结构中没有协议版本。
The design of VLESS server is switch version, which supports all VLESS versions at the same time. If you need to upgrade the protocol version (which may not happen), it is recommended that the server support it one month in advance, and then change the client after one month. VMess requests also have protocol versions, but their authentication information is outside, and the instruction part is highly coupled and has fixed encryption, which makes the protocol version meaningless inside. The server does not judge it, and the response does not have a protocol version. Trojan's protocol structure does not have a protocol version.
接下来是 UUID，我本来觉得 16 字节有点长，曾经考虑过缩短它，但后来看到 Trojan 用了 56 个可打印字符（56 字节），就彻底打消了这个念头。服务端每次都要验证 UUID，所以性能也很重要：VLESS 的 Validator 经历了多次重构/升级，相较于 VMess，它十分简洁且耗资源很少，可以同时支持非常多的用户，性能也十分强悍，验证速度极快（sync.Map）。API 动态增删用户则更高效顺滑。
The following is a UUID. I used to think that 16 bytes were a bit long and considered shortening it. However, I later saw that Trojan used 56 printable characters (56 bytes), which completely dispelled this idea. The server needs to verify the UUID every time, so performance is also very important: VLESS's Validator has undergone multiple refactoring/upgrades. Compared with VMess, it is very concise and consumes very few resources. It can support a large number of users at the same time, and its performance is also very strong. The verification speed is extremely fast (sync.Map). API dynamically adds and deletes users, making it more efficient and smooth.
https://github.com/XTLS/Xray-core/issues/158
引入 ProtoBuf 是一个创举，等下会详细讲解。“指令”到“地址”的结构目前与 VMess 完全相同，同样支持 Mux。
Introducing ProtoBuf is an innovation, which will be explained in detail later. The structure from "instruction" to "address" is currently identical to VMess and also supports Mux.
总体上，ALPHA 2 到 BETA 主要是：结构进化、清理整合、性能提升、更加完善。这些都是一点一滴的，详见 [VLESS Changes](https://github.com/rprx/v2ray-vless/releases)。
Overall, ALPHA 2 to BETA mainly includes: structural evolution, cleaning and integration, performance improvement, and more completeness. All of these are incremental improvements, please refer to [VLESS Changes](https://github.com/rprx/v2ray-vless/releases) for details.
## ProtoBuf
似乎只有 VLESS 可选内嵌 ProtoBuf，它是一种数据交换格式，信息被紧密编码成二进制，TLV 结构（Tag Length Value）。
It seems that only VLESS supports embedding ProtoBuf, which is a data exchange format that encodes information tightly into binary TLV (Tag Length Value) structures.
起因是我看到一篇文章称 SS 有一些缺点，如没有设计错误回报机制，客户端没办法根据不同的错误采取进一步的动作。
（但我并不认同所有错误都要回报，不然防不了主动探测。下一个测试版中，服务器可以返回一串自定义信息。）
于是想到一个可扩展的结构是很重要的，未来它也可以承载如动态端口指令。不止响应，请求也需要类似的结构。
本来打算自己设计 TLV，接着发觉 ProtoBuf 就是此结构、现成的轮子，完全适合用来做这件事，各语言支持等也不错。
The reason is that I saw an article that said that SS has some drawbacks, such as the lack of a design error reporting mechanism, and the client cannot take further action based on different errors. (But I don't agree that all errors should be reported, otherwise it can't prevent active probing. In the next beta version, the server can return a custom string of information.) So I think a scalable structure is important, and in the future, it can also carry dynamic port instructions. Not only the response, but the request also needs a similar structure. I originally planned to design TLV by myself, but then I found that ProtoBuf is the structure, ready-made, and it is completely suitable for this purpose, and the support for various languages is also good.
目前“附加信息”只有 Scheduler 和 SchedulerV，它们是 MessName 和 MessSeed 的替代者，**当你不需要它们时，“附加信息长度”为 0，也就不会有 ProtoBuf 序列化/反序列化的开销**。其实我更愿意称这个过程为“拼接”，因为 pb 实际原理上也只是这么做而已，相关开销极小。拼接后的 bytes 十分紧凑，和 ALPHA 的方案相差无几，有兴趣的可以分别输出并对比。
Currently, "Additional Information" only has Scheduler and SchedulerV, which are substitutes for MessName and MessSeed. **When you don't need them, the "Additional Information Length" is 0, so there is no ProtoBuf serialization/deserialization overhead**. Actually, I prefer to call this process "concatenation" because that's all pb does in principle, and the related overhead is minimal. The concatenated bytes are very compact, similar to ALPHA's solution, and those who are interested can output and compare them separately.
为了指示对附加信息（Addons，也可以理解成插件，以后可以有很多个插件）的不同支持程度，下个测试版会在“附加信息长度”前新增“附加信息版本”。256 - 1 = 255 字节是够用且合理的（65535 就太多了，还可能有人恶意填充），现有的只用了十分之一，以后也不会同时有那么多附加信息，且大多数情况下是完全没有附加信息的。真不够用的话，可以升级 VLESS 版本。
To indicate different levels of support for additional information (Addons, which can be understood as plugins and can have many plugins in the future), the next beta version will add "Addon Version" before "Addon Length". 256-1 = 255 bytes is enough and reasonable (65535 is too much and there may be malicious padding), and only one-tenth of the existing space is used. In the future, there will not be so many addons at the same time, and most of the time there will be no addons at all. If it is not enough, you can upgrade to a newer version of VLESS.
为了减少逻辑判断等开销，暂定 Addons 不使用多级结构。一个月前出现过“可变协议格式”的想法，pb 是可以做到打乱顺序，但没必要，因为现代加密的设计不会让旁观者看出两次传输的头部相同。
To reduce logical judgment and other expenses, it is temporarily decided that Addons will not use a multi-level structure. A month ago, there was an idea of "variable protocol format". PB can shuffle the order, but it is not necessary because the design of modern encryption will not allow bystanders to see that the headers of the two transmissions are the same.
下面介绍 Schedulers 和 Encryption 的构想，**它们都是可选的**，一个应对流量时序特征问题，一个应对密码学上的问题。
Below is an introduction to the concepts of Schedulers and Encryption, both of which are optional. One is designed to address issues related to traffic timing, while the other is designed to address cryptographic issues.
## ~~Schedulers~~ Flow
## Flow
~~中文名暂称：流量调度器~~（2020-09-03 更新：中文名确定为“流控”），指令由 ProtoBuf 承载，控制的是数据部分。
~~Temporary Chinese name: Traffic Scheduler~~ (Updated on 2020-09-03: The Chinese name is confirmed as "Flow Control"). The command is carried by ProtoBuf and controls the data section.
我之前发现，VMess 原有的 shake “元数据混淆”在 TLS 上完全不会带来有意义的改变，只会降低性能，所以 VLESS 弃用了它。并且，“混淆”这个表述容易被误解成伪装，也弃用了。顺便一提，我一直是不看好伪装的：做不到完全一样，那不就是强特征吗？做得到完全一样，那为什么不直接用伪装目标？我一开始用的是 SSR，后来发现它只是表面伪装骗运营商，就再也没用过了。
I previously found that the original "metadata obfuscation" feature of VMess did not bring any meaningful changes in TLS, but only reduced performance, so VLESS abandoned it. Also, the term "obfuscation" is easily misunderstood as camouflage, so it has been abandoned. By the way, I have always been skeptical of camouflage: if it cannot be exactly the same, isn't it a strong feature? If it can be exactly the same, why not directly use the target for camouflage? I initially used SSR, but later found that it only superficially camouflages and deceives the operator, so I never used it again.
那么，“流量调度器”要解决什么问题？它影响的是宏观流量时序特征，而不是微观特征，后者是加密要解决的事情。流量时序特征可以是协议带来的，比如 Socks5 over TLS 时的 Socks5 握手 ，TLS 上不同的这种特征对于监测者来说就是不同的协议，此时无限 Schedulers 就相当于无限协议（重新分配每次发送的数据量大小等）。流量时序特征也可以是行为带来的，比如访问 Google 首页时加载了多少文件、顺序、每个文件的大小，多套一层加密并不能有效掩盖这些信息。
So, what problem does the "Traffic Scheduler" solve? It affects the macro traffic temporal characteristics, rather than the micro characteristics that encryption aims to solve. Traffic temporal characteristics can be protocol-based, such as the Socks5 handshake when using Socks5 over TLS. Different characteristics on TLS are different protocols for monitors. At this point, infinite schedulers are equivalent to infinite protocols (re-assigning the amount of data sent each time). Traffic temporal characteristics can also be behavior-based, such as how many files are loaded, the order, and the size of each file when accessing the Google homepage. Adding another layer of encryption cannot effectively conceal this information.
Schedulers 没必要像下面的 Encryption 一样整个套在外面，因为头部的一丁点数据相对于后面的数据量来说太微不足道了。
Schedulers do not need to be wrapped like Encryption below because the tiny amount of data in the header is negligible compared to the rest of the data.
BETA 2 预计推出两个初级的 Scheduler：Zstd 压缩、数据量动态扩充。进阶操作才是从宏观层面来控制、分配，暂时咕咕。
BETA 2 is expected to introduce two basic schedulers: Zstd compression and dynamic data expansion. Advanced operations will control and distribute at a macro level, but for now, they are still pending.
## Encryption
与 VMess 的高度耦合不同，VLESS 的服务端、客户端不久后可以提前约定好加密方式，仅在外面套一层加密。这有点类似于使用 TLS，不影响承载的任何数据，也可以理解成底层就是从 TLS 换成预设约定加密。相对于高度耦合，这种方式更合理且灵活：一种加密方式出了安全性问题，直接扔掉并换用其它的就行了，十分方便。VLESS 服务端还会允许不同的加密方式共存。
Unlike VMess, which is highly coupled, VLESS allows the server and client to pre-agree on an encryption method, which is only encrypted with an outer layer. This is somewhat similar to using TLS, which does not affect any of the data carried, and can be understood as replacing TLS with pre-agreed encryption at the bottom. Compared with high coupling, this approach is more reasonable and flexible: if there is a security issue with one encryption method, it can be discarded and another one can be used directly, which is very convenient. The VLESS server also allows for different encryption methods to coexist.
对比 VMess，VLESS 相当于把 security 换成 encryption，把 disableInsecureEncryption 换成 decryption，就解决了所有问题。目前 encryption 和 decryption 只接受 \"none\" 且不能留空（即使以后有连接安全性检查），详见 [VLESS 配置文档](https://github.com/rprx/v2fly-github-io/blob/master/docs/config/protocols/vless.md)。encryption 并不需要往外移一级，一是因为无法复用很多代码，二是因为会影响控制粒度，看未来的应用就明白了。
Compared with VMess, VLESS replaces security with encryption and disableInsecureEncryption with decryption, which solves all the problems. Currently, encryption and decryption only accept "none" and cannot be left blank (even if there are connection security checks in the future), as detailed in the VLESS configuration document. Encryption does not need to be moved out one level, firstly because it cannot reuse a lot of code, and secondly because it will affect the control granularity, which will be understood by looking at future applications.
加密支持两类形式，一类是加密完全独立，需要额外密码，适合私用，另一类是结合已有的 UUID 来加密，适合公用。
（若用第一类加密形式，且密码是以某种形式公开的，比如多人共用，那么中间人攻击就不远了）
重新设计的动态端口可能会随加密同时推出，指令由 ProtoBuf 承载，具体实现和 VMess 的动态端口也会有很多不同。
Encryption supports two types of forms. One type is completely independent and requires an additional password, suitable for private use. The other type combines with the existing UUID for encryption, which is suitable for public use.
套现成加密是件很简单的事情，也就多一层 writer & reader。BETA 3 预计支持 SS 的 aes-128-gcm 和 chacha20-ietf-poly1305：
客户端的 encryption 可以填 “auto: ss_aes-128-gcm_0_123456, ss_chacha20-ietf-poly1305_0_987654”，auto 会选择最适合当前机器的，0 代表测试版，最后的是密码。服务端的 decryption 也是类似填法，收到请求时会逐一尝试解密。
(If the first type of encryption is used and the password is publicly available in some form, such as multiple people sharing it, then a man-in-the-middle attack is not far away.)
并不是所有组合都需逐一尝试：VMess 的加密分为三段，第一段是认证信息，结合了 UUID、alterId、时间因素，第二段是指令部分，以固定算法加密，指令中含有数据部分使用的加密算法，第三段才是重要的数据部分。可以看出，VMess 的加解密方式实际上是多对一（服务端适配），而不仅是结合 UUID。但仅是结合 UUID 来加密也是件相对麻烦的事情，短时间内不会出，鉴于我们现在有 VMessAEAD 可用，也并不着急。若 VLESS 推出了结合 UUID 的加密方式，相当于重构了整个 VMess。
A redesigned dynamic port may be released simultaneously with encryption, and the command is carried by ProtoBuf. The specific implementation and the dynamic port of VMess will also have many differences.
It is very easy to cash out encrypted currency, which adds an extra layer of writer & reader. BETA 3 is expected to support SS's aes-128-gcm and chacha20-ietf-poly1305:
The encryption on the client-side can be filled with "auto: ss_aes-128-gcm_0_123456, ss_chacha20-ietf-poly1305_0_987654". Auto will choose the most suitable one for the current machine, 0 represents the beta version, and the last one is the password. The decryption on the server-side is also filled in a similar way, and each decryption attempt will be made when the request is received.
Not all combinations need to be tried one by one: VMess encryption is divided into three parts. The first part is the authentication information, which combines UUID, alterId, and time factors. The second part is the instruction part, which is encrypted using a fixed algorithm. The instruction contains the encryption algorithm used in the data part. The third part is the important data part. It can be seen that the VMess encryption and decryption method is actually many-to-one (adapted by the server), not just combining UUID. However, it is also a relatively difficult thing to encrypt only by combining UUID. It will not be available in a short time. Considering that we now have VMessAEAD available, there is no need to rush. If VLESS introduces an encryption method that combines UUID, it is equivalent to reconstructing the entire VMess.
## UDP issues
[XUDP：VLESS & VMess & Mux UDP FullCone NAT](https://github.com/XTLS/Xray-core/discussions/252)
[XUDP: VLESS & VMess & Mux UDP FullCone NAT](https://github.com/XTLS/Xray-core/discussions/252)
## 客户端开发指引
## Client Development Guide
1. VLESS 协议本身还会有不兼容升级，但客户端配置文件参数基本上是只增不减的。iOS 客户端的协议实现则需紧跟升级。
2. **视觉标准：UI 标识请统一用 VLESS**，而不是 VLess / Vless / vless，配置文件不受影响，代码内则顺其自然。
3. `encryption` 应做成输入框而不是选择框，新配置的默认值应为 `none`，若用户置空则应代填 `none`。
1. The VLESS protocol itself may have incompatible upgrades, but the parameters in the client configuration file are basically only increased and not decreased. The protocol implementation of the iOS client needs to keep up with the upgrade.
2. Visual standard: Please use VLESS as the UI identifier uniformly, instead of VLess / Vless / vless. The configuration file is not affected, and the code should follow naturally.
3. `Encryption` should be made into an input box instead of a selection box. The default value of the new configuration should be `none`, and if the user leaves it blank, it should be filled in with `none`.
## VLESS 分享链接标准
## VLESS Sharing Link Standard
感谢 <img src="https://avatars2.githubusercontent.com/u/7822648?s=32" width="32px" height="32px" alt="a"/> [@DuckSoft](https://github.com/DuckSoft) 的提案!
Thank you to [@DuckSoft](https://github.com/DuckSoft) for the proposal!
详情请见 [VMessAEAD / VLESS 分享链接标准提案](https://github.com/XTLS/Xray-core/issues/91)
Please see [VMessAEAD/VLESS Sharing Link Standard Proposal](https://github.com/XTLS/Xray-core/issues/91) for more details.

274
docs/en/development/protocols/vmess.md
View file

@ -1,175 +1,175 @@
# VMess 协议
# VMess Protocol
VMess 是一个加密传输协议，可以作为 Xray 客户端和服务器之间的桥梁。
VMess is an encrypted transmission protocol that can serve as a bridge between the Xray client and server.
## 版本
## Version
当前版本号为 1。
The current version number is 1.
## 依赖
## Dependencies
### 底层协议
### Underlying Protocol
VMess 是一个基于 TCP 的协议，所有数据使用 TCP 传输。
VMess is a TCP-based protocol where all data is transmitted over TCP.
### 用户 ID
### User ID
ID 等价于 [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)，是一个 16 字节长的随机数，它的作用相当于一个令牌（Token）。
一个 ID 形如：de305d54-75b4-431b-adb2-eb6b9e546014，几乎完全随机，可以使用任何的 UUID 生成器来生成，比如[这个](https://www.uuidgenerator.net/)。
An ID is equivalent to a [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier), which is a 16-byte long random number. Its function is similar to a token. An ID looks like: `de305d54-75b4-431b-adb2-eb6b9e546014`, it is almost entirely random and can be generated using any UUID generator, such as [this one](https://www.uuidgenerator.net/).
用户 ID 可在[配置文件](../../config)中指定。
User ID can be specified in the [configuration file](../../config).
### 函数
### Functions
- MD5: [MD5 函数](https://en.wikipedia.org/wiki/MD5)
- 输入参数为任意长度的 byte 数组
- 输出为一个 16 byte 的数组
- HMAC: [HMAC 函数](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code)
- 输入参数为：
- H：散列函数
- K：密钥，任意长度的 byte 数组
- M：消息，任意长度的 byte 数组
- Shake: [SHA3-Shake128 函数](https://en.wikipedia.org/wiki/SHA-3)
- 输入参数为任意长度的字符串
- 输出为任意长度的字符串
- MD5: [MD5 Function](https://en.wikipedia.org/wiki/MD5)
- Input parameter is any length byte array
- Output is a 16-byte array
- HMAC: [HMAC Function](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code)
- Input parameters are:
- H: Hash function
- K: Key, any length byte array
- M: Message, any length byte array
- Shake: [SHA3-Shake128 Function](https://en.wikipedia.org/wiki/SHA-3)
- Input parameter is any length string
- Output is any length string
## 通讯过程
## Communication Process
VMess 是一个无状态协议，即客户端和服务器之间不需要握手即可直接传输数据，每一次数据传输对之前和之后的其它数据传输没有影响。
VMess is a stateless protocol, which means that data can be transmitted directly between the client and the server without the need for a handshake. Each data transmission has no impact on other data transmissions before or after it.
VMess 的客户端发起一次请求，服务器判断该请求是否来自一个合法的客户端。如验证通过，则转发该请求，并把获得的响应发回给客户端。
When a VMess client initiates a request, the server checks whether the request comes from a legitimate client. If the validation passes, the server forwards the request and sends the obtained response back to the client.
VMess 使用非对称格式，即客户端发出的请求和服务器端的响应使用了不同的格式。
VMess uses an asymmetric format, meaning that the requests sent by the client and the responses from the server use different formats.
## 客户端请求
## Client Request
| 16 字节 | X 字节 | 余下部分 |
| -------- | -------- | -------- |
| 认证信息 | 指令部分 | 数据部分 |
| 16 Bytes | X Bytes | Remaining |
| -------------------------- | ---------------- | --------- |
| Authentication Information | Instruction Part | Data Part |
### 认证信息
### Authentication Information
认证信息是一个 16 字节的哈希（hash）值，它的计算方式如下：
The authentication information is a 16-byte hash (hash) value, which is calculated as follows:
- H = MD5
- K = 用户 ID (16 字节)
- M = UTC 时间，精确到秒，取值为当前时间的前后 30 秒随机值(8 字节, Big Endian)
- K = User ID (16 bytes)
- M = UTC time accurate to seconds, with a random value of ±30 seconds from the current time (8 bytes, Big Endian)
- Hash = HMAC(H, K, M)
### 指令部分
### Command Section
指令部分经过 AES-128-CFB 加密：
The instruction part is encrypted using AES-128-CFB.
- Key：MD5(用户 ID + []byte('c48619fe-8f02-49e0-b9e9-edf763e17e21'))
- IV：MD5(X + X + X + X)，X = []byte(认证信息生成的时间) (8 字节, Big Endian)
- Key: MD5(user ID + []byte('c48619fe-8f02-49e0-b9e9-edf763e17e21'))
- IV: MD5(X + X + X + X), X = []byte(time generated by authentication information) (8 bytes, Big Endian)
| 1 字节 | 16 字节 | 16 字节 | 1 字节 | 1 字节 | 4 位 | 4 位 | 1 字节 | 1 字节 | 2 字节 | 1 字节 | N 字节 | P 字节 | 4 字节 |
| :--------: | :---------: | :----------: | :--------: | :------: | :----: | :----------: | :----: | :------: | :-------: | :--------: | :----: | :----: | :----: |
| 版本号 Ver | 数据加密 IV | 数据加密 Key | 响应认证 V | 选项 Opt | 余量 P | 加密方式 Sec | 保留 | 指令 Cmd | 端口 Port | 地址类型 T | 地址 A | 随机值 | 校验 F |
| 1 Byte | 16 Bytes | 16 Bytes | 1 Byte | 1 Byte | 4 bits | 4 bits | 1 Byte | 1 Byte | 2 Bytes | 1 Byte | N Bytes | P Bytes | 4 Bytes |
| :-----: | :----------------: | :-----------------: | :---------------------------: | :-----: | :------: | :---------------: | :------: | :-----: | :-----: | :----------: | :-----: | :----------: | :------: |
| Version | Data Encryption IV | Data Encryption Key | Response Authentication Value | Options | Reserved | Encryption Method | Reserved | Command | Port | Address Type | Address | Random Value | Checksum |
选项 Opt 细节：（当某一位为 1 时，表示该选项启用）
Options Opt Details: (When a bit is 1, it means the option is enabled)
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
| :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| X | X | X | X | X | M | R | S |
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
| :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| X | X | X | X | X | M | R | S |
of which:
- Version Number Ver: Always 1;
- Data Encryption IV: Random value;
- Data Encryption Key: Random value;
- Response Authentication V: Random value;
- Option Opt:
- S (0x01): Standard format data stream (recommended);
- R (0x02): Client expects to reuse TCP connection (deprecated in Xray 2.23+);
- This item only takes effect when S is enabled;
- M (0x04): Enable metadata obfuscation (recommended);
- This item only takes effect when S is enabled;
- When this item is enabled, the client and server need to construct two Shake instances respectively, RequestMask = Shake (request data IV), ResponseMask = Shake (response data IV).
- X: Reserved
- Redundancy P: Random value added before checksum value;
- Encryption Method: Specify the encryption method for the data part, and the optional values are:
- 0x00: AES-128-CFB;
- 0x01: No encryption;
- 0x02: AES-128-GCM;
- 0x03: ChaCha20-Poly1305;
- Instruction Cmd:
- 0x01: TCP data;
- 0x02: UDP data;
- Port Port: Integer port number in Big Endian format;
- Address Type T:
- 0x01: IPv4
- 0x02: Domain name
- 0x03: IPv6
- Address A:
- When T = 0x01, A is a 4-byte IPv4 address;
- When T = 0x02, A is a 1-byte length (L) + L-byte domain name;
- When T = 0x03, A is a 16-byte IPv6 address;
- Check F: FNV1a hash of all content in the instruction except F.
### Data Section
When Opt(S) is enabled, this format is used for the data section. The actual request data is divided into several small chunks, and each chunk has the following format. After the server verifies all the small chunks, it will be forwarded in the basic format.
| 2 Bytes | L Bytes |
| :------: | :---------: |
| Length L | Data Packet |
in which:
- Length L: A big-endian integer with a maximum value of 2^14.
- When Opt(M) is enabled, the value of L is equal to the true value xor Mask. Mask = (RequestMask.NextByte() << 8) + RequestMask.NextByte();
- Packet: A data packet encrypted by the specified encryption method.
Before the transmission is completed, the data packet must contain actual data, in addition to the length and authentication data. When the transmission is complete, the client must send an empty data packet, that is, L = 0 (unencrypted) or the length of the authentication data (encrypted), to indicate the end of the transmission.
The packets are formatted as follows, depending on the encryption method:
- Unencrypted:
  - L bytes: actual data;
- AES-128-CFB: The entire data section is encrypted using AES-128-CFB.
  - 4 bytes: FNV1a hash of actual data;
  - L - 4 bytes: actual data;
- AES-128-GCM: Key is the Key of the instruction section, IV = count (2 bytes) + IV (10 bytes). count starts at 0 and increases by 1 for each packet; IV is the 3rd to 12th byte of the instruction section IV.
  - L - 16 bytes: actual data;
  - 16 bytes: GCM authentication information
- ChaCha20-Poly1305: Key = MD5 (instruction part Key) + MD5 (MD5 (instruction part Key)), IV = count (2 bytes) + IV (10 bytes). count starts at 0 and increases by 1 for each packet; IV is the 3rd to 12th byte of the instruction section IV.
  - L - 16 bytes: actual data;
  - 16 bytes: Poly1305 authentication information
## Server Response
The header data is encrypted using AES-128-CFB encryption. The IV is MD5 of the data encryption IV, and the Key is MD5 of the data encryption Key. The actual response data varies depending on the encryption settings.
| 1 Byte | 1 Byte | 1 Byte | 1 Byte | M Bytes | Remaining Part |
| ------------------------- | ---------- | ----------- | ---------------- | --------------- | -------------------- |
| Response Authentication V | Option Opt | Command Cmd | Command Length M | Command Content | Actual Response Data |
其中：
- 版本号 Ver：始终为 1；
- 数据加密 IV：随机值；
- 数据加密 Key：随机值；
- 响应认证 V：随机值；
- 选项 Opt：
- S (0x01)：标准格式的数据流（建议开启）；
- R (0x02)：客户端期待重用 TCP 连接（Xray 2.23+ 弃用）；
- 只有当 S 开启时，这一项才有效；
- M (0x04)：开启元数据混淆（建议开启）；
- 只有当 S 开启时，这一项才有效；
- 当其项开启时，客户端和服务器端需要分别构造两个 Shake 实例，分别为 RequestMask = Shake(请求数据 IV), ResponseMask = Shake(响应数据 IV)。
- X：保留
- 余量 P：在校验值之前加入 P 字节的随机值；
- 加密方式：指定数据部分的加密方式，可选的值有：
- 0x00：AES-128-CFB；
- 0x01：不加密；
- 0x02：AES-128-GCM；
- 0x03：ChaCha20-Poly1305；
- 指令 Cmd：
- 0x01：TCP 数据；
- 0x02：UDP 数据；
- 端口 Port：Big Endian 格式的整型端口号；
- 地址类型 T：
- 0x01：IPv4
- 0x02：域名
- 0x03：IPv6
- 地址 A：
- 当 T = 0x01 时，A 为 4 字节 IPv4 地址；
- 当 T = 0x02 时，A 为 1 字节长度（L） + L 字节域名；
- 当 T = 0x03 时，A 为 16 字节 IPv6 地址；
- 校验 F：指令部分除 F 外所有内容的 FNV1a hash；
- Response Authentication V: must match the response authentication V in the client request.
- Option Opt:
- 0x01: server prepares to reuse TCP connections (deprecated in Xray 2.23+).
- Command Cmd:
- 0x01: dynamic port command.
- Actual response data:
- If Opt(S) in the request is enabled, the standard format is used. Otherwise, the basic format is used.
- Both formats are identical to the request data.
- When Opt(M) is enabled, the value of length L is equal to the true value XOR Mask. Mask = (ResponseMask.NextByte() << 8) + ResponseMask.NextByte().
### 数据部分
### Dynamic Port Instructions
当 Opt(S) 开启时，数据部分使用此格式。实际的请求数据被分割为若干个小块，每个小块的格式如下。服务器校验完所有的小块之后，再按基本格式的方式进行转发。
| 1 Byte | 2 Bytes | 16 Bytes | 2 Bytes | 1 Byte | 1 Byte |
| -------- | ------- | -------- | ------- | ---------- | ----------------- |
| Reserved | Port | User ID | AlterID | User level | Validity period T |
| 2 字节 | L 字节 |
| :----: | :----: |
| 长度 L | 数据包 |
in which:
其中：
- Port: Integer port number in Big Endian format
- T: Number of minutes as integer value.
- 长度 L：Big Endian 格式的整型，最大值为 2^14；
- 当 Opt(M) 开启时，L 的值 = 真实值 xor Mask。Mask = (RequestMask.NextByte() << 8) + RequestMask.NextByte()；
- 数据包：由指定的加密方式加密过的数据包；
When the client receives a dynamic port command, the server opens a new port for communication. The client can then send data to the new port. After T minutes, the port will expire, and the client must use the main port to communicate again.
在传输结束之前，数据包中必须有实际数据，即除了长度和认证数据之外的数据。当传输结束时，客户端必须发送一个空的数据包，即 L = 0（不加密） 或认证数据长度（有加密），来表示传输结束。
## Comment
按加密方式不同，数据包的格式如下：
- 不加密：
- L 字节：实际数据；
- AES-128-CFB：整个数据部分使用 AES-128-CFB 加密
- 4 字节：实际数据的 FNV1a hash；
- L - 4 字节：实际数据；
- AES-128-GCM：Key 为指令部分的 Key，IV = count (2 字节) + IV (10 字节)。count 从 0 开始递增，每个数据包加 1；IV 为 指令部分 IV 的第 3 至第 12 字节。
- L - 16 字节：实际数据；
- 16 字节：GCM 认证信息
- ChaCha20-Poly1305：Key = MD5(指令部分 Key) + MD5(MD5(指令部分 Key))，IV = count (2 字节) + IV (10 字节)。count 从 0 开始递增，每个数据包加 1；IV 为 指令部分 IV 的第 3 至第 12 字节。
- L - 16 字节：实际数据；
- 16 字节：Poly1305 认证信息
## 服务器应答
应答头部数据使用 AES-128-CFB 加密，IV 为 MD5(数据加密 IV)，Key 为 MD5(数据加密 Key)。实际应答数据视加密设置不同而不同。
| 1 字节 | 1 字节 | 1 字节 | 1 字节 | M 字节 | 余下部分 |
| ---------- | -------- | -------- | ---------- | -------- | ------------ |
| 响应认证 V | 选项 Opt | 指令 Cmd | 指令长度 M | 指令内容 | 实际应答数据 |
其中：
- 响应认证 V：必须和客户端请求中的响应认证 V 一致；
- 选项 Opt：
- 0x01：服务器端准备重用 TCP 连接（Xray 2.23+ 弃用）；
- 指令 Cmd：
- 0x01：动态端口指令
- 实际应答数据：
- 如果请求中的 Opt(S) 开启，则使用标准格式，否则使用基本格式。
- 格式均和请求数据相同。
- 当 Opt(M) 开启时，长度 L 的值 = 真实值 xor Mask。Mask = (ResponseMask.NextByte() << 8) + ResponseMask.NextByte()；
### 动态端口指令
| 1 字节 | 2 字节 | 16 字节 | 2 字节 | 1 字节 | 1 字节 |
| ------ | --------- | ------- | ------- | -------- | ---------- |
| 保留 | 端口 Port | 用户 ID | AlterID | 用户等级 | 有效时间 T |
其中：
- 端口 Port：Big Endian 格式的整型端口号；
- 有效时间 T：分钟数；
客户端在收到动态端口指令时，服务器已开放新的端口用于通信，这时客户端可以将数据发往新的端口。在 T 分钟之后，这个端口将失效，客户端必须重新使用主端口进行通信。
## 注释
- 为确保向前兼容性，所有保留字段的值必须为 0。
- To ensure forward compatibility, the values of all reserved fields must be 0.