Linux 설정 파일 갱신 중 JSON이 깨지는 이유: os.replace로 원자적 교체하기

Linux에서 서비스가 읽는 JSON 설정 파일을 갱신할 때는 대상 파일을 직접 비우고 다시 쓰기보다, 같은 디렉터리에 새 내용을 완성한 뒤 os.replace로 교체하는 편이 적절하다. 이 방식은 이름을 통해 파일을 여는 독자가 작성 중간 상태를 읽는 문제를 피한다. 다만 이미 열린 파일, 여러 작성자의 경쟁, 전원 장애 후 보존은 별도로 다뤄야 한다. 아래 Python 예제로 그 경계를 확인한다.

완성된 문서 카트리지와 교체 장치로 설정 스냅샷의 교체를 표현한 개념 일러스트. 실제 파일시스템 구조도는 아니다.

작성·문서 확인: 2026-11-01. 실행 검증: Python 3.12.14, Linux amd64의 로컬 임시 디렉터리. 사용자 서비스나 실제 설정 파일에는 접근하지 않았다.

덮어쓰기 중간의 파일도 독자는 열 수 있다

open(path, "w")는 기존 내용을 비운 뒤 쓴다. JSON 앞부분만 기록한 순간 다른 코드가 파일을 열면 파싱할 수 없는 내용을 볼 수 있다. 아래 재현은 임의의 지연이나 스레드 경쟁 대신 두 번의 쓰기 사이에서 읽는다. 경쟁이 발생할 수 있는 상태를 결정적으로 보여 주며, 장애 발생 빈도를 측정하지는 않는다.

해결의 핵심은 독자가 사용하는 이름에 불완전한 내용을 쓰지 않는 것이다. Python os.replace 문서는 성공한 이름 변경의 원자성을 설명한다. 임시 파일은 대상과 같은 디렉터리에 만들어 파일시스템 경계를 넘는 이동을 피한다.

교체 순서와 각 단계의 역할

단계	역할
문서를 먼저 직렬화한다	이 단계에서 실패하면 대상 파일을 건드리지 않는다
같은 디렉터리의 임시 파일에 쓴다	독자가 사용하는 대상 이름은 유지한다
flush 후 임시 파일을 fsync한다	Python 버퍼와 파일 동기화를 순서대로 요청한다
os.replace로 이름을 교체한다	완성된 새 파일을 대상 이름으로 공개한다
부모 디렉터리를 fsync한다	이름 변경의 디렉터리 항목 동기화를 요청한다

원자성은 독자가 관찰하는 교체의 성질이다. 저장장치까지 반영되는 내구성과는 구별한다. Linux fsync(2)는 파일 동기화만으로 부모 디렉터리 항목의 저장을 보장하지 않으며, 디렉터리에 대한 별도 호출이 필요함을 설명한다. 이 예제는 그 호출 순서를 사용하지만 전원 차단 복구 시험을 수행하지 않았다.

실행 가능한 최소 예제

아래를 atomic_config.py로 저장하고 python atomic_config.py로 실행한다. 외부 패키지는 필요 없다. 신뢰할 수 있고 실행 중 바뀌지 않는 부모 디렉터리, 하나의 협조적인 작성자를 전제로 한다. 예제는 전체 JSON을 메모리에 직렬화하므로 큰 파일용 스트리밍 구현이 아니다.

allow_nan=False는 예제에서 NaN을 직렬화 오류로 만드는 데 사용한다. 이것만으로 애플리케이션 설정의 필수 필드·허용 범위를 검증하는 것은 아니다. 실제 서비스의 스키마 검증은 임시 파일을 공개하기 전에 수행해야 한다.

실제 실행 결과와 독자의 관찰 범위

검증한 다섯 항목은 덮어쓰기 중간의 파싱 실패, 기존 열린 파일의 버전 1, 새로 연 파일의 버전 2, 직렬화 실패 시 버전 2 보존, 정상 실행 후 임시 파일이 남지 않는 상태다. 파일·디렉터리 fsync 호출도 이 실행에서 오류 없이 완료됐다. I/O 오류 주입, 강제 종료, 정전, NFS, Windows 환경은 시험하지 않았다.

Linux rename(2)에 설명된 것처럼 이름 교체는 기존 열린 파일 디스크립터를 새 파일로 바꾸지 않는다. 독자는 한 번 열어서 그 핸들로 끝까지 읽고 파싱해야 한다. 처리 중 여러 번 다시 열면 서로 다른 버전을 섞을 수 있다. 예제에서 version 1을 보는 기존 핸들은 교체 실패의 증거가 아니다.