ivada-infra/DOCS

Fork 0

Claude aa3444d750 docs: update 24 server root-cause remediation

2026-03-09 18:01:25 +09:00

13 KiB

Raw Blame History

24서버 우분투 터미널 불가, 네트워크 대역 오류, python3-apt 복구 기록

상위 원칙

Infra Project Identity
Core Infrastructure Principles
Operational Guardrails
공통 작성 원칙: /home/admin/0_VALUE/02_Governance/writing-principles.md

사건 요약

24 서버에서 GUI 터미널이 열리지 않아 Ctrl + Alt + F3로 텍스트 콘솔(TTY, 그래픽 없이 명령만 입력하는 콘솔)로 진입해 복구를 시작했다.
초반에는 apt update가 실패해 패키지 문제처럼 보였지만, 실제 선행 원인은 잘못된 IP 대역 유지였다.
네트워크 복구 후에는 ModuleNotFoundError: No module named 'apt_pkg'가 남았고, 이는 Ubuntu 22.04 시스템 Python 기준이 3.10이어야 하는데 python3 기본 링크가 3.13으로 바뀐 상태와 연결됐다.

증상

GUI 터미널 실행 불가
apt update 실패
이름 해석 실패 메시지 관측
ping 8.8.8.8 이전 단계에서 게이트웨이 도달 실패
네트워크 복구 후 ModuleNotFoundError: No module named 'apt_pkg' 발생

확인된 사실

1. 네트워크

24 서버에는 기존 고정 IP 192.168.219.52가 남아 있었다.
실제 운영 LAN 대역은 다른 장치 기준 192.168.0.x였다.
sudo dhclient -v eno1 실행 후 192.168.0.106을 새로 받아 인터넷 연결이 살아났다.
이후 인터페이스에 192.168.219.52와 192.168.0.106이 동시에 붙어 있어, 이전 고정 IP가 잔존한 상태로 확인됐다.
ping 8.8.8.8 성공으로 DNS 이전 단계의 외부 연결은 복구된 것으로 판단했다.

2. Python / apt

네트워크 복구 뒤에도 apt가 apt_pkg 모듈을 찾지 못했다.
python3 --version 확인 결과 24 서버의 기본 python3가 3.13.5였다.
Ubuntu 22.04 계열의 python3-apt는 Python 3.10 ABI(Application Binary Interface, 파이썬 확장 모듈이 맞춰져야 하는 바이너리 규격)를 기준으로 제공된다.
따라서 python3 -> 3.13 상태에서는 python3-apt가 설치돼 있어도 apt_pkg를 불러오지 못할 수 있다.

3. 최종 복구 방향

시스템 Python 기준을 3.10으로 되돌리고,
python3-apt를 다시 설치한 뒤,
apt update가 정상 완료되는 것을 확인하는 순서가 맞았다.
별도로 Codex CLI는 전역 진입점과 실제 Node 런타임 버전이 어긋나지 않도록 보정해야 했다.

원인 정리

직접 원인

24 서버 NIC(Network Interface Card, 네트워크 인터페이스) eno1에 현재 LAN과 맞지 않는 과거 대역 192.168.219.52/24가 남아 있었다.
Ubuntu 시스템 Python 링크가 3.13으로 바뀌어 apt의 Python 바인딩이 깨졌다.

근본 원인

네트워크 기준값과 실제 연결된 LAN 대역이 어긋난 채 고정 IP 흔적이 남아 있었다.
개발용 Python 3.13을 시스템 Python 자리에 올려 Ubuntu 22.04의 기본 패키지 체인과 분리되지 않았다.

실제 복구 순서

1. 네트워크 복구

sudo dhclient -v eno1
sudo ip addr del 192.168.219.52/24 dev eno1

2. 시스템 Python 기준 복구

sudo ln -sf /usr/bin/python3.10 /usr/bin/python3
sudo apt install --reinstall python3-apt -y

필요 시 선행 복구 명령:

sudo apt install python3.10 python3.10-minimal python3.10-distutils -y

3. 패키지 갱신 확인

