▶ 배포·공유

🖐 실무 따라하기 — 복붙해서 따라 하면 됩니다

1. 1정본(빌드) 만들기 — dev 말고 '검수된 결과물'을 굳힌다

   앱 폴더에서 개발용 실행을 멈추고, 배포용 최적화 빌드를 생성한다. dev 모드는 코드가 바뀔 때마다 다시 도는 '작업 중' 상태라 여러 명이 쓰기 부적합하다. build는 한 번 검수해 굳힌 '정본'을 만든다. 명령 앞의 폴더 경로만 본인 앱 경로로 바꾼다. (무설치 PC라면 이 단계를 건너뛰고 5단계 무설치 대안으로.)

   터미널 명령

   ⧉ 복사

   cd /home/gdi-s2/dev/aiedu
   npm run build
   
   # (무설치 대안) systemd·터널을 못 쓰는 청 내 PC라면, 빌드 후 아래로 로컬 정본만 띄워
   # 같은 망의 팀원이 http://<내PC_IP>:3999 로 접속하게 한다(포트 3999는 예시값):
   #   npm run start -- -p 3999

   → 결과 수십 초~2분 뒤 'Compiled successfully' 와 라우트 목록(예: ○ / , ƒ /api/explain)이 표로 출력되고 마지막에 에러 없이 프롬프트로 복귀한다. .next 폴더가 갱신되면 정본 완성. 빨간 'Failed to compile'이 뜨면 그 파일을 고친 뒤 다시 build.

2. 2비밀은 코드가 아니라 환경변수 파일로 — .env.local 주입

   API 키·관리자 비밀번호·세션 비밀키를 코드가 아니라 별도 파일에 넣고, 그 파일을 본인만 읽게 잠근다. 코드에 키를 박으면 공유·백업 과정에서 유출된다. 아래를 그대로 실행하되 값(합성 예시)만 실제 발급값으로 바꾼다. 도메인은 예시값 example.go.kr — 실제 기관 도메인은 승인 후 교체한다. 이 파일은 절대 깃/메일/메신저로 전송하지 않는다.

   터미널 명령

   ⧉ 복사

   cd /home/gdi-s2/dev/aiedu
   cp -n .env.example .env.local 2>/dev/null || true   # 예시 파일이 있으면만 복사
   
   # SESSION_SECRET용 긴 랜덤값을 먼저 만든다(아래 파일의 값과 교체):
   openssl rand -hex 32
   
   cat > .env.local <<'EOF'
   ANTHROPIC_API_KEY=sk-ant-실제발급키를여기에
   SESSION_SECRET=위_openssl_출력값으로_교체
   [email protected]
   ADMIN_PASSWORD=바꿀비밀번호
   ALLOWED_EMAIL_DOMAINS=example.go.kr
   EOF
   
   chmod 600 .env.local             # 본인만 읽기/쓰기
   ls -l .env.local

   → 결과 openssl 명령이 64자리 16진수 한 줄(예: 3b7e...9a1)을 출력 → 이 값을 SESSION_SECRET에 붙여넣는다. 마지막 ls 결과 권한이 '-rw-------'(600)이면 성공. ALLOWED_EMAIL_DOMAINS 덕분에 example.go.kr 메일만 가입/로그인 가능해진다(실제 도메인은 승인 후 교체).

