OpenShip AI Agent 배포, 2026년 실전 가이드

OpenShip AI Agent 배포는 표준 컨테이너 서비스라면 가능하지만, 처음부터 모든 도구와 데이터베이스를 함께 올리면 안 됩니다. 이번 주에는 최소 기능 서비스부터 배포하고, 재시작과 롤백을 확인한 뒤에 데이터베이스와 백그라운드 작업을 추가하는 순서가 가장 안전합니다.

이 글은 로컬 AI Agent 원형을 접속 가능한 서비스로 바꾸려는 독립 개발자를 위한 안내입니다. Git 푸시 배포와 복구 절차가 필요한 소규모 팀, 클라우드 빌드 환경이나 원격 맥을 검토하는 AI SaaS 개발자도 대상입니다.

마지막 업데이트: 2026년 8월 1일. 설치 방식과 배포 기능은 OpenShip 공식 설치 문서, 공식 홈페이지, 공식 저장소를 기준으로 확인했습니다.

배포 전 실행 형태 판별

“원형은 실행되는데 온라인에서는 데이터가 사라진다”는 문제는 대개 코드보다 배포 순서에서 발생합니다. 로컬 파일에 저장한 대화 기록, 백그라운드 작업, 임시 캐시를 하나의 프로세스에 맡기면 재시작 뒤 상태가 없어질 수 있습니다.

먼저 다음 네 가지 중 어떤 형태인지 구분해야 합니다.

웹 API: 외부 요청을 받고 응답하는 장기 실행 서비스입니다. 명확한 포트와 상태 확인 주소가 필요합니다.
상주 작업자: 모델 호출, 도구 실행, 대기열 처리를 계속 수행합니다. 프로세스가 중단됐을 때 다시 시작되는 정책이 필요합니다.
예약 작업: 매일 보고서를 만들거나 오래된 기록을 정리합니다. 실행 기록, 재시도, 중복 실행 방지가 필요합니다.
다중 서비스: API, 작업자, 데이터베이스, 캐시가 서로 통신합니다. 서비스 이름, 내부 네트워크, 시작 순서를 함께 검증해야 합니다.

OpenShip 공식 자료는 Git 저장소나 로컬 폴더에서 코드를 가져오고, 클라우드 또는 SSH로 연결한 자체 서버를 대상으로 배포하는 흐름을 안내합니다. 빌드는 개발 장비나 클라우드에서 수행하고 운영 서버는 완성된 이미지를 실행하는 구조로 설명됩니다. 배포 전에 실행 대상과 네트워크 구조를 먼저 고정해야 합니다.

주의: 특정 서버리스 실행 방식, 짧은 실행 시간에만 맞춘 함수 구조, 임시 파일에 의존하는 코드는 표준 장기 실행 컨테이너와 같은 방식으로 판단하면 안 됩니다. 먼저 애플리케이션이 계속 실행되는 서비스인지 확인해야 합니다.

OpenShip 배포 파일 준비

OpenShip 배포 프로젝트에는 어떤 파일이 필요한가요?

최소 구성은 다음과 같습니다.

실행 명령과 의존성이 정의된 package.json, requirements.txt 또는 이에 준하는 파일
외부 요청을 받을 애플리케이션 코드
서비스가 실제로 살아 있는지 확인할 /health 같은 상태 확인 주소
포트를 환경 변수에서 읽는 코드
필요한 경우 Dockerfile
데이터베이스 초기화나 구조 변경을 위한 마이그레이션 파일
비밀값을 제외한 환경 변수 예시 파일
재시작 뒤에도 남아야 하는 데이터의 저장 위치 문서

명령은 환경에 맞게 바꿔야 하지만, 로컬 폴더를 연결하는 기본 흐름은 다음과 같이 정리할 수 있습니다.

cd <프로젝트_폴더>
openship init
openship deploy

Git 저장소를 사용하는 팀은 기본 브랜치와 배포 대상, 빌드 명령, 테스트 명령을 먼저 고정해야 합니다. 저장소 이름과 주소는 실제 값 대신 <저장소_주소> 같은 자리 표시자를 사용하고, 비밀값은 파일에 넣지 않습니다.

OpenShip은 명령줄 도구, 웹 대시보드, 데스크톱 앱을 통해 같은 배포 흐름을 제공한다고 안내합니다. 설치 명령과 지원 운영체제는 OpenShip 공식 명령줄 도구 안내에서 배포 직전에 다시 확인해야 합니다.

첫 배포 최소 범위

처음부터 검색 도구, 파일 분석, 결제, 알림, 장기 기억을 모두 연결하지 않는 편이 좋습니다. 첫 배포의 목표는 “모델 답변이 나온다”가 아니라 “서비스가 재현 가능하게 실행되고 실패 원인을 찾을 수 있다”여야 합니다.

