mirror of
https://github.com/XTLS/Xray-docs-next.git
synced 2026-10-10 08:18:10 +03:00
EN: Retranslate all documents via Gemini Pro 3, Human proofreading
This commit is contained in:
Meow
@@ -1,80 +1,96 @@
|
||||
# Compile the document
|
||||
# Compilation Documentation
|
||||
|
||||
## Preparatory Work
|
||||
## Prerequisites
|
||||
|
||||
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.
|
||||
Xray uses [Golang](https://golang.org/) as its programming language. You need to install the latest version of Golang to compile it.
|
||||
|
||||
::: tip TIP
|
||||
Install Golang: [golang.org/doc/install](https://golang.org/doc/install)
|
||||
:::
|
||||
|
||||
If you happen to use Windows, please **make sure** to use Powershell.
|
||||
> If you are unfortunately using Windows, please **be sure** to use PowerShell.
|
||||
|
||||
## Pull Xray source code
|
||||
## Pull Xray Source Code
|
||||
|
||||
```bash
|
||||
git clone https://github.com/XTLS/Xray-core.git
|
||||
git clone [https://github.com/XTLS/Xray-core.git](https://github.com/XTLS/Xray-core.git)
|
||||
cd Xray-core && go mod download
|
||||
```
|
||||
|
||||
If you have free time, you can try GitHub's official tool: `gh repo clone XTLS/Xray-core`
|
||||
> If you have nothing better to do, you can try the GitHub official tool: `gh repo clone XTLS/Xray-core`
|
||||
|
||||
Note: In a network environment where Google cannot be accessed normally, dependencies cannot be pulled normally, and `GOPROXY` needs to be set first:
|
||||
Note: In network environments where Google cannot be accessed normally, dependencies cannot be pulled correctly. You need to set `GOPROXY` first:
|
||||
|
||||
```bash
|
||||
go env -w GOPROXY=https://goproxy.io,direct
|
||||
go env -w GOPROXY=[https://goproxy.io](https://goproxy.io),direct
|
||||
```
|
||||
|
||||
## Build Binary
|
||||
|
||||
:::warning
|
||||
This command needs to be executed within Xray root directory.
|
||||
The commands in this section need to be run inside the Xray root directory.
|
||||
:::
|
||||
|
||||
### Windows(Powershell):
|
||||
### Windows (Powershell)
|
||||
|
||||
```powershell
|
||||
$env:CGO_ENABLED=0
|
||||
go build -o xray.exe -trimpath -ldflags "-s -w -buildid=" ./main
|
||||
go build -o xray.exe -trimpath -buildvcs=false -ldflags "-s -w -buildid=" ./main
|
||||
```
|
||||
|
||||
### macOS, Linux:
|
||||
### macOS, Linux
|
||||
|
||||
```bash
|
||||
CGO_ENABLED=0 go build -o xray -trimpath -ldflags "-s -w -buildid=" ./main
|
||||
CGO_ENABLED=0 go build -o xray -trimpath -buildvcs=false -ldflags "-s -w -buildid=" ./main
|
||||
```
|
||||
|
||||
Running the above command will generate an xray executable file in the directory.
|
||||
Running the above commands will generate the `xray` executable file in the directory.
|
||||
|
||||
::: tip
|
||||
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.
|
||||
If you need to compile a debuggable program (i.e., you can attach `dlv` to the running program for debugging), please remove the `-w -s` options from `ldflags`.
|
||||
|
||||
- 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.
|
||||
- `-w`: Disable DWARF generation (debug info). After using this option, you cannot use gdb for debugging.
|
||||
- `-s`: Disable the symbol table.
|
||||
|
||||
## Cross compilation:
|
||||
PS: Actually, debugging with VSCode or other IDEs seems more convenient.
|
||||
:::
|
||||
|
||||
Here, we take the example of compiling to a Linux server in a Windows (Powershell) environment:
|
||||
## Cross Compilation
|
||||
|
||||
Here is an example of compiling for 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```
|
||||
go build -o xray -trimpath -buildvcs=false -ldflags "-s -w -buildid=" ./main
|
||||
```
|
||||
|
||||
After uploading to the server, remember to execute `chmod +x xray` in the server terminal.
|
||||
|
||||
::: tip
|
||||
Execute `go tool dist list` to view all supported systems and architectures.
|
||||
Run `go tool dist list` to view all supported systems and architectures.
|
||||
:::
|
||||
|
||||
## Reproducible Build:
|
||||
## Reproducible Build
|
||||
|
||||
Following the above steps, it is possible to compile and release an identical binary file as the one in Release.
|
||||
Use the following command to build (`<short commit ID>` should be replaced with the first seven characters of the corresponding commit SHA-256):
|
||||
|
||||
```bash
|
||||
CGO_ENABLED=0 go build -o xray -trimpath -buildvcs=false -gcflags="all=-l=4" -ldflags="-X [github.com/xtls/xray-core/core.build=](https://github.com/xtls/xray-core/core.build=)<short commit ID> -s -w -buildid=" -v ./main
|
||||
```
|
||||
|
||||
For MIPS/MIPSLE architectures, you should use:
|
||||
|
||||
```bash
|
||||
CGO_ENABLED=0 go build -o xray -trimpath -buildvcs=false -gcflags="-l=4" -ldflags="-X [github.com/xtls/xray-core/core.build=](https://github.com/xtls/xray-core/core.build=)<short commit ID> -s -w -buildid=" -v ./main
|
||||
```
|
||||
|
||||
::: warning
|
||||
Please confirm that you are using the same Golang version as the one used to compile the release.
|
||||
Please ensure that the Golang version you are using is consistent with the one used to compile the Release.
|
||||
:::
|
||||
|
||||
## Compiling for Windows 7
|
||||
|
||||
Replace the Golang tools with the version provided in [go-win7](https://github.com/XTLS/go-win7), and then proceed with the compilation steps above.
|
||||
|
||||
@@ -1,43 +1,43 @@
|
||||
# Design Objectives
|
||||
# Design Goals
|
||||
|
||||
- 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.
|
||||
- The Xray core provides a platform that supports necessary network proxy functions, upon which secondary development can be conducted to provide a better user experience.
|
||||
- Cross-platform support is the primary principle to reduce the cost of secondary development.
|
||||
|
||||
## Architecture
|
||||
|
||||
|
||||
|
||||
The kernel is divided into three layers: the application layer, the proxy layer, and the transport layer.
|
||||
The core is divided into three layers: Application Layer, Proxy Layer, and Transport Layer.
|
||||
|
||||
Each layer contains several modules, which are independent of each other. Modules of the same type can be seamlessly replaced.
|
||||
Each layer contains several modules. Modules are independent of each other, and 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 Application Layer contains common functions used in the Proxy Layer. These functions are abstracted to be reused across 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.
|
||||
Modules in the Application Layer should be pure software implementations, independent of hardware or platform-specific technologies.
|
||||
|
||||
List of Important Modules:
|
||||
Important module list:
|
||||
|
||||
- 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;
|
||||
- **Dispatcher**: Used to transmit data received by the inbound proxy to the outbound proxy.
|
||||
- **Router**: Routing module, see [Routing Configuration](../../config/routing.md) for details.
|
||||
- **DNS**: Built-in DNS server module.
|
||||
- **Proxy Manager**: Manages proxies.
|
||||
|
||||
### Proxy Layer
|
||||
|
||||
The proxy layer is divided into two parts: Inbound Proxy and 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.
|
||||
The two parts are independent of each other. An inbound proxy does not depend on a specific outbound proxy, and vice versa.
|
||||
|
||||
#### Inbound Proxy
|
||||
|
||||
- Implement the [proxy.Inbound](https://github.com/xtls/Xray-core/blob/main/proxy/proxy.go) interface;
|
||||
- Implements the [proxy.Inbound](https://github.com/xtls/Xray-core/blob/main/proxy/proxy.go) interface.
|
||||
|
||||
#### Outbound Proxy
|
||||
|
||||
- Implement the [proxy.Outbound](https://github.com/xtls/Xray-core/blob/main/proxy/proxy.go) interface;
|
||||
- Implements 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.
|
||||
The Transport Layer provides tool modules related to network data transmission.
|
||||
|
||||
@@ -4,94 +4,94 @@
|
||||
|
||||
### Version Control
|
||||
|
||||
Project X's code is hosted on GitHub:
|
||||
Project X code is hosted on GitHub:
|
||||
|
||||
- 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)
|
||||
- Xray Core: [Xray-core](https://github.com/XTLS/Xray-core)
|
||||
- Install Script: [Xray-install](https://github.com/XTLS/Xray-install)
|
||||
- Configuration Templates: [Xray-examples](https://github.com/XTLS/Xray-examples)
|
||||
- Xray Documentation: [Xray-docs-next](https://github.com/XTLS/Xray-docs-next)
|
||||
|
||||
You can use [Git](https://git-scm.com/) to get the code.
|
||||
You can use [Git](https://git-scm.com/) to fetch the code.
|
||||
|
||||
### Branch
|
||||
### Branches
|
||||
|
||||
- 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.
|
||||
- The trunk branch of this project is `main`.
|
||||
- The release branch of this project is also `main`.
|
||||
- Ensure that `main` is compilable and usable at any given time.
|
||||
- If you need to develop new features, please create a new branch for development. After development is complete and fully tested, merge it back into the trunk branch.
|
||||
- Branches that have already been merged into the trunk and are no longer necessary should be deleted.
|
||||
|
||||
### Release
|
||||
|
||||
<Badge text="WIP" type="warning"/> (Note: this is not translatable as it is a technical tag)
|
||||
<Badge text="WIP" type="warning"/>
|
||||
|
||||
- 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.
|
||||
- Establish two release channels: Bleeding Edge and Stable.
|
||||
- Bleeding Edge: Can be daily builds, mainly used for specific testing scenarios, trying out new features, and obtaining immediate feedback for further improvement.
|
||||
- Stable: Scheduled updates (e.g., monthly), merging stable changes and releasing.
|
||||
|
||||
### Citing other projects
|
||||
### Referencing Other Projects
|
||||
|
||||
- Golang
|
||||
- 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.
|
||||
- For product code, it is recommended to use the Golang standard library and libraries under [golang.org/x/](https://pkg.go.dev/search?limit=25&m=package&q=golang.org%2Fx).
|
||||
- If you need to reference other projects, please create an issue for discussion beforehand.
|
||||
- Others
|
||||
- Tools that do not violate the agreements of either party and are helpful to the project can be used.
|
||||
|
||||
## Development Process
|
||||
|
||||
### Before Writing Code
|
||||
|
||||
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
|
||||
- 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
|
||||
|
||||
- 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.
|
||||
If you find any issues or have any ideas for the project, please create an [issue](https://github.com/XTLS/Xray-core/issues) for discussion to reduce repetitive work and time spent on code.
|
||||
|
||||
### Modifying Code
|
||||
|
||||
#### Functional issue
|
||||
- Golang
|
||||
- Please refer to [Effective Go](https://golang.org/doc/effective_go.html).
|
||||
- Before every push, please run: `go generate core/format.go`.
|
||||
- If you need to modify protobuf, such as adding new configuration items, please run: `go generate core/proto.go`.
|
||||
- Before submitting a pull request, it is recommended to pass tests: `go test ./...`.
|
||||
- Before submitting a pull request, it is recommended that new code has over 70% code coverage.
|
||||
- Others
|
||||
- Please pay attention to code readability.
|
||||
|
||||
Please submit at least one test case to verify changes to existing functionality.
|
||||
### Pull Request
|
||||
|
||||
- Before submitting a PR, please run `git pull https://github.com/XTLS/Xray-core.git` to ensure the merge can proceed smoothly.
|
||||
- One PR should do one thing. If there are fixes for multiple bugs, please submit a separate PR for each bug.
|
||||
- Due to the special requirements of Golang (Package path), the PR process for Go projects differs 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 locally: `git clone https://github.com/<your_name>/Xray-core.git`.
|
||||
3. Create a new branch based on the `main` branch, e.g., `git branch issue24 main`.
|
||||
4. Make changes and commit them on the newly created branch.
|
||||
5. Before pushing the completed branch to your own repository, switch to the `main` branch and run `git pull https://github.com/XTLS/Xray-core.git` to pull the latest remote code.
|
||||
6. If new remote code was pulled in the previous step, switch back to the branch you created and run `git rebase main` to perform the branch merge operation. If you encounter file conflicts, you need to resolve them.
|
||||
7. After the previous step is completed, you can push your created branch to your own repository: `git push -u origin your-branch`.
|
||||
8. Finally, send a PR from the newly pushed branch in your repository to the `main` branch of `XTLS/Xray-core`.
|
||||
9. In the title and body of the PR, please fully describe the problem solved / new feature added / intention of the code changes, etc.
|
||||
10. Wait patiently for the developers' response.
|
||||
|
||||
### Changes to Code
|
||||
|
||||
#### Functional Issues
|
||||
|
||||
Please submit at least one Test Case to verify changes to existing functions.
|
||||
|
||||
#### Performance Related
|
||||
|
||||
Please provide the necessary test data to demonstrate performance issues in existing code or performance improvements in new code.
|
||||
Please submit necessary test data to prove performance defects in existing code or performance improvements in new code.
|
||||
|
||||
#### New Feature
|
||||
#### New Features
|
||||
|
||||
- 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.
|
||||
- If the new feature does not affect existing features, please provide a switch (e.g., flag) that can turn it on/off, and keep the new feature off by default.
|
||||
- Before developing large new features (such as adding a new protocol), please submit an issue first and proceed with development after discussion.
|
||||
|
||||
#### Other
|
||||
#### Others
|
||||
|
||||
It depends on the specific situation.
|
||||
To be determined based on the specific situation.
|
||||
|
||||
## Xray Coding Guidelines
|
||||
## Xray Coding Standards
|
||||
|
||||
The following content is applicable to Golang code in Xray.
|
||||
The following applies to Golang code in Xray.
|
||||
|
||||
### Code Structure
|
||||
|
||||
@@ -100,7 +100,7 @@ Xray-core
|
||||
├── app // Application module
|
||||
│ ├── router // Router
|
||||
├── common // Common code
|
||||
├── proxy // Communication protocol
|
||||
├── proxy // Communication protocols
|
||||
│ ├── blackhole
|
||||
│ ├── dokodemo-door
|
||||
│ ├── freedom
|
||||
@@ -111,21 +111,41 @@ Xray-core
|
||||
|
||||
### Coding Standards
|
||||
|
||||
Basic practices are consistent with the recommendations of the official Golang, with a few exceptions. Written here to help everyone familiarize themselves with Golang.
|
||||
Basically consistent with the practices recommended by official Golang documentation, with some exceptions. Written here to help everyone get familiar with Golang.
|
||||
|
||||
#### Naming
|
||||
|
||||
- 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`.
|
||||
- Try to use single English words for file and directory names, such as `hello.go`.
|
||||
- If unavoidable, use hyphens for directories / underscores for filenames to connect two (or more) words, e.g., `hello-world/hello_again.go`.
|
||||
- Test code should end with `_test.go`.
|
||||
- Use PascalCase for types, such as `ConnectionHandler`.
|
||||
- Abbreviations are not forced to be lowercase, i.e., `HTML` does not need to be written as `Html`.
|
||||
- Public member variables also use PascalCase.
|
||||
- Private member variables use [lowerCamelCase](https://en.wikipedia.org/wiki/Camel_case), such as `privateAttribute`.
|
||||
- To facilitate refactoring, it is recommended to use PascalCase for all methods.
|
||||
- Put completely private types into `internal`.
|
||||
|
||||
#### Content Organization
|
||||
|
||||
- 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.
|
||||
- A file contains one main type and its related private functions, etc.
|
||||
- Test-related files, such as Mock utility classes, should be placed in the `testing` subdirectory.
|
||||
|
||||
#### Int32Range
|
||||
|
||||
**For end user**
|
||||
|
||||
A value representing an optional range, which can be written in the following ways:
|
||||
|
||||
- A single number or range enclosed in quotes:
|
||||
- `""` (Treated as 0. Note: Not setting a field at all and setting it to empty might be two different concepts for some fields.)
|
||||
- `"114"`
|
||||
- `"114-514"`
|
||||
|
||||
- An independent int (in this case, it can only be a single number):
|
||||
- `114`
|
||||
|
||||
**For dev**
|
||||
|
||||
If you need to include a range in the configuration file, please use the `Int32Range` type.
|
||||
|
||||
Use `.From` and `.To` to get values. When From > To (e.g., 1919-810), the values will be automatically swapped to ensure From is less than To. If you want to get the raw values, you can use `.Left` and `.Right`.
|
||||
|
||||
Reference in New Issue
Block a user