[SaaS만]{class="badge positive" title="Adobe Commerce as a Cloud Service 및 Adobe Commerce Optimizer 프로젝트에만 적용됩니다(Adobe 관리 SaaS 인프라)."}

대량 데이터 마이그레이션 실행

이 안내서는 대량 데이터 마이그레이션 도구를 사용하여 Adobe Commerce PaaS 또는 온-프레미스 설치에서 Adobe Commerce as a Cloud Service​(으)로 데이터 마이그레이션을 실행하기 위한 단계별 운영 참조입니다. 실제 구성 값 및 환경별 세부 정보는 설정에 따라 다릅니다.

시작하기 전에 고객 준비 검사 목록의 모든 항목을 완료했는지 확인하고 마이그레이션 서비스 액세스 안내서를 통해 API 액세스를 확인했습니다.

사전 요구 사항

도구 패키지 설정

대량 데이터 마이그레이션을 위한 환경 설정:

예제 구성 파일

저장소 루트의 .example.env 및 .my.cnf.example 파일이 구성의 시작점입니다. 각 파일을 작업 이름으로 복사하고 필요한 값을 입력합니다.

환경 파일 구성

프로젝트 루트의 .env 파일이 마이그레이션 및 추출 구성입니다. 소스 및 타겟 URL, OAuth, 원격 CDMS 연결, SaaS 및 IMS 인증 및 기타 스위치를 비롯한 CLI 파이프라인을 구동합니다.

.env 파일을 편집하고 적어도 다음 값을 올바르게 설정하십시오. 지원되는 변수의 전체 목록을 보려면 .example.env의 인라인 주석을 참조하십시오.

SOURCE_INSTANCE_URL=https://<source-host>
SOURCE_INSTANCE_GRAPHQL_URL=https://<source-host>/graphql
SOURCE_INSTANCE_REST_URL=https://<source-host>/rest
SOURCE_INSTANCE_CONSUMER_KEY=<consumer_key>
SOURCE_INSTANCE_CONSUMER_SECRET=<consumer_secret>
SOURCE_INSTANCE_ACCESS_TOKEN=<access_token>
SOURCE_INSTANCE_ACCESS_TOKEN_SECRET=<access_token_secret>

소스 OAuth 자격 증명 구성

이 네 가지 값은 마이그레이션 도구에서 소스 스토어 API로의 요청에 서명합니다. 다운로드하려면 원본 Admin을(를) 열고 시스템 > 확장 > 통합​(으)로 이동하세요. 통합을 만들거나 연 다음 값을 .env에 복사합니다.

SOURCE_INSTANCE_CONSUMER_KEY=<consumer_key>
SOURCE_INSTANCE_CONSUMER_SECRET=<consumer_secret>
SOURCE_INSTANCE_ACCESS_TOKEN=<access_token>
SOURCE_INSTANCE_ACCESS_TOKEN_SECRET=<access_token_secret>

Cloud CLI 토큰 설정

Commerce 관리 설정 정렬

마이그레이션 전에 소스와 타겟 간에 다음 설정이 일치하는지 확인하십시오.

대상 SaaS 및 IMS 자격 증명 구성

대상의 Adobe Commerce as a Cloud Service IMS 및 API 설정입니다. 사용자 환경에 대한 테넌트 ID, 조직 ID, IMS OAuth 서버 간 자격 증명 및 올바른 IMS 호스트가 필요합니다. 조직, 테넌트 및 프로필 액세스를 위해 Adobe 팀과 협력합니다. 중요한 값을 유추하거나 추정하지 마십시오.

IMS 자격 증명 생성

Adobe Developer Console을(를) 사용합니다. 프로젝트를 만들려면 Adobe 조직에 대한 Developer 또는 Admin 액세스 권한이 필요합니다. 기본 사용자 로그인으로 API를 추가할 수 없습니다.

IMS 토큰 끝점(ADOBE_IMS_URL)은 자격 증명의 환경과 일치해야 합니다.

