青龙面板版本管理完全指南：稳定与测试环境无缝切换

你是否在更新青龙面板时遇到任务中断？测试新功能怕影响生产环境？本文详解稳定版与测试版管理，教你无缝切换，兼顾稳定性与新功能体验。读完本文你将掌握：版本区别对比、稳定版安全更新流程、测试版尝鲜技巧、版本切换故障处理。

版本区别：稳定版 vs 测试版

特性	稳定版	测试版
发布周期	月度更新	周度更新
适用场景	生产环境	功能测试
风险等级	低	中高
升级建议	必更安全补丁	选择性尝鲜
切换命令	bash shell/update.sh stable	bash shell/update.sh beta

稳定版管理：保障生产环境可靠

一键更新稳定版

通过项目内置更新脚本快速升级，自动处理依赖变更和静态资源更新：

# 执行稳定版更新
bash shell/update.sh stable

脚本路径：shell/update.sh

脚本核心逻辑会先检查网络连接，从镜像源下载最新稳定版代码（默认使用gitee镜像），自动处理依赖差异后重启服务：

# 脚本关键步骤
wget -cqO "${dir_tmp}/ql.zip" "${downloadQLUrl}/${primary_branch}.zip"  # 下载代码包
unzip -oq ${dir_tmp}/ql.zip -d ${dir_tmp}                               # 解压文件
npm_install_2 "${dir_tmp}/qinglong-${primary_branch}"                   # 安装依赖
reload_qinglong "system"                                                # 重启服务

版本回滚机制

若更新异常，可通过日志定位问题并手动恢复：

# 查看更新日志
cat logs/update.log

# 恢复至上一版本（需提前配置备份脚本）
bash shell/backup.sh restore

测试版管理：尝鲜新功能

切换测试环境

在设置页面开启测试版通道，图形化界面操作更直观：

1. 登录青龙面板
2. 进入【系统设置】→【版本管理】
3. 勾选"启用测试版更新"

前端实现：src/pages/setting/checkUpdate.tsx

界面会调用API检查测试版更新并展示变更日志：

// 前端检查更新核心代码
request
  .put(`${config.apiPrefix}system/update-check`)
  .then(({ code, data }) => {
    if (data.hasNewVersion) {
      showConfirmUpdateModal(data);  // 显示更新确认弹窗
    }
  })

测试版更新命令

命令行方式快速切换测试分支：

# 切换测试版并更新
bash shell/update.sh beta

脚本会自动切换到develop分支，拉取最新测试代码并安装依赖：

# 分支选择逻辑
if [[ "${QL_BRANCH}" == "develop" ]] || [[ "${QL_BRANCH}" == "debian-dev" ]]; then
  primary_branch="${QL_BRANCH}"  # 测试环境分支
fi

版本切换流程图

graph TD
    A[当前版本] --> B{选择版本类型}
    B -->|稳定版| C[执行stable更新脚本]
    B -->|测试版| D[开启测试通道]
    C --> E[验证更新完整性]
    D --> F[执行beta更新脚本]
    E --> G[完成稳定版更新]
    F --> H[测试新功能]
    H --> I{发现问题?}
    I -->|是| J[回滚版本]
    I -->|否| K[完成测试版更新]

环境变量配置

通过环境变量可持久化设置版本偏好，修改back/config/serverEnv.ts配置文件：

// 设置默认分支
process.env.QL_BRANCH = "stable";  // stable/beta/develop

// 配置镜像源（国内用户推荐gitee）
process.env.MIRROR = "gitee";

常见问题解决

更新失败

检查网络连接或查看日志定位问题：

# 查看更新日志
cat logs/update.log

# 典型错误排查
- 网络问题：检查代理设置或切换镜像源
- 依赖冲突：删除node_modules后重新安装
  rm -rf node_modules && npm install

版本切换后任务异常

清除缓存并重启服务：

# 清除缓存
rm -rf /data/web/disk1/git_repo/GitHub_Trending/qi/qinglong/data/cache

# 重启服务
pm2 restart qinglong

总结

通过本文方法，你可以安全管理青龙面板的版本更新，既保障生产环境稳定，又能及时体验新功能。建议定期备份数据，重大更新前先在测试环境验证。版本管理核心在于：稳定版求稳，测试版求新，根据实际需求选择合适的更新策略。

下一篇将介绍《青龙任务自动化部署最佳实践》，敬请关注。