从 Marzban 迁移

Marzban 把数据存储在 MySQL 或 MariaDB 中，而 XLADA 存储在 PostgreSQL 中。 在不同 DBMS 之间直接迁移数据库目录是不可能的：用户通过面板 API 迁移，而旧的订阅链接通过订阅页面的兼容模式 继续可用。「一条命令」的迁移只适用于用户数据； Xray 配置、节点和主机需要在 XLADA 中重新配置。

哪些内容会被迁移

Marzban 数据	如何迁移
用户名	POST /api/users 中的 username
Trojan 和 Shadowsocks 密码、VLESS UUID	trojanPassword、ssPassword、vlessUuid 字段
流量限制和重置周期	trafficLimitBytes、trafficLimitStrategy
到期日期	ISO 8601 格式的 expireAt
状态（active、disabled、limited、expired）	status
分组归属	internal-squads 或批量操作
旧的订阅链接	订阅页面上的 MARZBAN_LEGACY_* 模式

管理员、流量历史、inbound/outbound 和主机不会被迁移 —— 它们 需要在 XLADA 中通过配置档案和主机重新创建。

限制

• Marzban 中的用户类型由协议决定：vless 需要 vlessUuid，trojan 需要 trojanPassword，shadowsocks 需要 ssPassword。 如果不迁移协议，用户就需要新的密钥。
• XLADA 中的用户名只允许拉丁字母、数字、_ 和 -（在 API 中不短于 三个字符）。解析旧链接时，不允许的字符会被替换为 _，而短于六个字符的名称会补足到六个字符。请从一开始就用这种 形式创建用户，否则旧链接将找不到归属者。
• 面板内没有现成的导入器：独立的迁移工具位于 组织 xray-panel/migrate 的仓库中，而面板只通过 API 接收数据。

对 legacy 链接的支持

订阅页面能够接受旧的 Marzban 链接，并按名称把它们与 XLADA 用户匹配。该模式通过环境变量启用：

变量	用途
MARZBAN_LEGACY_LINK_ENABLED	启用兼容模块
MARZBAN_LEGACY_SECRET_KEY	来自 Marzban 数据库的密钥；多个密钥用逗号分隔
MARZBAN_LEGACY_SUBSCRIPTION_VALID_FROM	时间截点：早于该日期创建的链接不被接受
MARZBAN_LEGACY_DROP_REVOKED_SUBSCRIPTIONS	为已撤销的订阅断开连接
CUSTOM_SUB_PREFIX	订阅链接前缀，例如 sub

启用该模式时 MARZBAN_LEGACY_SECRET_KEY 是必填项 —— 没有它， 订阅页面容器无法启动。

services:
  remnawave-subpage:
    image: ghcr.io/xray-panel/subscription-page:latest
    restart: unless-stopped
    environment:
      - APP_PORT=3010
      - REMNAWAVE_PANEL_URL=http://remnawave:3000
      - REMNAWAVE_API_TOKEN=token_from_panel
      - MARZBAN_LEGACY_LINK_ENABLED=true
      - MARZBAN_LEGACY_SECRET_KEY=secret_from_marzban_db
      - CUSTOM_SUB_PREFIX=sub

密钥存放在 Marzban 数据库的 jwt 表中：

SELECT secret_key FROM jwt LIMIT 1;

该模式支持哪些链接

Marzban 的两种方案都受支持：带 HS256 算法和 access: subscription 字段的 JWT，以及带 SHA-256 签名的 base64url 令牌。 如果 XLADA 中没有叫这个名字的用户，旧链接将无法打开。

分步计划

1. 盘点。 从 Marzban 导出用户列表，并保存 jwt 表中的 secret_key。统计用户数量 —— 这是校验的 基准。
2. 安装 XLADA。 按照 安装面板 和 安装节点 的说明部署面板和节点，在 Settings → API Tokens 中创建 API 令牌。
3. 迁移用户。 用 POST /api/users 方法创建它们，保留 名称、到期日期和流量限制：

curl -sX POST https://panel.example.com/api/users \
  -H "Authorization: Bearer $XLADA_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"username": "john_doe", "expireAt": "2026-01-17T15:38:45.065Z", "trafficLimitBytes": 0, "trafficLimitStrategy": "NO_RESET"}'

4. 分组。 把迁移过来的用户分配到内部分组 —— 可以逐个进行，也可以通过 /api/users/bulk/update-squads 批量进行。
5. 旧链接。 使用上面示例中的 MARZBAN_LEGACY_* 部署订阅页面， 并重启它的容器。
6. 检查。 打开几个旧的 Marzban 链接：页面应当显示 XLADA 用户的数据。然后在 用户 一节检查新链接。

提示

先迁移 5–10 个用户，并确认登录和旧链接都能 正常工作。在核对用户数量并确认客户端已连接之前， 不要关闭 Marzban。

接下来

• 从 Remnawave 迁移 —— 在同一数据库上迁移面板。
• 订阅页面 —— 安装和环境变量。
• 用户 —— 限制、状态和订阅。
• API Specification —— 创建和批量操作的方法。