운영 설정으로 띄운 포털 백엔드가 준비되지 않는다

목표

진짜 Backstage 백엔드를 운영처럼 띄웁니다. 설정 파일 두 개를 --config 로 겹치고, 비밀은 환경변수로 넣고,
브라우저 화면이 부를 수 있게 CORS 를 열고, 재시작해도 데이터가 남게 DB 를 옮깁니다. 판정은 파일이 아니라
떠 있는 프로세스의 동작(듣는 포트, 준비 상태, 401/200, 응답 헤더, 재시작 뒤 남은 데이터)으로 합니다.

왜 중요한가

로컬에서는 되던 백엔드가 운영에 올리면 엉뚱한 포트에서 듣거나, 떠 있는데 준비가 안 되거나, 화면에서만 API 호출이
막히거나, 재시작할 때마다 등록한 것이 사라집니다. 원인은 대부분 코드가 아니라 **설정이 겹치는 순서, 빠진 환경변수,
출처가 다른 클라이언트와 서버, 메모리 DB** 입니다. 병합 규칙을 머리로 아는 것과, 떠 있는 프로세스에서 그 결과를
재어 보는 것은 다릅니다.

처음 VM 이 뜨는 데 4분쯤 걸리고, 1단계 설치는 인터넷에서 약 30초 걸립니다. 이 VM 에는 docker·podman 이 없어
컨테이너 이미지 빌드는 하지 않습니다(command -v docker 가 비어 있습니다). 프런트엔드 앱도 빌드하지 않고,
브라우저 대신 Origin 헤더를 붙인 curl 로 CORS 응답을 확인합니다.

단계

1. /usr/local/cba-prod 에 백엔드 패키지를 고정 버전으로 설치합니다.
2. 기본·운영 설정 두 파일을 --config 로 겹쳐 띄우고, 순서를 뒤집으면 무엇이 달라지는지 봅니다.
3. ${PORTAL_API_TOKEN} 없이 뜬 백엔드가 준비되지 않는 것을 보고, 비밀을 환경변수로 넣습니다.
4. backend.cors.origin 으로 포털 화면의 출처만 허용합니다.
5. APP_CONFIG_ 환경변수로 파일을 고치지 않고 허용 출처를 넓힙니다.
6. :memory: DB 에서 재시작하면 등록한 location 이 사라지는 것을 기록합니다.
7. DB 를 디렉터리로 옮겨 재시작 뒤에도 남게 합니다.
8. 지금 프로세스에서 잰 값으로 운영 설정 점검표를 씁니다.

참고

• 운영 포트는 7300 입니다. 준비 확인: curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:7300/.backstage/health/v1/readiness
• 로그는 /usr/local/cba-prod/backend.log 에 이어 씁니다. 기동마다 Loading config from 줄로 시작하고, NODE_ENV=production 이면 그 뒤는 JSON 한 줄씩입니다.
• CORS 확인: curl -s -D - -o /dev/null -H 'Origin: http://portal.example.test:3000' http://127.0.0.1:7300/.backstage/health/v1/readiness
• 프로세스의 환경변수 확인: tr '\0' '\n' < /proc/$(pgrep -f 'node index.js' | head -1)/environ | grep -E 'NODE_ENV|APP_CONFIG|PORTAL'
• 설정 파일 쓰기(--config 순서·APP_CONFIG_·${VAR}): https://backstage.io/docs/conf/writing
• 외부 호출용 정적 토큰(externalAccess): https://backstage.io/docs/auth/service-to-service-auth
• 플러그인 DB 설정(better-sqlite3): https://backstage.io/docs/tutorials/configuring-plugin-databases
• 운영 배포 개요: https://backstage.io/docs/deployment/
• Docker 이미지로 배포(이 VM 에서는 다루지 않음): https://backstage.io/docs/deployment/docker
• 아키텍처 개요(프런트엔드 앱과 백엔드): https://backstage.io/docs/overview/architecture-overview
• backend.cors 설정 스키마(config.d.ts): https://github.com/backstage/backstage/blob/master/packages/backend-defaults/config.d.ts

단계 8개

1. 운영 설정을 시험할 백엔드를 고정 버전으로 받는다
2. 운영 파일을 얹었더니 다른 포트에서 듣는다
3. 비밀이 빠진 채 뜬 백엔드는 준비되지 않는다
4. 브라우저의 포털 화면만 백엔드를 부를 수 있다
5. 파일을 고치지 않고 이 배포에서만 Origin 을 넓힌다
6. 재시작했더니 등록한 location 이 사라졌다
7. DB 를 디스크로 옮기면 재시작해도 남는다
8. 운영 설정 점검표를 지금 프로세스로 채운다