AI 드리븐

지도 위치 : 3일차 · 신뢰와 운영 · 로컬에서 원격으로 | 이전: 20차시 자동화 파이프라인 ② | 다음: 22차시 배포 ② 서비스 완성 키워드 : 서버를 인터넷에 배포, 비밀값의 안전한 관리, 배포 검증

이 차시를 다 읽으면

1. 배포 를 유와 종차로 정의하고, 로컬과 배포 환경에서 달라지는 것 네 가지를 ④ 로컬 ↔ 원격 축으로 댈 수 있다.
2. 코드가 인터넷에서 응답하기까지의 단계를 컨테이너 이미지 · PaaS 를 써서 순서대로 말할 수 있다.
3. 비밀값 주입 을 정의하고, 이미지에 비밀값을 넣으면 왜 위험한지 설명할 수 있다.
4. "배포 명령 성공"과 "서비스 정상"을 증거 ↔ 주장 축으로 가르고, 스모크 테스트 를 포함한 배포 검증 다섯 가지를 댈 수 있다.
5. 롤백 을 정의하고, 18차시의 revert와 무엇이 다른지, 왜 DB 마이그레이션은 쉽게 되돌아가지 않는지 말할 수 있다.

---

0. 이 차시의 판별 축

이 차시가 답하는 질문은 "로컬에선 됐는데"가 가장 많이 나오는 단계를 어떻게 넘는가 입니다. 앞에서 배운 인프라 설정의 원칙 (15차시)과 비밀값 원칙 (14차시)이 처음으로 다른 컴퓨터 위에서 시험받습니다.

---

1. 배포 — 무엇에 속하는가

1.1 정의

배포 (deployment) — [소프트웨어 전달 단계]인데, [ 만든 프로그램을 다른 사람이 쓸 수 있는 원격 환경에 올려 실행시킨다 ]는 점에서 내 컴퓨터에서 돌려 보는 로컬 실행과 구별된다.

스테이징 (staging) — [배포 환경]인데, [ 운영과 같은 구성이지만 실제 사용자 · 실제 돈이 없는 시험장 ]이라는 점에서 실제 사용자가 쓰는 운영(production)과 구별된다.

환경변수 — 앞에서 배운 대로 (15차시), 프로그램이 실행될 때 바깥에서 받아 읽는 이름 = 값 설정 입니다. DB 주소나 키처럼 환경마다 다른 값을 코드 밖에 두는 통로입니다.

1.2 경계 — 로컬과 배포 환경에서 달라지는 것

⚠️ "로컬에선 됐는데"의 원인은 거의 이 네 줄 중 하나입니다. 19차시의 CI가 "깨끗한 환경"으로 일부를 미리 걸러 주지만, 실제 주소 · 실제 DB · 실제 비밀값은 배포해야 처음 만납니다.

1.3 반례 — 이건 배포가 아닙니다

---

2. 서버를 인터넷에 올리는 흐름

2.1 흐름

코드 ─▶ 빌드 ─▶ 컨테이너 이미지 ─▶ 실행 플랫폼에 올림 ─▶ 주소 연결(도메인, HTTPS)
                 (Dockerfile, 15차시)       │
                                          ├─ 환경변수 · 비밀값 주입   (3절)
                                          ├─ DB 연결 (관리형 DB, 8차시)
                                          └─ 마이그레이션 실행 (12차시) (5.2절)

🔍 읽는 포인트 : 가운데의 컨테이너 이미지 가 "옮길 수 있는 덩어리"이고, 오른쪽 세 갈래가 배포 환경에서만 채워지는 것 입니다.

컨테이너 이미지 — [실행 꾸러미]인데, [ 프로그램과 그 실행 환경(언어 버전 · 라이브러리)을 한 파일로 묶어 어느 컴퓨터에서나 같게 돌게 한다 ]는 점에서 소스 코드만 담은 저장소와 구별된다. 앞에서 배운 Dockerfile (15차시)이 이 이미지를 만드는 설계도입니다.

2.2 실행 플랫폼

PaaS (Platform as a Service) — [실행 플랫폼]인데, [ 이미지나 코드만 주면 서버 관리 · HTTPS · 재시작을 플랫폼이 맡는다 ]는 점에서 운영체제부터 내가 관리하는 가상 서버와 구별된다.

