Skip to content

docs: document logging configuration and fix dev-server white screen #313

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
KKRainbow merged 3 commits into from
Aug 18, 2026
+127 −16
Merged

docs: document logging configuration and fix dev-server white screen #313

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f7df80a
docs: expand logging settings section in configurations
KKRainbow Aug 18, 2026
6438f27
fix: avoid dev-server white screen caused by mermaid CJS deps
KKRainbow Aug 18, 2026
61264de
docs(configurations): flatten section structure so outline shows all …
KKRainbow Aug 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .vitepress/config/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@ import { en } from './en'

export default withMermaid({
base: '/',
vite: {
optimizeDeps: { include: ['mermaid'] },
},
lastUpdated: true,
head: [
['link', { rel: 'icon', type: 'image/png', sizes: '32x32', href: '/easytier.png' }],
Expand Down
70 changes: 62 additions & 8 deletions en/guide/network/configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
---
outline: deep
---

# Complete Configuration Options

You can use `easytier-core --help` to view all configuration options.

## Basic Settings

### Configuration Server
## Configuration Server

| Parameter | Description |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -17,7 +19,7 @@ You can use `easytier-core --help` to view all configuration options.
| `--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=] |

### Network Settings
## Network Settings

| Parameter | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -30,7 +32,7 @@ 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

| Parameter | Description |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -42,7 +44,7 @@ You can use `easytier-core --help` to view all configuration options.
| | [env: ET_RPC_PORTAL=] |
| `--rpc-portal-whitelist` | RPC portal whitelist, only allow these addresses to access RPC portal, e.g.: `127.0.0.1/32,127.0.0.0/8,::1/128` [env: ET_RPC_PORTAL_WHITELIST=] |

### Listener Settings
## Listener Settings

| Parameter | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -54,7 +56,7 @@ You can use `easytier-core --help` to view all configuration options.
| `--mapped-listeners` | Manually specify the public address of the listener, other nodes can use this address to connect to this node. E.g.: `tcp://123.123.123.123:11223`, can specify multiple. [env: ET_MAPPED_LISTENERS=] |
| `--no-listener` | Don't listen on any port, only connect to peer nodes [env: ET_NO_LISTENER=] |

### Other Settings
## Other Settings

| Parameter | Description |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand Down Expand Up @@ -105,7 +107,7 @@ You can use `easytier-core --help` to view all configuration options.
| `--stun-servers` | Override default STUN servers; If configured but empty, STUN servers are not used [env: ET_STUN_SERVERS=] |
| `--stun-servers-v6` | Override default STUN servers, IPv6; If configured but empty, IPv6 STUN servers are not used [env: ET_STUN_SERVERS_V6=] |

### Logging Settings
## Logging Settings

| Parameter | Description |
| --------------------- | ------------------------------------------------------------------ |
Expand All @@ -115,6 +117,58 @@ You can use `easytier-core --help` to view all configuration options.
| `--file-log-size` | Per file log size in MB, default is 100MB [env: ET_FILE_LOG_SIZE=] |
| `--file-log-count` | Max file log count, default is 10 [env: ET_FILE_LOG_COUNT=] |

Logging is process-level configuration, set via command-line flags or environment variables. It cannot be set in the `-c` config file: the logger is initialized at process startup, before any config files are loaded, and one process can host several network instances via multiple `-c` files, so logging options apply to the whole process.

### Default Behavior

By default EasyTier only prints `info`-level logs from the core module to the console, and file logging is disabled.

### Console Log Level

Set the console log level with `--console-log-level` (or the `ET_CONSOLE_LOG_LEVEL` environment variable). Valid values: `trace`, `debug`, `info`, `warn`, `error`, `off`.

```sh
easytier-core --console-log-level debug
ET_CONSOLE_LOG_LEVEL=debug easytier-core
```

You can also use the `RUST_LOG` environment variable for fine-grained per-target control, e.g. debug for the core module and disabled for hyper:

```sh
RUST_LOG=warn,easytier_core=debug,hyper=off easytier-core
```

`RUST_LOG` overrides the console log level and also applies to file logging.

### File Logging

File logging is disabled by default. It is enabled as soon as you set `--file-log-level` (or the `ET_FILE_LOG_LEVEL` environment variable) to anything other than `off`, writing to `easytier.log` in the process working directory by default:

```sh
easytier-core --file-log-level info
```

The remaining options are optional:

| Parameter | Description |
| --------------------- | ----------------------------------------------- |
| `--file-log-dir` | Directory for log files, default is the working directory |
| `--file-log-size` | Max size per file in MB, default is 100 |
| `--file-log-count` | Number of log files to keep, default is 10 |

Log files rotate daily and are cleaned up automatically once the size or count limit is reached.

### Adjusting the Log Level at Runtime

While the process is running you can inspect or change the log level over RPC:

```sh
easytier-cli logger # show the current configuration
easytier-cli logger set debug # set the level
```

`easytier-cli logger set` accepts `disabled`, `error`, `warning`, `info`, `debug`, `trace` and adjusts the file log level.

---

For more configuration options, please refer to the output of `easytier-core --help`.
Expand Down
70 changes: 62 additions & 8 deletions guide/network/configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
---
outline: deep
---

# 完整配置选项

可使用 `easytier-core --help` 查看全部配置项。

## 基本设置

### 配置服务器
## 配置服务器

| 参数 | 说明 |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -17,7 +19,7 @@
| `--config-dir` | 加载目录中的所有 .toml 文件以启动网络实例，并将下发的配置保存在此目录中。 [env: ET_CONFIG_DIR=] |
| `--disable-env-parsing` | 禁用配置文件中的环境变量解析 [env: ET_DISABLE_ENV_PARSING=] |

### 网络设置
## 网络设置

| 参数 | 说明 |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -35,7 +37,7 @@
| `-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 设置

| 参数 | 说明 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------ |
Expand All @@ -47,7 +49,7 @@
| | [env: ET_RPC_PORTAL=] |
| `--rpc-portal-whitelist` | RPC门户白名单，仅允许这些地址访问RPC门户，例如：`127.0.0.1/32,127.0.0.0/8,::1/128` [env: ET_RPC_PORTAL_WHITELIST=] |

### 监听器设置
## 监听器设置

| 参数 | 说明 |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -59,7 +61,7 @@
| `--mapped-listeners` | 手动指定监听器的公网地址，其他节点可以使用该地址连接到本节点。例如：`tcp://123.123.123.123:11223`，可以指定多个。 [env: ET_MAPPED_LISTENERS=] |
| `--no-listener` | 不监听任何端口，只连接到对等节点 [env: ET_NO_LISTENER=] |

### 其他设置
## 其他设置

| 参数 | 说明 |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
Expand Down Expand Up @@ -110,7 +112,7 @@
| `--stun-servers` | 覆盖内置的默认 STUN server 列表；如果设置了但是为空，则不使用 STUN servers；如果没设置，则使用默认 STUN server 列表 [env: ET_STUN_SERVERS=] |
| `--stun-servers-v6` | 覆盖内置的默认 IPv6 STUN server 列表；如果设置了但是为空，则不使用 IPv6 STUN servers；如果没设置，则使用默认 IPv6 STUN server 列表 [env: ET_STUN_SERVERS_V6=] |

### 日志设置
## 日志设置

| 参数 | 说明 |
| --------------------- | ------------------------------------------------------------------ |
Expand All @@ -120,6 +122,58 @@
| `--file-log-size` | 单个文件日志大小，单位 MB，默认值为 100MB [env: ET_FILE_LOG_SIZE=] |
| `--file-log-count` | 最大文件日志数量，默认值为 10 [env: ET_FILE_LOG_COUNT=] |

日志配置属于进程级配置，通过命令行参数或环境变量设置，不支持写在 `-c` 指定的配置文件中。原因是日志系统在进程启动时、加载任何配置文件之前就已初始化，且同一个进程可以通过多个 `-c` 配置文件运行多个网络实例，因此日志选项只作用于整个进程。

### 默认行为

默认情况下，EasyTier 只向控制台输出 core 模块的 `info` 级别日志，文件日志处于关闭状态。

### 控制台日志级别

通过 `--console-log-level`（或环境变量 `ET_CONSOLE_LOG_LEVEL`）设置控制台日志级别，可选值：`trace`、`debug`、`info`、`warn`、`error`、`off`。

```sh
easytier-core --console-log-level debug
ET_CONSOLE_LOG_LEVEL=debug easytier-core
```

也可以使用 `RUST_LOG` 环境变量按目标（target）精细控制日志，例如仅对 core 模块输出 debug、关闭 hyper 的日志：

```sh
RUST_LOG=warn,easytier_core=debug,hyper=off easytier-core
```

`RUST_LOG` 会覆盖控制台日志级别，同样作用于文件日志。

### 文件日志

文件日志默认关闭，设置 `--file-log-level`（或环境变量 `ET_FILE_LOG_LEVEL`）为除 `off` 之外的级别即会开启，默认写入进程工作目录下的 `easytier.log`：

```sh
easytier-core --file-log-level info
```

其余参数均为可选：

| 参数 | 说明 |
| ------------------- | ----------------------------------- |
| `--file-log-dir` | 日志文件目录，默认当前目录 |
| `--file-log-size` | 单个日志文件大小上限（MB），默认 100 |
| `--file-log-count` | 保留的日志文件数量，默认 10 |

日志文件按天滚动轮转，超过大小上限或数量限制后会自动清理旧文件。

### 运行时调整日志级别

进程运行期间可通过 RPC 查看或修改日志级别：

```sh
easytier-cli logger # 查看当前配置
easytier-cli logger set debug # 设置级别
```

`easytier-cli logger set` 的合法值为 `disabled`、`error`、`warning`、`info`、`debug`、`trace`，调整的是文件日志级别。

---

更多配置项请参考 `easytier-core --help` 输出。
Expand Down