휠하우스로 사내 파이썬 인덱스 세우기

목표

연결된 쪽에서 파이썬 패키지와 의존성을 휠로 모으고 해시로 고정한 뒤, 폐쇄망 쪽에 PEP 503 사내 인덱스를 세워 pip.conf 로 가리키고, 바깥이 막혀도 설치가 되는 것을 확인한다.

왜 중요한가

폐쇄망 반입에서 가장 비싼 실수는 "받아 갔는데 모자라서 다시 나오는 것" 과 "받아 갔는데 서버에서 안 맞는 것" 이다. 앞의 것은 의존성을 바깥에서 통째로 풀어 가면 막히고, 뒤의 것은 대상 서버의 파이썬 버전과 플랫폼을 적어 받으면 막힌다. 그리고 매체를 지나며 바뀐 파일은 해시 검사 모드가 잡는다. 이 파드는 처음부터 인터넷(80/443)에 닿으므로 받는 쪽 역할을 하고, 폐쇄망 쪽 확인은 채점기가 바깥으로 가는 HTTP(S)를 닫힌 프록시로 보내 막은 채로 한다.

단계

1. requests==2.32.3 과 그 의존성을 이 파드의 파이썬(3.12)용 휠로만 받아 /root/pip/wheelhouse/ 에 모은다.
2. 폐쇄망 서버는 파이썬 3.11(x86_64, manylinux2014)이다. 같은 요구사항을 그 대상용 휠로 받아 /root/pip/wheelhouse-py311/ 에 모은다.
3. /root/pip/wheelhouse/ 의 휠 전부를 이름==버전 --hash=sha256:<값> 줄로 적은 /root/pip/requirements.txt 를 만든다.
4. /srv/pypi/simple/<정규화한 이름>/ 디렉터리마다 해당 휠을 넣어 PEP 503 모양의 인덱스를 만든다.
5. /etc/hosts 에 127.0.0.1 pypi.airgap.internal 을 더하고, /srv/pypi 를 8080 포트로 내주는 python3 -m http.server 를 띄운다. 접근 기록은 /root/pip/index.log 로 남긴다.
6. /etc/pip.conf 에 index-url = http://pypi.airgap.internal:8080/simple 과 그 주소를 믿는 설정을 적는다. 채점기는 바깥을 막은 채 이 설정만으로 requests 가 받아지는지 본다.
7. venv /root/pip/venv 를 만들고 requirements.txt 를 해시 검사 모드로 설치한다.
8. 인덱스가 없는 곳을 가정해 venv /root/pip/venv-usb 에 --no-index --find-links /root/pip/wheelhouse 로 같은 요구사항을 설치한다.

참고

• 받기만: pip download -d <디렉터리> ... · 대상 지정: --platform manylinux2014_x86_64 --python-version 3.11 --only-binary=:all:
• 해시 한 줄: pip hash <휠> · 어느 설정 파일이 읽혔나: pip config debug
• 이름 정규화: 소문자로 바꾸고 .·-·_ 묶음을 - 하나로. charset_normalizer → charset-normalizer
• 흔한 실수 1: http:// 사내 인덱스에 trusted-host 를 빼기. pip 는 경고만 남기고 인덱스를 무시합니다.
• 흔한 실수 2: 시스템 파이썬에 바로 설치하기. 우분투 24.04 는 PEP 668 로 막습니다 — venv 를 쓰세요.
• 흔한 실수 3: 서버를 띄운 터미널을 닫거나 서버를 죽이기. 6~7단계 채점은 서버가 떠 있어야 합니다.

받는 쪽: 의존성까지 휠로 받기

requests==2.32.3 과 그 의존성을 이 파드의 파이썬용 휠로만 받아 /root/pip/wheelhouse/ 에 모은다.

pip 에는 설치하지 않고 파일만 모으는 하위 명령이 있습니다. 소스 배포본(.tar.gz)이 섞이면 폐쇄망 서버에서 빌드 도구를 요구하니, 바이너리만 받게 하는 옵션도 함께 쓰세요.

대상 서버의 파이썬에 맞춰 받기

파이썬 3.11(x86_64, manylinux2014) 서버용으로 같은 요구사항을 받아 /root/pip/wheelhouse-py311/ 에 모은다.

pip download 는 대상의 플랫폼과 파이썬 버전을 따로 받을 수 있습니다. 문서가 그 옵션들과 함께 반드시 써야 한다고 적은 옵션이 하나 있습니다. 받은 뒤 파일 이름의 태그(cp311 등)를 보세요.

버전과 해시로 고정하기

/root/pip/wheelhouse/ 의 휠 전부를 이름==버전 --hash=sha256:<값> 줄로 적은 /root/pip/requirements.txt 를 만든다.

휠 파일 이름의 첫 두 칸이 이름과 버전입니다. 해시는 pip 가 직접 계산해 주는 하위 명령이 있고, sha256sum 과 같은 값입니다. 한 줄에 요구사항과 --hash 를 함께 적습니다.

PEP 503 모양의 사내 인덱스 만들기

/srv/pypi/simple/<정규화한 이름>/ 디렉터리마다 해당 휠을 넣는다.

디렉터리 이름은 패키지 이름을 규격대로 정규화한 것이어야 pip 가 찾습니다. 소문자, 그리고 점·하이픈·밑줄 묶음은 하이픈 하나. 휠 파일 이름 안의 밑줄과 헷갈리지 마세요.

사내 이름으로 인덱스 띄우기

/etc/hosts 에 127.0.0.1 pypi.airgap.internal 을 더하고 /srv/pypi 를 8080 으로 내주는 서버를 띄운다. 접근 기록은 /root/pip/index.log 로 남긴다.

파이썬 표준 라이브러리의 http.server 는 디렉터리 목록을 파일 이름 링크로 내줍니다. 내줄 디렉터리와 포트를 인자로 주고, 터미널을 닫아도 살아 있게 백그라운드로 띄우세요. 이 서버는 접근 기록을 표준 오류로 냅니다.

pip.conf 로 사내 인덱스 가리키기

/etc/pip.conf 에 index-url = http://pypi.airgap.internal:8080/simple 과 그 주소를 믿는 설정을 적는다.

https 가 아닌 인덱스는 pip 가 기본으로 믿지 않습니다(localhost 만 예외). 호스트 이름을 믿게 하는 설정 키가 있습니다. pip config debug 로 파일이 실제로 읽히는지 확인하세요.

해시 검사 모드로 venv 에 설치

venv /root/pip/venv 를 만들고 /root/pip/requirements.txt 를 해시 검사 모드로 설치한다.

우분투 24.04 의 시스템 파이썬에는 바로 설치할 수 없습니다. venv 를 만든 뒤 그 안의 pip 로 requirements 파일을 설치하세요. 파일에 --hash 가 있으면 해시 검사 모드가 켜지지만, 명시하는 옵션도 있습니다.

인덱스 없이 휠하우스만으로 설치

venv /root/pip/venv-usb 를 만들고 --no-index --find-links /root/pip/wheelhouse 로 /root/pip/requirements.txt 를 설치한다.

인덱스를 아예 보지 않게 하는 옵션과, 파일을 찾을 디렉터리를 주는 옵션을 함께 씁니다. 이 설치가 되면 휠하우스가 스스로 완결되어 있다는 뜻입니다.