3. 3상주 서비스로 등록 — 재부팅·크래시에도 24시간 자동 재기동(systemd)

   터미널을 닫으면 앱이 꺼지는 dev와 달리, systemd 사용자 서비스로 등록하면 로그아웃·재부팅·오류로 죽어도 자동으로 다시 켜진다. 아래 파일을 만들고 등록·시작한다. node 경로는 반드시 which node로 먼저 확인해 ExecStart에 반영한다(아래 경로는 예시). 포트 3999도 예시값이다.

   터미널 명령

   ⧉ 복사

   which node    # 출력된 절대경로를 아래 ExecStart의 node 경로에 그대로 사용
   
   mkdir -p ~/.config/systemd/user
   cat > ~/.config/systemd/user/minwon-web.service <<'EOF'
   [Unit]
   Description=Minwon reply helper (Next.js on :3999)
   After=network.target
   
   [Service]
   Type=simple
   WorkingDirectory=/home/gdi-s2/dev/aiedu
   EnvironmentFile=-/home/gdi-s2/dev/aiedu/.env.local
   Environment=NODE_ENV=production
   ExecStart=/usr/bin/node /home/gdi-s2/dev/aiedu/node_modules/next/dist/bin/next start -p 3999
   Restart=always
   RestartSec=5
   
   [Install]
   WantedBy=default.target
   EOF
   
   loginctl enable-linger $USER          # 로그아웃 후에도 계속 돌게
   systemctl --user daemon-reload
   systemctl --user enable --now minwon-web
   systemctl --user status minwon-web --no-pager
   curl -s -o /dev/null -w "%{http_code}
   " http://localhost:3999

   → 결과 status 출력에 초록색 'active (running)'이 보이고, 마지막 curl이 '200'을 출력하면 서비스가 상주 실행 중. 이제 터미널을 닫아도 http://localhost:3999 이 계속 응답한다. 죽여도 5초 뒤 자동 재기동(Restart=always). 'status=203/EXEC'가 뜨면 ExecStart의 node 경로가 틀린 것 — which node 결과로 고친다.

4. 4팀에 공개 + 접근통제 — 터널로 도메인 연결, 로그인으로 아무나 못 들어오게

   내부 3999 포트를 방화벽 구멍 없이 외부 도메인에 안전하게 연결(터널)하고, 앱 자체 로그인+허용 도메인으로 '정해진 사람만' 들어오게 막는다. 접근통제 없이 도메인만 열면 URL 아는 누구나 API 키를 대신 쓰게 된다. 아래 도메인 minwon.example.com은 예시값 — 실제 기관 도메인은 승인 후 교체하며, 실운영 중인 DNS/터널 네임스페이스는 절대 건드리지 않는다.

   터미널 명령

   ⧉ 복사

   # 터널 생성·도메인 연결 (cloudflared 로그인은 최초 1회: cloudflared tunnel login)
   cloudflared tunnel create minwon
   cloudflared tunnel route dns minwon minwon.example.com   # 예시 도메인
   
   # 위 create 출력의 Tunnel ID(UUID)를 확인:
   cloudflared tunnel list
   
   # 설정파일 작성(<UUID>를 방금 확인한 값으로 교체):
   cat > ~/.cloudflared/minwon.yml <<'EOF'
   tunnel: <UUID>
   credentials-file: /home/gdi-s2/.cloudflared/<UUID>.json
   ingress:
     - hostname: minwon.example.com
       service: http://localhost:3999
     - service: http_status:404
   EOF
   
   cloudflared --no-autoupdate tunnel --config ~/.cloudflared/minwon.yml run <UUID>
   
   # (무설치 대안) 터널을 못 쓰면 공개하지 말고 같은 사내망에서만: 팀원은 http://<내PC_IP>:3999 접속.
   # 접근통제는 앱 로그인(ADMIN_EMAIL/PASSWORD로 로그인 → 팀원은 example.go.kr 메일로 가입)으로 유지된다.

   → 결과 터널 로그가 'Registered tunnel connection ... connIndex=0~3' 4줄을 찍으면 연결 완료. 브라우저에서 https://minwon.example.com 접속 시 앱 로그인 화면이 뜨고, example.go.kr 이외 메일은 가입이 거부된다(ALLOWED_EMAIL_DOMAINS). 로그인해야 답변 생성 기능이 열린다 = 접근통제 확인. (실제 도메인은 기관 승인 후 교체.)

