우분투 환경변수 설정 처리 cli php-fpm 한곳에서 사용

Ubuntu 서버에서 환경변수를 /etc/environment 한 곳에만 등록하고, PHP CLI와 PHP-FPM에서 모두 getenv()로 사용하는 방법을 정리합니다. 예시 변수명과 값은 모두 가상 데이터입니다.

1. 왜 CLI와 PHP-FPM 설정이 다른가요?

SSH로 로그인해 실행하는 PHP CLI는 일반적으로 로그인 세션의 환경변수를 상속받습니다. 반면 PHP-FPM은 systemd 서비스로 실행되므로, 로그인 세션과 관계없이 환경변수를 별도로 전달해야 합니다. 또한 PHP-FPM은 기본적으로 Worker 환경을 비우도록 설정되어 있습니다.

2. /etc/environment에 변수 등록

sudo nano /etc/environment

파일의 기존 설정은 유지하고 다음과 같은 예시를 추가합니다.

EXAMPLE_API_KEY="replace-with-your-key"
EXAMPLE_SERVICE_ID="replace-with-your-id"
EXAMPLE_OPTION="enabled"

• export를 붙이지 않습니다.
• 셸 스크립트가 아니므로 $(...) 실행이나 일반적인 셸 변수 확장을 기대하면 안 됩니다.
• 이 글의 EXAMPLE_* 이름과 값은 실제 서비스와 무관한 예시입니다.
• 설정값에 복잡한 인용부호나 역슬래시가 있다면 PAM과 systemd의 파싱 규칙 차이를 별도로 확인해야 합니다.

3. PHP CLI에서 확인

SSH 세션을 종료하고 다시 로그인한 다음 확인합니다. 기존 셸에는 변경 내용이 자동 반영되지 않습니다.

printenv EXAMPLE_API_KEY

php -r '$v = getenv("EXAMPLE_API_KEY"); echo ($v !== false && $v !== "") ? "OK\n" : "FAIL\n";'

특정 PHP 버전으로 확인하려면 설치된 명령어를 선택해 실행합니다.

php5.6 -r 'var_dump(getenv("EXAMPLE_API_KEY") !== false);'
php8.4 -r 'var_dump(getenv("EXAMPLE_API_KEY") !== false);'

주의: cron, systemd 타이머, 다른 서비스가 실행하는 CLI는 SSH 로그인 환경을 상속받지 않을 수 있습니다. 이 글의 CLI 절차는 일반적인 SSH 로그인 후 실행을 기준으로 합니다.

4. PHP-FPM 서비스에 파일 연결

먼저 서버에 설치된 PHP-FPM 서비스 이름을 확인합니다.

systemctl list-units --all --type=service 'php*-fpm.service'

예를 들어 PHP 8.4를 사용한다면 다음 명령어로 systemd override를 생성합니다.

sudo systemctl edit php8.4-fpm

편집기에 다음 두 줄을 추가합니다. 기존 서비스 파일을 직접 변경하지 않는 방식입니다.

[Service]
EnvironmentFile=/etc/environment

PHP 5.6도 사용 중이라면 sudo systemctl edit php5.6-fpm으로 같은 설정을 추가합니다. 실제 서비스명은 서버에 따라 다를 수 있습니다.

sudo systemctl cat php8.4-fpm

출력에 EnvironmentFile=/etc/environment가 포함되어 있으면 override 설정을 확인할 수 있습니다.

5. PHP-FPM Worker의 환경변수 상속 허용

서비스에 환경변수를 전달해도 PHP-FPM의 clear_env 기본 설정으로 인해 PHP Worker에서 보이지 않을 수 있습니다. 사용할 Pool의 설정 파일을 엽니다.

sudo nano /etc/php/8.4/fpm/pool.d/www.conf

해당 Pool에서 다음 설정을 적용합니다.

clear_env = no

PHP 5.6에서도 /etc/php/5.6/fpm/pool.d/www.conf 등 실제 Pool 파일에서 동일하게 설정합니다. Pool 이름이 www가 아니면 사용 중인 Pool 파일을 확인하세요.

6. 설정 검사와 서비스 재시작

PHP-FPM 버전에 맞게 설정 검사를 먼저 진행합니다.

sudo php-fpm8.4 -t

systemd override를 최초 등록하거나 변경했다면 다음 명령어를 실행합니다.

sudo systemctl daemon-reload

서비스를 재시작하여 새 환경변수를 읽습니다.

sudo systemctl restart php8.4-fpm
sudo systemctl status php8.4-fpm --no-pager

PHP 5.6 서비스를 사용한다면 위 명령어의 버전을 5.6으로 바꾸어 실행합니다. /etc/environment의 변수 값만 변경한 경우에는 daemon-reload 없이 PHP-FPM 재시작만 하면 됩니다.

7. PHP-FPM과 CLI에서 실제로 동작하는지 검증

다음 코드는 PHP 5.6과 PHP 8.4 양쪽에서 사용할 수 있습니다. CLI에서는 php로 실행하고, PHP-FPM은 인증된 관리자 경로에서 임시 PHP 검사 파일로 실행하여 결과를 비교합니다.

<?php
header('Content-Type: text/plain; charset=utf-8');

$keys = array(
    'EXAMPLE_API_KEY',
    'EXAMPLE_SERVICE_ID',
    'EXAMPLE_OPTION'
);

foreach ($keys as $key) {
    $value = getenv($key);
    echo $key . ': ' .
        ($value !== false && $value !== '' ? 'OK' : 'FAIL') .
        PHP_EOL;
}

EXAMPLE_API_KEY: OK
EXAMPLE_SERVICE_ID: OK
EXAMPLE_OPTION: OK

위 결과는 예시입니다. 웹에서 검사할 경우 파일을 외부에 공개하지 말고, 테스트가 끝나면 삭제해야 합니다. 실제 환경변수 값은 브라우저나 로그에 출력하지 않습니다.

8. 이후에는 /etc/environment만 수정

최초 설정이 완료되었다면 새로운 변수의 등록 위치는 계속 /etc/environment 하나입니다.

sudo nano /etc/environment

EXAMPLE_NEW_SETTING="replace-with-value"

변경한 값을 PHP-FPM에 반영하려면 해당 PHP-FPM 서비스를 다시 시작하고, SSH CLI에서는 새로 로그인합니다.

sudo systemctl restart php8.4-fpm

9. 운영 시 주의사항

• /etc/environment는 시스템 공통 설정으로, 비밀값 격리를 보장하지 않습니다. 모든 사용자에게 접근을 제한해야 하는 자격증명에는 별도 비밀 관리 방식을 고려하세요.
• 파일 권한을 무조건 600으로 바꾸면 일부 PAM 로그인 환경에서 정상 로드되지 않을 수 있습니다.
• 환경변수를 설정했다고 cron, systemd timer, PM2 등 별도 실행 주체에 자동 반영되는 것은 아닙니다.
• 환경변수 값을 직접 출력하는 printenv 명령은 로그 기록·화면 공유 시 노출에 주의하세요.

참고 문서

• systemd.exec - EnvironmentFile
• PHP 공식 문서 - FPM 설정