From f7df80afeee3d0916382ba80034554306eb9d7c5 Mon Sep 17 00:00:00 2001 From: "sijie.sun" Date: Tue, 18 Aug 2026 21:07:12 +0800 Subject: [PATCH 1/3] docs: expand logging settings section in configurations The configuration page only listed the logging flags as a table without any explanation. Add usage details covering: - default behavior (console prints core info only, file logging off) - setting the console level via --console-log-level / ET_CONSOLE_LOG_LEVEL and the RUST_LOG per-target filter syntax - enabling file logging with --file-log-level (non-off), the optional --file-log-dir / --file-log-size / --file-log-count knobs and daily rotation - adjusting the file log level at runtime with easytier-cli logger set/get - why logging options are process-level and cannot be put in the -c config file Applies to both the Chinese and English versions. --- en/guide/network/configurations.md | 52 ++++++++++++++++++++++++++++++ guide/network/configurations.md | 52 ++++++++++++++++++++++++++++++ 2 files changed, 104 insertions(+) diff --git a/en/guide/network/configurations.md b/en/guide/network/configurations.md index 659984a..b4b1511 100644 --- a/en/guide/network/configurations.md +++ b/en/guide/network/configurations.md @@ -115,6 +115,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`. diff --git a/guide/network/configurations.md b/guide/network/configurations.md index 06b6942..5326276 100644 --- a/guide/network/configurations.md +++ b/guide/network/configurations.md @@ -120,6 +120,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` 输出。 From 6438f27b5a36ec0384da6e167e46f55df9389a5e Mon Sep 17 00:00:00 2001 From: "sijie.sun" Date: Tue, 18 Aug 2026 21:17:33 +0800 Subject: [PATCH 2/3] fix: avoid dev-server white screen caused by mermaid CJS deps In dev mode vite serves node_modules sources as-is unless they are prebundled. mermaid 11 imports { sanitizeUrl } from the pure-CJS @braintree/sanitize-url package, which fails to load natively in the browser and crashes the whole page (white screen). Build output is unaffected because rollup converts the CJS dependency during bundling. Add vite.optimizeDeps.include for mermaid so the dev server prebundles it and its CJS dependencies with esbuild. --- .vitepress/config/index.ts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.vitepress/config/index.ts b/.vitepress/config/index.ts index 884cd03..91e2e2a 100644 --- a/.vitepress/config/index.ts +++ b/.vitepress/config/index.ts @@ -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' }], From 61264debe2f4f8ffe97f0e707b42c8e18e8a2463 Mon Sep 17 00:00:00 2001 From: "sijie.sun" Date: Tue, 18 Aug 2026 21:22:04 +0800 Subject: [PATCH 3/3] docs(configurations): flatten section structure so outline shows all groups The page had a single h2 (Basic Settings) wrapping every parameter group as h3, so the on-page outline only listed that one entry. Promote each parameter group (configuration server, network, RPC, listener, other, logging) to its own h2 and enable outline: deep so the logging sub-topics also appear. Applies to both the Chinese and English pages. --- en/guide/network/configurations.md | 18 ++++++++++-------- guide/network/configurations.md | 18 ++++++++++-------- 2 files changed, 20 insertions(+), 16 deletions(-) diff --git a/en/guide/network/configurations.md b/en/guide/network/configurations.md index b4b1511..3122841 100644 --- a/en/guide/network/configurations.md +++ b/en/guide/network/configurations.md @@ -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 | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -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 | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -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 | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | @@ -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 | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -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 | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -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 | | --------------------- | ------------------------------------------------------------------ | diff --git a/guide/network/configurations.md b/guide/network/configurations.md index 5326276..9378673 100644 --- a/guide/network/configurations.md +++ b/guide/network/configurations.md @@ -1,10 +1,12 @@ +--- +outline: deep +--- + # 完整配置选项 可使用 `easytier-core --help` 查看全部配置项。 -## 基本设置 - -### 配置服务器 +## 配置服务器 | 参数 | 说明 | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | @@ -17,7 +19,7 @@ | `--config-dir` | 加载目录中的所有 .toml 文件以启动网络实例，并将下发的配置保存在此目录中。 [env: ET_CONFIG_DIR=] | | `--disable-env-parsing` | 禁用配置文件中的环境变量解析 [env: ET_DISABLE_ENV_PARSING=] | -### 网络设置 +## 网络设置 | 参数 | 说明 | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -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 设置 | 参数 | 说明 | | ------------------------ | ------------------------------------------------------------------------------------------------------------------ | @@ -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=] | -### 监听器设置 +## 监听器设置 | 参数 | 说明 | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | @@ -59,7 +61,7 @@ | `--mapped-listeners` | 手动指定监听器的公网地址，其他节点可以使用该地址连接到本节点。例如：`tcp://123.123.123.123:11223`，可以指定多个。 [env: ET_MAPPED_LISTENERS=] | | `--no-listener` | 不监听任何端口，只连接到对等节点 [env: ET_NO_LISTENER=] | -### 其他设置 +## 其他设置 | 参数 | 说明 | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -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=] | -### 日志设置 +## 日志设置 | 参数 | 说明 | | --------------------- | ------------------------------------------------------------------ |