권장 순서는 다음과 같습니다.

/health 주소가 항상 성공하도록 만듭니다.
모델 호출은 하나의 읽기 전용 API로 제한합니다.
요청 본문과 응답 형식을 고정합니다.
빌드 로그에서 의존성 설치와 실행 명령을 확인합니다.
서비스 상태가 정상인지 확인합니다.
공개 주소에서 상태 확인과 모델 호출을 각각 실행합니다.
프로세스를 재시작한 뒤에도 같은 결과가 나오는지 확인합니다.

예시 요청은 실제 주소와 비밀값을 넣지 않고 검증합니다.

curl -i https://<서비스_주소>/health

curl -X POST https://<서비스_주소>/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"테스트"}'

모델 API가 실패했을 때도 애플리케이션이 내부 오류와 외부 공급자 오류를 구분해서 기록해야 합니다. 전체 요청 헤더나 사용자 입력을 그대로 로그에 남기면 이후 보안 점검이 어려워집니다.

실행 환경 선택 기준

선택지	적합한 경우	먼저 확인할 항목	피해야 할 경우
로컬 폴더 배포	빠른 원형 검증과 단일 개발자 작업	포트, 빌드 도구, 네트워크	장기 운영과 팀 공동 배포
Git 저장소 배포	팀 작업과 변경 이력 관리	브랜치, 테스트, 비밀값 분리	저장소에 설정 파일이 섞인 경우
OpenShip Cloud	서버 운영을 직접 맡고 싶지 않은 경우	비용, 지역, 백업 범위	데이터 위치와 운영 책임을 직접 통제해야 하는 경우
자체 서버 배포	네트워크와 저장소를 직접 관리해야 하는 경우	SSH, 디스크, 백업, 방화벽	운영 담당자가 없는 경우

공식 자료에는 클라우드와 자체 서버, 로컬 빌드, 로그, 지표, 이전 버전 복구 기능이 제시되어 있습니다. 다만 특정 AI Agent 프레임워크가 항상 같은 방식으로 동작한다는 보장은 별도로 확인해야 합니다. 설치 명령과 배포 방식이 바뀌었는지 OpenShip 공식 저장소의 변경 내역을 배포 직전에 확인하는 편이 안전합니다.

데이터베이스와 백그라운드 작업 연결

OpenShip에서 데이터베이스와 백그라운드 작업을 함께 운영할 수 있나요?

가능 여부보다 중요한 것은 데이터 보존과 재시작 순서입니다. OpenShip은 PostgreSQL, Redis, MongoDB, MySQL, 작업자, 예약 작업과 사설 네트워크 기능을 지원 항목으로 소개합니다. 하지만 실제 서비스에서는 선택한 데이터베이스의 백업 책임과 복구 범위를 따로 문서화해야 합니다.

추가 순서는 다음처럼 나누는 것이 좋습니다.

데이터베이스 연결만 추가합니다.
읽기와 쓰기 테스트를 실행합니다.
서비스 재시작 뒤 데이터가 남는지 확인합니다.
캐시를 연결하되, 캐시가 없어도 핵심 기능이 동작하게 만듭니다.
작업자를 추가하고 실패한 작업의 재시도 방식을 확인합니다.
예약 작업은 한 번만 실행되는지와 중복 실행 방지를 검증합니다.
백업 파일의 위치, 보관 기간, 복구 담당자를 기록합니다.

파일 저장을 컨테이너 내부 임시 경로에 두면 새 배포나 재생성 뒤 사라질 수 있습니다. 사용자가 올린 파일, 대화 기록, 작업 결과처럼 반드시 남아야 하는 데이터는 영속 저장소나 별도 객체 저장소의 보존 정책을 먼저 정해야 합니다.

모델 API 키와 공개 경계

모델 API 키는 OpenShip에서 어떻게 설정하나요?

모델 키는 소스 코드와 저장소에 넣지 않고 환경 변수 또는 비밀 관리 기능으로 주입해야 합니다. 개발, 미리 보기, 운영 환경의 값을 분리하고, 운영 키에는 필요한 권한만 부여합니다.

예시는 구조만 보여 줍니다.

MODEL_API_KEY=<비밀값>
DATABASE_URL=<데이터베이스_주소>
REDIS_URL=<캐시_주소>
APP_ENV=production

다음 항목은 배포 기록과 로그에서 제거해야 합니다.

Authorization 헤더 전체
모델 API 키와 데이터베이스 비밀번호
사용자 입력에 포함된 개인 정보
외부 도구 호출의 전체 응답
서명용 쿠키와 세션 토큰

환경 범위별 비밀값 저장 기능을 사용하더라도 애플리케이션이 예외 메시지에 환경 변수를 출력하면 노출될 수 있습니다. 따라서 플랫폼 설정과 애플리케이션 로그 형식을 함께 점검해야 합니다.

