# 서버를 새 버전으로 마이그레이션

> Learn how to migrate your Unity Licensing Server to a new version.

최신 서버 버전에서는 종종 다른 서버 데이터베이스 또는 구성이 필요할 수 있습니다. 예를 들어 버전 1.6이 설치되어 있는데 버전 1.9를 실행하려는 경우 서버에는 다른 구성이 필요합니다.

마이그레이션 프로세스에서는 [서버 구성 파일](./server-admin.md#advanced-server-configuration)에서 `serverVersion` 프로퍼티를 확인합니다. 마이그레이션 프로세스에서 현재 버전의 Unity Licensing Server가 새 버전과 호환되지 않는 것을 감지하면 다음 메시지가 표시되고 중지됩니다.

```bash
Cannot start the licensing server. 
Incompatible version is already installed. 
Please, make sure to stop existing Licensing.Server 
service (if it is running) and run setup command.
```

이 비호환성 문제를 해결하려면 사용하는 운영체제에 따라 아래 해당하는 커맨드를 실행하십시오.

* **Linux**: Linux Terminal을 사용하여 `./Unity.Licensing.Server setup`을 `sudo`로 실행합니다.
* **Windows**: 관리자 권한으로 Windows PowerShell을 열고 `.\Unity.Licensing.Server.exe setup`을 실행합니다.

```bash
- - -
Welcome to Unity Licensing Server setup command line interface.
This setup will help you configure your license server 
and generate server registration request file.
- - -
Upgrading from 1.6.0 to 1.9.0...
Backup installed version 1.6.0...Done
Scripts to run: 1.9.0
Executing 1.9.0...Done
Stamping version 1.9.0...Done
Successfully migrated from 1.6.0 to 1.9.0
```

> **Important:**
>
> 설정 커맨드를 실행하기 전에 [Licensing Server 서비스](./server-setup-svc.md)를 중지합니다.
>
> 라이선스 서버 마이그레이션을 시작하기 전에 다운타임에 대한 계획을 수립하십시오. 현재 버전과 타겟 버전에 따라 마이그레이션하는 데 시간이 걸릴 수도 있습니다. 예를 들어 Unity 연구실에서는 1.11.0 이전 버전에서 1.11.0 이후 버전으로 마이그레이션하기 위해 3GB 데이터베이스에서 완료하는 데 15분이 소요되었습니다.
>
> 복잡한 마이그레이션의 경우 진행하기 전에 확인 메시지가 표시됩니다.

확인이 필요한 마이그레이션의 예(Windows):

```bash
> .\Unity.Licensing.Server.exe setup
- - - -
Welcome to Unity Licensing Server setup command line interface.
This setup will help you configure your license server 
and generate server registration request file.
- - - -

Upgrading from 1.10.0 to 1.11.0...

This migration can take more than a few minutes. Are you sure you want to run it now? [y/N] y

Proceeding with migration...
Backup installed version 1.10.0...Done
Scripts to run: 1.11.0
Executing 1.11.0...Done
Stamping version 1.11.0...Done
Successfully migrated from 1.10.0 to 1.11.0
Enter the server name (e.g. LicenseServer):
```

> **Note:**
>
> 마이그레이션 프로세스는 서버 로그 파일에 자세한 정보를 기록하지만 새 정보가 표시되는 데 시간이 걸릴 수도 있습니다.

## 마이그레이션 작동 방식

`setup` 커맨드는 현재 서버 버전을 감지하고 마이그레이션을 시작하기 전에 서버 데이터를 `LicensingServerBackups` 디렉토리에 복사합니다. 이 디렉토리의 위치는 서버의 운영체제 및 라이선스 서버의 버전에 따라 다릅니다.

* **Linux**:
  * 버전 2.0 이상: `/usr/share/unity3d/LicensingServerBackups`
  * 버전 1.x: `~/.config/unity3d/Unity/LicensingServerBackups`
* **Windows**:
  * 버전 2.0 이상: `%PROGRAMDATA%\Unity\LicensingServerBackups`
  * 버전 1.x: `%LOCALAPPDATA%\Unity\LicensingServerBackups`

새 서버 버전과 호환되도록 데이터를 전환하면서 마이그레이션이 계속됩니다. 마이그레이션이 완료되면 이전 서버 설정에서 제공한 정보를 사용하여 구성 프로세스가 시작됩니다.

> **Note:**
>
> 만약 마이그레이션 중에 문제가 발생하면 `setup`  커맨드는 마이그레이션을 취소하고 데이터를 마이그레이션 이전 상태로 복원합니다.

### 허용 목록을 사용한 관리자 액세스

버전 1.x에서 마이그레이션하는 경우 관리자 액세스를 제어하기 위해 IP 주소를 사용하는 허용 목록이 있을 수 있습니다. 버전 2.0 이상으로 마이그레이션하는 경우에는 관리자 액세스 권한을 유지하기 위해 수행해야 할 명시적인 단계가 없습니다. 허용 목록에 있는 모든 IP 주소는 API의 `admin` 엔드포인트와 [대시보드](./server-admin-dash.md)의 관리자 모드에 계속 액세스할 수 있습니다. 이러한 IP 주소를 가진 사용자가 대시보드에 액세스하면 로그인 화면을 우회하여 관리자 모드로 자동 로그인됩니다.

## 데이터베이스 복원

서버를 더 높은 버전으로 마이그레이션하면 `setup` 커맨드가 자동으로 데이터베이스 파일의 백업 복사본을 생성합니다. 복원에 실패하면 다음과 같은 심각한 오류 메시지가 나타납니다.

```bash
An error occurred while restoring a backup.
```

이는 서버가 유효한 상태가 아니며, 이로 인해 이전 서버 버전을 계속 사용하지 못할 수 있음을 나타냅니다. 이 오류를 해결하려면 `LicensingServerBackups/<your_old_server_version />/` 디렉토리의 콘텐츠를 `LicensingServer` 디렉토리에 복사하여 백업 데이터를 수동으로 복원해야 합니다. 예를 들면 다음과 같습니다.

```plaintext
├── LicensingServer
│   ├── config
│   │   ├── key-b4573620-ca22-423f-8d52-e3a767391234.xml
│   │   ├── licensing-server-config.json
│   │   └── unity.licensing.delegation.key
│   ├── data
│   └── wwwroot\v1\package\acl
│
└── LicensingServerBackups
    └── 1.6.0
        ├── config
        ├── data
        └── wwwroot
```

서버를 이전 버전으로 복원하려면 다음 단계를 따릅니다.

1. 서버의 운영체제 및 라이선스 서버의 버전에 따라 달라지는 아래 타겟 폴더에 기존 데이터베이스를 넣습니다.

   * **Linux**:
     * 버전 2.0 이상: `/usr/share/unity3d/LicensingServer/data/`
     * 버전 1.x: `~/.config/unity3d/Unity/LicensingServer/data/`
   * **Windows**:
     * 버전 2.0 이상: `%PROGRAMDATA%\Unity\LicensingServer\data\`
     * 버전 1.x: `%LOCALAPPDATA%\Unity\LicensingServer\data\`

2. 파일의 이름을 `LicensingServerDb.sqlite`로 변경합니다.

## 추가 리소스

* [설정 커맨드 실행](./server-setup-cfg-v2.md#running-the-setup-command)(버전 2.0 이상)
* [설정 커맨드 실행](./server-setup-cfg-v1.md#running-the-setup-command)(버전 1.x)