Cron PHP 오류 (실행 환경, NULL 원인, API 검증)

터미널에서 직접 실행하면 멀쩡히 돌아가는 PHP 스크립트가, cron에 등록하는 순간 DB에 NULL을 집어넣는다면 어떻게 생각하시겠습니까? 저는 처음에 DB 연결 문제나 권한 문제를 의심했습니다. 그런데 파고들수록 진짜 원인은 전혀 다른 곳에 있었습니다. 한국투자증권 Open API 토큰 발급 자동화를 구축하면서 직접 겪은 이야기입니다.

cron 실행 환경이 CLI와 다르다는 걸 몰랐습니다

당시 저는 PHP로 한국투자증권 Open API의 액세스 토큰(access token)을 발급받아 DB에 저장하는 스크립트를 운영하고 있었습니다. 액세스 토큰이란 API 서버에 요청을 보낼 때 신원을 증명하는 임시 인증 키로, 일정 시간이 지나면 만료되기 때문에 주기적으로 갱신해야 합니다. 아침 5시, 저녁 5시 하루 두 번 자동으로 갱신되도록 crontab에 등록했습니다.

처음에는 아무 문제가 없어 보였습니다. 터미널에서 직접 실행하면 토큰이 정상 발급되고 DB에도 깔끔하게 저장됐으니까요. 그런데 cron이 자동으로 돌기 시작하자 DB의 a1_token 테이블을 열었을 때 access_token 컬럼이 비어 있거나 NULL로 찍혀 있는 경우가 생겼습니다. 실행 자체는 된 것 같은데, 데이터가 없는 상황이었습니다.

제가 직접 겪어보니 cron 환경은 터미널 환경과 생각보다 훨씬 다릅니다. 단순히 “같은 스크립트를 실행한다”는 것 외에 거의 모든 것이 다르다고 봐야 합니다. 실제로 cron 잡(cron job)이란 지정된 시각에 시스템이 자동으로 명령어를 실행하는 작업 스케줄러인데, 이때 적용되는 사용자 계정, PATH, 환경변수, 작업 디렉터리가 터미널 세션과는 완전히 다른 맥락으로 구성됩니다.

예를 들어 터미널에서는 php라고만 쳐도 실행되지만, cron에서는 PATH가 다르게 설정되어 있어서 PHP 실행 파일을 찾지 못할 수 있습니다. 그래서 crontab에 등록할 때는 /usr/bin/php처럼 절대 경로(absolute path)를 명시해야 합니다. 절대 경로란 루트 디렉터리부터 파일까지의 전체 경로를 말하며, 어떤 환경에서 실행하든 동일하게 파일을 가리킬 수 있습니다. 저는 이 부분을 처음에 빠뜨렸고, 그게 문제의 시작이었습니다.

cron 실행 환경에서 확인해야 할 주요 차이점을 정리하면 다음과 같습니다.

  1. 실행 사용자 계정이 달라 파일 접근 권한이 제한될 수 있습니다.
  2. PATH 환경변수가 다르게 설정되어 명령어 경로를 찾지 못할 수 있습니다.
  3. 작업 디렉터리(working directory)가 달라 상대 경로로 설정된 파일을 열지 못합니다.
  4. SSL 인증서 경로나 네트워크 설정이 달라 외부 API 호출에 실패할 수 있습니다.
  5. php.ini 설정이 CLI와 cron에서 다르게 적용되는 경우가 있습니다.

NULL의 진짜 원인은 INSERT가 아니었습니다

환경 차이를 파악하고 나서 코드를 다시 들여다봤습니다. 그리고 솔직히 이건 예상 밖이었습니다. DB INSERT 문 자체에는 문제가 없었습니다. 문제는 INSERT 직전 데이터가 이미 망가진 상태라는 점이었습니다.

당시 코드의 핵심 로직은 다음과 같았습니다. curl_exec()로 API 응답을 받고, json_decode()로 배열로 변환한 뒤, error_code 키가 없으면 성공으로 판단하고 DB에 저장하는 흐름이었습니다. 겉으로 보면 꽤 합리적인 구조입니다. API가 에러를 반환하면 error_code를 실어 보낼 테니까요.

