[경기문화재단] 아트경기 인프라 재구축, 유지보수

2025/05/03 ~ 2025/06/07배포 링크

역할 풀스택 전담: 프론트엔드, 서버, DB, 인프라 전체 (1인 / 경기문화재단 외주 / 안전관리실 및 예술지원팀과 협업)

요약 git, 문서, 환경변수 없이 코드 압축 파일만으로 5일 안에 전체 인프라를 재구축 및 무중단 이전함. any뿐이던 프로젝트에 타입 생성 자동화 파이프라인 구축.

프로젝트 개요

  • 경기문화재단의 ‘아트경기’ 홈페이지를 인계받아 유지보수 업무를 맡았습니다.

  • 서버 이전 및 전체 재배포: 기존 인프라 복원 없이 코드만으로 전체 서비스를 재구축했습니다.

  • 타입이 모두 any로 작성되어 있었던 타입스크립트 프로젝트에 타입을 붙이고, 백엔드 스키마 변경 시 타입 생성이 자동화되도록 했습니다.

프로젝트 인수: 코드 압축 파일 하나

경기문화재단 '아트경기' 홈페이지의 유지보수를 인계받았는데, 상황이 다음과 같았습니다:

  • git 히스토리 없이 코드 압축 파일만 전달받음

  • .env 미제공, 문서 없음

  • 기존 배포 인스턴스 접근 불가

  • 업로드 파일이 여러 클라우드에 중첩 저장된 상태

  • 5일 뒤 기존 인스턴스 가동 중단 통보, 이후 이전 개발자와 연락 두절

기술 스택(SvelteKit, Strapi CMS)도 처음 다뤄보는 것들이었습니다. 코드와 에러 메시지만을 단서로 시스템을 파악해야 했습니다.

인프라 재구축 과정

다시 구축한 인프라
다시 구축한 인프라

  1. 환경변수 복원 (리버스 엔지니어링): 코드 전체에서 process.env 참조를 역추적해 이전 배포 환경을 분석하고, .env·외부 API 키·DB 연결 URI를 재구성했습니다.

  2. 인프라 재설계: 각 서비스(프론트엔드 2기, CMS, Search)를 개별 컨테이너로 분리 배포하고, nginx 리버스 프록시로 접속 기기별 라우팅을 구성했습니다.

  3. 데이터 마이그레이션: 여러 클라우드에 흩어져 있던 업로드 파일을 통합 이전하고, DB의 file path를 일괄 업데이트했습니다.

  4. DNS 무중단 이전: 경기문화재단 안전관리실과 협업해 도메인 이전과 SSL 인증을 처리하고, 서비스 중단 없이 전환했습니다.

  5. 운영 계정 정리 및 인수인계 문서화: "문서 없는 인수"가 반복되지 않도록 배포 구조와 운영 절차를 문서로 남겼습니다.

타입 시스템 복원: any 지옥 탈출

인수한 프로젝트는 API 스펙을 어디서도 참조할 수 없는 상태였습니다:

  • 프론트엔드의 모든 타입이 any

  • 서버는 타입스크립트 컴파일 없이 개발됨, 타입 유틸리티 플러그인이 import만 되고 의존성에서 누락

타입을 수기로 작성하는 대신, 서버 스펙이 바뀌면 타입이 자동으로 다시 생성되는 구조를 만들기로 했습니다. 1인 유지보수 프로젝트라 다음 인수자가 API 문서와 타입만으로 구조를 파악할 수 있어야 한다고 판단했기 때문입니다.

  1. Strapi CMS에 Swagger(문서화 플러그인)를 부착해 OpenAPI 스펙 추출

  2. openapi-typescript로 스펙 → 타입 정의 자동 생성 파이프라인 구성

TS
// 생성된 타입은 아래처럼 바로 참조
type AuthorList = paths['/authors']['get']['responses']['200']['content']['application/json'];
type Author = components['schemas']['Author'];

타입 생성 자체는 금방 끝났지만, any가 적힌 모든 지점에 실제 타입을 붙이고 디버깅하는 것이 오래 걸리는 작업이었습니다.

회고

만드는 사람에게 가장 어려운 일은 있어야 하는 것들이 당연한 곳에 있게 하는 것임을 체감했습니다.

  • 문서가 없는 상태에서, 처음 접한 기술로 구성된 프로젝트를 분석하고 재구성하는 경험

    • 모든 정보가 누락된 상태에서 코드와 에러 메세지만을 단서로 시스템 흐름을 파악하고, 재구축하는 과정을 경험했습니다.

  • 배포 프로세스에 대한 간략한 경험

    • 리버스 프록시 구성, 컨테이너 관리, DNS 이전, DB 마이그레이션이라는 다양한 인프라 구성 요소를 직접 다루면서 서비스 인프라의 전반적인 흐름을 컨트롤했습니다.

  • 커뮤니케이션 역량

    • 경기문화재단 안전관리실, 예술지원팀과 협업하며 기술적인 문제 상황을 명확히 설명하고, 필요한 조치를 진행할 수 있도록 커뮤니케이션에 힘썼습니다.