도메인과 HTTPS 확인

도메인을 붙인 뒤에는 브라우저 접속만으로 완료 처리하지 않습니다.

DNS가 <서버_IP> 또는 플랫폼이 안내한 대상 주소를 가리키는지 확인합니다.
애플리케이션 포트와 외부 공개 포트를 구분합니다.
HTTPS 인증서가 발급되고 자동 갱신되는지 확인합니다.
HTTP 요청이 HTTPS로 이동하는지 확인합니다.
웹소켓이나 스트리밍 응답을 사용할 경우 연결이 중간에 끊기지 않는지 확인합니다.
외부에 공개할 서비스와 내부 네트워크 전용 서비스를 분리합니다.

사용자 도메인, 자동 인증서, 내부 네트워크, 웹소켓 라우팅을 사용할 때는 현재 배포 대상의 연결 방식을 직접 확인해야 합니다. 특히 모델 응답을 스트리밍하는 AI Agent는 일반적인 짧은 요청보다 연결 유지 시간이 길기 때문에 프록시와 시간 제한을 함께 검증해야 합니다.

로그와 롤백 검증

OpenShip 배포가 실패하면 어떻게 이전 버전으로 돌아가나요?

새 버전이 올라간 뒤 정상 응답 한 번만 확인해서는 부족합니다. 다음 세 가지 실패를 일부러 재현해야 합니다.

모델 공급자 응답 지연 또는 오류
애플리케이션 시작 명령 실패
새 버전에서 특정 API 응답 형식 변경

각 상황에서 확인할 내용은 다음과 같습니다.

어느 서비스에서 오류가 시작됐는지 로그로 찾을 수 있는가
실패한 배포와 이전 정상 버전을 구분할 수 있는가
이전 버전으로 되돌린 뒤 /health가 다시 성공하는가
데이터베이스 구조가 이전 코드와 호환되는가
작업자가 같은 작업을 중복 처리하지 않는가
팀원이 문서만 보고 복구할 수 있는가

OpenShip은 배포를 버전 단위로 관리하고 이전 버전으로 복구할 수 있다고 설명합니다. 그러나 데이터베이스 구조 변경은 코드 롤백만으로 되돌아가지 않을 수 있으므로, 마이그레이션의 역방향 절차와 백업 복구 책임을 별도로 적어야 합니다.

경험상 배포 완료의 기준은 공개 주소가 열리는 순간이 아닙니다. 건강 확인, 재시작 뒤 데이터 보존, 의도적인 실패, 이전 버전 복구까지 기록이 남아야 운영 가능한 상태로 볼 수 있습니다.

최종 인수 확인

다음 항목을 모두 통과한 뒤에 도구 호출과 복잡한 워크플로를 추가합니다.

[ ] Git 또는 로컬 폴더에서 같은 빌드가 재현됩니다.
[ ] 실행 포트와 상태 확인 주소가 문서화되어 있습니다.
[ ] 모델 API 키가 저장소와 일반 로그에 노출되지 않습니다.
[ ] 데이터베이스와 캐시의 연결 순서가 확인되었습니다.
[ ] 재시작 뒤 핵심 데이터가 보존됩니다.
[ ] 백그라운드 작업의 재시도와 중복 방지가 확인되었습니다.
[ ] 도메인, HTTPS, 스트리밍 연결이 정상입니다.
[ ] 모델 오류와 애플리케이션 오류를 로그에서 구분할 수 있습니다.
[ ] 실패한 새 버전에서 이전 버전으로 복구했습니다.
[ ] 배포 버전, 복구 명령, 백업 담당자, 팀 인수 문서가 있습니다.

클라우드 빌드 장비나 원격 맥이 필요한 팀은 맥 지원 환경 안내를 먼저 확인하고, 짧은 검증 기간에는 한국 맥 미니 렌탈 옵션처럼 프로젝트 기간에 맞는 환경을 비교할 수 있습니다. 다만 장기간 계속 실행되는 운영 서비스 자체를 원격 맥에 맡기는 것과, 빌드·테스트·관리용 장비로 사용하는 것은 분리해서 판단해야 합니다.

OpenShip은 표준 컨테이너 AI Agent를 빠르게 올리고 이전 버전으로 되돌리는 데 적합하지만, 자체 서버를 선택하면 운영체제 업데이트와 백업, 방화벽, 장애 대응을 직접 맡아야 합니다. 클라우드만 선택하면 인프라 부담은 줄어도 데이터 위치와 비용 구조를 더 세밀하게 확인해야 합니다. 지속적인 맥 빌드 환경, 원격 협업, 격리된 테스트 장비가 필요한 경우에는 서비스 운영 서버와 별도로 Vuncloud의 맥 환경을 프로젝트 기간에 맞춰 선택하는 편이 실제 장애 범위를 줄이는 방법입니다.