ethanplusai/astro-conversion-kit

capture-site

라이브 사이트가 제공하는 모든 것을 한 번에 저장하여, 이후의 모든 단계가 캡처를 기반으로 작업할 수 있게 합니다.

황금률

라이브 사이트는 읽기 전용이며, 캡처도 이후 읽기 전용입니다. 스크립트는 속도가 제어된 GET 및 HEAD 요청만 수행합니다. 양식을 제출하거나, 로그인하거나, 수동으로 가져와서 빈 곳을 채우지 마십시오. 노트가 작성된 후에는 capture/ 아래의 어떤 것도 편집되지 않습니다. 모든 게이트가 읽는 증거입니다.

사용 시기

변환의 2단계(convert-site가 실행), 또는 라이브 사이트를 인벤토리로 작성해야 할 때(스테이징 또는 새 사이트는 launch-audit의 작업입니다). 종료 코드 3으로 종료된 캡처는 아래와 같이 재개됩니다.

속도 제어

모든 스크립트는 데스크톱 Chrome 사용자 에이전트를 전송합니다. 캡처 스크립트(capture, media, assets, fingerprint)는 호스트별 제한기를 공유합니다. 기본적으로 요청 시작은 400ms 간격으로 최대 4개 동시 실행(media: 6개)되므로, 빠르게 응답하는 호스트는 몇 분 안에 읽힙니다. Chromium 단계(shoot, css-coverage, styles)는 한 번에 한 페이지씩 500ms 간격으로 로드하며, launch-audit과 pre-launch는 자체 속도 제어를 유지합니다. 제한기는 자체적으로 적응합니다.

• 429 또는 503은 해당 호스트의 지연 시간을 두 배(최대 32배)로 늘리고 한 번에 하나의 요청으로 떨어뜨립니다. 30초 동안 깨끗한 응답이 있으면 한 단계씩 회복(지연 시간 절반, 동시 실행 하나 더 추가)하여 기본값으로 돌아갑니다.
• 응답 시간이 5초를 초과하면 해당 호스트의 동시 실행 요청 수를 절반으로 줄이고(절반으로 줄이는 동안에는 다시 수행하지 않음), 30초 동안 깨끗한 응답마다 동시 실행 하나씩 동일한 방식으로 회복합니다.
• 403 또는 네트워크 오류는 아래의 연속 3회 중단 기준에 포함됩니다.

--polite는 이전 속도입니다. 한 번에 하나의 요청, 2500ms 간격(capture, media, assets). 봇 차단 벽(예: SiteGround의 /.well-known/sgcaptcha/ 또는 몇 번의 빠른 요청에 429/503을 응답하는 호스트)이 있는 공유 호스팅에서 처음부터 사용하거나, 차단으로 인해 실행이 중단된 경우 --polite로 재개하십시오. --delay <ms> 및 --concurrency <n>은 기본값 또는 --polite를 재정의합니다. 라이브 사이트에 대해서는 기본값 또는 --polite를 유지하고(--delay 0은 로컬 픽스처 전용), 차단을 우회하기 위해 --ua를 변경하지 마십시오.

• capture는 최대 --concurrency개의 대기 중인 URL을 미리 가져와 큐 순서로 기록하므로, 캡처는 한 번에 하나씩 크롤링하는 것과 동일합니다. 각 URL을 3번 시도합니다. 그 후에도 차단된 URL(403, 429, 503 또는 네트워크 오류)은 해당 상태 및 attempts와 함께 inventory.json에 기록되고(사이트맵 또는 REST 목록은 meta.json discoveryErrors에 기록), 크롤링은 계속 진행됩니다. 연속으로 3개의 다른 URL이 성공 없이 시도 횟수를 모두 소진한 경우에만 중단되며, 상태가 저장되고 해당 3개는 새로운 시도 횟수로 다시 큐에 추가됩니다. wp-admin, wp-login, xmlrpc.php 또는 ?s= 검색은 요청하지 않습니다.
• media는 각 파일을 3번 시도합니다. 지속적인 429 또는 503은 즉시 중단됩니다. 403 또는 네트워크 오류는 해당 파일의 상태로 기록되며, 이러한 파일이 3개 연속으로(응답이 도착하는 순서대로) 발생하면 중단됩니다. 중단 시 이미 다운로드 중인 파일은 완료될 때까지 놔둡니다. 100개 파일마다 media.json을 저장하므로, 종료된 실행은 중단된 지점 근처에서 재개됩니다.
• fingerprint는 재시도하지 않습니다. 차단된 홈 페이지 또는 봇 챌린지가 있는 페이지는 종료 코드 3입니다. assets 및 shoot는 물러나서 연속으로 3개의 차단된 응답 후 중단됩니다.