(서비스별 기능과 가격은 바뀌므로 공식 문서 확인.)

배포 순서 : 스테이징에 먼저 → 확인(4절) → 운영. 운영 배포는 앞 차시에서 정한 대로 사람 승인 (20차시)입니다.

---

3. ⭐ 비밀값의 안전한 관리

3.1 정의와 경계

비밀값 주입 — [설정 전달 방식]인데, [ 비밀값을 코드와 이미지 밖에 두고, 프로그램을 실행하는 순간에만 환경변수로 넣는다 ]는 점에서 이미지나 설정 파일에 구워 넣는 방식과 구별된다.

앞에서 배운 비밀값 원칙 (14차시)을 배포 환경으로 확장합니다. 배포 순간 비밀값이 처음으로 다른 컴퓨터 에 넘어갑니다. 넘기는 방법이 잘못되면 유출됩니다.

❌ 코드에 직접               const key = "sk_live_abc..."
❌ Git에 올린 설정 파일        config.prod.json 안에 키
❌ 컨테이너 이미지 안          Dockerfile에서 ENV로 키를 박음
⭕ 플랫폼 비밀값 설정          실행할 때 환경변수로 주입
⭕ 비밀값 관리 서비스          AWS Secrets Manager, GCP Secret Manager 등에서 읽음
⭕ CI 비밀값                 GitHub Secrets → 배포 단계에서만 사용

🔍 읽는 포인트 : ❌ 세 줄은 비밀값이 파일 안에 영구히 남는 방식, ⭕ 세 줄은 실행할 때만 건네는 방식입니다. 0절 축 2가 이 경계입니다.

⚠️ 이미지 안의 비밀값이 특히 위험한 이유 : 이미지는 옮기고 나누기 위한 파일입니다. 이미지에 넣은 환경변수는 docker inspect 같은 명령으로 이미지를 받은 누구나 꺼내 볼 수 있습니다. 앞에서 배운 대로 (18차시) Git 이력에 남은 키처럼, 한번 퍼진 이미지에서 키를 지울 방법은 없고 키 교체 만 남습니다.

3.2 네 가지 원칙

3.3 비밀값 등록은 내가 직접

README 9.2의 "내가 직접 (위임 불가)" 첫 줄에 있는 일입니다. AI에게는 필요한 환경변수의 이름 목록 만 받고, 실제 값은 내가 플랫폼 설정 화면에 직접 붙여 넣습니다. 키를 AI와의 대화에 붙여 넣으면 대화 기록에 남습니다. 대화 기록도 0절 축 2의 왼쪽(영구히 남는 곳)입니다.

---

4. ⭐ 배포 검증 — 명령 성공 ≠ 서비스 정상

4.1 정의

헬스체크 (health check) — [상태 확인 주소]인데, [ 서버가 스스로 "살아 있고 DB에 연결됐다"를 알려 주는 전용 응답 ]이라는 점에서 실제 기능을 호출하는 API와 구별된다.

스모크 테스트 (smoke test) — [배포 후 검증]인데, [ 핵심 기능 몇 개만 빠르게 호출해 "켜졌고 기본 동작은 한다"를 확인한다 ]는 점에서 모든 규칙을 확인하는 전체 테스트(17차시)와 구별된다. 이름은 "전원을 넣었을 때 연기가 나는지 본다"는 데서 왔습니다.

4.2 배포가 끝났다고 말하려면

🔍 읽는 포인트 : curl 줄은 주소(/health)와 기대 응답("ok", "connected")만 보면 됩니다. 앞에서 배운 상태 코드 (4차시)대로 200은 성공, 401은 "로그인 필요"입니다.

⭐ 이 표의 대부분은 코드 없이 할 수 있습니다. /health 주소를 브라우저로 열기, 자물쇠 확인, 클래스 목록 보기. "배포 성공"이라는 에이전트의 말(주장) 대신 이 다섯 줄(증거)로 끝을 판정합니다.

스모크 테스트를 스크립트로 만들어 두면 배포마다 같은 확인을 반복할 수 있습니다.

앞으로 다시 만납니다 — 22차시에서 이 스모크 스크립트를 자동 배포 흐름의 한 단계 로 넣고, 그 뒤에 E2E 테스트를 붙입니다.

