NetBird自托管服务中Peer节点消失问题的分析与解决

问题现象

在NetBird自托管环境中，当管理服务(management service)重启后，管理界面中Peer节点列表显示异常。具体表现为：

1. 管理界面显示0个Peer节点
2. 客户端实际连接状态正常（通过netbird status命令可见）
3. 界面中"All Groups"筛选组消失但被默认选中

根本原因分析

该问题主要由两个因素共同导致：

1. 存储引擎配置问题
   早期版本默认使用内存存储，重启后数据丢失。虽然后续版本已改进，但未正确迁移到持久化存储（SQLite）的环境仍会受影响。

2. 前端缓存问题
   管理界面UI保留了旧的状态数据，导致筛选条件异常，无法正确显示Peer列表。

完整解决方案

一、数据存储迁移（核心步骤）

1. 停止管理服务容器
2. 备份现有数据
3. 执行SQLite迁移命令
4. 修改management.json配置文件，显式指定SQLite引擎
5. 重启管理服务

迁移完成后，管理服务日志应显示"Using SQLite store engine"确认信息。

二、前端缓存清理

1. 完全退出管理界面
2. 清除浏览器针对该站点的所有缓存数据（包括Cookies、LocalStorage等）
3. 重新登录管理界面

三、验证步骤

1. 检查管理界面"All Groups"筛选器是否正常显示
2. 确认Peer节点列表完整显示
3. 通过客户端命令行验证连接状态

技术原理详解

NetBird管理服务支持多种存储后端：

• 内存存储（易失性，仅适合测试）
• SQLite（轻量级持久化方案）
• PostgreSQL（企业级方案）

在版本迭代过程中，SQLite已成为推荐的默认存储方案。该方案具有以下优势：

1. 单文件存储，部署简单
2. 支持ACID事务
3. 无需额外数据库服务
4. 性能满足中小规模部署需求

最佳实践建议

1. 新部署时应在初始配置中明确指定SQLite引擎
2. 定期备份/var/lib/netbird/目录下的数据文件
3. 重要操作前执行完整服务停止→备份→启动流程
4. 管理界面更新后应执行强制刷新（Ctrl+F5）

总结

通过存储引擎的合理配置和数据迁移，可以有效解决NetBird自托管环境中的Peer节点显示问题。该案例也提醒我们，在服务重启等维护操作前，应充分了解系统的数据持久化机制，做好相应的预案和验证工作。