명령어 시퀀스

capture/를 보유할 폴더(사이트 저장소의 루트)에서 실행합니다. <skill-dir>는 npm install이 실행된 키트 사본에 있는 이 스킬 폴더의 절대 경로입니다(스크립트가 패키지를 가져옴). 모든 스크립트는 --help를 출력합니다. 소스를 읽기보다는 실행하십시오. 각 단계를 자체 명령어로 다음 순서대로 실행하십시오.

1. 핑거프린트를 실행한 다음, 플랫폼 참조에서 이름을 읽습니다(아래 표 참조).

   node <skill-dir>/scripts/fingerprint.mjs https://www.example.com
   

2. 캡처. 발견은 사이트맵(robots.txt의 모든 Sitemap: 줄, 플랫폼의 기본 인덱스), REST 목록(핑거프린트가 REST를 찾은 경우 WordPress, --no-rest는 건너뜀), 링크 크롤링, 그리고 크롤링이 도달할 수 없는 경로(이전 URL, 이전 .htaccess)에 대한 --seed <path> 또는 --seed-file <file>(줄당 하나의 경로 또는 URL, # 주석)입니다. 크롤링 후, 찾지 못한 Wayback 경로는 wayback-unverified.txt로 이동합니다(--no-wayback은 건너뜀, 실패한 목록은 meta.json wayback이 failed를 기록하기 전에 10초 후에 한 번 더 요청됨). ?p= 단축 링크는 확인되지 않은 상태로 기록되며 --verify-shortlinks를 전달하지 않으면 가져오지 않습니다. 크롤링 후 존재할 수 없는 경로(/<32 hex>/)를 한 번 요청하여 사이트 자체의 404 페이지가 pages/404.html로 저장되도록 합니다(meta.json notFound, 200으로 응답하거나 리디렉션하는 사이트는 페이지 없이 기록됨). 또한 /favicon.ico 및 /apple-touch-icon.png를 각각 한 번씩 요청하고 리디렉션을 따릅니다(meta.json icons: { status, file, contentType, bytes } 경로). 200으로 응답하는 것은 assets/root-favicon.ico 또는 assets/root-apple-touch-icon.png로 바이트 단위로 저장됩니다(HTML 응답은 저장되지 않으며 note가 있음, 5MB 초과는 상태 "too-large"). assets.mjs는 이를 assets/index.json에 kind "root-icon"과 path로 나열하므로, 빌드가 해당 위치로 전송합니다. URL은 대문자 퍼센트 이스케이프(%c3%a9 및 %C3%A9는 하나의 URL)로 키가 지정되므로, 두 철자로 연결된 페이지는 한 번만 캡처됩니다. robots.txt가 명명하고 404(또는 200이 아닌 모든 응답)로 응답하는 사이트맵은 해당 상태와 함께 sitemaps/index.json에, meta.json discoveryErrors에 나열됩니다. 다른 호스트에 있는 사이트맵(robots.txt가 자매 사이트 또는 인덱스가 하나를 나열하는 경우, www와 apex는 하나의 호스트로 간주)은 { url, host, skipped: "other host" }로 나열되며 가져오지 않으므로 해당 URL 중 어느 것도 크롤링에 들어가지 않습니다. 동일한 파일 이름을 가진 두 개의 사이트맵 URL은 서로 덮어쓰지 않습니다. 두 번째는 디렉토리 경로(예: page-sitemap-es.xml)의 접미사로 저장됩니다. --exclude <prefix>[,<prefix>...]는 호스트의 일부를 제외합니다(WordPress 멀티사이트의 하위 사이트(예: /president/) 또는 소유자가 유지하는 섹션). 경로가 이 중 하나로 시작하는 URL은 사이트맵, REST 목록, 링크 또는 리디렉션이 이끌든 요청되지 않습니다. 제외된 경로 아래의 사이트맵은 sitemaps/index.json에 { url, skipped: "excluded" }로 나열됩니다. 제외된 경로로의 리디렉션은 요청되지 않은 해당 대상과 함께 기록됩니다. 제외된 경로로의 링크는 저장된 HTML에 남아 있으며 links.json excluded( internal이 아님)에 나열됩니다. meta.json excluded는 접두사와 기준을 명명합니다. 접두사와 경로는 한 가지 형태로 비교되므로, /présidence/, /pr%c3%a9sidence/ 및 /pr%C3%A9sidence/는 동일한 접두사입니다. 제외된 경로 아래로 리디렉션되는 스타일시트 또는 루트 아이콘은 그곳으로 이동하지 않습니다(시트는 상태 "excluded"로 나열됨). --resume은 이를 유지합니다. --resume에 추가된 접두사는 그 아래에 이미 캡처된 내용(해당 pages/ 및 text/ 파일이 있는 페이지, 해당 리디렉션, 해당 피드 및 사이트맵, 해당 페이지에서만 사용된 스타일시트 및 스크립트)을 제거하고 제거된 항목을 출력합니다. media.mjs 및 assets.mjs도 그 아래의 파일을 건너뜁니다.

   node <skill-dir>/scripts/capture.mjs https://www.example.com --out capture
   

   그런 다음 wayback-unverified.txt가 비어 있지 않은 경우 Wayback 2차 패스: 각 보관된 경로를 한 번씩 요청하여, 여전히 리디렉션되는 것은 source seed로 capture/redirects.json에 저장되고(기준의 리디렉션이 이를 선택함), 나머지는 해당 상태와 함께 inventory.json에 기록됩니다. --seed, --seed-file 및 --include-query는 모두 --resume에 적용되며, Wayback Machine은 다시 요청되지 않습니다.

   node <skill-dir>/scripts/capture.mjs https://www.example.com --out capture --resume --seed-file capture/wayback-unverified.txt
   

3. 미디어. capture/media.json의 모든 미디어 파일을 나열하고 변환의 작업 디렉토리인 .conversion/media-cache/ 아래에 저장합니다. 이 디렉토리는 git에서 제외됩니다.

   node <skill-dir>/scripts/media.mjs --capture capture --download .conversion/media-cache
   

   한 번에 6개의 파일을 다운로드합니다. 기본적으로(--sizes referenced) 사이트에서 사용하는 모든 크기와 원본을 가져옵니다. 페이지, 스타일시트, srcset, og 태그 또는 사이트맵이 가리키는 것, 또는 캡처된 페이지, 스타일시트 또는 스크립트(데이터 썸네일, 데이터 배경, JSON 설정, 슬라이더 스크립트)의 어느 곳에나 파일 이름이 나타나는 것입니다. REST 미디어 목록만 명명하는 WordPress 크기는 downloaded: false, reason: "unreferenced size"로 나열되며 요청되지 않습니다. 분할을 출력합니다(예: 920 originals + referenced sizes (downloaded), 4,520 unreferenced sizes (listed only)). 해당 줄을 사람에게 반복하십시오. 소유자가 오래된 이메일이나 다른 사이트가 해당 크기에 링크할 수 있다고 말하는 경우 --sizes all을 사용하십시오.

   쿼리 문자열로 크기를 조정하는 호스트(WordPress VIP, Jetpack Photon: photo.jpg?w=1024, ?resize=300,200)는 동일한 경로에서 모든 크기를 제공합니다. 원본은 베어 경로이므로 요청 및 저장되는 것입니다. 각 본 쿼리 문자열은 variants 아래에 나열됩니다(요청되지 않음, --sizes all은 이를 형제 폴더 .conversion/media-cache-variants/ 아래에 <path>%3F<query>로 저장하므로 업로드되거나 저장소에 복사되는 미디어 캐시는 베어 경로만 보유함). 베어 경로가 오류(4xx 또는 5xx, 리디렉션은 해당 위치와 함께 기록됨, 너무 큰 파일은 용량 제한이 올라가면 한 번 더 요청됨)로 응답하는 경우, 변형이 그 자리에 저장되고 항목의 downloadedFrom은 해당 URL이 됩니다. 캐시 버스팅 쿼리(w, h, resize, crop, fit, quality, format 또는 s 매개변수가 없는 경우, 예: ?ver=3)는 동일한 파일이므로 선호되며 다른 것은 표시되지 않습니다. 그렇지 않으면 가장 넓은 변형이 저장되고 항목은 resized: true도 말합니다. 실행은 파일당 한 줄과 개수(2 originals unavailable (resized: true) ...)를 출력하고, baseline/media.json은 두 필드를 모두 유지하며, 미디어 게이트는 실패하지 않고 개수를 N resized (original unavailable on live)로 반복합니다. 실제 저장된 바이트와 비교하기 때문입니다. 해당 개수를 사람에게 반복하고 계획 및 런북에 라이브 사이트에서 더 이상 제공하지 않는 원본으로 해당 파일을 나열하십시오.

4. 템플릿. 200으로 응답한 페이지를 capture/templates.json으로 클러스터링합니다. WordPress에서 페이지는 먼저 템플릿 본문 클래스(home, page, single-post, archive, 템플릿 클래스)별로 그룹화되고, 마크업이 명확하게 다른 페이지(Jaccard 0.5 미만)는 page-2로 분할됩니다. 다른 플랫폼은 Jaccard 0.6에서 마크업별로 병합되어 template-<n>이 됩니다.

   node <skill-dir>/scripts/templates.mjs --capture capture
   

5. 에셋. 로고, 파비콘, apple-touch-icon, <link rel=manifest> 웹 매니페스트 및 모든 @font-face 글꼴을 capture/assets/에 저장합니다. 또한 루트 /favicon.ico 및 /apple-touch-icon.png(root-favicon.*, root-apple-touch-icon.*)를 meta.json icons가 200으로 기록한 경우 저장합니다.

   node <skill-dir>/scripts/assets.mjs --capture capture
   

   로고는 홈 페이지의 <header> 내부에서 먼저 찾은 다음, 로고 이름을 클래스나 id로 지정하는 다른 요소(예: .logo, .site-logo, #logo-wrap) 내부에서 찾습니다. 각각에서 src, alt, class 또는 id에 "logo"( "logout"은 아님)라는 단어가 있는 <img>, 그 다음 class, id, aria-label 또는 <title>에 "logo"가 있는 인라인 <svg>( logo.svg로 저장, assets/index.json에서 url: null, 해당 참고는 페이지의 다른 곳에 정의된 기호를 <use>만 하는 경우(자체적으로 렌더링됨)라고 명시함), 그 다음 홈 페이지에 대한 링크의 첫 번째 <img>, 그 다음 첫 번째 <img>입니다. assets/logo.*를 육안으로 확인하십시오. 계정 아바타 또는 스폰서 마크가 특이한 헤더에서 여전히 승리할 수 있습니다. 파비콘 및 apple-touch-icon은 해당 <link> href에서 제공된 대로 저장되며 쿼리 문자열이 포함되므로, 업로드 파일의 크기 조정(?w=32, ?w=180)을 가리키는 것은 media.json의 해당 파일 항목과 바이트가 다릅니다. 저장된 아이콘을 유지하고 원본은 유지하지 마십시오.

6. 라이브 스크린샷, 템플릿당 390, 768 및 1440에서 시각 검토 슈터 사용:

   node <skill-dir>/../visual-review/scripts/shoot.mjs --base https://www.example.com --routes capture/templates.json --widths 390,768,1440 --out capture/screens/live
   

7. 라이트하우스(선택 사항). npx --no-install lighthouse --version이 응답하는 경우에만, 요청하지 않고 설치하지 마십시오. 누락된 경우 노트에 그렇게 명시하십시오(건너뛰기, 통과 아님). mkdir -p capture/lighthouse-live를 실행한 다음, templates.json의 representative당 한 번씩 차례로 실행합니다.

   npx --no-install lighthouse https://www.example.com/ --quiet --chrome-flags="--headless=new" --output json --output html --output-path capture/lighthouse-live/home
   

8. README. capture/README.md에 캡처를 요약합니다. ## Notes는 생성된 줄로 시작하며, 매 실행마다 다시 작성됩니다(2차 패스가 확인한 Wayback 경로 수 및 각각이 응답한 내용: 상태, 리디렉션 대상; 실패했거나 크기로 거부된 Wayback 목록; 재시도 후에도 여전히 실패하는 모든 URL). 마지막으로 실행하고, 재실행 후에도 실행합니다.

   node <skill-dir>/scripts/readme.mjs --capture capture
   

스크립트	종료 코드
fingerprint	0 완료, 2 사용법 오류 또는 연결 불가, 3 차단 또는 봇 챌린지
capture	0 완료, 2 사용법 오류, 3 차단으로 중단, 연결 불가, 봇 챌린지(모두 재개 가능), 또는 200으로 응답한 페이지 없음
media	0 완료(누락 파일 포함), 2 사용법 오류, 캡처 없음 또는 200으로 응답한 페이지 없음, 3 차단으로 중단
assets	0 완료(누락 파일 포함), 2 사용법 오류 또는 캡처 없음, 3 차단으로 중단
templates	0 완료, 2 사용법 오류, inventory.json 없음, 또는 "캡처된 페이지 없음"(200으로 응답한 항목 없음)
readme	0 완료, 2 사용법 오류 또는 inventory.json 없음
shoot	0 모두 촬영, 1 경로 실패, 2 사용법 오류, 3 차단으로 중단

종료 코드 3인 경우

사이트가 요청을 차단 중이거나 연결할 수 없습니다. (초가 아닌) 분 단위로 기다린 후 다음을 수행하십시오.

• fingerprint: 다시 실행합니다.
• capture: --resume을 사용하여 동일한 명령어를 실행합니다. 아직 대기 중인 URL이 재시도됩니다.

...