그런데 curl_exec() 자체가 실패하면 어떻게 될까요. 이 함수가 실패하면 반환값은 불리언 false(boolean false)입니다. 불리언 false란 참/거짓 중 ‘거짓’을 나타내는 값으로, 문자열이나 배열이 아닙니다. 이 false를 json_decode()에 넘기면 당연히 정상적인 배열이 만들어지지 않습니다. 결과적으로 $t_arr는 의미 없는 상태가 되고, 그 상태에서 error_code 키를 검사하면 없는 게 당연합니다. 그러니 “에러 없음 = 성공”이라는 조건을 그냥 통과해 버립니다.

이렇게 되면 access_token 값도 당연히 존재하지 않고, 그 상태로 DB INSERT가 실행되면서 NULL이 저장되는 겁니다. cron이 DB에 NULL을 넣은 게 아니라, cron 환경에서 API 요청이 실패했는데 코드가 그걸 눈치채지 못하고 INSERT를 실행한 것이었습니다.

제 경험상 이런 종류의 버그가 가장 무서운 이유는 에러가 발생하지 않기 때문입니다. 프로그램은 정상적으로 종료되고, cron도 정상 실행된 것으로 기록됩니다. 그런데 데이터는 조용히 망가져 있습니다. 이걸 발견하려면 DB를 직접 열어봐야 합니다.

또 한 가지 문제는 cron 로그 설정이 잘못되어 있었다는 점입니다. 초기 crontab 설정에 로그 리다이렉션(log redirection) 문법이 틀려 있었습니다. 리다이렉션이란 프로그램의 출력 결과나 오류 메시지를 파일로 저장하는 방법인데, 2 > /test3.txt처럼 숫자와 꺾쇠 사이에 공백이 들어가면 stderr를 파일로 연결하는 것이 아니라 전혀 다른 동작을 합니다. 제대로 하려면 2>&1처럼 공백 없이 붙여써야 합니다. 로그가 안 쌓이니 오류를 추적할 수도 없었던 겁니다.

API 응답 검증은 이 순서로 해야 합니다

이 경험을 계기로 외부 API를 호출하는 코드를 작성할 때 저는 반드시 단계별로 검증하는 습관을 갖게 됐습니다. 한 번에 성공을 가정하는 코드가 얼마나 위험한지 몸으로 배웠기 때문입니다.

먼저 curl_exec() 반환값이 false인지 확인합니다. false라면 curl_error()로 오류 메시지를 남기고 즉시 종료합니다. 다음으로 HTTP 상태 코드(HTTP status code)를 확인합니다. HTTP 상태 코드란 서버가 요청을 어떻게 처리했는지 알려주는 세 자리 숫자로, 200번대는 정상, 400번대는 클라이언트 오류, 500번대는 서버 오류를 뜻합니다. curl_getinfo()로 꺼낼 수 있으며, 200번대가 아니면 역시 저장하지 않습니다.

그다음은 json_decode() 결과가 배열인지 확인합니다. is_array()로 체크하면 됩니다. 여기까지 통과했다면 마지막으로 실제로 필요한 데이터가 있는지 확인합니다. 기존처럼 error_code의 부재를 성공 기준으로 삼는 게 아니라, access_token과 access_token_token_expired가 실제로 비어 있지 않은지를 직접 확인하는 방식입니다. 이렇게 하면 API가 예상과 다른 응답을 보냈을 때 실수로 성공 처리하는 일이 없습니다.

cron 설정에서도 몇 가지를 바꿨습니다. PHP 실행 파일을 절대 경로로 명시했고, 표준 출력과 표준 오류를 모두 로그 파일로 저장하도록 수정했습니다. PHP 공식 문서(curl_exec)에서도 curl 실패 시 반드시 false 여부를 확인하도록 명시하고 있으며, 이 검증을 생략하면 이후 코드 전체가 잘못된 전제 위에서 실행됩니다. 또한 HTTP 시맨틱스 명세(RFC 9110)에서도 클라이언트는 상태 코드를 반드시 해석하고 처리해야 한다고 정의하고 있습니다.

결국 제가 정착한 API 호출 검증 순서는 다음과 같습니다.

  1. curl_exec() 반환값이 false인지 확인하고 curl 오류 메시지를 로그에 기록합니다.
  2. HTTP 상태 코드가 200번대인지 확인하고 비정상이면 응답 본문을 로그에 남깁니다.
  3. json_decode() 결과가 배열인지 is_array()로 확인합니다.
  4. 실제 필요한 데이터 키가 비어 있지 않은지 empty()로 확인합니다.
  5. 위 단계를 모두 통과한 경우에만 DB INSERT를 실행합니다.

