Skip to Content
권대환매뉴얼
CSO 정산 조회 (운영 종료)운영자 매뉴얼실행 구성과 배포

실행 구성과 배포

참고: CSO 정산 포털의 정산 업무는 2026-09-29에 다른 정산 시스템으로 옮겼습니다. 이 쪽은 운영 당시 구성의 기록입니다. 지금 상태는 소개를 보세요.

이 쪽은 포털이 어떤 프로그램으로 나뉘어 돌았는지, 새 판을 어떤 순서로 올렸는지 정리합니다.

프로그램 구성

포털은 같은 서버에서 도는 프로그램 세 개와 데이터베이스 하나로 이루어집니다.

구성 요소하는 일
웹 서버화면과 API를 냅니다. Next.js를 단독 실행용(standalone)으로 빌드한 결과물을 Node.js로 실행합니다.
이메일 워커메일머지 발송 대기열에서 메일을 하나씩 꺼내 SMTP로 보냅니다.
OCR 워커EDI 검토용 처방통계 파일의 방향을 바로잡고 OCR(문자 인식)로 읽습니다.
데이터베이스워크스페이스 공용 Supabase(셀프호스팅, PostgreSQL 17.6)에서 csoweb_ 접두사가 붙은 표를 씁니다.

세 프로그램은 systemd 서비스로 등록되어 비정상 종료 때 자동으로 다시 시작합니다. 웹 서버 앞에는 Nginx가 있어 외부 요청을 받아 넘깁니다.

새 판을 올리는 순서

운영 기간에는 워크스페이스 공통 배포 스크립트 하나로 올렸습니다. 서비스를 손으로 재시작하면 빌드 결과물이 바뀌는 도중에 요청을 받아 오류가 날 수 있어서 이 경로만 씁니다.

  1. 변경을 main 브랜치에 병합합니다.
  2. 공통 배포 스크립트를 csoweb 대상으로 실행합니다.
  3. 스크립트가 같은 대상의 동시 배포를 막고 pnpm run build:standalone으로 빌드합니다.
  4. 스크립트가 빌드 결과물(.next/standalone/server.js와 정적 파일 폴더)이 있는지 확인합니다.
  5. 스크립트가 웹 서버, 이메일 워커, OCR 워커를 재시작합니다.
  6. 스크립트가 웹 서버 첫 화면에 요청을 보내 응답을 확인합니다.
  7. 응답이 없으면 스크립트가 직전 결과물로 되돌립니다.

배포가 끝나면 시스템 정보 화면에서 버전과 연결 상태를 확인합니다. 화면 설명은 모니터링에 있습니다.

설정 값

설정 값은 저장소에 올리지 않는 환경 파일에 둡니다. 웹 서버와 워커는 서로 다른 파일을 읽습니다. 항목 이름은 저장소의 예시 파일에 있습니다.

예시 파일쓰는 곳주요 항목
.env.example웹 서버Supabase 주소와 키, JWT 서명 키, Resend 키와 발신 주소, 관리자 알림 주소, 심평원·국세청 API 키, 사이트 기본 주소
.env.worker.example이메일·OCR 워커Supabase 주소와 키, OCR API 주소와 키, Redis 주소, OCR 동시 처리 수

SMTP 접속 정보는 환경 파일이 아니라 데이터베이스에 저장하고 이메일 설정 화면에서 바꿉니다.

주의: 환경 파일에는 비밀 값이 들어 있습니다. 저장소에 올리지 않고 대화나 문서에 옮겨 적지 않습니다.

로컬에서 실행하기

개발용 실행과 검사는 저장소 안 명령으로 합니다. 먼저 .env.example을 복사해 로컬 환경 파일을 만들고 값을 채웁니다.

pnpm install pnpm run dev # 개발 서버 pnpm exec vitest run # 단위 테스트 pnpm run build # 운영 빌드 확인

변경 이력

  • 2026-05: 자체 서버의 프로세스 관리를 PM2에서 systemd로 옮겼습니다(커밋 2c98c577, 8845b75a).
  • 운영 기간에는 Vercel에도 같은 main을 자동 배포했습니다(vercel.json). OCR 워커와 메일머지 워커는 오래 도는 프로세스라 자체 서버에서만 돌렸습니다. 저장소 안내(AGENTS.md)는 운영 중지 뒤 이 이중 배포를 현재 구성으로 보지 않습니다.
  • 2026-11-16: 패키지 관리자를 npm에서 pnpm으로 바꿨습니다(커밋 268609c6).

확인 기준: 2026-11-18, csoweb 저장소 기준.