sudo apt update
sudo apt upgrade -y

4. Codex CLI 런타임 근본 복구

문제 재현:

sudo -u happybell80 bash -lc 'which node; node -v; which codex; codex login status'

재현 시점 확인값:

which node -> /usr/bin/node
node -v -> v12.22.9
which codex -> /usr/local/bin/codex
결과: SyntaxError: Unexpected reserved word

원인:

/usr/local/bin/codex는 #!/usr/bin/env node shebang을 사용한다.
하지만 happybell80의 로그인 셸 기본 PATH에서는 시스템 node v12.22.9가 먼저 잡혔다.
반면 실제 Codex CLI 패키지는 /home/happybell80/.nvm/versions/node/v24.4.0/... 아래에 설치돼 있었고, engines.node >= 16 요구와 충돌했다.

적용 조치:

sudo cp -a /usr/local/bin/codex /usr/local/bin/codex.pre_node24_fix
sudo cp -a /usr/local/bin/codex /usr/local/bin/codex.wrapper.20260309
sudo ln -sfn /home/happybell80/.nvm/versions/node/v24.4.0/bin/node /usr/local/bin/node
sudo ln -sfn /home/happybell80/.nvm/versions/node/v24.4.0/bin/codex /usr/local/bin/codex

적용 내용:

/usr/local/bin/node를 node v24.4.0 바이너리로 연결해, #!/usr/bin/env node가 더 이상 시스템 node v12.22.9를 집지 않도록 했다.
/usr/local/bin/codex는 래퍼가 아니라 원래 Codex CLI 바이너리 심볼릭 링크로 되돌렸다.
기존 전역 진입점은 /usr/local/bin/codex.pre_node24_fix로 유지했고, 임시 래퍼는 /usr/local/bin/codex.wrapper.20260309로만 보관했다.
happybell80의 ~/.profile에 Node v24.4.0 경로를 PATH 앞단에 두는 설정을 추가해 로그인 셸에서도 동일한 런타임을 사용하도록 맞췄다.

검증:

sudo -u happybell80 bash -lc 'which node; node -v; codex --help | sed -n "1,4p"; codex login status'
env -i PATH=/usr/local/bin:/usr/bin:/bin HOME=/home/happybell80 USER=happybell80 /usr/local/bin/codex --help

검증 결과:

which node -> /home/happybell80/.nvm/versions/node/v24.4.0/bin/node
node -v -> v24.4.0
codex --help 정상 출력
codex login status -> Logged in using ChatGPT
최소 PATH 환경에서도 /usr/local/bin/codex --help 정상 출력
즉 최종 상태는 래퍼 우회가 아니라, env node가 시스템 차원에서 지원 버전 Node를 찾도록 바로잡은 상태다.

Python 관련 핵심 해설

Ubuntu 22.04는 시스템 도구 다수가 python3.10 기준으로 패키징돼 있다.
여기에는 apt, software-properties, 일부 배포 관리 유틸리티가 포함된다.
따라서 python3 기본 링크를 3.13으로 바꾸면 개발 환경은 편할 수 있어도 시스템 패키지 관리 체인이 깨질 수 있다.
Python 3.13이 필요하면 시스템 링크를 바꾸지 말고 아래 방식 중 하나로 분리해야 한다.

/usr/bin/python3.13
python3.13 -m venv .venv

즉 24 서버 문제의 핵심은 "Python 3.13 설치" 자체가 아니라 "Ubuntu 시스템 python3를 3.13으로 교체한 것"이었다.

검증 결과

24 서버

