From 8b6d128ab797861cd01c9d65daf98207049b42c7 Mon Sep 17 00:00:00 2001 From: UUBulb <35923940+uubulb@users.noreply.github.com> Date: Sat, 27 Apr 2024 15:38:41 +0800 Subject: [PATCH] Update DDNS documentation (#64) * Update DDNS documentation * fix --- docs/en_US/guide/dashboardq.md | 9 ++- docs/en_US/guide/servers.md | 128 +++++++++++++++++++++++++++++- docs/guide/dashboardq.md | 6 ++ docs/guide/servers.md | 140 ++++++++++++++++++++++++++------- 4 files changed, 251 insertions(+), 32 deletions(-) diff --git a/docs/en_US/guide/dashboardq.md b/docs/en_US/guide/dashboardq.md index dd957bc3..d894f49c 100644 --- a/docs/en_US/guide/dashboardq.md +++ b/docs/en_US/guide/dashboardq.md @@ -44,4 +44,11 @@ location ~ .*\.(js|css)?$ access_log /dev/null; } ```` -3. Save the configuration and clear the cache in the browser, NginX, and CDN, then refresh the page and it should return to normal. \ No newline at end of file +3. Save the configuration and clear the cache in the browser, NginX, and CDN, then refresh the page and it should return to normal. + +## Dashboard cannot start：panic: 无法找到配置的DDNS提供者... +The value entered for the DDNS provider is incorrect. Currently, only `webhook`, `cloudflare`, `tencentcloud`, and `dummy` are supported. + + +## Dashboard crashes when updating DDNS: panic: interface conversion: interface {} is nil, not []interface {} +The DDNS `AccessID` or `AccessSecret` filled is incorrect. \ No newline at end of file diff --git a/docs/en_US/guide/servers.md b/docs/en_US/guide/servers.md index a6662483..11c32e22 100644 --- a/docs/en_US/guide/servers.md +++ b/docs/en_US/guide/servers.md @@ -25,4 +25,130 @@ This feature does not take effect when `-disable-force-update` is turned on. This feature does not take effect when `disable-command-execute` is turned on. Both Linux and Windows are available and can be pasted using Ctrl+Shift+V. For connection failure, please refer to [Real-time channel disconnection/online terminal connection failure](/en_US/guide/q4.html). -Note that in theWebShell function, the Agent also connects to the **Domain names for public access** via WebSocket, not via grpc. \ No newline at end of file +Note that in theWebShell function, the Agent also connects to the **Domain names for public access** via WebSocket, not via grpc. + +## DDNS +DDNS feature is suitable for servers that have dynamic IP addresses. When a different IP is reported by Agent, Dashboard will update DNS record automatically using configured settings. + +### Why choose Nezha's DDNS feature +- Manage your DDNS configuration centrally, without deploying a single service on every server. +- Save your credentials only on the Dashboard server to prevent data leaks. + +### Configuration description +Currently, DDNS supports two types of configurations: Single and Multiple. If Single is chosen, all Agent servers will use the same configuration to update DNS records, whereas selecting Multiple allows each server to use a specified configuration. + +#### Single +```yaml +DDNS: + Enable: true + Provider: "webhook" + AccessID: "" + AccessSecret: "" + WebhookMethod: "" + WebhookURL: "" + WebhookRequestBody: "" + WebhookHeaders: "" + MaxRetries: 3 + Profiles: null +``` +##### Enable +Boolean value indicating whether the DDNS function is enabled. +##### Provider +Name of the DDNS provider, currently support `webhook`, `cloudflare` and `tencentcloud`. +##### AccessID +Secret ID associated with DDNS provider. +Only applied to `tencentcloud`. +##### AccessSecret +Secret key associated with DDNS provider. +Only applied to `cloudflare` and `tencentcloud`. +##### WebhookMethod +Request method of Webhook. +For example, `GET` and `POST`. +Only applied to `webhook`. +##### WebhookURL +Request URL of Webhook. +Only applied to `webhook`. +##### WebhookRequestBody +Request body of Webhook. +Only applied to `webhook`. +##### WebhookHeaders +Request headers of Webhook. +Only applied to `webhook`. +##### MaxRetries +The number of retry attempts after an update request has failed. +##### Profiles +Multiple configuration setting. Will be ignored in Single configuration setting. + +#### Multiple +Please leave `DDNS.Provider` field blank while using Multiple configuration. If not, the Multiple configuration will be ignored. +```yaml +DDNS: + Enable: true + MaxRetries: 3 + Profiles: + example: + Provider: "" + AccessID: "" + AccessSecret: "" + WebhookMethod: "" + WebhookURL: "" + WebhookRequestBody: "" + WebhookHeaders: "" +``` +##### Enable +Boolean value indicating whether the DDNS function is enabled. +##### MaxRetries +The number of retry attempts after an update request has failed. +##### Profiles +Multiple configuration setting. +##### Provider +Name of the DDNS provider, currently support `webhook`, `cloudflare` and `tencentcloud`. +##### example +Name of DDNS configuration, can be any string. +##### AccessID +Secret ID associated with DDNS provider. +Only applied to `tencentcloud`. +##### AccessSecret +Secret key associated with DDNS provider. +Only applied to `cloudflare` and `tencentcloud`. +##### WebhookMethod +Request method of Webhook. +For example, `GET` and `POST`. +Only applied to `webhook`. +##### WebhookURL +Request URL of Webhook. +Only applied to `webhook`. +##### WebhookRequestBody +Request body of Webhook. +Only applied to `webhook`. +##### WebhookHeaders +Request headers of Webhook. +Only applied to `webhook`. + +### Dashboard configuration +After configuring `config.yaml`, you will need to modify server settings in Dashboard to make DDNS function effective. + +Explanation of DDNS-related options: +- Enable DDNS +Enable the DDNS functionality for this server. +- Enable DDNS IPv4 +Enable IPv4 resolution when updating DDNS records. +- Enable DDNS IPv6 +Enable IPv6 resolution when updating DDNS records. +- DDNS Domain +The domain name the record points to. +- DDNS Configuration +The DDNS configuration to use in case of multiple configurations. + +::: tip +When modifying settings in the Dashboard and saving them, default configuration options will be filled into the `config.yaml` file. At this time, in the DDNS field, there will be both single configuration and multiple configurations options available. +If you need to use a single configuration, please ignore the content related to the Profiles option. +Please leave `DDNS.Provider` field blank while using Multiple configuration. If not, the Multiple configuration will be ignored. +::: + +### View log + In the Dashboard's logs, you can view the relevant logs for the DDNS. When configured correctly, there will be corresponding log entries when the DNS records are updated. + ```shell + dashboard_1 | 2024/03/16 23:16:25 NEZHA>> 正在尝试更新域名(ddns.example.com)DDNS(1/3) + dashboard_1 | 2024/03/16 23:16:28 NEZHA>> 尝试更新域名(ddns.example.com)DDNS成功 + ``` \ No newline at end of file diff --git a/docs/guide/dashboardq.md b/docs/guide/dashboardq.md index cbe88ba3..5d3a5857 100644 --- a/docs/guide/dashboardq.md +++ b/docs/guide/dashboardq.md @@ -49,3 +49,9 @@ location ~ .*\.(js|css)?$ } ```` 3. 保存配置，并清空浏览器、NginX、CDN 中的缓存，此时刷新页面应恢复正常 + +## 面板无法启动：panic: 无法找到配置的DDNS提供者... +填入的DDNS provider的值有误，目前仅支持 `webhook`、`cloudflare`，`tencentcloud` 和 `dummy`。 + +## 面板更新DDNS崩溃：panic: interface conversion: interface {} is nil, not []interface {} +填入的DDNS `AccessID` 或 `AccessSecret` 有误。 \ No newline at end of file diff --git a/docs/guide/servers.md b/docs/guide/servers.md index de4f29f3..af16e0c8 100644 --- a/docs/guide/servers.md +++ b/docs/guide/servers.md @@ -36,42 +36,122 @@ Linux 和 Windows 均可用，可使用 Ctrl+Shift+V 粘贴。 注意在线终端功能中，Agent 也是通过 WebSocket 连接到**公开访问域名**，而非通过 gRPC 交互。 ## DDNS 功能 -DDNS 功能适用于使用动态IP的服务器，当检测到当前的服务器 IP 发生变更，Dashboard 会根据配置自动更新 DNS 记录。 +DDNS 功能适用于使用动态 IP 的服务器，当 Agent 上报了一个新的 IP，Dashboard 会根据配置自动更新 DNS 记录。 + +### 为什么我要使用哪吒监控的 DDNS 功能？ +- 方便集中管理 DDNS 设置，而不是在每台机器上都部署一个 DDNS 服务； +- 仅在面板机上保存您的机密信息，防止外泄。 ### 配置说明 -DDNS 功能依赖于 DNS 供应商的 API，目前支持 `cloudflare`。你需要提前在 Cloudflare 上添加一个域名，并创建一个拥有 `编辑区域 DNS` 权限的令牌。 -如果您还不知道如何创建令牌，请参考 [Cloudflare API Token](https://developers.cloudflare.com/api/tokens/create)。 -1. **基本配置** - 在配置文件 `/opt/nezha/dashboard/data/config.yaml` 中，可以修改 DNS 供应商的 API 信息，如果配置文件中没有 `DDNS` 配置项，可以手动添加。 - ```yaml - DDNS: +目前 DDNS 功能支持两种形式的配置：单配置和多配置。如使用单配置，则所有 Agent 服务器都使用相同的配置更新 DDNS；如使用多配置，则可为每台服务器指定一个配置更新 DDNS，灵活性更强。 + +#### 单配置 +```yaml +DDNS: + Enable: true + Provider: "webhook" + AccessID: "" + AccessSecret: "" + WebhookMethod: "" + WebhookURL: "" + WebhookRequestBody: "" + WebhookHeaders: "" + MaxRetries: 3 + Profiles: null +``` +##### Enable +布尔值，选择是否开启 DDNS 功能。 +##### Provider +DDNS 供应商的名称。目前支持 `webhook`、`cloudflare` 以及 `tencentcloud`。 +##### AccessID +DDNS 供应商的令牌 ID。 +仅适用于供应商 `tencentcloud`。 +##### AccessSecret +DDNS 供应商的令牌 Secret。 +仅适用于供应商 `cloudflare` 及 `tencentcloud`。 +##### WebhookMethod +Webhook 的请求方法。 +例如 `GET`、`POST`等。 +仅适用于供应商 `webhook`。 +##### WebhookURL +Webhook 的请求地址。 +仅适用于供应商 `webhook`。 +##### WebhookRequestBody +Webhook 的请求体。 +仅适用于供应商 `webhook`。 +##### WebhookHeaders +Webhook 的请求头。 +仅适用于供应商 `webhook`。 +##### MaxRetries +当请求失败时，重试请求的次数。 +##### Profiles +多配置设定。在单配置设定中，此项不进行处理。 + +#### 多配置 +当使用多配置时，请将 `DDNS.Provider` 留空。如 `DDNS.Provider` 的值不为空，多配置设定将被无视。 +```yaml +DDNS: + Enable: true + MaxRetries: 3 + Profiles: + example: + Provider: "" AccessID: "" AccessSecret: "" - Enable: true - MaxRetries: 3 - Provider: cloudflare - WebhookHeaders: "" - WebhookMethod: POST - WebhookRequestBody: "" + WebhookMethod: "" WebhookURL: "" - ``` - * `AccessID` 是 DNS 供应商的登录账号 - * `AccessSecret` 是 DNS 供应商中创建好的令牌 - * `Enable` 布尔值，选择是否开启 DDNS 功能 - * `MaxRetries` 整数，失败时的重试次数 - * `Provider` DNS 供应商的名称 - * `WebhookHeaders` 字符串，Webhook 的请求头 - * `WebhookMethod` 字符串，Webhook 的请求方法 - * `WebhookRequestBody` 字符串，Webhook 的请求体 - * `WebhookURL` 字符串，Webhook 的请求地址 -配置完成后，重启 Dashboard 即可生效。 - ::: tip - Webhook 相关配置是可选的，如果不需要可以不填写。 - ::: + WebhookRequestBody: "" + WebhookHeaders: "" +``` +##### Enable +布尔值，选择是否开启 DDNS 功能。 +##### MaxRetries +当请求失败时，重试请求的次数。 +##### Profiles +多配置设定。 +##### Provider +DDNS 供应商的名称。目前支持 `webhook`、`cloudflare` 以及 `tencentcloud`。 +##### example +你的 DDNS 配置名，可填任意字符串。 +##### AccessID +DDNS 供应商的令牌 ID。 +仅适用于供应商 `tencentcloud`。 +##### AccessSecret +DDNS 供应商的令牌 Secret。 +仅适用于供应商 `cloudflare` 及 `tencentcloud`。 +##### WebhookMethod +Webhook 的请求方法。 +例如 `GET`、`POST`等。 +仅适用于供应商 `webhook`。 +##### WebhookURL +Webhook 的请求地址。 +仅适用于供应商 `webhook`。 +##### WebhookRequestBody +Webhook 的请求体。 +仅适用于供应商 `webhook`。 +##### WebhookHeaders +Webhook 的请求头。 +仅适用于供应商 `webhook`。 -2. **Dashboard 配置** - 在 Dashboard 中，可以在服务器列表中看到 `启用DDNS` 和 `DDNS域名` 两个字段，分别表示是否开启 DDNS 功能和当前的 DDNS 域名。 - 如果需要开启 DDNS 功能，可以在服务器列表中点击 `修改` 按钮，然后在弹出的对话框中填写 `DDNS域名`，并勾选`启用DDNS`，然后点击 `保存` 按钮即可。 +### Dashboard 配置 +修改好配置文件后，还需要在 Dashboard 中修改服务器设置才能使 DDNS 生效。 +DDNS 相关选项说明： +- 启用DDNS +为此服务器启用 DDNS 功能。 +- 启用DDNS IPv4 +更新 DDNS 记录时，启用 IPv4 解析。 +- 启用DDNS IPv6 +更新 DDNS 记录时，启用 IPv6 解析。 +- DDNS域名 +记录指向的域名。 +- DDNS配置 +在多配置情况下，要使用的 DDNS 配置。 + +::: tip +在 Dashboard 设置中修改配置并保存时，会在 `config.yaml` 中填入默认配置选项，此时 DDNS 段中会同时存在单配置和多配置的选项。 +如需使用单配置，请无视 `Profiles` 选项相关内容。 +如需使用多配置，请将 `DDNS.Provider` 留空。如 `DDNS.Provider` 的值不为空，多配置设定将被无视。 +::: ### 查看日志 在 Dashboard 的日志中，可以看到 DDNS 功能的相关日志，配置正确时，更新 DNS 记录时会有相应的日志记录。