---

5. 롤백 준비

5.1 정의와 경계

롤백 (rollback) — [되돌리기]인데, [ 배포된 서비스를 이전 버전의 실행본으로 바꿔 놓는다 ]는 점에서 코드 이력에 취소 커밋을 덧붙이는 git revert(18차시)와 구별된다.

롤백 방법은 배포 전에 알아 둡니다. 대부분의 PaaS에는 이전 배포로 되돌리는 기능이 있습니다(위치와 이름은 플랫폼마다 다르니 공식 문서 확인).

5.2 ⚠️ 반례 — 롤백으로 돌아오지 않는 것

0절 축 4의 오른쪽입니다. DB 마이그레이션은 코드처럼 쉽게 되돌아가지 않습니다. 코드를 이전 버전으로 돌려도 DB의 구조 변경과, 그 사이 들어온 데이터는 그대로입니다. 열을 지우는 마이그레이션이었다면 지워진 데이터는 돌아오지 않습니다(앞에서 배운 파괴적 마이그레이션, 12차시).

그래서 파괴적 마이그레이션은 코드 배포와 분리해서 , 별도 단계로 신중하게 합니다. 순서의 원칙은 "먼저 더하고, 나중에 지운다"입니다. 새 열을 추가하는 배포와 옛 열을 지우는 배포를 나누면, 첫 배포는 롤백해도 데이터가 다치지 않습니다.

5.3 대시보드의 세 자리를 미리 찾아 두기

장애가 나면(23차시) 코드를 고칠 시간이 없습니다. 배포 플랫폼 화면에서 아래 세 곳이 비상 장비 입니다.

⚠️ 스테이징에서 롤백 버튼을 한 번 실제로 눌러 보세요. 처음 누르는 날이 장애 날이면 안 됩니다.

💡 비유는 마지막에 — 배포는 이삿짐 옮기기 입니다. 이미지는 짐을 싼 상자, 비밀값은 상자에 넣지 않고 새집 문 앞에서 직접 건네는 열쇠 , 스모크 테스트는 이사 직후 전기 · 수도 · 가스가 들어오는지 확인하는 것, 롤백은 원래 집 열쇠를 아직 반납하지 않은 상태 입니다.

---

6. 클래스온에 적용하면

---

7. 실습 — 맡기고 검수하기

지시

결정 기록(ADR-0003)에 따라 apps/api를 스테이징 환경에 배포할 설정을 만들어줘.
- 필요한 환경변수 목록을 표로 정리하되, 값은 넣지 마 (내가 플랫폼에 직접 등록할 것).
  표 형식: | 이름 | 무엇에 쓰나 | 비밀값인가(예/아니오) | 스테이징과 운영이 달라야 하나 |
- Dockerfile에 비밀값이 들어가지 않았음을 확인하고, 확인한 방법을 적어줘.
- 배포 후 실행할 스모크 테스트를 scripts/smoke.sh로 만들어줘. 각 확인마다 [확인 | 기대 | 실제 | 통과/실패] 한 줄씩 출력하게.
- 실제 배포 명령은 실행하지 마. 내가 실행할 명령만 알려줘.
배포는 내가 한 뒤에 알려 줄 테니, 그때 스모크 테스트를 돌리고 출력 원문을 그대로 붙여.

🔍 읽는 포인트 : "값은 넣지 마", "실제 배포 명령은 실행하지 마"가 되돌리기 어려운 일은 사람이 라는 원칙(20차시 3절)을 지시로 옮긴 것입니다.

받을 증거

• 환경변수 이름 목록 표 (값 없음)
• Dockerfile에 비밀값이 없다는 확인 방법과 결과
• 배포 후 smoke.sh 실행 출력 원문 (한 줄씩 통과 / 실패)
• 내가 실행할 배포 명령과, 그 플랫폼의 롤백 방법 (화면 위치)

내가 직접 확인할 것

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 21차시 노트만 근거로 5문제를 내줘. 비전공자 기준으로.
"구워 넣기와 실행 시 주입의 차이", "배포 명령 성공과 서비스 정상의 차이", "롤백과 git revert의 차이"는 반드시 포함해줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.