From 2ee8cf85d6ce8fda21ecaadbfe6aa98d7da8c31c Mon Sep 17 00:00:00 2001 From: Tao Chen <42793494+IamTaoChen@users.noreply.github.com> Date: Mon, 18 Nov 2024 15:44:31 +0800 Subject: [PATCH] add example for "Automatic Node Registration" (#107) * add example for "Automatic Node Registration" * update script url --------- Co-authored-by: uubulb <uub@kuzu.uk> --- docs/en_US/guide/api.md | 105 +++++++++++++++++++++++++++++++++++++- docs/guide/api.md | 108 +++++++++++++++++++++++++++++++++++++++- 2 files changed, 211 insertions(+), 2 deletions(-) diff --git a/docs/en_US/guide/api.md b/docs/en_US/guide/api.md index 2c982b62..88065ef4 100644 --- a/docs/en_US/guide/api.md +++ b/docs/en_US/guide/api.md @@ -241,6 +241,37 @@ Example response: Note: `created_at` corresponds with `avg_delay`. +### Automatic Node Registration + +Description: Script for automating node registration. Example code is provided below. +Reference: [https://github.com/naiba/nezha/pull/472](https://github.com/naiba/nezha/pull/472) + +```http +POST /api/v1/server/register?simple=1 +``` + +Parameters: + +- `simple`: (optional): Specifies the format of the response data. + - When set to `simple=1` or `simple=true`, the response will only include a Token string (e.g., `8GYwaxYuLfU7zl7ndC`). + - Otherwise the response will return a complete JSON object::`{"code": 200, "message": "Server created successfully","secret": "8GYwaxYuLfU7zl7ndC"}` + +Request Payload: + +The payload can be completely empty (`{}`), and the system will apply the following default values: +- `Name`: Defaults to the node’s IP address ($IP). +- `Tag`: Defaults to "AutoRegister". +- `Note`: Defaults to an empty string (""). +- `HideForGuest`: Defaults to "on". + +You can also customize your data: +```json + "Name": "abcd", // Node name + "Tag": "", // Tag (optional) + "Note": "", // Note or description (optional) + "HideForGuest": "on" // Whether to hide from guests +``` + ## Usage Examples ### Get All Server Information @@ -283,4 +314,76 @@ print(f"Network In Speed: {server['status']['NetInSpeed']} bytes/s") print(f"Network Out Speed: {server['status']['NetOutSpeed']} bytes/s") ``` -With the above example code, you can easily obtain and process server status information, enabling automated monitoring and management. \ No newline at end of file +With the above example code, you can easily obtain and process server status information, enabling automated monitoring and management. + +### Automatic Node Registration +1. Create a file named `nezha_register.sh`, and copy the following content into it: +```bash +#!/bin/bash + +# Exit if NEZHA_TOKEN is not set +if [ -z "${NEZHA_TOKEN}" ]; then + echo "NEZHA_TOKEN is not set. Exiting." + exit 0 +fi + +# Set default values if variables are not set +NEZHA_PROBE_ADDRESS="${NEZHA_PROBE_ADDRESS:-probe.example.com}" +NEZHA_PROBE_PORT="${NEZHA_PROBE_PORT:-5555}" +NEZHA_DASHBOARD_URL="${NEZHA_DASHBOARD_URL:-https://nezha.example.com}" + +NODE_NAME=${NODE_NAME:-$(hostname)} + +# Send POST request and capture response and HTTP status code +response=$(curl -s -o response_body.json -w "%{http_code}" -X POST "${NEZHA_DASHBOARD_URL}/api/v1/server/register?simple=true" \ + -H "Content-Type: application/json" \ + -H "Authorization: ${NEZHA_TOKEN}" \ + -d "{\"Name\": \"${NODE_NAME}\"}") + +# Extract HTTP status code and Nezha secret +HTTP_CODE="$response" +NEZHA_SECRET=$(cat response_body.json) +rm -f response_body.json + +if [ "$HTTP_CODE" != "200" ]; then + echo "Failed to get Nezha Secret. HTTP status code: $HTTP_CODE" + exit 1 +fi + +# Additional check for NEZHA_SECRET to ensure it's not JSON-formatted (indicating failure) +if [[ "${NEZHA_SECRET:0:1}" == "{" ]]; then + echo "Failed to get Nezha Secret. Received response: ${NEZHA_SECRET}" + exit 1 +fi + +# Download and execute the install script with cleanup +curl -fsSL https://raw.githubusercontent.com/nezhahq/scripts/main/install_en.sh -o nezha.sh && \ +chmod +x nezha.sh || { echo "Failed to download or make the script executable"; exit 1; } + +# Clean up nezha.sh on exit +trap 'rm -f nezha.sh' EXIT + +# Run the Nezha agent installation script +CMD="./nezha.sh install_agent "${NEZHA_PROBE_ADDRESS}" "${NEZHA_PROBE_PORT}" "${NEZHA_SECRET}" --tls" + +echo "Run commnad : ${CMD}" + +eval $CMD +``` +2. Grant execution permission to the script: `chmod +x nezha_register.sh` +3. Get `Token` from Nezha dashboard, e.g. `POXbxorKJBM8wPMKX8r2PdMblyXvpggB` +4. Set Environment Variables +```bash +export NEZHA_TOKEN="POXbxorKJBM8wPMKX8r2PdMblyXvpggB" # Obtain this token from the dashboard +export NEZHA_PROBE_ADDRESS="your_probe_address" # Set your probe address +export NEZHA_DASHBOARD_URL="https://nezha.example.com" # Replace with your dashboard URL +export NEZHA_PROBE_PORT="5555" # Modify this port if needed +``` +5. Run the script to complete node registration and probe installation: +```bash +./nezha_register.sh +``` +6. If the script runs successfully, you will see output like the following: +```bash +Run command: ./nezha.sh install_agent probe.example.com 5555 YOUR_SECRET --tls +``` \ No newline at end of file diff --git a/docs/guide/api.md b/docs/guide/api.md index 46bb5d21..8bdc8209 100644 --- a/docs/guide/api.md +++ b/docs/guide/api.md @@ -241,6 +241,40 @@ GET /api/v1/monitor/{id} 注: `created_at` 和 `avg_delay` 为对应关系。 +### 自动注册节点 + +说明: 用于自动化注册节点的脚本,示例代码详见下文。 + +参考: [https://github.com/naiba/nezha/pull/472](https://github.com/naiba/nezha/pull/472) + +```http +POST /api/v1/server/register?simple=1 +``` + +参数: + +- `simple`:(可选) 指定返回数据的格式。 + - 当设置为 `simple=1`或者`simple=true` 时,返回的数据仅包含 Token 字符串(如 `8GYwaxYuLfU7zl7ndC`)。 + - 其他则返回完整的 JSON 对象:`{"code": 200, "message": "Server created successfully","secret": "8GYwaxYuLfU7zl7ndC"}` + +请求体 (Payload): + +你可以设置为空内容(`{}`), 然后nezha面板会使用默认值进行填充 +- `Name`: 默认是节点的IP +- `Tag`: 默认是 "AutoRegister". +- `Note`:默认是 "". +- `HideForGuest`: 默认是 "on". + +你也可以设置自己的请求参数: +```json +{ + "Name": "abcd", // 节点名称 + "Tag": "", // 标签,可选 + "Note": "", // 备注信息,可选 + "HideForGuest": "on" // 是否对访客隐藏 +} +``` + ## 使用案例 ### 获取所有服务器信息 @@ -283,4 +317,76 @@ print(f"Network In Speed: {server['status']['NetInSpeed']} bytes/s") print(f"Network Out Speed: {server['status']['NetOutSpeed']} bytes/s") ``` -通过以上示例代码,可以轻松获取和处理服务器的状态信息,从而实现自动化监控和管理。 \ No newline at end of file +通过以上示例代码,可以轻松获取和处理服务器的状态信息,从而实现自动化监控和管理。 + +### 自动注册节点 +1. 创建文件 `nezha_register.sh`,将以下内容复制到文件中: +```bash +#!/bin/bash + +# Exit if NEZHA_TOKEN is not set +if [ -z "${NEZHA_TOKEN}" ]; then + echo "NEZHA_TOKEN is not set. Exiting." + exit 0 +fi + +# Set default values if variables are not set +NEZHA_PROBE_ADDRESS="${NEZHA_PROBE_ADDRESS:-probe.example.com}" +NEZHA_PROBE_PORT="${NEZHA_PROBE_PORT:-5555}" +NEZHA_DASHBOARD_URL="${NEZHA_DASHBOARD_URL:-https://nezha.example.com}" + +NODE_NAME=${NODE_NAME:-$(hostname)} + +# Send POST request and capture response and HTTP status code +response=$(curl -s -o response_body.json -w "%{http_code}" -X POST "${NEZHA_DASHBOARD_URL}/api/v1/server/register?simple=true" \ + -H "Content-Type: application/json" \ + -H "Authorization: ${NEZHA_TOKEN}" \ + -d "{\"Name\": \"${NODE_NAME}\"}") + +# Extract HTTP status code and Nezha secret +HTTP_CODE="$response" +NEZHA_SECRET=$(cat response_body.json) +rm -f response_body.json + +if [ "$HTTP_CODE" != "200" ]; then + echo "Failed to get Nezha Secret. HTTP status code: $HTTP_CODE" + exit 1 +fi + +# Additional check for NEZHA_SECRET to ensure it's not JSON-formatted (indicating failure) +if [[ "${NEZHA_SECRET:0:1}" == "{" ]]; then + echo "Failed to get Nezha Secret. Received response: ${NEZHA_SECRET}" + exit 1 +fi + +# Download and execute the install script with cleanup +curl -fsSL https://raw.githubusercontent.com/nezhahq/scripts/main/install.sh -o nezha.sh && \ +chmod +x nezha.sh || { echo "Failed to download or make the script executable"; exit 1; } + +# Clean up nezha.sh on exit +trap 'rm -f nezha.sh' EXIT + +# Run the Nezha agent installation script +CMD="./nezha.sh install_agent "${NEZHA_PROBE_ADDRESS}" "${NEZHA_PROBE_PORT}" "${NEZHA_SECRET}" --tls" + +echo "Run commnad : ${CMD}" + +eval $CMD +``` +2. 为脚本赋予可执行权限: `chmod +x nezha_register.sh` +3. 从dashboard获取token, 比如为 `POXbxorKJBM8wPMKX8r2PdMblyXvpggB` +4. 配置环境变量 +```bash +export NEZHA_TOKEN="POXbxorKJBM8wPMKX8r2PdMblyXvpggB" # 从面板获取 +export NEZHA_PROBE_ADDRESS="your_probe_address" # 填写探针地址 +export NEZHA_DASHBOARD_URL="https://nezha.example.com" # 修改为你的面板地址 +export NEZHA_PROBE_PORT="5555" # 修改为你的探针端口(如有不同) +``` +5. 运行注册脚本 +```bash +./nezha_register.sh +``` +6. 如果脚本成功运行,你会看到类似以下的日志: +```bash +Run command: ./nezha.sh install_agent probe.example.com 5555 YOUR_SECRET --tls +```