환경변수 설정하기
API 키 · DB 주소 같은 설정값을 코드 밖에 안전하게 두고, 콘솔 · CLI로 넣고 코드에서 이름으로 읽는 방법이에요.
API 키나 DB 주소처럼 코드에 박으면 안 되는 설정값을 두는 곳이 환경변수예요. 이 문서에서 콘솔 · CLI로 값을 넣고, 코드에서 이름으로 읽는 것까지 해요.
왜 코드 밖에 두나요
값이 코드에 있으면 git 기록에 영원히 남고, 저장소를 보는 모든 사람에게 노출돼요. 환경변수로 두면 AxHub가 값을 암호화해서 저장했다가 빌드하거나 앱을 실행할 때 넣어 줘요 — 코드에는 process.env.DATABASE_URL처럼 이름만 남아요.
준비물
- AxHub에 만들어 둔 앱 — 환경변수는 앱 단위로 저장돼요
- (터미널로 넣으려면) CLI 로그인 —
axhub로 시작하는 명령어 도구예요
콘솔에서 넣기
앱 콘솔 → 리소스 탭 → 환경변수 → 변수 추가. 네 가지를 정해요.
| 칸 | 무엇을 정하나요 |
|---|---|
| Key | 코드에서 부를 이름 (예: OPENAI_API_KEY) |
| Value | 실제 값 |
| Stage | 언제 넣어 줄지 — Runtime · Build · Both |
| Secret | 값을 가릴지 여부. 기본으로 켜져 있어요 |
환경변수를 추가하거나 바꾸면 다시 배포해야 적용돼요 — 실행 중인 앱에 자동으로 반영되지는 않아요.
이름 규칙 — Key는 대문자로 시작하고 영문 대문자 · 숫자 · 밑줄(_)만 써요 — 패턴 ^[A-Z][A-Z0-9_]*$. 패턴이 낯설면 아래 예시만 봐도 돼요.
DATABASE_URL OPENAI_API_KEY NEXT_PUBLIC_API_URL ✅
databaseUrl 1ST_KEY MY-KEY ❌AXHUB_로 시작하는 이름은 쓸 수 없어요 — AxHub가 직접 넣어 주는 값의 자리라서예요.
Stage — 같은 값이라도 어느 시점에 앱에 들어갈지 정해요. 코드를 실행 가능한 형태로 조립하는 빌드 때 필요한 값이 있고, 앱이 실제로 돌 때 필요한 값이 따로 있어서예요.
| Stage | 언제 넣어 주나요 | 예시 |
|---|---|---|
| Runtime (기본) | 실행 중인 앱에만 — 빌드 때는 없어요 | DB 비밀번호, 외부 API 키 |
| Build | 빌드할 때만 — 실행 때는 없어요 | 빌드에만 필요한 토큰 |
| Both | 빌드와 실행 양쪽 모두 | 양쪽에서 다 필요할 때 |
Runtime전용 값은 빌드 로그나 이미지에 남지 않아요 — 비밀값은Runtime으로 두는 게 안전해요.- 이름이
NEXT_PUBLIC_·VITE_·PUBLIC_으로 시작하는 값은 프론트엔드 번들에 담겨 브라우저에 그대로 노출돼요. 비밀값을 이런 이름으로 두면 안 돼요.
Secret — 켜 두면 값이 암호화돼 저장되고, 목록 · 응답에서 ***로 가려져요. 대신 나중에 값을 고칠 때 화면에 채워지지 않아 다시 입력해야 해요. 가릴 필요가 없는 값(공개 API 주소 같은 것)은 꺼 두면 목록에서 바로 확인하고 고칠 수 있어요.
Key는 만든 뒤에 바꿀 수 없어요. 값 · Stage · Secret만 고칠 수 있고, 이름을 바꾸려면 지우고 새로 만들어요.
앱 소유자가 열람 정책으로 잠가 둔 앱이라면, 관리자라도 콘솔에서 환경변수 값 열람이 제한될 수 있어요.
CLI로 넣기
터미널에서 쓰는 명령은 이래요.
# 가려야 하는 값 — 값을 stdin 으로 받아 명령 기록에 안 남게
axhub env set DATABASE_URL --app demo --secret --stage runtime --from-stdin
# 가릴 필요 없는 값 — KEY VALUE 를 그대로
axhub env set NEXT_PUBLIC_API_URL https://api.example.com --app demo --plain --stage buildaxhub env list --app demo
axhub env get DATABASE_URL --app demo
axhub env update DATABASE_URL 새값 --app demo --stage runtime
axhub env delete DATABASE_URL --app demo--secret을 쓰면 값을 명령줄에 적을 수 없고 --from-stdin으로만 넣어요. 명령 히스토리 · 로그에 비밀값이 남지 않게 하려는 거예요.
스테이징(시험용) 환경에서만 다른 값을 쓰고 싶으면 axhub env set-staging-value로 그 환경 전용 값을 따로 둬요. 단 Build 스테이지 값에는 쓸 수 없어요 — 빌드로 만든 결과물은 운영과 스테이징이 같은 것을 쓰기 때문이에요.
화면만 있는 앱(정적 호스팅)에는 환경변수를 넣을 수 없어요. 계속 돌고 있는 서버가 없어서 값을 넣을 자리가 없거든요 — 앱 콘솔에도 리소스 탭이 나오지 않아요.
코드에서 읽기
코드에서는 이름으로만 읽어요 — node라면 process.env.OPENAI_API_KEY처럼요. 실제 값은 코드 어디에도 남지 않아요.
앱이 어떤 환경변수를 필요로 하는지는 저장소의 axhub.yaml(manifest)에 이름과 stage만 선언해 둘 수 있어요. 값은 절대 넣지 않아요.
env:
required:
- name: DATABASE_URL
scope: runtime
- name: NEXT_PUBLIC_API_URL
scope: buildmanifest의 scope가 콘솔 · CLI의 Stage와 같은 뜻이에요(build · runtime · both).
이렇게 보이면 성공
axhub env list --app <앱>(또는 앱 콘솔의 리소스 탭 → 환경변수)에 넣은 키가 보이고, 다시 배포한 앱이 그 값을 읽어 동작하면 성공이에요.
다음은 SDK 설치하기에서 앱 코드에 AxHub 기능을 붙이기 시작해요.