DHCP로 192.168.0.x 대역 IP를 다시 받았다.
2026-03-09 현재 SSH 접속 기준은 ssh -p 51124 -i ~/.ssh/id_rsa_51123_to_51124 admin@192.168.0.106이다.
외부 IP 8.8.8.8 대상 ping 성공이 확인됐다.
apt update가 최종적으로 정상 동작하는 상태까지 복구됐다.
복구 완료 시점에 233 packages can be upgraded 메시지가 관측돼 패키지 목록 로드가 정상화된 것으로 판단했다.
23 서버에서 위 SSH 명령으로 실제 접속 검증 시 hostname=robeing-i9, user=admin 응답을 확인했다.
추가 확인 결과 Codex CLI 직접 장애 원인은 네트워크 전면 차단이 아니라 node v12.22.9와 @openai/codex 0.53.0 조합의 런타임 충돌이었다.
2026-03-09 수정 후 happybell80 로그인 셸과 /usr/local/bin/codex 직접 호출 모두 node v24.4.0 기준으로 정상 동작한다.
/usr/local/bin/node도 node v24.4.0를 가리키도록 맞춰, env node 기반 실행 경로의 런타임 충돌을 제거했다.

23 서버 현재 점검 범위

본 문서는 2026-03-09 현재 작업 환경에서 23 서버로 사용 중인 호스트를 기준으로 확인했다.
확인 결과:
- hostname: robeing-brains
- Ubuntu: 22.04.5 LTS
- kernel: 6.8.0-101-generic
- 물리 NIC: enp6s0, 주소 192.168.0.100/24
- 기본 게이트웨이: 192.168.0.1
- uptime: 2 days, 18:36
- 루트 디스크 사용률: 38% (/dev/sda2, 81G/228G)
- 메모리: 29Gi 중 7.0Gi 사용, 21Gi available
- python3 --version: Python 3.10.12
- /usr/bin/python3 -> /usr/bin/python3.10
- /usr/lib/python3/dist-packages/apt_pkg.cpython-310-x86_64-linux-gnu.so 존재
- python3 -c 'import apt_pkg' 성공
- apt-cache policy python3 python3-apt 기준 설치 상태 정상
- ping -c 2 8.8.8.8 성공
- ping -c 2 git.ro-being.com 성공, 106.254.1.37 해석 확인
- git -C /home/admin/infra/DOCS pull --ff-only: Already up to date.
- sudo apt update 성공, 업그레이드 가능 패키지 2개 확인
따라서 23 서버에서는 이번 24 서버와 동일한 python3 -> 3.13 치환 및 apt_pkg 손상 징후가 없고, 네트워크/DNS/Git/apt 기본 동작도 현재 시점에 정상으로 확인됐다.

23 서버 추가 발견 이슈와 조치