ADOBE_IMS_META_SCOPES은(는) 해당 자격 증명에 프로비전된 범위와 일치해야 합니다. .example.env 파일에 쉼표로 구분된 전체 범위 문자열이 참조로 포함되어 있습니다. Adobe에서 지시한 경우에만 변경합니다.

Adobe I/O 자격 증명을 환경 파일에 매핑

Developer Console에서 OAuth 서버 간 값은 다음 JSON 구조에 해당하는 클라이언트 ID 및 클라이언트 암호로 표시됩니다.

{
  "client_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

.env에 매핑합니다(자리 표시자 예).

TARGET_ORG_ID=<org_id>@AdobeOrg
ADOBE_IMS_URL=https://ims-na1.adobelogin.com
ADOBE_IMS_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxx
ADOBE_IMS_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxx
ADOBE_IMS_META_SCOPES=AdobeID,openid,additional_info.projectedProductContext

SaaS API 호스트는 사전 프로덕션 및 프로덕션마다 다릅니다. TARGET_INSTANCE_REST_URL 및 TARGET_INSTANCE_GRAPHQL_URL은(는) 프로덕션 전 또는 프로덕션으로 마이그레이션과 동일한 Commerce API 환경을 사용해야 합니다. 한 계층을 다른 계층의 CDMS 또는 테넌트와 혼합하지 마십시오.

TARGET_TENANT_ID=<tenant_id>
TARGET_ORG_ID=<org_id>@AdobeOrg
ADOBE_IMS_URL=https://ims-na1.adobelogin.com
ADOBE_IMS_CLIENT_ID=<client_id>
ADOBE_IMS_CLIENT_SECRET=<client_secret>
ADOBE_IMS_META_SCOPES=AdobeID,openid,additional_info.projectedProductContext
TARGET_INSTANCE_REST_URL=https://na1-sandbox.api.commerce.adobe.com/{tenantId}
TARGET_INSTANCE_GRAPHQL_URL=https://na1-sandbox.api.commerce.adobe.com/{tenantId}/graphql

프로덕션 SaaS 호스트의 경우 TARGET_INSTANCE_* URL에서 na1-sandbox을(를) na1(으)로 바꾸십시오. 이전 표에 표시된 대로 해당 계층에 대해 일치하는 ADOBE_IMS_URL을(를) 사용합니다.

CDMS 엔드포인트 설정

마이그레이션 대상 환경과 일치하는 CDMS API 호스트에 마이그레이션 도구를 지정합니다. .env에서 CDMS_HOST(및 일반적으로 CDMS_PORT=443)을(를) 설정합니다. 운영 전 또는 운영 호스트 중 하나만 사용하고 둘 다 사용하지 마십시오.

실행과 일치하는 블록을 설정하거나 주석 처리를 제거합니다.

# Pre-production CDMS
CDMS_HOST=https://commerce-data-migration-service-preprod-external.adobe.io
CDMS_PORT=443

# Production CDMS (use for prod cutover only)
# CDMS_HOST=https://na1.api.commerce.adobe.com
# CDMS_PORT=443

스토어 코드 설정

STORE_CODE은(는) 원본 인스턴스 REST API 호출, 가상 테스트 고객 생성 및 데이터 정리를 위해 마이그레이션 도구에서 사용하는 저장소 보기 코드입니다. 또한 로드 단계 중에 x-store-code 헤더로 전송됩니다.

STORE_CODE의 기본값은 .example.env의 default입니다. 소스 인스턴스의 기본 스토어 보기 코드와 일치하는지 확인합니다. 확인하려면 원본 Admin에서 스토어 > 모든 스토어​(으)로 이동하여 사용해야 하는 스토어 보기에 대한 코드 열을 확인합니다. 표시된 코드가 default이(가) 아니면 .env에서 STORE_CODE을(를) 업데이트하여 일치시키십시오.

데이터베이스 연결 파일 구성

.my.cnf 파일은 마이그레이션 도구의 추출 측에 MySQL 연결 설정을 제공합니다. 프로젝트 루트의 .my.cnf에 .my.cnf.example을(를) 복사하여 만드십시오. 섹션 이름은 .env의 SOURCE_CONNECTION_NAME과(와) 일치해야 합니다.

온-프레미스 또는 자체 호스팅 소스의 경우:

[<connection-name>]
user=<db_user>
password='<db_password>'
host=<db_host>
port=3306
database=<db_name>

Adobe Commerce on Cloud 소스의 경우:

[<connection-name>]
id=<project_id>:<environment>

id= 필드는 원본이 PaaS이고 MAGENTO_CLOUD_CLI_TOKEN을(를) 사용하여 터널 설정을 트리거함을 도구에 알려줍니다. project_id 및 environment 값은 Cloud Console 또는 magento-cloud project:list 및 magento-cloud environment:list 명령을 통해 사용할 수 있습니다.

네트워크 및 인스턴스 준비

스토어 앞에 있는 HTTP 기본 인증은 API 및 도구 트래픽을 차단할 수 있습니다. 마이그레이션에 사용되는 소스 URL에 대해 비활성화되어 있거나 도구의 경로가 허용되어 REST 및 GraphQL 요청이 스토어에 도달할 수 있는지 확인하십시오.

추출 중 소스 데이터베이스 안정성 유지

이 툴은 소스 데이터베이스에서 데이터를 추출하지만 다른 프로세스는 이 데이터 소스에 쓰지 않아야 합니다. 동시 쓰기로 인해 스냅샷이 일치하지 않을 수 있습니다.

대상

마이그레이션 전에 대상 카탈로그를 지워야 하는 경우 중복 카탈로그 충돌과 대량 삭제 시간 초과를 방지하기 위해 Admin의 제품을 한 번에 200개씩 작은 배치로 삭제하십시오.

마이그레이션 구축 및 실행

쓰기 권한이 있는 추출된 프로젝트 디렉토리에서 작업합니다.

SSH를 통해 세션 유지

SSH를 통해 연결하는 경우, 삭제된 네트워크는 셸을 죽이고 긴 마이그레이션을 방해할 수 있습니다. GNU screen 명령은 서버에서 세션을 사용 가능하도록 유지합니다.

screen -S migration          # new session named "migration"
# run ./bin/console commands here; when you want to disconnect without stopping work:
# press Ctrl+A, release, then press d   # detach
screen -ls                   # list sessions
screen -x migration          # reattach to "migration"

서버에서 사용할 수 있는 경우 tmux을(를) 사용할 수도 있습니다.

도커 이미지 빌드

PHP, CLI 및 종속성을 포함하는 bin/console에서 사용하는 Docker 이미지를 빌드합니다. 첫 번째 실행 전에 또는 Dockerfile 또는 기본 이미지 변경 후에 이 작업을 실행합니다.

./bin/console build

지원 서비스 시작

로컬 테스트 데이터베이스와 같은 도구에 대한 Docker Compose 지원 서비스를 시작하고 .env에서 활성화된 경우 선택적 로컬 서비스를 시작합니다. 정확한 서비스는 구성에 따라 다릅니다. 빌드 성공 후 셸, 마이그레이션 또는 단계 명령 전에 이 작업을 실행합니다.

./bin/console start

CLI 컨테이너 초기화

CLI 컨테이너를 한 번 시작하면 진입점이 탑재된 프로젝트에 대해 필요한 경우 Composer 설치와 같은 설치를 완료할 수 있습니다. 새 환경에서 첫 번째 마이그레이션이 실행되기 전에 이 작업을 한 번 실행합니다.

./bin/console shell
exit

마이그레이션 실행

이 도구는 두 가지 마이그레이션 접근 방식을 지원합니다. 사용 사례에 맞는 항목을 선택합니다.

단일 단계 마이그레이션

소스 인스턴스에는 유지 관리 모드가 필요하지 않습니다. 단일 명령으로 전체 마이그레이션 파이프라인을 실행합니다.

./bin/console migration

이 명령은 모든 파이프라인 단계를 다음 순서로 끝에서 끝까지 자동으로 실행합니다.

유지 관리 창이 필요하지 않은 경우 이 옵션을 사용합니다. 이 창은 일반적으로 엔드 투 엔드 드라이 실행, 개발 또는 샌드박스 환경 또는 추출 중에 소스가 라이브로 유지될 수 있는 모든 마이그레이션에 사용됩니다.

유지 관리 모드를 사용한 다단계 마이그레이션

추출 중에 데이터 일관성을 유지하려면 소스 인스턴스에 유지 관리 모드가 필요합니다. 마이그레이션은 순서대로 실행해야 하는 개별 단계로 분할됩니다.

1단계 — 유지 관리 전(소스가 라이브)

소스 인스턴스가 라이브이고 트래픽을 수락하는 동안 실행됩니다. 소스에 대한 REST 및 GraphQL 액세스를 완전히 사용할 수 있어야 합니다. 이 단계가 완료되기 전에 유지 관리 모드를 활성화하지 마십시오.

서버 루트로 돌아가서 다음을 실행합니다.

./bin/console migration:before-maintenance

2단계 — 유지 관리 모드 사용(수동)

소스에서 유지 관리 모드를 활성화하고 예약된 작업, 서드파티 통합, 주문 처리 및 미디어 에셋 동기화를 포함하여 데이터베이스에 기록되거나 데이터베이스에 영향을 주는 모든 작업을 일시 중지합니다.

소스 Commerce 서버(설치 루트)에서 다음을 실행합니다.

bin/magento maintenance:enable

3단계 — 유지 관리 중(원본이 동결됨)

유지 관리 모드에서 소스 인스턴스로 를 실행합니다. 소스는 이 단계의 전체 기간 동안 고정된 상태를 유지해야 합니다. 단계 3​이(가) 성공적으로 완료될 때까지 유지 관리 모드를 비활성화하지 마십시오.

./bin/console migration:during-maintenance

4단계 — 유지 관리 모드 비활성화(수동, 조건부)

이 단계에서는 유지 관리 모드를 비활성화하여 소스 인스턴스에 대한 트래픽을 다시 활성화합니다. 정리 단계는 REST를 통해 소스와 통신하며 유지 관리 모드가 아직 활성 상태인 경우 HTTP 503과(와) 함께 실패하기 때문에 정리 단계를 실행하기 전에 필요합니다.

소스 Commerce 서버에서 다음을 실행합니다.

bin/magento maintenance:disable

5단계 — 정리(선택 사항, 원본은 라이브여야 함)

단계 1​에서 만든 가상 테스트 고객 및 주문을 REST를 통해 원본 인스턴스에서 제거합니다. 이 단계는 유지 관리 모드가 비활성화된 후에만 실행할 수 있습니다.

서버 루트로 돌아가서 다음을 실행합니다.

./bin/console migration:cleanup

마이그레이션 다시 시작 또는 다시 실행

마이그레이션 도구는 프로젝트 루트의 .migration_id 파일을 사용하여 진행 상황을 추적합니다. 이 파일은 새 마이그레이션이 시작될 때 자동으로 만들어지며 현재 마이그레이션 식별자를 기록합니다.

실패 후 다시 시작

마이그레이션 실행이 실패하거나 중단되는 경우 처음부터 다시 시작하지 않고 동일한 명령을 다시 실행하여 마지막으로 성공한 단계(추출, 로드 또는 확인)에서 다시 시작하십시오. 이미 완료된 단계는 자동으로 건너뜁니다.

새 마이그레이션 시작

이전 실행을 무시하고 완전히 새로운 마이그레이션을 시작하려면 다음 마이그레이션을 시작하기 전에 .migration_id 파일을 삭제하십시오.

rm .migration_id

.migration_id이(가) 있고 이전 마이그레이션이 이미 완료된 경우 도구에서 마이그레이션이 이미 완료되었다는 메시지를 인쇄하고 파일을 삭제하도록 권장합니다.

로그 검토 및 디버그

모든 마이그레이션 로그는 프로젝트 루트의 logs/ 디렉터리에 기록되며 타임스탬프가 지정된 하위 디렉터리로 구성됩니다.

logs/
  2026-03-23_14-30-00/     ← one directory per run
    index.log              ← main pipeline log (start here)
    ...