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' }], diff --git a/en/guide/network/configurations.md b/en/guide/network/configurations.md index 659984a..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 | | --------------------- | ------------------------------------------------------------------ | @@ -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`. diff --git a/guide/network/configurations.md b/guide/network/configurations.md index 06b6942..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=] | -### 日志设置 +## 日志设置 | 参数 | 说明 | | --------------------- | ------------------------------------------------------------------ | @@ -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` 输出。