YAPI 로컬 환경 구성 및 오류 해결 가이드

YAPI 소개

YAPI는 오픈소스 기반의 API 관리 플랫폼으로, 프로젝트 관리, API 문서화, Mock 서버 설정, 그리고 API 테스트 등을 지원합니다. 사용자 친화적인 인터페이스와 직관적인 기능 덕분에 많은 개발자들에게 사랑받고 있습니다.

YAPI 로컬 설치 방법

MongoDB 설치 및 실행

MongoDB는 YAPI 데이터베이스 역할을 합니다. 각 운영체제별 설치 방법은 아래와 같습니다.

MacOS에서 MongoDB 설치

sudo chown -R "$USER":admin /usr/local
brew tap mongodb/brew
brew install mongodb-community

Windows에서 MongoDB 설치

Windows MongoDB 설치 가이드 참조

Linux에서 MongoDB 설치

Linux MongoDB 설치 가이드 참조

Node.js 설치

YAPI는 Node.js를 필요로 하며, MacOS에서는 다음과 같이 설치할 수 있습니다.

brew install node

다른 운영체제의 경우 공식 사이트에서 다운로드하여 설치하세요.

국내 NPM 소스 설정

npm install -g cnpm --registry=https://registry.npm.taobao.org

yapi-cli 설치

npm install -g yapi-cli

YAPI 서비스 시작

yapi server

Docker를 이용한 YAPI 설치

Docker를 사용하면 간편하게 YAPI를 구동할 수 있습니다.

MongoDB 컨테이너 생성

docker run -d --name mongo-yapi mongo

YAPI 이미지 가져오기

docker pull registry.cn-hangzhou.aliyuncs.com/anoy/yapi

데이터베이스 초기화

docker run -it --rm \
  --link mongo-yapi:mongo \
  --entrypoint npm \
  --workdir /api/vendors \
  registry.cn-hangzhou.aliyuncs.com/anoy/yapi \
  run install-server

YAPI 서비스 시작

docker run -d \
  --name yapi \
  --link mongo-yapi:mongo \
  --workdir /api/vendors \
  -p 3000:3000 \
  registry.cn-hangzhou.aliyuncs.com/anoy/yapi \
  server/app.js

YAPI 사용 방법

브라우저에서 다음 주소로 접속해보세요.

http://127.0.0.1:3000/

Docker 배포 시 기본 계정 정보는 다음과 같습니다.

주요 오류 해결 방법

데이터베이스 초기화 중 발생하는 경고 메시지

오류 메시지:

Error: (node:90198) DeprecationWarning: current Server Discovery and Monitoring engine is deprecated...

해결 방법: ~/my-yapi/vendors/exts/server/utils.js 파일의 22번째 줄에 다음 옵션을 추가하세요.

let options = {useNewUrlParser: true, useCreateIndex: true, useUnifiedTopology: true};

서비스 재시작:

cd ~/my-yapi
node vendors/server/app.js

관리자 계정 초기화 실패

MongoDB의 기존 관리자 데이터를 삭제하고 다시 초기화하세요.

Mac OS에서는 NoSQL Booster와 같은 도구를 사용하여 데이터를 삭제할 수 있습니다.

Node.js 버전 관련 문제

YAPI는 Node.js 15 미만 버전을 권장합니다. 필요한 경우 nvm을 통해 버전을 조정하세요.

brew install nvm
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "/usr/local/opt/nvm/nvm.sh" ] && . "/usr/local/opt/nvm/nvm.sh"' >> ~/.zshrc
source ~/.zshrc
nvm install 10
nvm use 10.24.1

Python 명령어 누락 문제

node-gyp rebuild 명령 수행 중 Python 명령어가 없다는 오류가 발생한다면 다음 단계를 따르세요.

brew install pyenv
pyenv install 3.9.6
pyenv global 3.9.6

.zshrc 파일에 다음 내용을 추가하세요.

if command -v pyenv 1>/dev/null 2>&1; then
  eval "$(pyenv init -)"
fi

설정 적용:

source ~/.zshrc

서버 시작 후 yapi.demo.qunar.com 오류

오류 메시지:

Error: getaddrinfo ENOTFOUND yapi.demo.qunar.com

해결 방법: server.js 파일에서 로그 전송 부분을 주석 처리하세요.

// const logData = await fetch('http://yapi.demo.qunar.com/logs', { method: 'POST', body });

참고 링크: GitHub 이슈 #2180

태그: YAPI MongoDB docker

5월 26일 16:07에 게시됨

인기 태그

©2026 괴물 클럽