5. 5서버측 PII 재검증 — 주민번호는 차단, 전화는 마스킹해 통과

   클라이언트(브라우저) 검사는 우회 가능하므로, 서버가 외부 AI API로 보내기 직전 개인정보를 한 번 더 잡는다. 이때 (1) 주민번호는 즉시 차단(400)하고, (2) 전화번호는 차단 대신 [전화]로 마스킹해 통과시킨다 — 실습 표준 합성 전화 '010-0000-0000'이 든 정상 요청까지 400으로 거부되는 오작동을 막기 위해서다. 날짜(2026-07-07)·접수번호(MW-2026-0001) 같은 하이픈 숫자열은 절대 걸리지 않도록 계좌·일반 숫자열 광역 패턴은 아예 쓰지 않는다. 아래 최소 코드를 API 라우트 맨 앞에 넣는다. (무설치 대안 — 코드 수정이 어렵다면) ChatGPT·Claude 웹 또는 이 플랫폼 /playground에 아래 '시스템 프롬프트'를 붙여넣어 같은 재검증을 사람이 아닌 모델에게 시킨다: 『너는 민원 답변 도우미의 안전필터다. 사용자 입력에 주민등록번호(6자리-7자리)가 있으면 답변을 생성하지 말고 "개인정보가 포함되어 처리할 수 없습니다"만 출력하라. 전화번호(010-xxxx-xxxx)가 있으면 [전화]로 가린 뒤 답변하라. 접수번호(MW-YYYY-NNNN)와 날짜(YYYY-MM-DD)는 개인정보가 아니므로 그대로 둔다.』

   코드

   ⧉ 복사

   // app/api/explain/route.ts 등 사용자 입력을 받는 API 핸들러 맨 앞에 추가
   // 주민번호 = 차단(400). 전화번호 = 마스킹 후 통과. 날짜/접수번호는 매칭하지 않음.
   const RRN = /(?<!\d)\d{6}-[1-4]\d{6}(?!\d)/;              // 주민번호: 880101-1234567
   const PHONE = /(?<!\d)01[016-9]-?\d{3,4}-?\d{4}(?!\d)/g;   // 휴대전화: 010-0000-0000
   
   function guardPII(text: string): { blocked?: Response; clean: string } {
     if (RRN.test(text)) {
       return {
         blocked: Response.json(
           { error: "주민등록번호 등 민감 개인정보가 포함되어 처리할 수 없습니다. 홍길동 / 010-0000-0000 처럼 가상값으로 바꿔 주세요." },
           { status: 400 }
         ),
         clean: text,
       };
     }
     // 전화번호는 차단하지 않고 [전화]로 마스킹해 외부 API로 보낸다
     return { clean: text.replace(PHONE, "[전화]") };
   }
   
   // 핸들러 안에서:
   //   const { blocked, clean } = guardPII(userInput);
   //   if (blocked) return blocked;
   //   // 이후 clean(마스킹된 텍스트)만 Anthropic API로 전송

   → 결과 저장 후 step1의 build를 다시 돌리고 systemctl --user restart minwon-web. 이제: (1) '880101-1234567' 입력은 400 에러+안내 문구로 차단된다. (2) '홍길동 010-0000-0000 민원 답변 써줘'는 서버가 전화만 [전화]로 가린 뒤 정상 생성한다(차단 아님). (3) 반례 검증 — '접수 2026-07-07 MW-2026-0001 관련 답변'처럼 날짜·접수번호만 든 입력은 아무것도 안 걸리고 정상 통과한다. 세 가지가 모두 맞으면 재검증 로직 완성.

6. 6롤백 안전망 확인 — 되돌릴 수 있어야 '공표'다

   배포는 되돌릴 수 있을 때만 안전하다. 새 빌드를 넣기 전 직전 정본을 보관하고, 문제가 생기면 한 줄로 되돌리는 절차를 실제로 한 번 연습해 둔다. (IT담당 작업 — 무설치 담당자는 5단계 무설치 대안까지만 따라오면 된다.)

   터미널 명령

   ⧉ 복사

   # (1) 새로 빌드하기 전, 현재 잘 도는 정본을 백업
   cp -r /home/gdi-s2/dev/aiedu/.next /home/gdi-s2/dev/aiedu/.next.bak
   
   # (2) 새 빌드 후 문제가 생기면 → 즉시 롤백:
   rm -rf /home/gdi-s2/dev/aiedu/.next
   mv /home/gdi-s2/dev/aiedu/.next.bak /home/gdi-s2/dev/aiedu/.next
   systemctl --user restart minwon-web
   curl -s -o /dev/null -w "%{http_code}
   " http://localhost:3999
   
   # (3) 모니터링: 상태와 최근 로그로 오류 감시
   systemctl --user status minwon-web --no-pager
   journalctl --user -u minwon-web -n 30 --no-pager

   → 결과 롤백 후 curl이 다시 '200'을 반환하면 직전 정본으로 정상 복귀. journalctl 로그에 500/에러가 없고 정상 요청만 보이면 안정. 이 롤백을 미리 한 번 연습해 두면 실제 사고 때 30초 내 원복 가능 = '되돌릴 수 있는 배포' 완성.