Marzban에서 마이그레이션

이 가이드는 Remnawave 마이그레이션 도구를 사용하여 Marzban 패널에서 Remnawave 패널로 데이터를 마이그레이션하는 과정을 안내합니다.

1. 서버 준비

1.1. 필수 의존성 설치

시스템 패키지를 업데이트하고 Git 및 wget을 설치하여 서버에 필요한 도구가 설치되어 있는지 확인하세요.

# Update system packages
sudo apt-get update

# Install Git and wget
sudo apt-get install -y git wget

팁

git --version 및 wget --version을 실행하여 설치가 성공했는지 확인하세요.

2. 마이그레이션 도구 다운로드

2.1. 최신 릴리스 다운로드

GitHub 릴리스 페이지에서 사전 컴파일된 Remnawave 마이그레이션 도구를 다운로드하세요.

# Create and navigate to a working directory
mkdir -p /opt/remnawave && cd /opt/remnawave

# Download the latest version (v2.1.0 as of this guide)
wget https://github.com/remnawave/migrate/releases/download/v2.1.0/remnawave-migrate-v2.1.0-linux-amd64.tar.gz

2.2. 도구 압축 해제

다운로드한 아카이브를 압축 해제하여 바이너리에 접근하세요.

# Extract the tarball
tar -xf remnawave-migrate-v2.1.0-linux-amd64.tar.gz

팁

압축 해제 후, 디렉토리에서 remnawave-migrate 바이너리를 확인할 수 있어야 합니다. ls -l로 확인하세요.

3. 설정 구성

3.1. 마이그레이션 매개변수 설정

마이그레이션 도구는 설정에 커맨드라인 플래그를 사용합니다. 다음은 필요한 모든 매개변수를 포함하는 예시 명령어입니다. 플레이스홀더 값을 실제 서버 정보로 교체하세요.

./remnawave-migrate \
  --panel-type=marzban \
  --panel-url=https://your-marzban-server \
  --panel-username=admin \
  --panel-password=your-admin-password \
  --remnawave-url=https://your-remnawave-server \
  --remnawave-token=your-remnawave-token \
  --preserve-status

3.2. 설정 옵션

도구는 다음 플래그와 해당하는 환경 변수를 지원합니다:

플래그	환경 변수	설명	기본값
`--panel-type`	`PANEL_TYPE`	소스 패널 유형 (`marzban` 또는 `marzneshin`)	`marzban`
`--panel-url`	`PANEL_URL`	소스 패널 URL (예: `https://marzban.example.com`)	-
`--panel-username`	`PANEL_USERNAME`	소스 패널 관리자 사용자명	-
`--panel-password`	`PANEL_PASSWORD`	소스 패널 관리자 비밀번호	-
`--remnawave-url`	`REMNAWAVE_URL`	대상 패널 URL (예: `https://remnawave.example.com`)	-
`--remnawave-token`	`REMNAWAVE_TOKEN`	대상 패널 API 토큰 (Authorization Bearer로 사용)	-
`--batch-size`	`BATCH_SIZE`	배치당 처리할 사용자 수	`100`
`--last-users`	`LAST_USERS`	마지막 N명의 사용자만 마이그레이션 (0 = 모든 사용자)	`0`
`--preferred-strategy`	`PREFERRED_STRATEGY`	트래픽 초기화 전략 (`NO_RESET`, `DAY`, `WEEK`, `MONTH`)	-
`--source-headers`	`SOURCE_HEADERS`	소스 패널을 위한 추가 헤더	-
`--dest-headers`	`DEST_HEADERS`	Remnawave를 위한 추가 헤더 (예: X-Api-Key)	-
`--preserve-status`	`PRESERVE_STATUS`	소스 패널의 사용자 상태 유지	`false`
`--preserve-subhash`	`PRESERVE_SUBHASH`	소스 패널의 사용자 구독 URL 해시 유지	`false`
`--internal-squad`	`INTERNAL_SQUAD`	할당할 내부 그룹의 UUID (쉼표로 구분)	-
`--external-squad`	`EXTERNAL_SQUAD`	생성된 모든 사용자에게 할당할 외부 그룹의 UUID	-

팁

Caddy로 추가 보안이 제공된 Remnawave를 사용하는 경우 다음 단계를 따르세요:

Auth 포털에 로그인하고 API Keys로 이동하세요
새 API 키를 발급하세요
다음 형식으로 --dest-headers 플래그를 사용하여 이 키를 전달하세요:
```
--dest-headers="X-Api-Key:api-key-from-auth-portal"
```

팁

소수의 사용자로 테스트 마이그레이션을 하려면 --last-users=5를 사용하세요.
Remnawave API 토큰은 Remnawave 패널 설정(예: API 또는 통합 아래)에서 가져오세요.
--preferred-strategy가 지정되지 않은 경우, Marzban의 원래 전략이 사용됩니다. YEAR 전략은 NO_RESET으로 변환됩니다.

3.3. 사용자를 그룹에 할당

마이그레이션된 모든 사용자를 내부 및/또는 외부 그룹에 자동으로 할당할 수 있습니다:

# Assign to a single internal squad
./remnawave-migrate \
  [other flags...] \
  --internal-squad=e5201a6a-c50e-4b58-9ecb-a4c26c5e74c8

# Assign to multiple internal squads
./remnawave-migrate \
  [other flags...] \
  --internal-squad=uuid1,uuid2,uuid3

# Assign to an external squad
./remnawave-migrate \
  [other flags...] \
  --external-squad=f6302b7b-d61f-5c69-0fdc-b5d37d6e85d9

# Assign to both internal and external squads
./remnawave-migrate \
  [other flags...] \
  --internal-squad=uuid1,uuid2 \
  --external-squad=uuid3