이 다섯 단계 중 하나라도 실패하면 DB에는 아무것도 쓰지 않습니다. 불완전한 데이터가 쌓이는 것보다 아무것도 없는 편이 훨씬 낫고, 로그에 기록이 남으니 나중에 추적도 쉽습니다.

자주 묻는 질문

Q. CLI에서 잘 되는 PHP 스크립트가 cron에서 실패하는 가장 흔한 이유는 무엇인가요?

A. 가장 많은 경우는 PHP 실행 파일 경로와 환경변수 차이입니다. cron은 터미널처럼 사용자의 PATH를 상속받지 않기 때문에, crontab에 그냥 php라고만 쓰면 실행 파일을 찾지 못합니다. which php 명령어로 절대 경로를 확인한 뒤 /usr/bin/php처럼 명시해야 합니다. 작업 디렉터리와 실행 사용자도 달라지므로 상대 경로 사용은 피하는 것이 좋습니다.

Q. cron에서 PHP가 실행됐는지 어떻게 확인하나요?

A. crontab 설정에 >> /var/log/cron_script.log 2>&1을 붙이면 표준 출력과 표준 오류를 모두 파일로 저장할 수 있습니다. 이때 2 > 처럼 공백을 넣으면 stderr 리다이렉션이 되지 않으니 주의해야 합니다. 직접 겪어보니 로그 설정 하나 잘못돼 있으면 오류가 나도 아무것도 남지 않아서 원인 파악이 거의 불가능합니다.

Q. curl_exec()가 실패했는데 왜 DB에 NULL이 저장될 수 있나요?

A. curl_exec()가 실패하면 반환값이 false가 되는데, 이를 바로 json_decode()에 넘기면 배열이 생성되지 않습니다. 이후 error_code 키의 부재를 성공으로 판단하는 조건이 있으면, 배열에 아무것도 없어도 조건을 통과해 INSERT가 실행됩니다. 결국 NULL이나 빈 값이 DB에 저장되는 겁니다. curl 실패 여부를 먼저 확인하지 않으면 이런 조용한 오류가 생깁니다.

Q. cron에서 API 외부 요청이 실패하는 경우가 있나요?

A. 있습니다. cron이 실행될 때의 네트워크 환경이나 SSL 인증서 경로가 터미널과 다르게 설정된 경우, 외부 HTTPS 요청이 실패할 수 있습니다. 특히 서버 환경에 따라 ca-bundle 인증서 파일 경로가 달라서 curl이 SSL 검증에 실패하는 경우도 있습니다. curl_error()로 오류 메시지를 반드시 로그에 남기면 이런 경우도 추적할 수 있습니다.

Q. cron PHP 스크립트에서 외부 API 성공 여부를 판단하는 가장 안전한 방법은 무엇인가요?

A. error_code의 부재가 아니라 실제 필요한 데이터가 존재하는지를 직접 확인하는 방식이 가장 안전합니다. empty()로 access_token 같은 핵심 값을 체크하고, 값이 없으면 저장하지 않는 원칙을 지키는 것입니다. 제 경험상 “에러가 없다”는 것과 “원하는 데이터가 있다”는 것은 완전히 다른 조건입니다.

이번 일을 겪고 나서 외부 API를 사용하는 코드를 볼 때마다 curl 실패 처리가 있는지부터 확인하는 습관이 생겼습니다. 에러 처리가 없는 코드는 정상적인 상황에서는 완벽하게 작동하는 것처럼 보이지만, 딱 한 번 예외 상황이 생기면 조용히 데이터를 망가뜨립니다. cron처럼 사람이 직접 보지 않는 자동화 환경이라면 그 피해는 발견하기도 어렵습니다. 스크립트를 cron에 등록하기 전에 로그 설정과 단계별 검증 코드부터 확인해 보시기 바랍니다.

—
참고: https://velog.io/@freetercoder/CRON%EC%97%90%EC%84%9C-PHP-%EC%8B%A4%ED%96%89-%EC%95%88%EB%90%A8

Similar Posts