github/easytier.github.io
4
0
Fork 0
mirror of https://github.com/EasyTier/easytier.github.io.git synced 2026-10-19 16:16:34 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Adds previously-missing documentation for logging configuration (fixes
#2498) and a couple of related fixes to the doc site.

- **docs: expand logging settings section in configurations** — the page
only listed the logging flags as a table without any explanation. Adds
usage details: default behavior, `--console-log-level` /
`ET_CONSOLE_LOG_LEVEL`, `RUST_LOG` per-target filters, enabling file
logging with a non-`off` `--file-log-level` plus the optional
`--file-log-dir`/`--file-log-size`/`--file-log-count` knobs, runtime
adjustment via `easytier-cli logger`, and why logging is a process-level
option that cannot go in the `-c` config file. Both zh and en.
- **fix: dev-server white screen** — vite dev serves `node_modules`
sources as-is unless prebundled; mermaid's named import from the
pure-CJS `@braintree/sanitize-url` then fails in the browser and blanks
the whole page. Add `optimizeDeps.include: ['mermaid']` so the dev
server prebundles it (rollup build was already fine).
- **docs(configurations): flatten section structure** — the single h2
"Basic Settings" wrapped every parameter group as h3, so the on-page
outline only showed one entry. Promote each group to its own h2 and
enable `outline: deep` so the logging sub-topics also appear. Both zh
and en.
This commit is contained in:
KKRainbow
2026-08-18 21:24:30 +08:00
committed by GitHub
parent 7b9a8b27b4
commit c0660fe2f7
3 changed files with 127 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.vitepress/config/index.ts
+3
View File
@@ -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' }],
en/guide/network/configurations.md
+62 -8
View File
@@ -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`.
guide/network/configurations.md
+62 -8
View File
@@ -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` 输出。