x-ui配置迁移：从旧版本到新版本数据无缝过渡

2026-02-05 04:57:58作者：牧宁李

项目地址：https://gitcode.com/gh_mirrors/xui/x-ui

引言：为什么配置迁移至关重要？

在使用x-ui（Xray面板）的过程中，版本升级是不可避免的。然而，许多用户在升级过程中面临一个共同的痛点：如何确保现有配置、用户数据和入站规则能够完整保留并正常工作？数据丢失、配置错误或服务中断不仅影响使用体验，更可能导致业务中断。本文将详细介绍从旧版本x-ui或v2-ui迁移到新版本x-ui的完整流程，帮助你实现数据的无缝过渡。

读完本文后，你将能够：

了解x-ui配置迁移的核心原理
掌握从v2-ui迁移到x-ui的方法
学会手动备份和恢复x-ui配置
解决迁移过程中常见的问题
制定完善的迁移前后检查清单

x-ui配置迁移概述

迁移原理与核心概念

x-ui作为一款功能强大的Xray管理面板，其配置数据主要存储在SQLite数据库中。迁移过程本质上是将旧版本数据库中的关键信息（用户、入站规则、设置等）转换并导入到新版本数据库的过程。

flowchart TD
    A[旧版本数据] -->|提取| B(用户信息)
    A -->|提取| C(入站规则)
    A -->|提取| D(设置参数)
    B -->|转换| E[新版本数据格式]
    C -->|转换| E
    D -->|转换| E
    E -->|导入| F[新版本数据库]
    F --> G[验证数据完整性]
    G --> H[完成迁移]

支持的迁移场景

目前x-ui主要支持以下两种迁移场景：

从v2-ui迁移到x-ui
x-ui不同版本间的迁移（通过备份恢复实现）

从v2-ui迁移到x-ui

迁移前准备工作

在开始迁移前，请确保满足以下条件：

检查项	要求
系统环境	Linux系统（推荐Ubuntu 20.04+或CentOS 7+）
v2-ui状态	已安装并正常运行
数据备份	已对v2-ui数据进行备份
网络连接	服务器可正常访问网络
权限	拥有root或sudo权限

使用命令行工具迁移

x-ui提供了专门的命令行工具来从v2-ui迁移数据。整个过程只需执行以下步骤：

下载并安装最新版本的x-ui：

