diff --git a/.vitepress/config/cn.ts b/.vitepress/config/cn.ts index 2096aba..58f7494 100644 --- a/.vitepress/config/cn.ts +++ b/.vitepress/config/cn.ts @@ -34,6 +34,7 @@ export const cn = defineConfig({ { text: '改善 P2P', link: '/guide/network/p2p-optimize' }, { text: '魔法 DNS', link: '/guide/network/magic-dns' }, { text: 'ACL', link: '/guide/config/acl' }, + { text: '服务管理与混合模式', link: '/guide/network/service-mode' }, ] }, { text: '开机自启（注册服务）', collapsed: true, items: [ { text: '一键安装服务', link: '/guide/network/oneclick-install-as-service' }, @@ -49,6 +50,9 @@ export const cn = defineConfig({ text: '图形界面 GUI 组网', link: 'guide/gui/index', items: [ + { text: '运行模式', link: '/guide/gui/modes' }, + { text: '公共服务器组网', link: '/guide/gui/basic' }, + { text: '使用 Web 控制台组网', link: '/guide/gui/web-console' }, { text: '手动组网', link: '/guide/gui/manual' }, { text: 'WireGuard 接入', link: '/guide/gui/vpn_portal' }, { text: '子网代理', link: '/guide/gui/subnet_proxy' }, diff --git a/.vitepress/config/en.ts b/.vitepress/config/en.ts index c607735..1da8747 100644 --- a/.vitepress/config/en.ts +++ b/.vitepress/config/en.ts @@ -34,6 +34,7 @@ export const en = defineConfig({ { text: 'P2P Optimization', link: '/en/guide/network/p2p-optimize' }, { text: 'Magic DNS', link: '/en/guide/network/magic-dns' }, { text: 'ACL', link: '/en/guide/config/acl' }, + { text: 'Service Management & Hybrid Mode', link: '/en/guide/network/service-mode' }, ] }, { text: 'Autostart (Register Service)', collapsed: true, items: [ { text: 'One-Click Install Service', link: '/en/guide/network/oneclick-install-as-service' }, @@ -49,6 +50,9 @@ export const en = defineConfig({ text: 'GUI Networking', link: '/en/guide/gui/index', items: [ + { text: 'Running Modes', link: '/en/guide/gui/modes' }, + { text: 'Public Server Networking', link: '/en/guide/gui/basic' }, + { text: 'Networking with Web Console', link: '/en/guide/gui/web-console' }, { text: 'Manual Networking', link: '/en/guide/gui/manual' }, { text: 'WireGuard Access', link: '/en/guide/gui/vpn_portal' }, { text: 'Subnet Proxy', link: '/en/guide/gui/subnet_proxy' }, diff --git a/assets/cn/mode_switcher.png b/assets/cn/mode_switcher.png new file mode 100644 index 0000000..3b20bdd Binary files /dev/null and b/assets/cn/mode_switcher.png differ diff --git a/en/guide/gui/basic.md b/en/guide/gui/basic.md new file mode 100644 index 0000000..e0554cb --- /dev/null +++ b/en/guide/gui/basic.md @@ -0,0 +1,15 @@ +# Public Server Networking + +The GUI defaults to using official shared nodes for networking, which is convenient for friends without public IPs. In most cases, P2P tunneling can be successful. If P2P tunneling fails, the bandwidth between nodes may be relatively low. + +The configuration method is shown in the figure. + +![Configuration Interface](/assets/cn/config.png) + +After the configuration is complete, click the Run Network button. The interface after the network runs successfully is shown in the figure. + +![Running](/assets/cn/running.png) + +## Running Modes + +Starting from version v2.5.0, the GUI supports multiple running modes (Normal, Service, Remote). If you want the network to remain connected after exiting the GUI, or to manage remote servers, please refer to [GUI Running Modes](/en/guide/gui/modes). diff --git a/en/guide/gui/easytier-harmonyos.md b/en/guide/gui/easytier-harmonyos.md new file mode 100644 index 0000000..2a8de47 --- /dev/null +++ b/en/guide/gui/easytier-harmonyos.md @@ -0,0 +1,62 @@ +# [EasyTier HarmonyOS Version](https://appgallery.huawei.com/app/detail?id=top.frankhan.easytier&channelId=SHARE&source=appshare) + +## Download + +
+ + + +
+ +## Usage Tutorial + +- 1. New Button + +If you have already configured it on another device, you only need to copy the configuration from the other device and click the paste button here. + +If not, you need to give the configuration file you want to add a name for identification. + + + +- 2. Configuration Page + +Most configurations are aligned with the original configuration items, except for the credentials. Credentials are merged from the network name and network password to facilitate reuse across multiple configurations. + +[Original Configuration Items](https://easytier.cn/guide/network/configurations.html) + + + +- 3. Share Button and Air Capture + +The left side of p2 is Air Capture, and the right side is the window pulled up after clicking [System Share (Touch-to-Share available)]. You can share it with your other devices. Once listed, other devices will automatically install EasyTier and import the configuration you shared. + + + + +- 4. Sidebar + +Here you can switch configuration files. Swiping left on a configuration file will reveal a delete button to remove the configuration. Below are the EasyTier official group and the App communication group; feel free to join. + + + +- 5. Community Shared Nodes + +These are the community shared nodes obtained, provided entirely by the community for public welfare. Please do not use them for illegal or criminal activities that cause trouble for others. + + + +- 6. Important Tips + +#### Whether it is a Peer, a credential, or other configuration items, you need to click them to light them up to indicate they are enabled; otherwise, you have only added the configuration item. + +## Introduction + +EasyTier HarmonyOS Version is a HarmonyOS native application developed based on EasyTier. It uses ArkTS to implement a modern UI, provides VPN services and configuration management, allows for quick importing of community shared nodes, and supports new HarmonyOS features such as Touch-to-Share. + +## Bug Feedback & Suggestions + +Please jump directly via the App feedback group in the sidebar. + +## System Support + +Currently supports HarmonyOS 5 and above; HarmonyOS 5 may be deprecated in the future. diff --git a/en/guide/gui/modes.md b/en/guide/gui/modes.md new file mode 100644 index 0000000..9e6e436 --- /dev/null +++ b/en/guide/gui/modes.md @@ -0,0 +1,46 @@ +# GUI Running Modes + +EasyTier GUI supports three running modes, allowing users to flexibly deploy and manage the EasyTier core according to different scenarios. + +## Introduction to Running Modes + +At the bottom of the GUI interface, you can see the mode switcher. + +![Mode Switcher](/assets/cn/mode_switcher.png) + +### 1. Normal Mode +* **Description**: This is the default mode. The EasyTier core runs as a child process of the GUI. +* **Behavior**: When you close the GUI, the EasyTier network connection will also be disconnected. +* **Use Case**: Temporary networking, open and use as needed. + +### 2. Service Mode +* **Description**: Installs EasyTier as a native system service (Windows Service, systemd, etc.). +* **Behavior**: EasyTier will run persistently in the background. Even if you close the GUI or log out, the network remains connected. Supports auto-start on boot. +* **Use Case**: Servers or personal computers that need to be online stably for a long time. +* **Note**: On Windows, if Service Mode is running, you may need to stop the service in the GUI before updating the software. + +### 3. Remote Mode +* **Description**: The GUI acts only as a management terminal, connecting to an EasyTier instance on a remote machine via RPC. +* **Behavior**: You can manage EasyTier on headless servers, view status, or modify configurations. +* **Configuration**: Requires entering the IP address and RPC port (default 15713) of the remote node. + +## Configuration Server (Web Console) + +In addition to the three core management modes mentioned above, the EasyTier GUI also supports unified configuration management through a **Configuration Server** (Web Console). + +* **Centralized Management**: In both Normal and Service modes, you can fill in the "Configuration Server" information. +* **Configuration Deployment**: Once connected successfully, the GUI will automatically synchronize configurations from the Web Console and start or stop the network based on server instructions. +* **Use Case**: Scenarios where multiple nodes need to be managed and you want to control all node configurations uniformly from a web page. + +> For more details, please refer to [Networking with Web Console (GUI)](/en/guide/gui/web-console). + +## Service Management + +In **Service Mode**, you can easily manage system services through the GUI: + +* **Install Service**: Writes the current configuration to the system service and starts it. +* **Uninstall Service**: Stops and removes the EasyTier service from the system. +* **Stop/Start**: Temporarily controls the running status of the background service. + +> [!TIP] +> It is recommended to click "Uninstall Service" in the GUI before uninstalling the EasyTier software to ensure the system is cleaned up. diff --git a/en/guide/gui/web-console.md b/en/guide/gui/web-console.md new file mode 100644 index 0000000..24be34b --- /dev/null +++ b/en/guide/gui/web-console.md @@ -0,0 +1,25 @@ +# Networking with Web Console (GUI) + +In addition to manual configuration and using public servers, the EasyTier GUI supports centralized management of nodes through the [Web Console](https://easytier.cn/web#/). This allows you to remotely deploy configurations and manage a large number of nodes uniformly. + +## Register an Account + +If you don't have a Web Console account yet, please visit the [Registration Link](https://easytier.cn/web#/auth/register) to register. + +## Configuring in the GUI + +In the EasyTier GUI main interface, you can see the "Configuration Server" option: + +1. **Enter Server Address/Username**: + - If you are using the official Web Console, simply enter your **Username**. + - If you are using a self-hosted console, enter the full server address, such as `udp://:22020/`. + +2. **Connection Status**: + - After filling it in, click "Connect" or "Start". + - The GUI will attempt to connect to the configuration server. Once connected successfully, the interface will typically show a "Connected" status and automatically synchronize the configuration assigned to the device on the server. + +## Benefits + +- **Remote Deployment**: No need to manually enter complex subnet, peer, and other information on each device; simply connect to the console to retrieve it. +- **Status Monitoring**: View the online status and topology of all GUI nodes in real-time on the Web Console web page. +- **Automatic Application**: When you modify configurations on the web page, all online GUI nodes will automatically receive and apply the new configuration without requiring a manual restart. diff --git a/en/guide/installation.md b/en/guide/installation.md index 874b761..eeba44d 100644 --- a/en/guide/installation.md +++ b/en/guide/installation.md @@ -104,3 +104,33 @@ This section only introduces installation methods. ``` Source installation requires Rust environment and LLVM installation. + +*** + +## Command Line Management Tool (easytier-cli) + +`easytier-cli` is used to manage a running `easytier-core` process. It connects to `127.0.0.1:15888` by default. + +### Basic Usage + +```bash +# View node info +easytier-cli node +# List peers +easytier-cli peer list +# List route table +easytier-cli route list +``` + +### Multi-instance Management + +If multiple network instances are running in a single `easytier-core` process (e.g., by loading multiple configuration files), you can use the `-n` or `-i` parameters to specify the target: + +```bash +# Manage via instance name (specified with -m in config or command line) +easytier-cli -n my_net_1 node +# Manage via instance ID +easytier-cli -i node +``` + +If only one instance is running in the process, `easytier-cli` will automatically select that instance. diff --git a/en/guide/network/config-file.md b/en/guide/network/config-file.md index 85e1609..c174e66 100644 --- a/en/guide/network/config-file.md +++ b/en/guide/network/config-file.md @@ -14,6 +14,47 @@ Running with parameters can generate a configuration file with the corresponding Running `easytier-core` directly without parameters will generate the minimal configuration file. +## Environment Variables in Configuration File + +EasyTier supports parsing environment variable placeholders in configuration files. This allows you to separate sensitive information (such as network secrets) from configuration files, making it easier to commit configuration files to version control systems. + +### Syntax Rules + +Standard Shell-style syntax is supported: +- `${VAR}` or `$VAR`: Use the value of the environment variable `VAR`. +- `${VAR:-default}`: If the environment variable `VAR` is not set, use `default` as the default value. +- `$$`: Escape sequence used to represent a literal `$`. For example, `$$VAR` will be parsed as `$VAR` and will not trigger environment variable replacement. + +### Usage Example + +Suppose your configuration file `config.toml` looks like this: + +```toml +[network_identity] +network_name = "my-network" +network_secret = "${ET_SECRET}" + +[[peer]] +uri = "tcp://1.1.1.1:${ET_PORT:-11010}" +``` + +Set the corresponding environment variables at startup: + +```bash +export ET_SECRET="my-secret-key" +export ET_PORT="12345" +easytier-core -c config.toml +``` + +### Security and Limitations + +::: warning Security Notes +1. **Read-only Protection**: Configuration instances that use environment variables are marked as **read-only**. You cannot remotely modify or delete these configurations through the Web Console or GUI. +2. **RPC Leakage Prevention**: To prevent sensitive information leakage, the content of read-only configurations cannot be retrieved through RPC APIs (such as `get_instance_config`). +3. **Applicability**: Environment variable parsing **only takes effect for configurations loaded from the local filesystem**. Configurations delivered remotely via Web or GUI will not parse environment variables. +4. **Disable Feature**: If you need to completely disable this feature, you can use the command-line argument `--disable-env-parsing`. +::: + ## Multiple Configuration Files Startup You can specify multiple configuration files through the `-c` parameter. EasyTier will load multiple configuration files in one process and start multiple virtual networks. @@ -22,6 +63,12 @@ You can specify multiple configuration files through the `-c` parameter. EasyTie easytier-core -c ./config1.yaml -c ./config2.yaml ``` +::: tip Note +When starting multiple virtual networks using multiple configuration files, the RPC service is shared globally. Settings such as the RPC listening port should be specified via command-line arguments (e.g., `-r`) or environment variables, rather than in individual `.toml` configuration files. +::: + +If you need more flexible configuration directory management or real-time management of multiple configurations via the Web, please refer to [Service Management & Hybrid Mode](service-mode.md). + ## Configuration File Generator The official website provides a configuration file generator, which you can access via Configuration File Generator to generate configuration files. diff --git a/en/guide/network/configurations.md b/en/guide/network/configurations.md index 0350f04..3138e44 100644 --- a/en/guide/network/configurations.md +++ b/en/guide/network/configurations.md @@ -13,9 +13,10 @@ You can use `easytier-core --help` to view all configuration options. | | - Username only: `--config-server admin`, will use the official server | | | [env: ET_CONFIG_SERVER=] | | `--machine-id` | Web configuration server identifies machines through machine id, used for configuration recovery after disconnection and reconnection, must be unique and fixed. Default obtained from system. [env: ET_MACHINE_ID=] | -| `-c, --config-file` | Configuration file path, note: options configured in command line will override options in configuration file [env: ET_CONFIG_FILE=] | +| `-c, --config-file` | Configuration file path. Supports specifying multiple configuration files (separated by commas or by using this parameter multiple times). Options configured in command line will override options in configuration file [env: ET_CONFIG_FILE=] | | `--config-dir` | Load all .toml files in the directory to start network instances, and store the received configurations in this directory. [env: ET_CONFIG_DIR=] | -| `--disable-env-parsing` | Disable environment variable parsing in config file [env: ET_DISABLE_ENV_PARSING=] | +| `--daemon` | Run in daemon mode. The process will not exit automatically even if no network instances are running. [env: ET_DAEMON=] | +| `--disable-env-parsing` | Disable environment variable parsing in the configuration file. Useful when the configuration contains many `$` symbols and you do not wish to use escape sequences. [env: ET_DISABLE_ENV_PARSING=] | ### Network Settings @@ -30,7 +31,11 @@ You can use `easytier-core --help` to view all configuration options. | `-e, --external-node` | Use public shared nodes to discover peer nodes [env: ET_EXTERNAL_NODE=] | | `-n, --proxy-networks` | Export local network to other peer nodes in VPN, e.g.: `10.0.0.0/24`. Supports mapping to other CIDR, e.g.: `10.0.0.0/24->192.168.0.0/24` [env: ET_PROXY_NETWORKS=] | -### RPC Settings +### RPC Settings (Global Parameters) + +::: tip Note +RPC settings are global and apply to the entire `easytier-core` process. When running multiple network instances in a single process, all instances share the same RPC portal. These parameters can generally only be set via command-line arguments or environment variables. +::: | Parameter | Description | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/en/guide/network/install-as-a-macos-service.md b/en/guide/network/install-as-a-macos-service.md index bade9ff..921269a 100644 --- a/en/guide/network/install-as-a-macos-service.md +++ b/en/guide/network/install-as-a-macos-service.md @@ -1,5 +1,11 @@ # Install as a macOS Service +::: tip Recommended Method +Starting from v2.5.0, it is recommended to use the `easytier-cli service install` command to register the service with one click. See [One-Click Register Service](./oneclick-install-as-service) for details. +::: + +The following is the manual installation method using the third-party tool `serviceman`: + Download and install [serviceman](https://webinstall.dev/serviceman). Open Terminal and run the following commands to register the service: diff --git a/en/guide/network/networking-without-public-ip.md b/en/guide/network/networking-without-public-ip.md index ef24233..8e56c68 100644 --- a/en/guide/network/networking-without-public-ip.md +++ b/en/guide/network/networking-without-public-ip.md @@ -24,6 +24,6 @@ After successful execution, Node A can access Node B via the virtual IP `10.144. `--ipv4 x.x.x.x` can be replaced with `-d` to enable DHCP functionality, allowing EasyTier to automatically allocate the IP address of this node based on other existing virtual IPs within the virtual network. -Nodes can connect to multiple public servers. If one public server fails, nodes can still communicate using other active public servers. Simply specify multiple `-p` parameters, such as `-p tcp://1.1.1.1:11010 -p udp://1.1.1.2:11011`. Note that each node in the virtual network must specify the same list of public servers; otherwise, networking may not function properly. +Nodes can connect to multiple public servers. If one public server fails, nodes can still communicate using other active public servers. Simply specify multiple `-p` parameters, such as `-p tcp://1.1.1.1:11010 -p udp://1.1.1.2:11010`. Note that each node in the virtual network must specify the same list of public servers; otherwise, networking may not function properly. --- diff --git a/en/guide/network/oneclick-install-as-service.md b/en/guide/network/oneclick-install-as-service.md index b273eb7..700093e 100644 --- a/en/guide/network/oneclick-install-as-service.md +++ b/en/guide/network/oneclick-install-as-service.md @@ -1,12 +1,12 @@ # One-Click Register Service -EasyTier Cli provides a service registration command that can register EasyTier as a system service with one click on most systems. After registration, EasyTier will automatically start when the system boots and run in the background. +EasyTier Cli provides a service registration command that can register EasyTier as a system service with one click on most systems (Windows, Linux, macOS). After registration, EasyTier will automatically start when the system boots and run in the background. Using this command requires `easytier-core` and `easytier-cli` to be in the same directory. After entering that directory, run the following command: ::: code-group -```sh [Linux] +```sh [Linux / macOS] # Assuming EasyTier's startup parameters are -w abc sudo ./easytier-cli service install -w abc ``` @@ -26,7 +26,7 @@ After the service is successfully installed, you can use the following commands ::: code-group - ```sh [Linux] + ```sh [Linux / macOS] sudo ./easytier-cli service start ``` @@ -40,7 +40,7 @@ After the service is successfully installed, you can use the following commands ::: code-group - ```sh [Linux] + ```sh [Linux / macOS] sudo ./easytier-cli service stop ``` @@ -54,7 +54,7 @@ After the service is successfully installed, you can use the following commands ::: code-group - ```sh [Linux] + ```sh [Linux / macOS] sudo ./easytier-cli service status ``` @@ -68,7 +68,7 @@ After the service is successfully installed, you can use the following commands ::: code-group - ```sh [Linux] + ```sh [Linux / macOS] sudo ./easytier-cli service uninstall ``` diff --git a/en/guide/network/p2p-optimize.md b/en/guide/network/p2p-optimize.md index ed463d2..427e316 100644 --- a/en/guide/network/p2p-optimize.md +++ b/en/guide/network/p2p-optimize.md @@ -13,6 +13,12 @@ You can use the `-l` option to configure the IPv6 listener. For example: easytier-core -l 'tcp://[::]:12345' -l 'udp://[::]:12345' ``` +## TCP Hole Punching + +EasyTier has introduced support for TCP hole punching. Previously, P2P connections relied primarily on UDP hole punching. However, in some network environments (such as where firewalls are strict with UDP or ISP policies cause severe UDP packet loss), TCP hole punching can serve as an effective supplement to further improve P2P success rates. + +TCP hole punching is automatically attempted between nodes without additional configuration. If your network environment strictly prohibits behaviors related to TCP hole punching, you can use the `--disable-tcp-hole-punching` parameter to disable it. + ## Specify Public IP and Port In some cases, the node has a public IP and port, but EasyTier cannot correctly identify them (e.g., NAT host). You can use the `--mapped-listeners` option to configure the public IP and port. For example: @@ -23,6 +29,16 @@ easytier-core --mapped-listeners tcp://8.8.8.8:12345 -l tcp://0.0.0.0:11010 This EasyTier instance listens on the local 11010 TCP port, and this port is mapped to the public 12345 port. Other nodes will try to connect to the public 12345 port. +## P2P-Only Mode + +In scenarios where security or latency requirements are extremely high, you may want nodes to communicate only when a P2P connection can be established, without forwarding traffic through relay nodes. You can use the `--p2p-only` parameter to enable this mode. + +```sh +easytier-core --p2p-only ... +``` + +Once enabled, if a P2P connection cannot be established between two nodes, they will not be able to communicate with each other. + ## Disable Internet Assistance Tools Some internet assistance tools may affect the results of STUN tests, causing EasyTier to fail to identify the NAT type or to identify the wrong public IP and port. You can try disabling these tools. diff --git a/en/guide/network/service-mode.md b/en/guide/network/service-mode.md new file mode 100644 index 0000000..3ae7447 --- /dev/null +++ b/en/guide/network/service-mode.md @@ -0,0 +1,52 @@ +# Service Management & Hybrid Mode + +EasyTier supports a highly flexible "service-oriented" operating mode. By combining a local configuration directory with remote management interfaces, `easytier-core` can function as a persistent system service that simultaneously manages multiple static and dynamic network instances. + +## Core Concepts + +### Hybrid Mode +In Hybrid Mode, an EasyTier node no longer relies solely on command-line arguments or a single configuration file at startup. It can: +1. **Load Local Configs**: Automatically load all configuration files from a specified directory. +2. **Accept Remote Management**: Add, modify, or stop network instances in real-time via the Web Console or GUI. **Note: The `-w ` parameter is required to connect to the Web Console for remote management (see [Using the Web Console](web-console.md)).** +3. **Persistent Service**: Even if no networks are currently running, the service process stays alive waiting for instructions as long as remote management is enabled (or the daemon flag is specified). + +### Directory-Based Configuration (`--config-dir`) +Using the `--config-dir` parameter, you can specify a folder as a configuration source. EasyTier will scan all `.toml` files in that folder and start an independent network instance for each. + +```sh +easytier-core --config-dir /etc/easytier/conf.d -w +``` + +## Remote Configuration Persistence + +When running EasyTier with `--config-dir`, network configurations pushed remotely via the Web Console or GUI are automatically persisted to that directory. + +- **Automatic Naming**: Remotely created networks are named after their UUIDs (e.g., `8e5f...toml`). +- **Resumption on Restart**: These persisted files are re-scanned and loaded upon service restart, ensuring continuous network connectivity. + +## Permissions & Security Control + +To prevent accidental modification of core configuration files, EasyTier introduces a granular permission control model. The permissions for each network instance depend on its source: + +| Source | Remote Modify (Web/GUI) | Remote Stop/Delete | Notes | +| :--- | :---: | :---: | :--- | +| **UUID files in config-dir** | ✅ | ✅ | Dynamic configs generated by remote management | +| **Single config file (`-c`)** | ✅ | ❌ | Statically specified files can be modified but not deleted remotely | +| **Read-only files / Env vars** | ❌ | ❌ | Configs marked as read-only or using `${VAR}` cannot be modified | +| **CLI args / FFI** | ❌ | ❌ | Temporarily running instances do not support remote persistence | + +::: tip Hint +If you want a manually created config file to be both remotely modifiable and deletable, place it in the `--config-dir` directory and ensure its filename matches the UUID format (or ensure it has write permissions). +::: + +## Best Practice: Running as a System Service + +It is recommended to install EasyTier as a system service (e.g., Systemd) and use it with `--config-dir`: + +1. **Install Service**: Use `easytier-cli service install` or manually configure a Systemd unit. +2. **Configuration Entry**: Add `--config-dir /etc/easytier/conf.d` to the service configuration. +3. **Dynamic Management**: From then on, you only need to operate via the Web Console. All changes will be saved locally on the server, eliminating the need to log in and modify Systemd settings again. + +::: tip GUI User Hint +If you are using EasyTier GUI, you do not need to manually configure the command line. The GUI has a built-in "Service Mode" that supports one-click installation, uninstallation, and management of system services. For more details, please refer to [GUI Running Modes](/en/guide/gui/modes). +::: diff --git a/en/guide/network/web-console.md b/en/guide/network/web-console.md index 2d4a21b..b99fd2b 100644 --- a/en/guide/network/web-console.md +++ b/en/guide/network/web-console.md @@ -29,7 +29,7 @@ Please ensure the machine code is unique and unchanged across all devices. **It ::: ::: danger Note -Only one EasyTier process on a machine can be managed by the Web Console. Having multiple processes may cause unexpected issues. +Only one EasyTier process can be managed by the Web console on a single machine. If you need to run multiple virtual networks, please start them within the same process by loading multiple configuration files (using multiple `-c` parameters), or use the more advanced [Config Directory Mode](service-mode.md). ::: ::: tip Note @@ -57,6 +57,10 @@ Configure The subsequent configuration steps are the same as configuring a program with a GUI. +::: tip Note +If you prefer to use a graphical interface to connect to the Web Console, please refer to [Networking with Web Console (GUI)](/en/guide/gui/web-console). +::: + # Self-Hosted Web Console EasyTier supports self-hosting a web console for managing EasyTier nodes. The EasyTier Web Console adopts a separated front-end and back-end architecture, consisting of 3 services in design: diff --git a/guide/gui/basic.md b/guide/gui/basic.md new file mode 100644 index 0000000..1b88679 --- /dev/null +++ b/guide/gui/basic.md @@ -0,0 +1,15 @@ +# 公共服务器组网 + +GUI 默认使用官方共享节点组网，方便没有公网 IP 的朋友组网。大部分情况可以打洞 P2P 成功，若无法 P2P 成功，节点间带宽可能会比较低。 + +配置方法如图所示。 + +![配置界面](/assets/cn/config.png) + +配置完成后点击运行网络按钮即可，运行网络成功后的界面如图 + +![running](/assets/cn/running.png) + +## 运行模式 + +从 v2.5.0 版本开始，GUI 支持多种运行模式（普通、服务、远程）。如果你希望退出 GUI 后网络依然保持连接，或者管理远程服务器，请参考 [GUI 运行模式](/guide/gui/modes)。 diff --git a/guide/gui/modes.md b/guide/gui/modes.md new file mode 100644 index 0000000..b8457d0 --- /dev/null +++ b/guide/gui/modes.md @@ -0,0 +1,46 @@ +# GUI 运行模式 + +EasyTier GUI 支持三种运行模式，允许用户根据不同场景灵活部署和管理 EasyTier 核心。 + +## 运行模式介绍 + +在 GUI 界面的底部，你可以看到模式切换器。 + +![模式切换](/assets/cn/mode_switcher.png) + +### 1. 普通模式 (Normal) +* **说明**：这是默认模式。EasyTier 核心作为 GUI 的子进程运行。 +* **行为**：当你关闭 GUI 时，EasyTier 网络连接也会随之断开。 +* **适用场景**：临时组网，随用随开。 + +### 2. 服务模式 (Service) +* **说明**：将 EasyTier 安装为原生系统服务（Windows 服务、systemd 等）。 +* **行为**：EasyTier 将在后台持久运行。即使你关闭 GUI 或注销登录，网络依然保持连接。支持开机自启。 +* **适用场景**：需要长期稳定在线的服务器或个人电脑。 +* **注意事项**：在 Windows 平台上，如果正在运行服务模式，更新软件前可能需要先在 GUI 中停止服务。 + +### 3. 远程模式 (Remote) +* **说明**：GUI 仅作为管理终端，通过 RPC 连接到远程机器上的 EasyTier 实例。 +* **行为**：你可以管理无显示器服务器上的 EasyTier，查看状态或修改配置。 +* **配置**：需要输入远程节点的 IP 地址和 RPC 端口（默认 15713）。 + +## 配置服务器 (Web 控制台) + +除了上述三种核心管理模式，EasyTier GUI 还支持通过 **配置服务器**（即 Web 控制台）来统一管理配置。 + +* **集中管理**：在普通模式或服务模式下，你都可以填写“配置服务器”信息。 +* **配置下发**：一旦连接成功，GUI 将自动同步来自 Web 控制台的配置，并根据服务器指令启动或停止网络。 +* **适用场景**：需要管理多个节点，且希望在网页端统一控制所有节点配置的场景。 + +> 详情请参阅 [使用 Web 控制台组网 (GUI)](/guide/gui/web-console)。 + +## 服务管理 + +在 **服务模式** 下，你可以通过 GUI 方便地管理系统服务： + +* **安装服务**：将当前配置写入系统服务并启动。 +* **卸载服务**：停止并从系统中移除 EasyTier 服务。 +* **停止/启动**：临时控制后台服务的运行状态。 + +> [!TIP] +> 建议在卸载 EasyTier 软件之前，先在 GUI 中点击“卸载服务”，以确保系统清理干净。 diff --git a/guide/gui/web-console.md b/guide/gui/web-console.md new file mode 100644 index 0000000..d6edc70 --- /dev/null +++ b/guide/gui/web-console.md @@ -0,0 +1,25 @@ +# 使用 Web 控制台组网 (GUI) + +除了手动配置和使用公共服务器，EasyTier GUI 还支持通过 [Web 控制台](https://easytier.cn/web#/) 来实现节点的集中化管理。通过这种方式，你可以远程下发配置，实现大批量节点的统一管控。 + +## 注册账号 + +如果你还没有 Web 控制台账号，请先访问 [注册地址](https://easytier.cn/web#/auth/register) 完成注册。 + +## 在 GUI 中配置 + +在 EasyTier GUI 主界面中，你可以看到“配置服务器”这一选项： + +1. **输入服务器地址/用户名**： + - 如果你使用的是官方 Web 控制台，直接输入你的 **用户名** 即可。 + - 如果你使用的是私有部署的控制台，请输入完整的服务器地址，例如 `udp://:22020/`。 + +2. **连接状态**： + - 填写完成后，点击“连接”或“启动”。 + - GUI 会尝试连接到配置服务器。连接成功后，界面通常会显示“已连接”状态，并自动同步服务器上为该设备分配的配置。 + +## 优势 + +- **远程下发**：无需在每台设备上手动输入复杂的子网、Peer 等信息，只需连接控制台即可获取。 +- **状态监控**：在 Web 控制台网页端可以实时查看所有 GUI 节点的在线状态和拓扑结构。 +- **自动应用**：当你在网页端修改配置后，所有在线的 GUI 节点会自动接收并应用新配置，无需手动重启。 diff --git a/guide/installation.md b/guide/installation.md index db66f79..711dc46 100644 --- a/guide/installation.md +++ b/guide/installation.md @@ -112,3 +112,33 @@ easytier-core --gen-autocomplete fish > ~/.config/fish/completions/easytier-core.fish easytier-cli gen-autocomplete fish > ~/.config/fish/completions/easytier-core.fish ``` + +*** + +## 命令行管理工具 (easytier-cli) + +`easytier-cli` 用于管理正在运行的 `easytier-core` 进程。它默认连接到 `127.0.0.1:15888`。 + +### 基本用法 + +```bash +# 查看节点信息 +easytier-cli node +# 查看对等节点 +easytier-cli peer list +# 查看路由表 +easytier-cli route list +``` + +### 多实例管理 + +如果一个 `easytier-core` 进程中运行了多个网络实例（例如通过加载多个配置文件），你可以使用 `-n` 或 `-i` 参数指定操作目标： + +```bash +# 通过实例名称管理（在配置文件或命令行中使用 -m 指定） +easytier-cli -n my_net_1 node +# 通过实例 ID 管理 +easytier-cli -i node +``` + +如果进程中仅有一个实例，`easytier-cli` 会自动选择该实例。 diff --git a/guide/network/config-file.md b/guide/network/config-file.md index 457b537..ccd034d 100644 --- a/guide/network/config-file.md +++ b/guide/network/config-file.md @@ -14,6 +14,47 @@ easytier-core -c ./config.yaml 在不使用参数的情况下直接运行 `easytier-core` 可以获得最小配置文件。 +## 在配置文件中使用环境变量 + +EasyTier 支持在配置文件中解析环境变量占位符。这使得您可以将敏感信息（如网络密钥）与配置文件分离，方便将配置文件提交到版本控制系统。 + +### 语法规则 + +支持标准 Shell 风格的语法： +- `${VAR}` 或 `$VAR`：使用环境变量 `VAR` 的值。 +- `${VAR:-default}`：如果环境变量 `VAR` 未设置，则使用 `default` 作为默认值。 +- `$$`：转义符，用于表示字面量 `$`。例如 `$$VAR` 会被解析为 `$VAR` 而不会触发环境变量替换。 + +### 使用示例 + +假设您的配置文件 `config.toml` 内容如下： + +```toml +[network_identity] +network_name = "my-network" +network_secret = "${ET_SECRET}" + +[[peer]] +uri = "tcp://1.1.1.1:${ET_PORT:-11010}" +``` + +在启动时设置对应的环境变量： + +```bash +export ET_SECRET="my-secret-key" +export ET_PORT="12345" +easytier-core -c config.toml +``` + +### 安全与限制 + +::: warning 安全须知 +1. **只读保护**：使用了环境变量的配置实例会被标记为**只读**。您无法通过 Web 控制台或 GUI 远程修改或删除该配置。 +2. **RPC 泄露防护**：为了防止敏感信息泄露，只读配置的内容无法通过 RPC API（如 `get_instance_config`）获取。 +3. **适用范围**：环境变量解析**仅对从本地文件系统加载的配置生效**。通过 Web 或 GUI 远程下发的配置不会解析环境变量。 +4. **禁用功能**：如果需要完全禁用此功能，可以使用命令行参数 `--disable-env-parsing`。 +::: + ## 多配置文件启动 可以通过 `-c` 参数指定多个配置文件，EasyTier 会在一个进程中加载多个配置文件并启动多个虚拟网络。 @@ -22,6 +63,11 @@ easytier-core -c ./config.yaml easytier-core -c ./config1.yaml -c ./config2.yaml ``` +::: tip 提示 +当使用多个配置文件启动多个虚拟网络时，RPC 服务是全局共享的。RPC 监听端口等设置应通过命令行参数（如 `-r`）或环境变量指定，而不应在单个 `.toml` 配置文件中定义。 +::: + +如果需要更灵活的配置目录管理或通过 Web 实时管理多个配置，请参考[服务管理与混合模式](service-mode.md)。 ## 配置文件生成工具 diff --git a/guide/network/configurations.md b/guide/network/configurations.md index 9d09327..66b3b04 100644 --- a/guide/network/configurations.md +++ b/guide/network/configurations.md @@ -13,9 +13,10 @@ | | - 仅用户名：`--config-server admin`，将使用官方的服务器 | | | [env: ET_CONFIG_SERVER=] | | `--machine-id` | Web 配置服务器通过 machine id 来识别机器，用于断线重连后的配置恢复，需要保证唯一且固定不变。默认从系统获得。 [env: ET_MACHINE_ID=] | -| `-c, --config-file` | 配置文件路径，注意：命令行中的配置的选项会覆盖配置文件中的选项 [env: ET_CONFIG_FILE=] | +| `-c, --config-file` | 配置文件路径，支持指定多个配置文件（使用逗号分隔或多次使用此参数）。命令行中的配置的选项会覆盖配置文件中的选项 [env: ET_CONFIG_FILE=] | | `--config-dir` | 加载目录中的所有 .toml 文件以启动网络实例，并将下发的配置保存在此目录中。 [env: ET_CONFIG_DIR=] | -| `--disable-env-parsing` | 禁用配置文件中的环境变量解析 [env: ET_DISABLE_ENV_PARSING=] | +| `--daemon` | 以守护进程模式运行。即使没有运行任何网络实例，进程也不会自动退出。 [env: ET_DAEMON=] | +| `--disable-env-parsing` | 禁用配置文件中的环境变量解析。适用于配置文件中包含大量 `$` 符号且不希望使用转义的场景。 [env: ET_DISABLE_ENV_PARSING=] | ### 网络设置 @@ -30,7 +31,11 @@ | `-e, --external-node` | 使用公共共享节点来发现对等节点 [env: ET_EXTERNAL_NODE=] | | `-n, --proxy-networks` | 将本地网络导出到VPN中的其他对等节点，例如：`10.0.0.0/24`。支持映射到其他CIDR，例如：`10.0.0.0/24->192.168.0.0/24` [env: ET_PROXY_NETWORKS=] | -### RPC 设置 +### RPC 设置 (全局参数) + +::: tip 提示 +RPC 设置是全局性的，应用于整个 `easytier-core` 进程。在一个进程中运行多个网络实例时，所有实例共享同一个 RPC 门户。这些参数通常只能通过命令行参数或环境变量设置。 +::: | 参数 | 说明 | | ------------------------ | ------------------------------------------------------------------------------------------------------------------ | diff --git a/guide/network/install-as-a-macos-service.md b/guide/network/install-as-a-macos-service.md index 22fb181..31655d0 100644 --- a/guide/network/install-as-a-macos-service.md +++ b/guide/network/install-as-a-macos-service.md @@ -1,5 +1,11 @@ # 安装为 macOS 服务 +::: tip 推荐方式 +从 v2.5.0 开始，推荐使用 `easytier-cli service install` 命令一键注册服务，详见 [一键注册服务](./oneclick-install-as-service)。 +::: + +以下是使用第三方工具 `serviceman` 的手动安装方式： + 下载并安装 [serviceman](https://webinstall.dev/serviceman)。 打开终端，运行如下命令注册服务： diff --git a/guide/network/networking-without-public-ip.md b/guide/network/networking-without-public-ip.md index d92398a..9b44c62 100644 --- a/guide/network/networking-without-public-ip.md +++ b/guide/network/networking-without-public-ip.md @@ -23,6 +23,6 @@ sudo easytier-core --ipv4 10.144.144.2 --network-name abc --network-secret abc - `--ipv4 x.x.x.x` 可以替换为 `-d` 开启 DHCP 功能，由 EasyTier 根据虚拟网内已经存在的其他虚拟 IP 自动的分配本节点的 IP 地址。 -节点可以连接到多个公共服务器，当其中一个公共服务器失效后，节点间依然可以使用其他存活的公共服务器通信。只需要指定多个 -p 参数即可，如：`-p tcp://1.1.1.1:11010 -p udp://1.1.1.2:11011`。需要注意，虚拟网中每个节点都要指定相同的公共服务器列表，否则可能无法正常组网。 +节点可以连接到多个公共服务器，当其中一个公共服务器失效后，节点间依然可以使用其他存活的公共服务器通信。只需要指定多个 -p 参数即可，如：`-p tcp://1.1.1.1:11010 -p udp://1.1.1.2:11010`。需要注意，虚拟网中每个节点都要指定相同的公共服务器列表，否则可能无法正常组网。 --- diff --git a/guide/network/oneclick-install-as-service.md b/guide/network/oneclick-install-as-service.md index 5aaeed1..6da5a9d 100644 --- a/guide/network/oneclick-install-as-service.md +++ b/guide/network/oneclick-install-as-service.md @@ -1,12 +1,12 @@ # 一键注册服务 -EasyTier Cli 提供注册服务命令，可以在大部分系统上一键将 EasyTier 注册为系统服务。注册后，EasyTier 会在系统启动时自动启动，并在后台运行。 +EasyTier Cli 提供注册服务命令，可以在大部分系统（Windows, Linux, macOS）上一键将 EasyTier 注册为系统服务。注册后，EasyTier 会在系统启动时自动启动，并在后台运行。 使用该命令需要 `easytier-core` 和 `easytier-cli` 在同一目录下。进入该目录后，运行以下命令： ::: code-group -```sh [Linux] +```sh [Linux / macOS] # 假设 EasyTier 的启动参数为 -w abc sudo ./easytier-cli service install -w abc ``` @@ -22,7 +22,7 @@ sudo ./easytier-cli service install -w abc 完整示例: ::: code-group -```sh [Linux] +```sh [Linux / macOS] # 假设 EasyTier 的启动参数为 -w abc sudo ./easytier-cli service install \ --description "自定义服务描述" \ # 可选，默认使用包描述 @@ -51,7 +51,7 @@ sudo ./easytier-cli service install \ ::: code-group - ```sh [Linux] + ```sh [Linux / macOS] sudo ./easytier-cli service start ``` @@ -65,7 +65,7 @@ sudo ./easytier-cli service install \ ::: code-group - ```sh [Linux] + ```sh [Linux / macOS] sudo ./easytier-cli service stop ``` @@ -79,7 +79,7 @@ sudo ./easytier-cli service install \ ::: code-group - ```sh [Linux] + ```sh [Linux / macOS] sudo ./easytier-cli service status ``` @@ -93,7 +93,7 @@ sudo ./easytier-cli service install \ ::: code-group - ```sh [Linux] + ```sh [Linux / macOS] sudo ./easytier-cli service uninstall ``` diff --git a/guide/network/p2p-optimize.md b/guide/network/p2p-optimize.md index 84e9a0e..3910d31 100644 --- a/guide/network/p2p-optimize.md +++ b/guide/network/p2p-optimize.md @@ -22,6 +22,12 @@ easytier-core -l 'tcp://[::]:12345' -l 'udp://[::]:12345' 如果您的 IPv6 使用了 NAT66 技术，即网络地址转换技术，可以参考 IPv4 部分，如果可以的话建议关闭 NAT66 技术。 +## TCP 打洞 + +EasyTier 引入了 TCP 打洞支持。此前 P2P 连接主要依赖 UDP 打洞，但在某些网络环境下（如防火墙对 UDP 限制严格、或者由于运营商策略导致 UDP 严重丢包），TCP 打洞可以作为有效的补充，进一步提高 P2P 成功率。 + +TCP 打洞会自动在节点之间尝试，无需额外配置。如果您的网络环境完全禁止 TCP 打洞相关的行为，可以使用 `--disable-tcp-hole-punching` 参数将其禁用。 + ## IPv4 如果您的节点拥有公网 IPv4 地址，并且可以入站（即被外网访问），就可以通过监听地址+默认监听端口(11010)来建立 P2P 连接。 @@ -66,6 +72,16 @@ easytier-core --mapped-listeners tcp://8.8.8.8:12345 -l tcp://0.0.0.0:11010 该 EasyTier 实例监听本地的 11010 TCP 端口，且该端口被映射到公网的 12345 端口。其他节点会尝试连接到公网的 12345 端口。 +## 仅 P2P 模式 + +在某些对安全性或延迟要求极高的场景下，您可能希望节点仅在能够建立 P2P 连接时才进行通信，而不通过中转节点转发流量。可以使用 `--p2p-only` 参数开启此模式。 + +```sh +easytier-core --p2p-only ... +``` + +开启后，如果两个节点之间无法建立 P2P 连接，它们将无法互相通信。 + ## 关闭上网辅助工具 一些上网辅助工具会影响 STUN 测试的结果，导致 EasyTier 无法识别 NAT 类型，或者识别到错误的公网 IP 和端口。可以尝试关闭这些工具。 diff --git a/guide/network/service-mode.md b/guide/network/service-mode.md new file mode 100644 index 0000000..a92f6cb --- /dev/null +++ b/guide/network/service-mode.md @@ -0,0 +1,52 @@ +# 服务管理与混合模式 + +EasyTier 支持一种高度灵活的“服务化”运行模式。通过结合本地配置文件目录和远程管理接口，`easytier-core` 可以作为一个持久运行的系统服务，同时管理多个静态和动态的网络实例。 + +## 核心概念 + +### 混合模式 (Hybrid Mode) +在混合模式下，EasyTier 节点不再仅仅依赖于启动时的命令行参数或单个配置文件。它可以： +1. **加载本地配置**：自动加载指定目录下的所有配置文件。 +2. **接受远程管理**：通过 Web 控制台或 GUI 实时添加、修改或停止网络实例。**注意：必须配合 `-w <用户名>` 参数才能连接到 Web 控制台进行远程管理（详见 [使用 Web 控制台](web-console.md)）。** +3. **服务常驻**：即使没有任何网络正在运行，只要开启了远程管理（或指定了守护进程标志），服务进程也会保持运行，等待指令。 + +### 目录级配置加载 (`--config-dir`) +通过 `--config-dir` 参数，你可以指定一个文件夹作为配置源。EasyTier 会扫描该文件夹下所有的 `.toml` 文件并为每个文件启动一个独立的网络实例。 + +```sh +easytier-core --config-dir /etc/easytier/conf.d -w <用户名> +``` + +## 远程配置持久化 + +当使用 `--config-dir` 运行 EasyTier 时，通过 Web 控制台或 GUI 远程下发的配置将自动持久化到该目录下。 + +- **自动命名**：远程创建的网络会以其 UUID 命名（如 `8e5f...toml`）。 +- **重启恢复**：服务重启后，这些持久化文件会被重新扫描并加载，确保网络连接的连续性。 + +## 权限与安全性控制 + +为了防止意外修改核心配置文件，EasyTier 引入了精细的权限控制模型。每个网络实例的权限取决于其来源： + +| 配置来源 | 远程修改 (Web/GUI) | 远程停止/删除 | 说明 | +| :--- | :---: | :---: | :--- | +| **配置目录中的 UUID 文件** | ✅ | ✅ | 由远程管理端生成的动态配置 | +| **单个配置文件 (`-c`)** | ✅ | ❌ | 静态指定的文件允许修改，但不能被远程删除 | +| **只读文件 / 环境变量** | ❌ | ❌ | 文件系统标记为只读或使用了 `${VAR}` 的配置不可修改 | +| **命令行参数 / FFI** | ❌ | ❌ | 临时运行的实例不支持远程持久化修改 | + +::: tip 提示 +如果你希望某个手动创建的配置文件既能被远程修改也能被远程删除，请将其放置在 `--config-dir` 目录下，并确保其文件名符合 UUID 格式（或确保其拥有写权限）。 +::: + +## 最佳实践：作为系统服务运行 + +建议将 EasyTier 安装为系统服务（如 Systemd），并配合 `--config-dir` 使用： + +1. **安装服务**：使用 `easytier-cli service install` 或手动配置 Systemd 单元。 +2. **配置入口**：在 Service 配置中加入 `--config-dir /etc/easytier/conf.d`。 +3. **动态管理**：之后你只需在 Web 控制台操作，所有变更都会同步保存到服务器本地，无需再次登录服务器修改 Systemd 配置。 + +::: tip GUI 用户提示 +如果你正在使用 EasyTier GUI，则不需要手动配置命令行。GUI 已内置了“服务模式”，支持在界面中一键安装、卸载和管理系统服务。详情请参考 [GUI 运行模式](/guide/gui/modes)。 +::: diff --git a/guide/network/web-console.md b/guide/network/web-console.md index fe27110..f874265 100644 --- a/guide/network/web-console.md +++ b/guide/network/web-console.md @@ -29,7 +29,7 @@ sudo ./easytier-core -w <你的用户名> --machine-id abc123 ::: ::: danger 注意 -一台机器只能有一个 EasyTier 进程被 Web 控制台管理，如果有多个进程可能会导致奇怪的问题。 +一台机器只能有一个 EasyTier 进程被 Web 控制台管理。如果您需要运行多个虚拟网络，请在同一个进程中通过加载多个配置文件（使用多个 `-c` 参数）来启动，或者使用更高级的[配置目录模式](service-mode.md)。 ::: ::: tip 提示 @@ -57,6 +57,10 @@ sudo ./easytier-core -w <你的用户名> --machine-id abc123 接下来的配置步骤与之前配置带 GUI 的程序相同。 +::: tip 提示 +如果你更倾向于使用图形界面来连接 Web 控制台，请参考 [使用 Web 控制台组网 (GUI)](/guide/gui/web-console)。 +::: + # 自建 Web 控制台 EasyTier 支持自建 Web 控制台来管理 EasyTier 节点，EasyTier Web 控制台采用前后端分离的架构，在设计上共有3个服务