最完整的Beszel升级指南：从v0.12到v1.0无缝迁移

你是否正在使用Beszel v0.12版本，担心升级到v1.0会遇到兼容性问题？本文将帮助你完成从v0.12到v1.0的平滑过渡，确保数据不丢失、服务不中断。读完本文后，你将能够：

• 了解v0.12到v1.0的核心变化
• 掌握两种升级方法（自动升级和手动升级）
• 解决常见的迁移问题
• 验证升级结果

核心变化概览

v1.0版本带来了多项重要改进，包括：

• 系统链接永久化：系统链接现在使用ID而非名称，避免名称变更导致的链接失效。(supplemental/CHANGELOG.md#5)
• 性能优化：磁盘I/O统计精度提升，一分钟图表采样间隔缩短至1秒。(supplemental/CHANGELOG.md#9, #11)
• 环境变量支持：新增SYSTEM_NAME环境变量，可覆盖系统名称。(supplemental/CHANGELOG.md#13)

升级前准备

检查当前版本

/opt/beszel/beszel --version

备份数据

# 创建数据备份
cp -r /opt/beszel/beszel_data /opt/beszel/beszel_data_backup_$(date +%Y%m%d)

检查系统要求

确保系统满足以下条件：

• 操作系统：Linux (推荐Ubuntu 20.04+)、FreeBSD或macOS
• 内存：至少512MB
• 磁盘空间：至少100MB可用空间

升级方法

方法一：自动升级（推荐）

适用于使用安装脚本安装的用户：

# Hub升级
sudo /opt/beszel/beszel update && sudo systemctl restart beszel-hub

# Agent升级
sudo /opt/beszel-agent/beszel-agent update && sudo systemctl restart beszel-agent

方法二：手动升级

1. 下载最新版本

# 下载安装脚本
curl -sL https://gitcode.com/GitHub_Trending/be/beszel/raw/main/supplemental/scripts/install-hub.sh -o install-hub.sh && chmod +x install-hub.sh

# 指定国内镜像（如果需要）
./install-hub.sh --mirror https://gh.beszel.dev

2. 执行安装

# 安装Hub（默认端口8090）
./install-hub.sh -p 8090

# 安装Agent（需替换YOUR_KEY）
curl -sL https://gitcode.com/GitHub_Trending/be/beszel/raw/main/supplemental/scripts/install-agent.sh -o install-agent.sh && chmod +x install-agent.sh
./install-agent.sh -k "YOUR_KEY"

3. 重启服务

# 重启systemd服务
sudo systemctl daemon-reload
sudo systemctl restart beszel-hub beszel-agent

迁移注意事项

系统链接变更

由于v1.0使用ID而非名称作为系统链接，升级后需更新所有外部链接。例如，原链接http://your-hub/system/my-server需替换为http://your-hub/system/123（其中123为系统ID）。

环境变量配置

新增的SYSTEM_NAME环境变量可在注册时覆盖系统名称：

# 在Agent服务文件中添加
Environment="SYSTEM_NAME=Production-Server"

编辑服务文件：

sudo nano /etc/systemd/system/beszel-agent.service

保存后重启服务：

sudo systemctl daemon-reload
sudo systemctl restart beszel-agent

数据迁移验证

升级后检查数据完整性：

# 检查Hub日志
journalctl -u beszel-hub -n 50

# 检查Agent连接状态
systemctl status beszel-agent

常见问题解决

服务启动失败

问题：升级后服务无法启动，日志显示"address already in use"。

解决：检查端口占用情况并修改配置：

# 查找占用端口的进程
sudo lsof -i :8090

# 修改Hub端口
sudo nano /etc/systemd/system/beszel-hub.service
# 修改ExecStart行中的端口号
sudo systemctl daemon-reload
sudo systemctl restart beszel-hub

数据丢失

问题：升级后部分历史数据丢失。

解决：从备份恢复数据：

# 停止服务
sudo systemctl stop beszel-hub

# 恢复数据
rm -rf /opt/beszel/beszel_data
cp -r /opt/beszel/beszel_data_backup_20251008 /opt/beszel/beszel_data
chown -R beszel:beszel /opt/beszel/beszel_data

# 重启服务
sudo systemctl start beszel-hub

升级后验证

检查版本

/opt/beszel/beszel --version
# 应显示v1.0.x

验证功能

1. 访问Web界面：http://your-hub:8090
2. 检查系统列表是否完整
3. 验证图表数据是否正常显示
4. 测试告警功能是否工作

总结

Beszel从v0.12到v1.0的升级过程相对简单，通过自动升级脚本可快速完成。核心注意事项包括：

• 系统链接使用ID而非名称
• 新增环境变量的配置
• 数据备份的重要性

如有任何问题，可查阅官方文档或提交issue获取帮助。

提示：定期执行beszel update命令可保持系统最新，或启用自动更新功能：

# 为Hub启用自动更新
./install-hub.sh --auto-update

感谢使用Beszel！如有任何问题，请查阅官方文档或项目GitHub仓库。