실행 구성과 배포
참고: CSO 정산 포털의 정산 업무는 2026-09-29에 다른 정산 시스템으로 옮겼습니다. 이 쪽은 운영 당시 구성의 기록입니다. 지금 상태는 소개를 보세요.
이 쪽은 포털이 어떤 프로그램으로 나뉘어 돌았는지, 새 판을 어떤 순서로 올렸는지 정리합니다.
프로그램 구성
포털은 같은 서버에서 도는 프로그램 세 개와 데이터베이스 하나로 이루어집니다.
| 구성 요소 | 하는 일 |
|---|---|
| 웹 서버 | 화면과 API를 냅니다. Next.js를 단독 실행용(standalone)으로 빌드한 결과물을 Node.js로 실행합니다. |
| 이메일 워커 | 메일머지 발송 대기열에서 메일을 하나씩 꺼내 SMTP로 보냅니다. |
| OCR 워커 | EDI 검토용 처방통계 파일의 방향을 바로잡고 OCR(문자 인식)로 읽습니다. |
| 데이터베이스 | 워크스페이스 공용 Supabase(셀프호스팅, PostgreSQL 17.6)에서 csoweb_ 접두사가 붙은 표를 씁니다. |
세 프로그램은 systemd 서비스로 등록되어 비정상 종료 때 자동으로 다시 시작합니다. 웹 서버 앞에는 Nginx가 있어 외부 요청을 받아 넘깁니다.
새 판을 올리는 순서
운영 기간에는 워크스페이스 공통 배포 스크립트 하나로 올렸습니다. 서비스를 손으로 재시작하면 빌드 결과물이 바뀌는 도중에 요청을 받아 오류가 날 수 있어서 이 경로만 씁니다.
- 변경을
main브랜치에 병합합니다. - 공통 배포 스크립트를
csoweb대상으로 실행합니다. - 스크립트가 같은 대상의 동시 배포를 막고
pnpm run build:standalone으로 빌드합니다. - 스크립트가 빌드 결과물(
.next/standalone/server.js와 정적 파일 폴더)이 있는지 확인합니다. - 스크립트가 웹 서버, 이메일 워커, OCR 워커를 재시작합니다.
- 스크립트가 웹 서버 첫 화면에 요청을 보내 응답을 확인합니다.
- 응답이 없으면 스크립트가 직전 결과물로 되돌립니다.
배포가 끝나면 시스템 정보 화면에서 버전과 연결 상태를 확인합니다. 화면 설명은 모니터링에 있습니다.
설정 값
설정 값은 저장소에 올리지 않는 환경 파일에 둡니다. 웹 서버와 워커는 서로 다른 파일을 읽습니다. 항목 이름은 저장소의 예시 파일에 있습니다.
| 예시 파일 | 쓰는 곳 | 주요 항목 |
|---|---|---|
.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 저장소 기준.