从 Remnawave 迁移

XLADA 是采用 AGPL-3.0-only 的 Remnawave 分支，因此迁移归结为替换 镜像：服务名、数据库卷和网络都保持不变，而 PostgreSQL 在同一个数据目录上启动。下面是「原地」、在同一台 服务器上的操作顺序。

哪些内容会被保留

只有容器镜像会改变。分支中有意没有重命名表和列的名称， 因此现有数据库仍然有效：

模型	表
用户	users
节点	nodes
主机	hosts
管理员	admin
API 令牌	api_tokens
HWID 设备	hwid_user_devices
配置档案	config_profiles
内部分组和外部分组	internal_squads, external_squads
设置	remnawave_settings

.env 文件无需重命名键即可迁移：APP_SECRET、 POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB、DATABASE_URL、 PANEL_DOMAIN、FRONT_END_DOMAIN、SUB_PUBLIC_DOMAIN 等变量的读取方式 相同。订阅页面仍然使用带 REMNAWAVE_ 前缀的变量 （REMNAWAVE_PANEL_URL、REMNAWAVE_API_TOKEN）。

XLADA 的迁移只是追加式的：会新增管理员操作日志表和 两步验证字段。因此迁移是可逆的 —— 只要把面板镜像 换回原来的即可。

准备工作

开始之前请核对实际的名称和版本 —— 数据库能否启动取决于它们：

docker volume ls
docker ps --format 'table {{.Names}}\t{{.Image}}'

卷与 PostgreSQL 版本

迁移文件会保留旧安装的卷名（在标准 compose 中是 remnawave-db-data）。如果你的卷名不同，不要重命名它，而是把 compose 中的 name: 指令改成已有的名称。

数据目录在不同大版本之间不兼容。新的 XLADA compose 面向 PostgreSQL 18，但迁移时要使用创建了你那个卷的同一个大版本 —— 在现成的文件中是 postgres:17.6。升级到 18 要稍后再做， 作为单独一步通过备份和恢复完成。

备份

为数据库创建备份并保存 .env。在迁移经过验证之前， 请把备份放在数据库卷之外。

docker exec remnawave-db pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB" \
  > ~/remnawave-backup-$(date +%F).sql
tail -n 1 ~/remnawave-backup-*.sql   # 预期输出：-- PostgreSQL database dump complete

cp deploy/.env ~/remnawave-env-backup
chmod 600 ~/remnawave-env-backup

停止旧栈

cd deploy && docker compose down

停止时请不要加 -v 标志：它会连同数据库一起删除卷。

在同一数据库上启动 XLADA

从 XLADA 仓库中取出 docker-compose.migrate-from-remnawave.yml 文件。 它与普通 compose 的区别只在于：它保留旧安装的服务名和 卷；普通 compose 会创建一个空数据库。在 .env 中添加 可选的镜像标签变量：

XLADA_VERSION=latest

启动：

docker compose -f docker-compose.migrate-from-remnawave.yml up -d
docker logs -f remnawave

容器启动时会自动应用迁移：entrypoint 会执行 prisma migrate deploy 和 prisma db seed。请在日志中等待 Migrations deployed successfully! 和 Nest application successfully started 这两行。

自动化

同样的步骤由 migrate-to-xlada.sh 脚本完成：它会把 备份、.env、compose 文件和卷列表放进 backups/<日期-时间>/， 检查备份是否完整，在不加 -v 的情况下停止栈并启动 XLADA。

检查

# 面板有响应
curl -s -o /dev/null -w '%{http_code}\n' https://panel.example.com/api/auth/status

# 数据库能看到用户 —— 之前和之后的数量必须一致
docker exec remnawave-db psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -tAc "SELECT count(*) FROM users;"

# 迁移已应用
docker exec remnawave-db psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c \
  'SELECT migration_name FROM _prisma_migrations ORDER BY finished_at DESC LIMIT 5;'

迁移列表中应当有 20260912120000_add_admin_audit_log 和 20260912130000_add_admin_totp。然后使用原来的管理员 凭据登录面板，并确认 Nodes 页面上的节点已连接。

不能做的事

危险

• docker compose down -v —— -v 标志会连同数据库一起删除卷。这是 唯一一条真正会销毁用户的命令。
• 修改 APP_SECRET —— 密码哈希、JWT 签名和 TOTP 密钥加密都依赖它。修改之后没有人能登录面板。
• 重命名卷、服务和网络 —— compose 会创建新的空卷， 而旧的会继续留在旁边。DATABASE_URL 指向主机 remnawave-db。
• 在现有卷上升级 PostgreSQL 大版本以及修改已经 应用过的迁移 —— Prisma 会比对 _prisma_migrations 中的校验和。

在确认登录、节点和订阅都能正常工作之前，不要删除备份和 .env 的 副本。

接下来

• 从 Marzban 迁移 —— 当原面板是另一种时。
• 更新 —— 迁移后如何发布新版本。
• 面板安全 —— 两步验证和登录尝试限制。
• 环境变量 —— 包括 AUDIT_LOG_RETENTION_DAYS。