更新以匹配 Dashboard v0.18.0 的新功能和特性变化

2024-07-15 02:22:21 +02:00 · 2024-07-15 02:22:21 +02:00 · 394dbfc5d2
commit 394dbfc5d2
parent bc600e000d
9 changed files with 134 additions and 43 deletions
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@ -173,6 +173,7 @@ function getGuideSidebarZhCN() {
        { text: '服务', link: '/guide/services.html' },
        { text: '任务', link: '/guide/tasks.html' },
        { text: '告警', link: '/guide/notifications.html' },
+        { text: '内网穿透', link: '/guide/nat.html' },
        { text: '设置', link: '/guide/settings.html' },
        { text: 'API', link: '/guide/api.html' }
      ],
@ -183,7 +184,7 @@ function getGuideSidebarZhCN() {
        { text: '反向代理 Telegram API', link: '/guide/q1.html' },
        { text: 'Agent 启动/上线 问题自检流程', link: '/guide/q2.html' },
        { text: '反向代理 gRPC 端口', link: '/guide/q3.html' },
-        { text: '实时通道断开/在线终端连接失败', link: '/guide/q4.html' },
+        { text: '实时通道断开', link: '/guide/q4.html' },
        { text: '面板数据迁移、备份和恢复', link: '/guide/q5.html' },
        { text: '设置每月重置流量统计', link: '/guide/q6.html' },
        { text: '自定义 Agent 监控项目', link: '/guide/q7.html' },
@ -246,6 +247,7 @@ function getGuideSidebarEnUS() {
        { text: 'Services', link: '/en_US/guide/services.html' },
        { text: 'Tasks', link: '/en_US/guide/tasks.html' },
        { text: 'Notifications', link: '/en_US/guide/notifications.html' },
+        { text: 'NAT traversal', link: '/en_US/guide/nat.html' },
        { text: 'Settings', link: '/en_US/guide/settings.html' },
        { text: 'API', link: '/en_US/guide/api.html' }
      ]
@ -255,7 +257,7 @@ function getGuideSidebarEnUS() {
      items: [
        { text: 'Agent Startup/Online Troubleshooting Process', link: '/en_US/guide/q2.html' },
        { text: 'Reverse Proxy gRPC Port (Support Cloudflare CDN)', link: '/en_US/guide/q3.html' },
-        { text: 'Real-Time Channel Disconnection/Online Terminal Connection Failure', link: '/en_US/guide/q4.html' },
+        { text: 'Real-Time Channel Disconnection', link: '/en_US/guide/q4.html' },
        { text: 'Perform Data Migration and Backup Recovery', link: '/en_US/guide/q5.html' },
        { text: 'Reset Traffic Statistics Monthly', link: '/en_US/guide/q6.html' },
        { text: 'Customizing Agent Monitoring Items', link: '/en_US/guide/q7.html' },
--- a/docs/en_US/guide/dashboardq.md
+++ b/docs/en_US/guide/dashboardq.md
@ -77,11 +77,11 @@ The entered DDNS `AccessID` or `AccessSecret` is incorrect.
 This error indicates that no TCP-Ping or ICMP-Ping type monitoring has been set in the services page or monitoring data has not yet been generated.   
 If it has been set up, wait for some time and then check again.

-### What to do if /terminal or /ws can't connect properly after enabling HTTPS?
+## What to do if /terminal or /ws can't connect properly after enabling HTTPS?

 This is often due to an incomplete certificate. Add the -d parameter to the agent run command. If the log contains `x509:certificate signed by unknown authority`, replacing with a complete certificate will solve the problem.

-### What if I'm not satisfied with the data modification/addition functionality provided by the dashboard and want to modify/add data myself?
+## What if I'm not satisfied with the data modification/addition functionality provided by the dashboard and want to modify/add data myself?

 Common in scenarios like batch adding Agents, you can directly modify the database.  
 Note that not everything in the database can be modified; incorrect modifications can lead to data corruption and inability to start the Dashboard. **Do not modify the database casually!**
@ -91,6 +91,11 @@ Again, **do not modify the database casually!**
 If you need to modify data in the database, **stop** the dashboard container first.  
 The database type is sqlite3, located at `/opt/nezha/dashboard/data/sqlite.db`. Backup before modifying.

-### Will the Dashboard automatically update?
+## Will the Dashboard automatically update?

-Agents typically update automatically, but the Dashboard does not and requires manual updates.
+Agents typically update automatically, but the Dashboard does not and requires manual updates.
+
+## `Agent Command Issuance Failed` When Connecting to Web Terminal
+
+When the Agent is offline, or the connection between the Agent and the Dashboard is unstable, it may cause issues with connecting to the Web Terminal.
+Please check if the Agent is running normally and maintaining a stable connection with the Dashboard.
--- a/docs/en_US/guide/nat.md
+++ b/docs/en_US/guide/nat.md
@ -0,0 +1,34 @@
+---
+outline: deep
+---
+# NAT Traversal Configuration
+
+Nezha Server Monitoring includes built-in NAT traversal capabilities, allowing users to expose internal services running on an Agent (such as home OpenWrt routers or NAS devices) to the public internet. This functionality facilitates remote access and is currently limited to supporting HTTP protocol traversal.
+
+## Preparation
+
+Prior to configuring NAT traversal, please ensure the following preparatory steps are completed:
+
+- Verify that the Nezha Monitoring Agent is installed and actively running on your device and maintains a stable connection with the Dashboard.
+- Acquire a public domain name, ideally using a subdomain configuration, such as `service-1.example.com`. Point this domain name to the public IP address of your Dashboard server.
+- It is important to note that each domain name can only map to the service of one Agent. For mapping services from multiple Agents, distinct domain names should be used, such as `service-2.example.com`.
+
+::: warning
+If your Dashboard server uses tools like the aaPanel or similar management platforms, ensure that your domain (e.g., `service-1.example.com`) is correctly linked to the Dashboard site within these tools to avoid access issues.
+:::
+
+## NAT Traversal Configuration Steps
+
+1. Log into the Dashboard Admin Panel and navigate to the "NAT Traversal" section in the menu.
+2. Click the "Add" button and provide the following required details:
+   - **Name**: Assign a custom name to this traversal setup, for example, `OpenWrt Login Page`.
+   - **Agent ID**: Input the ID of the Agent for which traversal is needed.
+   - **Internal Service Address**: Specify the internal service address that requires traversal, in the `IP:port` format, such as `127.0.0.1:80`.
+   - **Domain Name**: Enter the previously configured public domain name, like `service-1.example.com`.
+3. After filling in the details, click the "Add" button and wait for the traversal setup to activate.
+4. Test the configuration by accessing `http://service-1.example.com` to ensure the internal service on the Agent is successfully accessible.
+
+## Usage Notes
+
+- Continuous connectivity between the Agent and the Dashboard is crucial for the NAT traversal functionality to operate correctly. If the connection to the Agent is lost, the traversal setup will temporarily cease to function.
+- Given that the NAT traversal does not encrypt traffic by itself, it is recommended to secure data transmissions by employing HTTPS protocol between the Agent and the Dashboard, as well as between the Dashboard and the client browser, to ensure data security during transmission.
--- a/docs/en_US/guide/q10.md
+++ b/docs/en_US/guide/q10.md
@ -1,23 +1,28 @@
 ---
 outline: deep
 ---
-# OIDC Configuration
-Edit `config.ymal` to enable **OIDC**
+# Configuring OIDC Authentication
+
+Modify the contents of `config.yaml` to configure OIDC (OpenID Connect) authentication. OIDC is an authentication layer on top of the OAuth 2.0 protocol, which allows applications to verify the identity of users based on the authentication performed by an Authorization Server. This method is widely used to implement single sign-on for modern applications.
+
+## Configuration Details
+
+Here is a step-by-step guide to configuring the OIDC settings in your `config.yaml`:
+
 ```yaml
 oauth2:
  type: oidc  # (Required) Specifies the authentication type as OIDC
-  oidcDisplayName: OIDC  # (Optional, default is OIDC) The name displayed on the login page button
-  admin: ""  # (At least one of admin or adminGroups must be provided; default is empty) List of admin usernames, separated by commas. If a user is one of these, they will be considered an admin
-  adminGroups: ""  # (At least one of admin or adminGroups must be provided; default is empty) List of admin groups, separated by commas. If a user belongs to one of these groups, they will be considered an admin. Can be left blank if not using group management
+  oidcDisplayName: OIDC  # (Optional, default: OIDC) The name displayed on the login page
+  admin: ""  # (Fill at least one of admin or adminGroups; default: empty) Admin usernames, separated by commas. Users listed here are considered administrators
+  adminGroups: ""  # (Fill at least one of admin or adminGroups; default: empty) Admin groups, separated by commas. Users in these groups are considered administrators. Omit if group management is not used
  clientid: # (Required) OIDC client ID
  clientsecret: # (Required) OIDC client secret
-  oidcIssuer: https://auth.example.com/realms/master  # (Required) The issuer URL of the OIDC provider, can be found from the OIDC provider
-  # oidcLogoutUrl: https://auth.example.com/realms/master/protocol/openid-connect/logout  # (Has a bug, currently not working)
-  # oidcRegisterUrl: # (Optional) Registration URL of the OIDC provider
-  oidcScopes: openid,profile,email  # (Optional, default is openid,profile,email) Scopes requested from OIDC, separated by commas
-  oidcLoginClaim: sub  # (Optional, default is sub) The username field returned from OIDC, can be preferred_username, sub, or email
-  oidcGroupsClaim: groups  # (Required if using adminGroups; default is groups) The field returned from OIDC containing user group information, can be groups or roles
-  oidcAutoCreate: false  # (Optional, default is false) Whether to automatically create a user if they do not exist
-  oidcAutoLogin: false  # (Optional, default is false) Automatically redirect to the OIDC login page when the URL is /login
-
+  oidcIssuer: https://auth.example.com/realms/master  # (Required) The issuer URL of the OIDC provider, obtainable from your OIDC provider
+  # oidcLogoutUrl: https://auth.example.com/realms/master/protocol/openid-connect/logout  # (Currently unusable due to a bug)
+  # oidcRegisterUrl: # (Optional) Registration link provided by the OIDC provider
+  oidcScopes: openid,profile,email  # (Optional, default: openid,profile,email) OIDC scopes requested, separated by commas
+  oidcLoginClaim: sub  # (Optional, default: sub) The username field returned by OIDC, can be preferred_username, sub, or email
+  oidcGroupsClaim: groups  # (Required if using adminGroups, default: groups) The user group information field returned by OIDC, can be groups or roles
+  oidcAutoCreate: false  # (Optional, default: false) Whether to automatically create a user if they do not exist
+  oidcAutoLogin: false  # (Optional, default: false) Whether to automatically redirect to the OIDC login page when the path is /login
 ```
--- a/docs/en_US/guide/q4.md
+++ b/docs/en_US/guide/q4.md
@ -1,4 +1,4 @@
-# Real-Time Channel Disconnection/Online & Terminal Connection Failure
+# Real-Time Channel Disconnection

 - If you are using a CDN, ensure that the CDN provider offers WebSocket services and that WebSocket is enabled.
 - Confirm that your reverse proxy rules have special configurations for the `/ws` and `/terminal` paths. You can [click here](/en_US/guide/dashboard.html#configure-reverse-proxy) to view the reverse proxy configuration.
--- a/docs/guide/dashboardq.md
+++ b/docs/guide/dashboardq.md
@ -77,11 +77,11 @@ systemctl status docker
 出现此错误说明没有在服务页中设置 TCP-Ping 和 ICMP-Ping 类型的监控或者监控数据还未生成。   
 如已经设置完毕，可以等待一段时间后再查看。

-### 启用 HTTPS 后 /terminal 或 /ws 不能正常连接
+## 启用 HTTPS 后 /terminal 或 /ws 不能正常连接

 常常是由于证书不完整造成的，请在 agent 运行参数中添加 -d，若 log 中有 `x509:certificate signed by unknown authority`，更换完整证书则可解决该问题。

-### 对面板提供的数据修改/增加功能不满意，想要修改/增加数据
+## 对面板提供的数据修改/增加功能不满意，想要修改/增加数据

 常见于批量新建 Agent 等需求中，可以直接修改数据库。  
 请注意，数据库中并非什么都可以修改，错误的修改会导致数据混乱无法启动 Dashboard，**请勿随意修改数据库！**  
@ -91,6 +91,11 @@ systemctl status docker
 如需要在数据库中修改数据，请先**停止**面板容器再修改。  
 数据库类型是 sqlite3，位于 `/opt/nezha/dashboard/data/sqlite.db`，修改前请备份。

-### Dashboard 会自动更新吗？
+## Dashboard 会自动更新吗？

-Agent 通常情况下会自动更新，但 Dashboard 并不会，需要手动更新。
+Agent 通常情况下会自动更新，但 Dashboard 并不会，需要手动更新。
+
+## 连接在线终端时提示：`Agent 信令下发失败`
+
+当 Agent 离线，或与 Dashboard 之间的连接不稳定时，可能会导致在线终端无法正常连接。
+请检查 Agent 是否正常运行，是否与 Dashboard 保持稳定的连接。
--- a/docs/guide/nat.md
+++ b/docs/guide/nat.md
@ -0,0 +1,34 @@
+---
+outline: deep
+---
+# 内网穿透功能配置
+
+哪吒服务器监控提供内置的内网穿透功能，允许用户通过设定 Dashboard 作为服务端，将运行在 Agent 上的内网服务（如家庭 OpenWrt 路由器、NAS 设备等）映射到公网上，便于外部访问。目前仅支持 HTTP 协议的穿透。
+
+## 准备工作
+
+在配置内网穿透前，请确保完成以下准备工作：
+
+- 确认已在您的设备上安装并运行哪吒监控的 Agent，并保持其与 Dashboard 的连接状态。
+- 准备一个公网域名，推荐使用子域名进行操作，如`service-1.example.com`。将此域名解析指向 Dashboard 服务器的公网 IP 地址。
+- 请注意，一个域名只能映射到一个 Agent 的内网服务。若需映射多个服务，请分别使用不同的域名，例如 `service-2.example.com`。
+
+::: warning
+如果您的 Dashboard 服务器使用宝塔面板或其他管理工具，请确保所用域名，如 `service-1.example.com` 已在该面板中正确绑定至 Dashboard 站点，否则可能导致无法访问。
+:::
+
+## 内网穿透配置步骤
+
+1. 登录至 Dashboard 管理页面，选择菜单栏中的“内网穿透”选项。
+2. 点击“添加”按钮，并填写以下所需信息：
+   - **穿透名称**：为此穿透配置自定义一个名称，如`OpenWrt 登录页`。
+   - **Agent ID**：填写需要进行穿透的 Agent 的 ID。
+   - **内网服务地址**：填写需穿透的内网服务地址，格式为 `IP:端口`，例如 `127.0.0.1:80`。
+   - **绑定域名**：填写已准备的公网域名，如 `service-1.example.com`。
+3. 完成填写后，点击“新增”按钮，等待穿透生效。
+4. 尝试访问 `http://service-1.example.com`，以验证是否成功映射至 Agent 上的内网服务。
+
+## 使用须知
+
+- 保持 Agent 与 Dashboard 之间的连接是内网穿透功能正常运作的前提。若 Agent 连接中断，已配置的穿透将暂时失效。
+- 考虑到内网穿透隧道本身不加密数据，建议在 Agent 与 Dashboard 之间以及 Dashboard 与客户端浏览器之间**使用 HTTPS 协议**，以确保数据传输过程的安全性。
--- a/docs/guide/q10.md
+++ b/docs/guide/q10.md
@ -1,22 +1,28 @@
 ---
 outline: deep
 ---
-# 使用OIDC认证
-修改`config.ymal`的内容来配置OIDC
+# 配置OIDC认证
+
+修改 `config.yaml` 文件的内容来配置 OIDC（OpenID Connect）认证。OIDC 是建立在 OAuth 2.0 协议之上的认证层，允许应用程序通过授权服务器执行的认证来验证用户的身份。这种方法广泛用于实现现代应用程序的单点登录。
+
+## 配置详细信息
+
+以下是在 `config.yaml` 中配置 OIDC 设置的逐步指南：
+
 ```yaml
 oauth2:
-  type: oidc  # (必填) 指定验证类型为OIDC
-  oidcDisplayName: OIDC  # (可选，默认值为OIDC) 登录页面按钮显示的名字
-  admin: ""  # (与adminGroups至少填写一项; 默认值为空) 管理员用户名，多个用户名用半角逗号分隔。如果用户在这些用户名列表中，则视为管理员
-  adminGroups: ""  # (与admin至少填写一项; 默认值为空) 管理员组，多个组名用半角逗号分隔。如果用户属于这些组，则视为管理员。如果不使用组管理，此项可省略
-  clientid: # (必填) OIDC客户端ID
-  clientsecret: # (必填) OIDC客户端密钥
-  oidcIssuer: https://auth.example.com/realms/master  # (必填) OIDC提供商的issuer地址，可从OIDC提供商查询
-  # oidcLogoutUrl: https://auth.example.com/realms/master/protocol/openid-connect/logout  # (有bug，目前不能使用)
-  # oidcRegisterUrl: # (可选) OIDC提供商的注册链接
-  oidcScopes: openid,profile,email  # (可选，默认值为openid,profile,email) OIDC请求的scope，多个scope用半角逗号分隔
-  oidcLoginClaim: sub  # (可选，默认值为sub) 从OIDC返回的用户名字段，可以是preferred_username、sub或email
-  oidcGroupsClaim: groups  # (如果使用adminGroups，则必填，默认值为groups) 从OIDC返回的用户组信息字段，可以是groups或roles
-  oidcAutoCreate: false  # (可选，默认值为false) 如果用户不存在，是否自动创建用户
-  oidcAutoLogin: false  # (可选，默认值为false) 当地址是/login时，是否自动跳转到OIDC登录页面
-```
+  type: oidc  # （必填）指定认证类型为 OIDC
+  oidcDisplayName: OIDC  # （可选，默认值为 OIDC）登录页面显示的名称
+  admin: ""  # （至少填写 admin 或 adminGroups 中的一个；默认为空）管理员用户名，用逗号分隔。列在此处的用户被视为管理员
+  adminGroups: ""  # （至少填写 admin 或 adminGroups 中的一个；默认为空）管理员组，用逗号分隔。属于这些组的用户被视为管理员。如果不使用组管理，可以省略此项
+  clientid: # （必填）OIDC 客户端 ID
+  clientsecret: # （必填）OIDC 客户端密钥
+  oidcIssuer: https://auth.example.com/realms/master  # （必填）OIDC 提供商的 issuer URL，可以从您的OIDC 提供商处获取
+  # oidcLogoutUrl: https://auth.example.com/realms/master/protocol/openid-connect/logout  # （因 bug 目前不能使用）
+  # oidcRegisterUrl: # （可选）OIDC 提供商的注册链接
+  oidcScopes: openid,profile,email  # （可选，默认值为 openid,profile,email ）OIDC 请求的 scope，用逗号分隔
+  oidcLoginClaim: sub  # （可选，默认值为 sub）OIDC 返回的用户名字段，可以是 preferred_username、sub 或email
+  oidcGroupsClaim: groups  # （如果使用 adminGroups，则必填，默认值为 groups ）OIDC 返回的用户组信息字段，可以是 groups 或 roles
+  oidcAutoCreate: false  # （可选，默认值为 false）如果用户不存在，是否自动创建用户
+  oidcAutoLogin: false  # （可选，默认值为 false）当地址是 /login 时，是否自动跳转到OIDC登录页面
+```
--- a/docs/guide/q4.md
+++ b/docs/guide/q4.md
@ -1,4 +1,4 @@
-# 实时通道断开/在线终端连接失败
+# 实时通道断开

 - 如果你使用了 CDN，请确认 CDN 服务商提供 WebSocket 服务，并且已开启 WebSocket。
 - 确认你的反代规则中针对 `/ws`, `/terminal` 路径的 WebSocket 进行了特别配置，你可以 [点击这里](/guide/dashboard.html#配置反向代理) 查看反向代理配置。