4. 마이그레이션 후 확인

4.1. 확인할 사항

마이그레이션 후 Remnawave 패널에서 다음을 확인하세요:

사용자 수: 마이그레이션된 사용자 수가 소스와 일치하는지 확인하세요.
데이터 무결성:
- 사용자명
- 비밀번호 (Trojan, VLESS UUID, Shadowsocks)
- 트래픽 한도 및 초기화 전략
- 만료 날짜
- 사용자 상태 (--preserve-status 사용 시)
- 구독 URL 해시 (--preserve-subhash 사용 시)
- 그룹 할당 (--internal-squad 또는 --external-squad 사용 시)

팁

Remnawave 패널에 로그인하여 몇 명의 사용자를 무작위로 확인해 데이터 정확성을 검증하세요.

5. 레거시 Marzban 구독 페이지 지원

Remnawave로 마이그레이션한 후, 레거시 Marzban 구독 페이지의 지원 및 렌더링을 보장하는 유일한 방법은 https://github.com/remnawave/subscription-page/ 저장소를 사용하는 것입니다.

5.1. 기본 Docker Compose 설정

기본적으로 구독 페이지 서비스의 docker-compose.yml 파일은 다음과 같습니다:

services:
    remnawave-subscription-page:
        image: remnawave/subscription-page:latest
        container_name: remnawave-subscription-page
        hostname: remnawave-subscription-page
        restart: always
        environment:
            - APP_PORT=3010
            - REMNAWAVE_PANEL_URL=http://remnawave:3000
        ports:
            - '127.0.0.1:3010:3010'
        networks:
            - remnawave-network
networks:
    remnawave-network:
        driver: bridge
        external: true

5.2. Marzban 호환성을 위한 조정

마이그레이션 중에는 Marzban 구독 경로와의 호환성을 보장하고 Marzban 구독 링크의 복호화를 활성화해야 합니다. 기본 설정의 environment 섹션을 다음으로 교체하세요:

services:
    remnawave-subscription-page:
        image: remnawave/subscription-page:latest
        container_name: remnawave-subscription-page
        hostname: remnawave-subscription-page
        restart: always
        environment:
            - APP_PORT=3010
            - REMNAWAVE_PANEL_URL=http://remnawave:3000
            - MARZBAN_LEGACY_LINK_ENABLED=true
            - MARZBAN_LEGACY_SECRET_KEY=secret
            - REMNAWAVE_API_TOKEN=token
            - CUSTOM_SUB_PREFIX=sub
        ports:
            - '127.0.0.1:3010:3010'
        networks:
            - remnawave-network
networks:
    remnawave-network:
        driver: bridge
        external: true

설정 옵션 설명

변수	설명	예시 값
`REMNAWAVE_PANEL_URL`	Remnawave 패널 URL, http://remnawave:3000 또는 https://panel.example.com 사용 가능	`http://remnawave:3000`
`APP_PORT`	구독 페이지 서비스가 실행되는 포트.	`3010`
`MARZBAN_LEGACY_LINK_ENABLED`	레거시 Marzban 구독 링크 지원을 활성화합니다. 아래 옵션을 사용하려면 `true`여야 합니다.	`true`
`MARZBAN_LEGACY_SECRET_KEY`	레거시 링크 복호화에 필요한 Marzban 데이터베이스의 비밀 키.	`secret`
`REMNAWAVE_API_TOKEN`	Remnawave 패널 대시보드("API Tokens" 아래)에서 생성된 API 토큰.	`token`
`CUSTOM_SUB_PREFIX`	Marzban 설정과 일치하도록 구독 URL의 사용자 지정 접두사 (예: `sub`).	`sub`

팁

MARZBAN_LEGACY_LINK_ENABLED가 true로 설정된 경우 이후의 모든 변수(MARZBAN_LEGACY_SECRET_KEY, REMNAWAVE_API_TOKEN, CUSTOM_SUB_PREFIX)를 제공해야 합니다.
MARZBAN_LEGACY_SECRET_KEY를 가져오려면 다음으로 Marzban 데이터베이스에 쿼리하세요:
```
SELECT secret_key FROM jwt LIMIT 1;
```
예를 들어, Marzban 데이터베이스가 marzban-mysql이라는 Docker 컨테이너에 있는 경우 다음을 사용하여 연결하세요:
```
docker exec -it marzban-mysql mysql -uroot -pPassword
```
marzban-mysql과 Password를 실제 컨테이너 이름과 root 비밀번호로 교체하세요.
Remnawave 대시보드의 "API Tokens" 섹션에서 REMNAWAVE_API_TOKEN을 생성하세요.

5.3. 레거시 지원 확인

업데이트된 설정을 배포한 후:

remnawave-subscription-page 서비스를 재시작하세요:
```
docker compose up -d --force-recreate
```
오래된 Marzban 구독 링크를 테스트하여 올바르게 해석되고 Remnawave 구독 페이지에 사용자 데이터가 표시되는지 확인하세요.

1. 서버 준비​

1.1. 필수 의존성 설치​

2. 마이그레이션 도구 다운로드​

2.1. 최신 릴리스 다운로드​

2.2. 도구 압축 해제​

3. 설정 구성​

3.1. 마이그레이션 매개변수 설정​

3.2. 설정 옵션​

3.3. 사용자를 그룹에 할당​

4. 마이그레이션 후 확인​

4.1. 확인할 사항​

5. 레거시 Marzban 구독 페이지 지원​

5.1. 기본 Docker Compose 설정​

5.2. Marzban 호환성을 위한 조정​

설정 옵션 설명​

5.3. 레거시 지원 확인​