다만 전체 systemd 상태 확인에서 systemctl is-system-running 결과가 처음에는 degraded였다.
실패 유닛은 logrotate.service 1건이었고, 원인은 /etc/logrotate.d/nginx.backup.20251021가 /etc/logrotate.d/nginx와 동일한 /var/log/nginx/*.log 항목을 중복 선언한 것이었다.
백업 파일을 아래처럼 .bak로 변경해 logrotate 대상에서 제외했다.

sudo mv /etc/logrotate.d/nginx.backup.20251021 /etc/logrotate.d/nginx.backup.20251021.bak
sudo systemctl start logrotate.service
sudo systemctl reset-failed

이후 sudo logrotate -d /etc/logrotate.conf에서 Ignoring nginx.backup.20251021.bak, because of *.bak pattern match를 확인했다.
sudo systemctl status logrotate.service는 status=0/SUCCESS로 종료됐고, systemctl --failed는 0 loaded units listed., sudo systemctl is-system-running은 running으로 복귀했다.

2026-03-09 추가 확인 및 수정: 잔존 사설 IP 설정

작업 전 활성 인터페이스 eno1에는 192.168.219.52/24와 192.168.0.106/24가 동시에 붙어 있었다.
작업 전 ip route 기준 기본 경로도 192.168.0.1 외에 192.168.219.1 metric 100이 함께 남아 있었다.
원인은 NetworkManager 프로필 /etc/NetworkManager/system-connections/Wired connection 1.nmconnection에 과거 고정값이 남아 있던 것이다.

[ipv4]
address1=192.168.0.106/24,192.168.0.1
dns=8.8.8.8;1.1.1.1;
method=manual
route-metric=0

적용 조치:

sudo nmcli connection modify 'Wired connection 1' \
  ipv4.method manual \
  ipv4.addresses '192.168.0.106/24' \
  ipv4.gateway '192.168.0.1' \
  ipv4.dns '8.8.8.8 1.1.1.1' \
  ipv4.routes '' \
  ipv4.route-metric 0
sudo ip addr del 192.168.219.52/24 dev eno1
sudo ip route del default via 192.168.219.1 dev eno1 metric 100

수정 결과:

활성 eno1에는 현재 192.168.0.106/24만 남아 있다.
기본 경로는 192.168.0.1만 남아 있다.
즉 과거 사설 IP 192.168.219.52/24는 런타임과 영구 설정 모두에서 제거됐다.

재발 방지

24 서버에서 시스템 python3 링크를 변경하지 않는다.
개발용 Python 3.13은 venv 또는 명시적 바이너리 경로로만 사용한다.
고정 IP를 운용할 때는 현재 LAN 대역과 SSOT를 먼저 대조하고, 과거 대역의 잔존 주소를 제거한다.
Node 기반 전역 CLI는 #!/usr/bin/env node shebang에 의존할 때 사용자별 PATH 차이로 런타임 충돌이 날 수 있으므로, 시스템이 먼저 찾는 node 경로 자체를 지원 버전으로 유지한다.
GUI 터미널 불가 시에는 바로 재설치부터 하지 말고 TTY 진입 -> 네트워크 확인 -> 시스템 Python 확인 -> apt 복구 순서로 본다.
23 서버에서는 /etc/logrotate.d/ 아래에 운영 중인 설정의 백업 파일을 같은 확장자 없이 남기지 않는다.

후속 권장 작업

24 서버에서 node 경로를 바꿀 일이 생기면 /usr/local/bin/node와 happybell80의 NVM 기본 버전이 함께 맞는지 점검한다.
24 서버에서 Python 3.13이 필요한 프로젝트가 있으면 시스템 링크 변경 없이 가상환경으로 분리한다.
24 서버에서 Codex/Node를 업데이트할 때는 /usr/local/bin/node, /usr/local/bin/codex, happybell80의 NVM 기본 버전이 함께 일치하는지 점검한다.
23/24 공통 운영 기준 문서에 "Ubuntu 22.04 시스템 Python 변경 금지"를 반복 규칙으로 승격할지 검토한다.
23 서버의 남은 패키지 업데이트 2건(network-manager-openvpn, network-manager-openvpn-gnome)은 영향 시간대 확인 후 반영 여부를 결정한다.

13 KiB

Raw Blame History

24서버 우분투 터미널 불가, 네트워크 대역 오류, python3-apt 복구 기록

상위 원칙

관련 문서

사건 요약

증상

확인된 사실

1. 네트워크

2. Python / apt

3. 최종 복구 방향

원인 정리

직접 원인

근본 원인

실제 복구 순서

1. 네트워크 복구

2. 시스템 Python 기준 복구

3. 패키지 갱신 확인

4. Codex CLI 런타임 근본 복구

Python 관련 핵심 해설

검증 결과

24 서버

23 서버 현재 점검 범위

23 서버 추가 발견 이슈와 조치

2026-03-09 추가 확인 및 수정: 잔존 사설 IP 설정

재발 방지

후속 권장 작업

상위 원칙/근거 문서 연결

13 KiB Raw Blame History

24서버 우분투 터미널 불가, 네트워크 대역 오류, python3-apt 복구 기록

상위 원칙

관련 문서

사건 요약

증상

확인된 사실

1. 네트워크

2. Python / apt

3. 최종 복구 방향

원인 정리

직접 원인

근본 원인

실제 복구 순서

1. 네트워크 복구

2. 시스템 Python 기준 복구

3. 패키지 갱신 확인

4. Codex CLI 런타임 근본 복구

Python 관련 핵심 해설

검증 결과

24 서버

23 서버 현재 점검 범위

23 서버 추가 발견 이슈와 조치

2026-03-09 추가 확인 및 수정: 잔존 사설 IP 설정

재발 방지

후속 권장 작업

상위 원칙/근거 문서 연결

13 KiB

Raw Blame History