bash <(curl -Ls https://gitcode.com/gh_mirrors/xui/x-ui/raw/main/install.sh)

执行迁移命令：

x-ui v2-ui --db /etc/v2-ui/v2-ui.db

注意：默认情况下，v2-ui的数据库路径为/etc/v2-ui/v2-ui.db，如果你的数据库路径不同，请修改上述命令中的路径参数。

迁移成功后，启动x-ui：

x-ui start

迁移命令解析

让我们深入了解迁移命令的工作原理。在x-ui的main.go文件中，迁移功能的核心代码如下：

case "v2-ui":
    err := v2uiCmd.Parse(os.Args[2:])
    if err != nil {
        fmt.Println(err)
        return
    }
    err = v2ui.MigrateFromV2UI(dbPath)
    if err != nil {
        fmt.Println("migrate from v2-ui failed:", err)
    }

这段代码的作用是：

解析命令行参数，获取v2-ui数据库路径
调用v2ui.MigrateFromV2UI函数执行迁移
处理迁移结果，输出成功或错误信息

x-ui版本间迁移

手动备份配置

虽然x-ui目前没有提供直接的版本间迁移命令，但我们可以通过手动备份和恢复的方式实现版本间迁移。

备份步骤

停止x-ui服务：

x-ui stop

备份数据库文件：

# 默认数据库路径
cp /etc/x-ui/x-ui.db /etc/x-ui/x-ui.db.bak-$(date +%Y%m%d)

备份配置文件（如果有自定义配置）：

cp /etc/x-ui/config.json /etc/x-ui/config.json.bak-$(date +%Y%m%d)

备份文件说明

文件路径	说明
/etc/x-ui/x-ui.db	x-ui主数据库文件，包含所有用户、入站规则和设置
/etc/x-ui/config.json	x-ui配置文件，包含面板设置等信息
/usr/local/x-ui/bin/xray	Xray核心可执行文件

从备份恢复配置

安装新版本x-ui（如果尚未安装）：

bash <(curl -Ls https://gitcode.com/gh_mirrors/xui/x-ui/raw/main/install.sh)

停止x-ui服务：

x-ui stop

恢复数据库文件：

cp /etc/x-ui/x-ui.db.bak-YYYYMMDD /etc/x-ui/x-ui.db

注意：将YYYYMMDD替换为实际备份日期

恢复配置文件（如果有）：

cp /etc/x-ui/config.json.bak-YYYYMMDD /etc/x-ui/config.json

启动x-ui服务：

x-ui start

迁移前后检查清单

迁移前检查项

[ ] 确认当前x-ui/v2-ui版本
[ ] 备份所有关键数据
[ ] 记录当前配置信息（端口、用户名、入站规则等）
[ ] 检查磁盘空间是否充足
[ ] 准备好新版本安装命令或安装包

迁移后检查项

[ ] 验证服务是否正常启动
[ ] 检查是否能正常登录面板
[ ] 确认所有用户信息是否完整
[ ] 测试所有入站规则是否正常工作
[ ] 检查流量统计是否准确
[ ] 验证SSL配置（如果使用）
[ ] 测试防火墙规则是否需要更新

常见问题与解决方案

迁移失败：数据库路径错误

错误信息：migrate from v2-ui failed: open /etc/v2-ui/v2-ui.db: no such file or directory

解决方案：

确认v2-ui数据库实际路径：

find / -name "v2-ui.db" 2>/dev/null

使用正确路径重新执行迁移命令：

x-ui v2-ui --db /path/to/your/v2-ui.db

迁移后无法登录面板

可能原因：

用户名密码未正确迁移
端口冲突导致服务未正常启动

解决方案：

检查服务状态：

x-ui status

如果服务未启动，尝试修改端口：

x-ui setting -port 新端口号

重置用户名密码：

x-ui setting -username 新用户名 -password 新密码

入站规则迁移后无法使用

解决方案：

检查入站端口是否被防火墙阻止：

# 对于ufw防火墙
ufw status

# 对于firewalld
firewall-cmd --list-ports

检查Xray配置是否正确生成：

cat /etc/x-ui/xray/config.json

重启Xray服务：

x-ui restart

迁移最佳实践

迁移流程优化

为确保迁移过程顺利，建议遵循以下优化流程：

timeline
    title x-ui配置迁移最佳实践时间线
    section 迁移前准备
        确定迁移策略 : 1天前
        备份关键数据 : 迁移前2小时
        记录当前配置 : 迁移前1小时
        准备测试环境 : 迁移前30分钟
    section 迁移执行
        执行迁移命令 : 0-5分钟
        验证基本功能 : 5-15分钟
        测试入站连接 : 15-30分钟
    section 迁移后优化
        监控系统运行 : 1-24小时
        清理备份文件 : 24小时后

数据安全建议

多重备份：至少保留两份不同位置的备份
备份验证：迁移前确认备份文件可正常打开
测试迁移：条件允许时，先在测试环境验证迁移流程
迁移窗口期：选择业务低峰期进行迁移
回滚计划：制定详细的回滚步骤，以防迁移失败

总结与展望

x-ui配置迁移是版本升级过程中的关键步骤，通过本文介绍的方法，你可以安全、高效地完成从v2-ui到x-ui的迁移，或x-ui不同版本间的迁移。核心迁移命令x-ui v2-ui提供了便捷的自动化迁移方式，而手动备份恢复则为不同场景下的迁移提供了灵活性。

随着x-ui的不断发展，未来可能会推出更完善的迁移工具和更多迁移选项。建议定期关注项目更新，及时了解新的迁移特性和最佳实践。

最后，无论使用哪种迁移方法，都请记住：备份是数据安全的最后一道防线。在进行任何迁移操作前，务必确保已创建完整的数据备份。

附录：迁移命令参考

命令	说明
`x-ui v2-ui --db /path/to/v2-ui.db`	从v2-ui迁移数据
`x-ui setting -port 端口号`	修改面板端口
`x-ui setting -username 用户名 -password 密码`	修改登录凭据
`x-ui setting -reset`	重置所有设置
`x-ui start`	启动x-ui服务
`x-ui stop`	停止x-ui服务
`x-ui restart`	重启x-ui服务
`x-ui status`	查看x-ui状态