파이썬으로 API 서버나 자동화 프로그램을 만들다 보면 API 키, 데이터베이스 비밀번호, 텔레그램 토큰처럼 외부에 공개해서는 안 되는 정보를 사용하게 됩니다.
초보 단계에서는 이러한 값을 코드에 직접 입력하기 쉽습니다.
예를 들어 다음과 같은 코드입니다.
API_KEY="my-secret-api-key"
개인 PC에서 잠깐 테스트할 때는 큰 문제가 없어 보일 수 있습니다. 하지만 코드를 GitHub에 올리거나 다른 사람에게 전달하는 순간 API 키까지 함께 공개될 수 있습니다.
이러한 문제를 줄이기 위해 많이 사용하는 방법이 환경변수와 .env 파일입니다.
환경변수란 무엇인가?
환경변수는 프로그램 코드와 설정값을 분리하기 위한 방법 중 하나입니다.
예를 들어 다음 정보는 프로그램의 기능 자체와는 관계가 없습니다.
API KEYDB PASSWORDTELEGRAM TOKENSECRET KEYSERVER ADDRESS
개발 환경과 실제 운영 서버에서 값이 서로 다를 수도 있습니다.
따라서 이러한 값을 파이썬 코드에 직접 작성하기보다 외부 환경에서 읽어오도록 구성하면 관리하기 편합니다.
python-dotenv 설치하기
.env 파일을 쉽게 읽기 위해 python-dotenv 라이브러리를 사용할 수 있습니다.
pip install python-dotenv
설치 후 프로젝트 폴더에 .env 파일을 생성합니다.
예를 들어 다음과 같습니다.
API_KEY=test_api_keyDB_PASSWORD=my_passwordTELEGRAM_TOKEN=my_token
따옴표가 반드시 필요한 것은 아니며 값의 형태에 따라 적절하게 작성하면 됩니다.
파이썬에서 .env 값 읽기
다음 코드를 작성합니다.
importosfromdotenvimportload_dotenvload_dotenv()api_key=os.getenv("API_KEY")print(api_key)
load_dotenv()가 .env 파일을 불러오고 os.getenv()를 이용해 원하는 값을 읽습니다.
데이터베이스 설정에서도 비슷하게 활용할 수 있습니다.
db_password=os.getenv("DB_PASSWORD")
텔레그램 봇을 운영한다면 다음처럼 사용할 수 있습니다.
telegram_token=os.getenv("TELEGRAM_TOKEN")
API 키를 코드에서 분리해야 하는 이유
가장 큰 이유는 보안입니다.
Git 저장소에는 프로그램의 변경 이력이 남습니다.
현재 코드에서 API 키를 삭제했다고 하더라도 과거 커밋에 값이 남아 있을 가능성이 있습니다.
따라서 한 번 외부 저장소에 노출된 API 키는 단순히 코드에서 지우는 것보다 해당 키를 폐기하고 새 키를 발급하는 것이 안전합니다.
또 다른 이유는 환경별 설정 관리입니다.
개발 PC에서는 테스트 데이터베이스를 사용하고 실제 서버에서는 운영 데이터베이스를 사용할 수 있습니다.
코드는 동일하게 유지하면서 환경변수만 다르게 설정하면 관리가 쉬워집니다.
.gitignore에 .env 추가하기
.env 파일을 만들었다면 Git 저장소에 업로드되지 않도록 설정해야 합니다.
프로젝트 폴더의 .gitignore 파일에 다음 내용을 추가합니다.
.env
필요하다면 다음 항목도 함께 관리할 수 있습니다.
.envvenv/__pycache__/*.log
그리고 Git 상태를 확인합니다.
git status
.env가 추적 대상에 나타나지 않는지 확인하는 습관을 들이는 것이 좋습니다.
이미 Git에 등록했다면?
.gitignore에 추가했다고 해서 이미 Git이 추적하고 있는 파일이 자동으로 제거되는 것은 아닙니다.
상황에 따라 Git 추적에서 파일을 제외하는 별도의 처리가 필요합니다.
무엇보다 API 키가 외부 저장소에 실제로 공개된 적이 있다면 해당 키를 더 이상 안전하다고 가정해서는 안 됩니다.
서비스 관리 페이지에서 기존 키를 폐기하고 새로운 키를 발급하는 것이 좋습니다.
값이 없는 경우 처리하기
환경변수가 존재하지 않으면 os.getenv()는 기본적으로 None을 반환할 수 있습니다.
중요한 설정값이라면 프로그램 시작 시 확인하도록 만들 수 있습니다.
api_key=os.getenv("API_KEY")ifnotapi_key:raiseValueError("API_KEY 환경변수가 설정되지 않았습니다.")
이렇게 하면 API 호출 과정에서 이상한 오류가 발생하는 것보다 프로그램 실행 초기에 문제를 발견할 수 있습니다.
기본값 설정하기
보안과 무관한 설정은 기본값을 지정할 수도 있습니다.
port=os.getenv("PORT", "8000")
PORT 환경변수가 존재하지 않으면 "8000"을 사용합니다.
개발 환경에서 편리한 방법입니다.
단 비밀번호나 API 키와 같은 민감한 값에 실제 비밀값을 기본값으로 작성하는 것은 피하는 것이 좋습니다.
FastAPI에서도 활용 가능하다
FastAPI 서버에서도 환경변수를 사용할 수 있습니다.
fromfastapiimportFastAPIimportosfromdotenvimportload_dotenvload_dotenv()app=FastAPI()@app.get("/")defhome():mode=os.getenv("APP_MODE", "development")return {"mode": mode}
개발 서버와 운영 서버의 설정을 구분할 때 유용합니다.
Ubuntu 서버에서는 어떻게 관리할까?
개발 단계에서는 .env가 편리하지만 서버 환경에서는 시스템 환경변수나 서비스 관리자 설정을 이용할 수도 있습니다.
특히 systemd로 파이썬 프로그램을 실행한다면 서비스 설정과 환경 파일을 분리하는 방법도 있습니다.
중요한 것은 비밀정보를 소스코드에 직접 넣지 않는 것입니다.
또한 .env 파일을 사용하더라도 서버에 로그인할 수 있는 모든 사용자가 파일을 읽을 수 있도록 두는 것은 바람직하지 않습니다.
Linux 파일 권한도 함께 관리해야 합니다.
실수로 API 키가 공개되는 대표 사례
첫 번째는 GitHub에 .env를 함께 업로드하는 경우입니다.
두 번째는 오류 로그에 API 키 전체를 출력하는 경우입니다.
세 번째는 블로그나 질문 게시판에 코드 전체를 복사하면서 실제 인증정보까지 올리는 경우입니다.
따라서 디버깅 과정에서도 다음과 같은 코드는 주의해야 합니다.
print(API_KEY)
실제 운영환경에서는 비밀정보를 로그에 남기지 않는 것이 좋습니다.
.env 파일도 완벽한 보안 방법은 아니다
.env를 사용한다고 해서 보안 문제가 자동으로 해결되는 것은 아닙니다.
.env 자체도 결국 파일이기 때문에 서버가 침해되거나 파일 권한이 잘못 설정되어 있다면 내용이 유출될 수 있습니다.
따라서 중요한 시스템에서는 비밀정보 관리 서비스나 클라우드 사업자가 제공하는 Secret 관리 기능을 검토할 수도 있습니다.
.env는 특히 개인 프로젝트와 소규모 개발 환경에서 코드와 설정을 분리하는 기본 습관을 배우기에 좋은 방법이라고 이해하면 됩니다.
자주 묻는 질문
.env 파일을 GitHub에 올려도 되나요?
API 키나 비밀번호가 포함되어 있다면 올리지 않는 것이 원칙입니다. .gitignore에 추가해 저장소에서 제외하는 것이 좋습니다.
.env 파일 이름을 다른 이름으로 바꿀 수 있나요?
가능합니다. 프로젝트 구조와 라이브러리 설정에 맞춰 별도의 환경 파일을 사용할 수 있습니다.
API 키가 한 번 노출되었다면 다시 숨기면 괜찮나요?
노출 가능성이 있었다면 해당 키를 폐기하고 새로 발급하는 것이 안전합니다.
마무리
파이썬 자동화 프로그램을 직접 서버에서 운영하기 시작하면 API 키 관리가 반드시 필요해집니다.
처음에는 코드와 설정을 분리하는 것이 번거롭게 느껴질 수 있지만 프로젝트 규모가 커질수록 환경변수를 사용하는 편이 훨씬 관리하기 쉽습니다.
특히 GitHub를 이용한다면 .env와 .gitignore 사용법은 초기에 익혀두는 것이 좋습니다.
자동화 프로그램을 오래 운영하려면 기능 구현뿐 아니라 인증정보 관리, 로그 관리, 서버 권한 같은 기본적인 보안 습관도 함께 갖춰야 합니다.