diff --git a/AIRGAP_DEPLOY.md b/AIRGAP_DEPLOY.md index 04660b9..5b64aa0 100644 --- a/AIRGAP_DEPLOY.md +++ b/AIRGAP_DEPLOY.md @@ -29,20 +29,52 @@ git archive --format=tar.gz -o pulp-console-src.tgz HEAD ``` **(b) wheelhouse** — 타깃 Python/플랫폼에 맞춰 다운로드 -```bash -# 타깃과 동일 환경(권장): -pip download -r requirements.txt -d vendor/ -# 빌드 머신과 타깃이 다르면 플랫폼/버전 명시: -pip download -r requirements.txt -d vendor/ \ - --only-binary=:all: --implementation cp \ - --platform manylinux2014_x86_64 --python-version 312 +가장 안전한 방법은 **타깃과 동일한 OS/파이썬**(예: RHEL9 + python3.9)에서 받는 것: +```bash +pip download -r requirements.txt -d vendor/ ``` -`vendor/`에 모든 의존성 .whl이 모인다. (개수 확인: `ls vendor | wc -l`) +이 경우 환경마커가 타깃 기준으로 평가돼 의존성이 정확히 맞는다. + +> ⚠️ **빌드 머신이 타깃과 다르면(특히 Windows→Linux) 주의.** +> `pip download`의 `--platform`/`--python-version`은 **wheel 태그 선택에만** 쓰이고, +> 환경마커(`sys_platform`, `python_version`)는 **빌드 머신 기준**으로 평가된다. +> 그 결과 Windows에서 받으면 **리눅스/특정파이썬 전용 의존성이 누락**되고 +> (`uvloop` = 리눅스 전용, `sniffio`/`exceptiongroup` = anyio·Py<3.11 의존), +> **win32 전용 잉여 wheel**(`colorama`, `tzdata`)이 딸려 온다. +> → 이대로 타깃에서 `pip install`하면 `No matching distribution for uvloop` 등으로 실패한다. + +Windows 등 이종 빌드 머신에서 **RHEL9 / Python 3.9** 용으로 받을 때(검증된 절차): +```bash +# 1) 본체 (플랫폼/버전/ABI 명시 — manylinux 범위를 넓게 잡아 2_28 전용 wheel도 잡는다) +pip download -r requirements.txt -d vendor/ \ + --only-binary=:all: --implementation cp --abi cp39 --python-version 39 \ + --platform manylinux_2_28_x86_64 --platform manylinux_2_17_x86_64 \ + --platform manylinux2014_x86_64 --platform manylinux1_x86_64 + +# 2) 마커 때문에 빠진 리눅스/Py3.9 전용 의존성을 "이름으로" 보강 (마커 게이팅 우회) +pip download uvloop sniffio "exceptiongroup>=1.0.2" -d vendor/ \ + --only-binary=:all: --implementation cp --abi cp39 --python-version 39 \ + --platform manylinux_2_28_x86_64 --platform manylinux_2_17_x86_64 \ + --platform manylinux2014_x86_64 --platform manylinux1_x86_64 + +# 3) 리눅스에서 안 쓰는 win32 전용 잉여 wheel 제거 +rm -f vendor/colorama-*.whl vendor/tzdata-*.whl +``` +`# --python-version 39 → 타깃이 3.11/3.12면 311/312, --abi 도 cp311/cp312 로 바꾼다.` + +**검증(반드시)** — 받은 뒤 폐쇄집합이 맞는지 확인: +```bash +ls vendor | grep -i uvloop # 있어야 함(리눅스) +ls vendor | grep -iE 'colorama|tzdata' # 없어야 함(win32 전용) +# 컴파일 wheel은 전부 cp39 manylinux x86_64 여야 함: +ls vendor | grep -viE 'py3-none-any|py2.py3-none-any' +``` +현재 requirements 기준 정상 폐쇄집합은 **29개**다(win32 잉여 제외). > 참고: `uvicorn[standard]`는 uvloop/httptools/watchfiles 등 컴파일 wheel을 포함한다. 버전 매칭이 > 까다로우면 `requirements.txt`의 `uvicorn[standard]`를 `uvicorn`(순정)으로 바꿔 wheel 세트를 줄일 수 있다 -> (운영은 `--reload` 안 쓰므로 watchfiles 불필요). +> (운영은 `--reload` 안 쓰므로 watchfiles 불필요). 다만 위 절차로 `[standard]`도 문제없이 반입된다. ---