AEM 클라우드 마이그레이션 기술 사용 using-cloud-migration-skill
이 참조서에서는 지원되는 각 마이그레이션 패턴, BPA 검색 결과를 제공하는 방법 및 대규모 프로젝트에서 세션을 관리하는 방법을 다룹니다. 소개 및 설정 지침은 개요를 참조하십시오.
마이그레이션 Runbook 생성 migration-runbook
전체 프로젝트 평가의 경우 단일 패턴의 이름을 지정하는 대신 Runbook으로 시작합니다. 다음을 사용하여 에이전트에 메시지 표시:
Review my code for AEMaaCS migration
스킬은 코드를 변경하지 않고 프로젝트 루트에 읽기 전용migration-runbook.md을(를) 생성합니다. Runbook은 마이그레이션 기술에서 처리할 수 있는 every 패턴을 포함하며, 각 패턴에 대해 다음을 기록합니다.
- 사용된 감지 전략(BPA/CAM 결과, 분석기 또는 휴리스틱 콘텐츠 스캔)
- 영향을 받는 파일 및 패턴당 검색 횟수
- 해당 패턴의 마이그레이션 세션을 시작하는 복사-붙여넣기 프롬프트
Runbook은 Markdown과 함께 결과 캐시도 기록하므로, 이후 패턴 세션은 이미 검색된 결과를 재사용합니다. 에이전트는 다시 검사하지 않습니다. Runbook을 사용하여 먼저 처리할 패턴의 우선 순위를 지정한 다음 아래에 설명된 대로 패턴 세션을 시작합니다.
세션 작동 방식 workflow-overview
모든 마이그레이션 세션은 다음 시퀀스를 따릅니다.
- 패턴 이름 지정: 패턴 하나를 지정하십시오(예:
scheduler). - 검색 결과 제공: BPA CSV 파일, MCP를 통한 CAM 또는 특정 파일 경로에서
- 에이전트가 변환 규칙을 읽습니다: 스킬이 코드를 변경하기 전에
code-assessment스킬에서 관련 변환 규칙을 읽습니다. - 5개의 첫 번째 일괄 처리: 에이전트는 최대 5개의 검색 결과를 변환하고 변경 내용을 보고합니다
- 검토 후 계속 진행: 각 일괄 처리를 검토한 후
continue에 회신하여 다음 단계로 진행합니다.
에이전트는 한 번에 하나의 패턴과 하나의 배치를 처리합니다. 자동으로 진행되지 않습니다. 각 배치에 확인이 필요합니다.
마이그레이션 패턴 patterns
스케줄러 scheduler
AEMaaCS의 상태 비저장 컨테이너화된 런타임과 호환되지 않는 sling.commons.scheduler 또는 Scheduler 삽입을 사용하는 Java 클래스를 타깃팅합니다.
BPA 패턴 ID: scheduler
에이전트는 @Designate을(를) 사용하여 Scheduler개의 주입 작업을 Runnable의 @Component 구현으로 전환하고 생성자 기반 스케줄러 등록을 @Activate/@Deactivate 라이프사이클 메서드로 바꿉니다.
ResourceChangeListen resource-change-listener
AEMaaCS에 대한 업데이트가 필요한 ResourceChangeListener 또는 ResourceChange 수신기 구현을 대상으로 합니다.
BPA 패턴 ID: resourceChangeListener
복제 replication
com.day.cq.replication.Replicator 또는 관련 복제 API를 가져오는 대상 클래스이며, AEMaaCS에서 지원되지 않습니다. 에이전트는 이 항목을 ContentDistribution 기반 항목으로 바꾸고 해당 OSGi 서비스 참조를 업데이트합니다.
BPA 패턴 ID: replication
이벤트 리스너 event-listener
AEMaaCS 이벤트 처리 의미 체계에 대해 업데이트해야 하는 OSGi EventListener 또는 EventHandler 구현을 대상으로 합니다.
BPA 패턴 ID: eventListener
이벤트 핸들러 event-handler
AEMaaCS에 맞게 조정해야 하는 동기 OSGi EventHandler 서비스를 대상으로 합니다.
BPA 패턴 ID: eventHandler
자산 API asset-api
더 이상 사용되지 않는 AssetManager, DAMEvent 또는 지원되지 않는 DAM API를 사용하는 타겟 클래스입니다. 에이전트는 이를 지원되는 AEM Assets API 동등한 기능으로 대체합니다.
BPA 패턴 ID: assetApi
구아바 캐시 투 카페인 guava-cache
Guava의 캐시를 사용하는 대상 번들(Cache, CacheBuilder 및 LoadingCache 등 com.google.common.cache.*). AEM as a Cloud Service에서 지원되는 처리 중 캐시 라이브러리는 카페인이므로 에이전트는 Maven 종속성을 교체하고 가져오기를 업데이트하며 영향을 받는 호출 사이트를 조정합니다. 카페인은 같은 작성자에 의해 작성되었고 그것의 API는 의도적으로 거의 동일하기 때문에, 변화는 대부분 기계적인 것이다.
BPA 패턴 ID: guavaCache
BPA는 번들 세부 기간(하위 유형 custom.guava.cache)에서 이 패턴을 보고하므로 에이전트는 실제로 Guava 캐시를 가져오고 편집하는 Java 파일로 번들을 확인합니다. Guava 캐시 사용은 네이티브 Cloud Service 코드가 아니라 레거시 AEM에서 이월된 코드에서만 발생하므로 이 패턴은 code-assessment이(가) 아닌 마이그레이션 스킬에서만 제공됩니다.
guavaCache은(는) BPA를 신뢰할 수 있는 소스로 사용합니다. BPA 또는 CAM 소스를 사용할 수 없는 경우 에이전트는 확인되지 않은 후보로 가져온 import com.google.common.cache개에 대한 Java 파일을 스캔하는 것으로 돌아갑니다.HTL Lint(data-sly-test) htl-lint
data-sly-test: redundant constant value comparison개의 lint 경고를 생성하는 ui.apps 아래의 HTL 템플릿을 대상으로 합니다. 에이전트는 콘텐츠 패키지를 직접 스캔하여 영향을 받는 템플릿을 검색합니다. 이 패턴은 BPA CSV 또는 CAM 연결이 필요하지 않습니다.
BPA 패턴 ID: htlLint
htlLint 결과가 BPA CSV 내보내기에 표시되지 않습니다. 에이전트는 이 패턴에 대한 세션을 시작할 때 직접 파일 검색을 통해 이를 검색합니다.Cloud Manager에 OSGi 구성 osgi-cloud-manager
ui.config의 OSGi 구성을 전체 환경별 처리를 통해 Cloud Manager 호환 .cfg.json 형식으로 변환합니다. 여기에는 다음과 같은 몇 가지 관련 작업이 포함됩니다.
구성 형식 변환
AEMaaCS에서는 실행 모드 범위 폴더(config.author/, config.publish/, config.dev/ 등)에 환경별 구성을 사용하여 OSGi 구성을 .cfg.json 파일로 저장해야 합니다. 에이전트:
- 기존
.config,.cfg및 XML 형식 OSGi 구성을.cfg.json(으)로 전환합니다. - 작성자 및 게시자 관련 값이 모두 포함된 구성을 별도의 실행 모드 범위 파일로 분할합니다.
- OSGi 메타타입 사양(문자열, 정수, 부울, 배열)에 대해 속성 형식을 확인합니다.
- Adobe 소유 PID를 자동 변환하지 않고 수동으로 검토하도록 플래그 지정
암호 및 환경 변수
커밋된 구성 파일에서 일반 텍스트 암호 및 환경별 값을 이동하고 Cloud Manager 자리 표시자로 대체합니다.
$[secret:NAME]: 암호, 토큰 및 기타 중요한 값의 경우$[env:NAME]: 환경별로 다른 민감하지 않은 값(예: 서비스 URL)의 경우
해당 변수와 비밀은 Cloud Manager에 적용되고 런타임에 삽입되며 값은 소스 제어에 저장되지 않습니다.
지원되지 않는 실행 모드(URC)
AEM as a Cloud Service은 고정된 실행 모드 식별자 집합을 지원합니다. 지원되지 않는 실행 모드를 사용하는 구성 폴더는 배포되면 영향을 주지 않습니다. 에이전트는 다음을 포함하여 이러한 지원되지 않는 URC(실행 모드 구성)에 플래그를 지정합니다.
- 알 수 없는 실행 모드 토큰(예:
config.qa또는install.local) - 대신 뒤에 오는 계층 토큰이 올바른
config.author.dev대신 환경 토큰—config.dev.author보다 우선합니다. config.Author.dev과(와) 같이 소문자가 아닌 토큰 및 예약된config.preview(미리 보기는 게시에서 상속)
URC 결과는 먼저 모범 사례 분석기에서 가져왔습니다(하위 유형 unsupported.runmode, 심각도 CRITICAL). BPA 원본에서 이를 보고하지 않으면 에이전트는 config.* 및 install.* 폴더를 안전망으로 로컬로 검사합니다. 각 검색 결과에 대해 폴더 경로, 문제가 되는 실행 모드 및 수정 사항을 보고합니다. 구성이 계속 필요한지 여부를 평가하거나 지원되는 실행 모드로 이름을 바꾸거나 더 이상 사용하지 않을 경우 제거합니다. 모든 토큰이 유효하지만 순서가 잘못된 순서 지정 전용 위반의 경우 에이전트가 안전한 순서 지정을 자동으로 적용할 수 있습니다(예: config.dev.author의 이름을 config.author.dev(으)로 변경). 알 수 없는 토큰 및 기타 모호한 사례는 사용자가 해결할 수 있도록 플래그가 지정됩니다.
구성 형식 변환 및 비밀 외부화는 BPA CSV 또는 CAM이 필요하지 않으며, URC 검색은 사용 가능한 경우 BPA 검색 결과를 사용합니다. 다음으로 세션 시작:
Scan my config files and create Cloud Manager environment secrets or variables.
대화 상자 마이그레이션(기존 UI) dialog-migration
클래식 UI 대화 상자를 Touch UI로 변환합니다. 에이전트는 두 개의 대화 상자 하위 유형을 처리합니다. ExtJS / 클래식 UI cq:Dialog 정의는 Coral 3 _cq_dialog 구조로 다시 작성되고, 기존 Coral 2 대화 상자가 Coral 3으로 업그레이드됩니다. 또한 수신기, optionsProvider, namePrefix 및 업데이트 filter.xml도 전달됩니다.
BPA 패턴 ID: lui(대화 상자 하위 유형만)
동일한 구성 요소에 대해 대화 상자 및 사용자 지정 위젯 결과가 모두 있는 경우 대화 상자를 변환하기 전에 모든 xtype 참조가 확인되도록 사용자 지정 위젯 마이그레이션을 먼저 실행하십시오.
Convert my Classic UI dialogs to Touch UI Coral 3.
사용자 정의 디자인 위젯(레거시 UI) custom-design-widgets
사용자 지정 ExtJS 위젯(cq:Widget 정의를 사용자 지정 xtype 값으로 마이그레이션함)을 마이그레이션합니다. 에이전트는 위젯의 인벤토리를 작성한 다음 각 xtype을(를) 알려진 Coral 3에 대응하거나 직접 매핑이 존재하지 않을 때 Granite UI 양식 구성 요소를 스캐폴딩합니다.
BPA 패턴 ID: cdw
Migrate my custom ExtJS widgets (CDW findings) from CAM.
템플릿 현대화 template-modernization
정적 템플릿을 편집 가능한 템플릿으로 변환하고 해당 AEM 현대화 도구 다시 작성 규칙(구조, 구성 요소 및 정책 규칙)을 생성합니다. 에이전트는 세 단계로 실행됩니다. 템플릿을 검색하고 템플릿별 계획을 생성하고, 템플릿별로 계획 템플릿을 실행하고, 생성된 /conf 구조의 유효성을 검사합니다.
검색하는 동안 에이전트는 중첩된 템플릿 폴더나 그룹화된 템플릿 폴더를 포함하여 apps/<appId>/templates/ 아래의 템플릿을 모든 깊이에서 이동하고 페이지 구성 요소의 리소스 유형에 따라 각 정적 템플릿을 레거시 또는 사용자 지정으로 분류합니다. 이 분류는 BPA 보고서 없이도 유지되므로 사용자 지정 템플릿은 기존 템플릿과 명확히 처리됩니다.
이 패턴은 BPA 패턴 ID를 사용하지 않습니다. 다음으로 세션 시작:
Migrate my static templates to editable templates and generate the Modernize Tools rewrite rules.
Dispatcher 전환 dispatcher-conversion
AMS 또는 온프레미스 Apache HTTPD 및 Dispatcher 구성을 AEM as a Cloud Service 구조로 변환합니다. 이 기능은 Adobe의 유지 관리되는 Dispatcher 변환기 도구를 래핑하여 감지, 구성 생성, 출력 확인 및 유효성 검사를 추가합니다.
에이전트는 단계별 흐름을 통해 작동합니다.
- 검색 및 인벤토리 - 구성 모드을(를) 결정하고 필터, 다시 작성 및 캐시 규칙의 기본 개수를 기록합니다. 인식된 모드는
standard(AMS),flexible(모노리식 온-프레미스),v1(이전 레이아웃),already-cloud,not-dispatcher및unknown입니다.already-cloud,not-dispatcher또는unknown에 대해 에이전트가 중지되고 계속하기 전에 확인을 요청합니다. - 구성 계획 및 생성 - 변환기 구성을 빌드하고 계획을 확인합니다.
- 변환 - Adobe의 Dispatcher 변환기(처음 사용할 때 자동으로 설치됨)를 실행합니다.
- 확인 - 기준선에 대해 출력을 확인합니다. 빈 필터 집합(
filter-acl-loss)은 계속하기 전에 해결해야 하는 하드 스톱입니다. - 교차 경계 전달 - Cloud Manager 환경 변수를 OSGi 구성 흐름으로 라우팅하고 CDN 또는 보안 헤더 후보에 플래그를 지정합니다.
- 유효성 검사 - Cloud Service Dispatcher 유효성 검사기를 실행하고 통합 전환 보고서를 생성합니다.
Runbook 패턴 id: dispatcherConversion(구성 레이아웃에서 발견됨). 이 패턴은 BPA 또는 CAM을 사용하지 않습니다. 다음으로 세션 시작:
Convert my AMS / on-prem Dispatcher config to AEM as a Cloud Service.
standard(AMS) 구성은 거의 자동화되었지만 flexible 및 v1 레이아웃은 더 자세히 검토해야 합니다.BPA Source 옵션 bpa-source
MCP 오류 처리 mcp-errors
MCP 연결이 오류(프로젝트를 찾을 수 없음 또는 인증 실패 포함)를 반환하는 경우 에이전트가 중지되고 오류를 표시합니다. 자동으로 다른 소스로 전환되지 않습니다. 정지됨 상태에서 다음을 수행할 수 있습니다.
- 표시된 에이전트 목록에서 올바른 프로젝트를 확인합니다
- 대안으로 BPA CSV 경로 제공
- 수동 마이그레이션을 위한 특정 Java 파일 경로 제공
대형 보고서에서 세션 관리 large-reports
많은 검색 결과가 있는 BPA 보고서의 경우, 일괄 처리 접근 방식을 사용하여 점진적으로 확인할 수 있습니다.
- 각 배치에 대한 차이 검토
- 패턴 범위 커밋 메시지로 배치 커밋
- 다음 일괄 처리를 시작하려면
continue에 회신 - 에이전트가 패턴에 대한 모든 검색 결과가 완료되었다고 보고할 때까지 반복합니다
커밋당 하나의 패턴을 사용하면 git 기록을 읽을 수 있으며 필요한 경우 개별 패턴 변환을 쉽게 되돌릴 수 있습니다.
Workspace 범위 workspace-scope
에이전트는 열려 있는 IDE 작업 영역 폴더 내에서만 파일을 검색하고 편집합니다. 디스크의 상위 디렉터리, 동일 수준의 폴더 또는 다른 위치를 검사하지 않습니다.
BPA 검색 결과가 작업 공간에 없는 파일 경로를 참조하는 경우 에이전트는 중지하고 누락된 경로를 알려줍니다. 올바른 프로젝트 폴더를 열거나 계속하려면 명시적으로 경로를 제공하십시오.