> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monad.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticated UDP 迁移

<Warning>
  在 Monad 基金会发出通知之前，请不要执行此操作。
</Warning>

## 概述

UDP 认证为 Monad 节点提供了安全、经过身份验证的点对点通信。此功能目前为**可选加入**，将在未来的版本中成为强制要求。

**优势：**

* **增强的安全性**：使用您现有的验证者密钥对对等连接进行加密认证
* **DoS 防护**：防止来自伪造数据包的资源耗尽
* **流量优先级**：为交易转发启用高效的 QoS 策略
* **性能**：与逐包 ECDSA 签名相比，数据包验证速度提升约 100 倍

***

## 前置条件

* **Monad 版本**：`0.12.6` 或更高版本
* **访问权限**：节点上的 Root/sudo 权限
* **密钥库**：现有的 `/home/monad/monad-bft/config/id-secp` 文件
* **网络**：能够在防火墙上打开 UDP 端口 8001

***

## 节点运营者操作说明

### 1. 验证 Monad 版本

验证安装：

```bash theme={null}
monad-node --version
# Expected output 0.12.6+
```

如果不是，请参考官方文档升级到最新推荐版本：[https://docs.monad.xyz/node-ops/upgrade-instructions/。](https://docs.monad.xyz/node-ops/upgrade-instructions/。)

***

### 2. 配置防火墙

为经过身份验证的流量打开 UDP 端口 8001：

```bash theme={null}
sudo ufw allow 8001/udp comment 'monad authenticated udp'
```

验证规则是否已添加：

```bash theme={null}
sudo ufw status | grep 8001
```

**预期输出：**

```
8001/udp                   ALLOW       Anywhere                   # monad authenticated udp
```

注意：如果节点位于网络防火墙后面，请确保也打开端口 8001。

***

### 3. 生成认证签名

生成节点的认证名称记录签名：

```bash theme={null}
source /home/monad/.env
monad-sign-name-record \
  --address $(curl -4 -s ifconfig.me):8000 \
  --authenticated-udp-port 8001 \
  --self-record-seq-num 1 \
  --keystore-path /home/monad/monad-bft/config/id-secp \
  --password "$KEYSTORE_PASSWORD"
```

> **重要**：`--self-record-seq-num` 值必须**大于**您当前 `node.toml` 中的 `self_record_seq_num`。
>
> * 如果您的配置显示 `self_record_seq_num = 0`，请使用 `1`
> * 如果您的配置显示 `self_record_seq_num = 1`，请使用 `2`

**输出示例：**

```
self_address = "15.235.224.21:8000"
self_record_seq_num = 1
authenticated_udp_port = 8001
self_name_record_sig = "f754ed009f82a5c0e402b8f573a1b7e44e9f5fc957cf6360316b5a3baf617f0d1ffe23558845747dd21a51408ac2555a4f4bb70a0032cdf59921d5905663e41200"
```

警告：不要复制 `authenticated_udp_port` 参数，因为在 `node.toml` 中该参数名为 `self_auth_port`。

**保存此输出** - 您将在下一步中需要它。

***

### 4. 更新配置

编辑您的 Monad 配置：

```bash theme={null}
sudo vim /home/monad/monad-bft/config/node.toml
```

#### 4.1 更新 Peer Discovery 部分

在节点配置中：

* 用步骤 3 的输出替换 `[peer_discovery]` 部分中的值
* 添加 `self_auth_port` 参数

```toml theme={null}
[peer_discovery]
self_address = "YOUR_IP:8000"
self_auth_port = 8001
self_record_seq_num = 1
self_name_record_sig = "YOUR_GENERATED_SIGNATURE_FROM_STEP_3"
```

#### 4.2 更新 Network 部分

将 `authenticated_bind_address_port` 参数添加到 `[network]`：

```toml theme={null}
[network]
bind_address_host = "0.0.0.0"
bind_address_port = 8000
authenticated_bind_address_port = 8001  # Add this line
max_rtt_ms = 300
max_mbps = 1000
```

#### 4.3 更新对等节点记录（仅限验证者）

如果您运营的**验证者**带有下游全节点，请在其启用 UDP 认证时更新对等节点配置。

**对于已启用 UDP 认证的对等节点**：

* 使用下游节点的新值更新 `record_seq_num` 和 `name_record_sig`
* 设置 `auth_port = 8001`

注意：已激活 Authenticated UDP 的节点将在 `peers.toml` 文件中显示 `auth_port = 8001`。

```toml theme={null}
[[bootstrap.peers]]
address = "188.214.131.5:8000"
record_seq_num = 1
secp256k1_pubkey = "0x0342f3e447bd6951b2cf7cd717958a84e58dbe8cfbe2780f0247c69591216d2d7c"
name_record_sig = "0x215e845dade986e48f6fcb1f065f3ff993ddf0d38b0ef41a05f6621d71bf4c6c2d25747629ac8a3d583418857bc0b4c75140202e14919faf643f431ade4b944d00"
auth_port = 8001  # Add this for upgraded peers
```

**对于尚未启用的对等节点**，无需更新任何内容，应省略 `auth_port` 行：

```toml theme={null}
[[bootstrap.peers]]
address = "188.214.131.6:8000"
record_seq_num = 0
secp256k1_pubkey = "0x..."
name_record_sig = "0x..."
# No auth_port - this peer hasn't upgraded yet
```

注意：下游节点的对等配置无需更新。

保存并退出文件。

***

### 5. 重启并验证

重启 Monad 服务：

```bash theme={null}
sudo systemctl restart monad-bft
```

监控日志以确认成功启动：

```bash theme={null}
journalctl -u monad-bft -f -n 50 --no-pager
```

***

## 验证

### 检查服务状态

```bash theme={null}
systemctl status monad-bft --no-pager
```

预期：`active (running)`

### 验证端口绑定

```bash theme={null}
sudo ss -ulpn | grep 8001
```

**预期输出：**

```
udp   UNCONN 0   0   0.0.0.0:8001   0.0.0.0:*   users:(("monad-node",pid=12345,fd=20))
```

## 故障排查

***

### 问题："invalid name record signature in config file"

**原因：** `node.toml` 中的签名与参数不匹配。

**解决方案：**

1. 验证您是否正确地递增了 `self_record_seq_num`
2. 使用正确的 seq\_num 重新运行 `monad-sign-name-record`
3. 将新签名复制到 `node.toml`
4. 重启服务

***

### 问题：端口 8001 未监听

**解决方案：**

```bash theme={null}
# Verify config
grep -A5 "\[network\]" /home/monad/monad-bft/config/node.toml | grep authenticated

# Check for startup errors
journalctl -u monad-bft -n 100 --no-pager | grep -i error

# Restart service
sudo systemctl restart monad-bft
```

***

### 问题：防火墙阻止连接

**解决方案：**

```bash theme={null}
# Check current UFW rules
sudo ufw status numbered

# Add rule if missing
sudo ufw allow 8001/udp comment 'monad authenticated udp'

# Reload firewall
sudo ufw reload
```

***

## 回滚说明

如果需要禁用 UDP 认证：

### 1. 生成不带认证端口的新签名

```bash theme={null}
source /home/monad/.env
monad-sign-name-record \
  --address $(curl -4 -s ifconfig.me):8000 \
  --self-record-seq-num 2 \
  --keystore-path /home/monad/monad-bft/config/id-secp \
  --password "$KEYSTORE_PASSWORD"
```

注意：从您当前的值递增 seq\_num。

### 2. 更新配置

编辑 `/home/monad/monad-bft/config/node.toml`：

* 更新 `[peer_discovery]` 中的 `self_record_seq_num` 和 `self_name_record_sig`
* 删除或注释掉 `[network]` 中的 `authenticated_bind_address_port`
* 从对等节点配置中删除所有 `auth_port` 条目

### 3. 重启服务

```bash theme={null}
sudo systemctl restart monad-bft
```

***

## 快速健康检查脚本

将此脚本保存为 `check_udp_auth.sh` 以便快速验证：

```bash theme={null}
#!/bin/bash
echo "=== Monad UDP Authentication Health Check ==="
echo ""
echo "Checking Monad version..."
monad-node --version 2>/dev/null || echo "monad-node not found"
echo ""
echo "Checking firewall rule..."
sudo ufw status | grep 8001 || echo "No UFW rule for 8001/udp"
echo ""
echo "Checking port binding..."
sudo ss -tulpn | grep 8001 || echo "Port 8001 not bound"
echo ""
echo "Checking service status..."
systemctl is-active monad-bft || echo "Service not active"
echo ""
echo "Checking configuration..."
grep -q "authenticated_bind_address_port = 8001" /home/monad/monad-bft/config/node.toml && \
  echo "authenticated_bind_address_port configured" || \
  echo "authenticated_bind_address_port not found"
echo ""
echo "Complete!"
```

使其可执行：

```bash theme={null}
chmod +x check_udp_auth.sh
./check_udp_auth.sh
```

**预期输出：**

```
=== Monad UDP Authentication Health Check ===

Checking Monad version...
monad-node {"commit":"e1e9489b8fc42c0a5af208bab20f6704f83c91c0","tag":"v0.12.7","branch":"","modified":true}

Checking firewall rule...
8001/udp                   ALLOW       Anywhere                   # authenticated udp port

Checking port binding...
udp   UNCONN 0      0             0.0.0.0:8001       0.0.0.0:*    users:(("monad-node",pid=3433495,fd=13))

Checking service status...
active

Checking configuration...
authenticated_bind_address_port configured

Complete!
```

***

## 附加说明

* **向后兼容性**：节点可以与已认证和未认证的对等节点通信
* **渐进式部署**：在可选加入期间，您可以按照自己的节奏启用认证
* **未来要求**：UDP 认证将在未来的版本中成为强制要求（日期待定）
* **序列号**：重新生成签名时始终递增 `self_record_seq_num`
* **密钥复用**：认证使用您现有的验证者密钥（secp256k1）

***

## 支持

如果您遇到本指南未涵盖的问题：

1. 检查日志：`journalctl -u monad-bft -n 500 --no-pager`
2. 验证所有配置参数与示例匹配
3. 确保您的防火墙和网络策略允许 UDP/8001
4. 联系 Monad 支持并提供您的日志和配置（请脱敏敏感数据）