중급API 서버 배포: Cloud Run으로 시작하기

웹 파일과 서버의 차이

정적 파일을 올리는 것만으로 로그인 검증·비밀키 API 호출·DB 저장을 처리하는 서버가 실행되지는 않습니다. 이 장에서는 HTTP API 서버를 Google Cloud Run에 배포합니다. Next.js 전체 앱을 Firebase와 연결하고 싶다면 App Hosting 가이드도 비교하세요.

배포할 서버의 조건

Cloud Run 서비스는 지정된 PORT 환경변수의 포트에서 요청을 받아야 하며 127.0.0.1만이 아닌 0.0.0.0에 바인딩해야 합니다. 로컬 파일을 영구 데이터 저장소로 사용하지 말고 DB·객체 저장소를 연결합니다. 컨테이너 실행 조건 ↗

Node.js 최소 실행 예시

아래는 실행 포트 확인용 예제이며 회원 기능이 있는 완성 API가 아닙니다. 프로젝트의 package.json에 start 스크립트를 두고 실제 프레임워크의 운영 실행 방법으로 바꿉니다.

const http = require("node:http");
const port = Number(process.env.PORT || 8080);
http.createServer((req, res) => {
  if (req.url !== "/health") {
    res.writeHead(404);
    res.end();
    return;
  }
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ ok: true }));
}).listen(port, "0.0.0.0");

소스에서 배포하기

Google Cloud 프로젝트·결제를 준비하고 Cloud Run·Cloud Build·Artifact Registry 등 필요한 API와 권한을 공식 시작 절차에 맞게 설정합니다. 소스 배포는 Cloud Build와 빌드팩 등을 이용해 이미지를 만듭니다. 소스 배포 안내 ↗

gcloud auth login
gcloud run deploy my-api --source . --project PROJECT_ID --region REGION

PROJECT_ID와 REGION을 실제 대상으로 바꾸고 서버 루트에서 실행합니다. .gcloudignore를 확인해 로컬 비밀 파일·자격증명·불필요한 파일이 업로드되지 않게 합니다. Dockerfile이 있는 프로젝트와 없는 프로젝트의 빌드 경로를 구분하고 실행 명령을 확인하세요.

공개 웹·모바일 클라이언트가 호출하는 API인지 내부 서비스인지에 따라 호출 권한을 정합니다. 공개 호출을 허용하더라도 앱의 토큰 검증·소유권 확인·입력 검증은 서버가 계속 수행해야 합니다. Cloud Run IAM과 앱 회원 인증은 서로 다른 경계입니다.

환경변수와 운영 확인

민감한 API 키는 비밀 저장소와 실행 계정 권한으로 연결하고 브라우저에 전달하지 않습니다. DB 리전·연결 수와 인스턴스 한도도 함께 검토합니다. 배포 주소가 발급되면 /health와 실제 API를 각각 호출하고 요청 로그·앱 로그를 확인하세요.

업데이트와 복구

Cloud Run의 리비전과 트래픽 설정을 기록하고 이전 정상 리비전으로 되돌릴 방법을 준비합니다. 앱 롤백이 DB 데이터나 스키마를 복원하지는 않습니다. DB 변경은 이전 앱과의 호환성을 따로 확인하세요. 리비전 롤백 ↗

완료 확인

• 개발 서버 없이 운영 명령으로 기동했다.
• 운영 주소의 API 성공·인증 실패·잘못된 입력을 확인했다.
• 실행 권한·비밀·로그·비용 알림·복구 경로를 기록했다.

공식 참고자료

확인 기준일: 2026-10-22. 요금·지원 런타임·권한은 배포 전에 공식 문서를 확인하세요.

• 소스 코드 배포 ↗
• 실행 조건 ↗
• 리비전과 트래픽 복구 ↗
• 다음: 서버 비용 줄이기