---
title: "SourceDeploy 문제 해결"
slug: "sourcedeploy-troubleshoot"
updated: 2026-07-23T09:02:41Z
published: 2026-07-23T09:02:41Z
canonical: "guide-fin.ncloud-docs.com/sourcedeploy-troubleshoot"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide-fin.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SourceDeploy 문제 해결

SourceDeploy 서비스를 이용하면서 다음과 같은 문제를 겪을 수 있습니다. 문제별 원인과 해결 방법을 확인하고 적절하게 조치해 주십시오.

## 에이전트 연결 오류

SourceDeploy용 에이전트를 설치했는데 배포를 수행하면 'agent connect fail' 로그가 발생합니다. 'failed to connect agent' 오류 메시지가 표시됩니다.

#### 원인

- NCP_AUTH_KEY 파일이 존재하지 않는 경우, 오류가 발생할 수 있습니다.
- 지원하는 Python 버전이 아닌 경우, 오류가 발생할 수 있습니다.
- 에이전트 버전이 잘못된 경우, 오류가 발생할 수 있습니다.
- 환경에 맞지 않은 에이전트를 설치, 오류가 발생할 수 있습니다.

#### 해결 방법

- **NCP_AUTH_KEY 파일이 존재하지 않는 경우**
  - 에이전트가 정상적으로 동작하려면 서버 내 /opt 아래에 NCP_AUTH_KEY 파일이 존재해야 합니다.
  - 해당 키 파일의 존재 여부를 확인해 주십시오.
  - 키 파일의 내용이 정상적으로 작성되었는지 확인해 주십시오.
  - NCP_AUTH_KEY 파일을 작성하는 방법은 [에이전트 설치 및 관리](/docs/devtools-sourcedeploy-deploysetting)를 참조해 주십시오.
- **지원하는 Python 버전이 아닌 경우**
  - 에이전트는 Python 2.6, 2.7 버전에서 동작합니다. 서버에 설치되어 있는 Python 버전을 확인해 주십시오.
- **환경에 맞지 않는 에이전트를 설치한 경우**
  - [에이전트 설치 및 관리](/docs/devtools-sourcedeploy-deploysetting)를 참조하여 지원 사양을 확인하고 사용 리전 및 환경에 해당하는 에이전트 다운로드 주소를 입력해 주십시오.
- **에이전트가 이전 버전인 경우**
  - 에이전트 상태 확인 명령어를 입력하여 에이전트가 정상적으로 설치되었는지 확인해 주십시오.

```
service sourcedeploy status
```

![devtools-devtools-4-4_status](https://cdn.document360.io/0406ed95-101f-4cde-8dd8-308d03444a94/Images/Documentation/devtools-devtools-4-4_status.png)
  - 설치된 에이전트 버전을 확인해 주십시오.

```
cat /opt/sdagent/Agent.ver
```

<예시> 2021/05/27 기준

```
[VERSION]
ver=2021/05/18/01
```
    - 설치된 에이전트 버전이 이전 버전일 경우, 에이전트를 삭제한 후 재설치해 주십시오.
      - 에이전트 삭제는 [에이전트 삭제](/docs/devtools-sourcedeploy-deploysetting#%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8%EC%82%AD%EC%A0%9C)를 참조해 주십시오.
- 서버 상태가 **운영중**인지 확인해 주십시오.
- 위 사항을 수행한 후에도 에이전트 오류가 발생할 경우, 에이전트 동작 로그를 [고객 지원](https://www.fin-ncloud.com/support/question/service)으로 전달해 주십시오.  

에이전트 동작 로그를 조회하는 방법은 다음과 같습니다.

```
$ grep gateway /opt/sdagent/resource.py;
$ service sourcedeploy status;
$ cat /opt/sdagent/Agent.ver;
$ cat /var/sourcedeploy/log/sourcedeploy-0-system.log
```

## 에이전트 프로세스 실행 오류

에이전트 프로세스가 정상적으로 실행되지 않습니다.

#### 원인

에이전트가 정상적으로 설치되지 않았습니다.

#### 해결 방법

- 재시작 명령어를 입력하여 에이전트를 재시작해 주십시오.

```
service sourcedeploy restart
```
- 재시작한 후에도 정상적으로 동작하지 않을 경우, 아래 리눅스 패키지들을 설치한 후 에이전트를 재설치해 주십시오.

```
# CentOS, Rocky
sudo yum install -y epel-release ca-certificates openssl-devel zlib-devel
# Ubuntu
sudo apt-get install -y build-essential ca-certificates libssl-dev zlib1g-dev
```
- 에이전트 프로세스를 확인하여 에이전트가 정상적으로 실행되는지 확인할 수 있습니다.

```
ps -ef | grep main.py
```

![devtools-devtools-4-4_process](https://cdn.document360.io/0406ed95-101f-4cde-8dd8-308d03444a94/Images/Documentation/devtools-devtools-4-4_process.png)

          참고

          

에이전트 프로세스의 정상 실행 기준은 다음과 같습니다.

- 프로세스 1개 실행

## 에이전트 설치 오류

에이전트가 정상적으로 설치되지 않습니다.

#### 원인

- 인증키 값이 잘못 입력되었습니다.
- 스크립트 경로가 잘못 지정되었습니다.
- 에이전트 설치 URL이 잘못 입력되었습니다.

#### 해결 방법

- 인증키 값이 정상적으로 입력되었는지 확인해 주십시오.

```
cat /opt/NCP_AUTH_KEY
```
- Init Script 첫 줄에 `#!/usr/bin/env python`, `#!/bin/perl`, `#!/bin/bash` 등과 같은 형태로, 실행하고자 하는 스크립트 경로를 지정했는지 확인해 주십시오.
- Init Script에 에이전트 설치 URL이 다음과 같이 입력되었는지 확인해 주십시오.  

`Shell wget {에이전트 다운로드 주소}`
  - 사용 환경 및 리전에 따른 에이전트 다운로드 주소는 다음과 같습니다. 

| <center data-tomark-pass="">환경</center> | <center data-tomark-pass="">리전</center> | <center data-tomark-pass="">에이전트 다운로드 주소</center> |
| --- | --- | --- |
| VPC | 한국 (FKR) | https://deploy-agent.apigw.fin-ntruss.com/agent/v1/download/install |

## Install Python 실패

Install Python 단계에서 실패합니다.

#### 원인

SourceDeploy의 에이전트는 Python 2.6, 2.7 버전을 사용하고 있습니다. Agent Install 스크립트를 통해 자동으로 Python 설치가 이루어지지 않을 경우, 문제가 발생할 수 있습니다.

#### 해결 방법

다음 명령어를 입력하여 Python을 설치해 주십시오.

```
$ apt-get install -y python2.7
```

## 롤백 실패

롤백에 실패했습니다.

#### 원인

- 이전에 배포한 파일이 Object Storage에 없습니다.
- 마지막 성공 배포 기록이 없습니다.
- 파일이 변경되었습니다.

#### 해결 방법

SourceDeploy의 롤백 기능은 마지막으로 성공한 배포를 재실행하는 방식으로 동작합니다. 마지막으로 성공한 배포 기록이 있는지 확인한 후, 배포 파일이 Object Storage에 존재하는지 확인해 주십시오.

## 둘러볼 콘텐츠

네이버 클라우드 플랫폼에서는 고객에게 도움을 주기 위해 다양한 방식으로 정보를 제공하고 있습니다. SourceDeploy 서비스 이용 시 활용할 수 있는 유용한 콘텐츠를 안내합니다.

- 자주 하는 질문: [SourceDeploy 자주 하는 질문](https://www.fin-ncloud.com/support/faq/prod?categoryCode2=DEVTL&amp;categoryCode3=SV_0106&amp;page=1)
- 네이버 클라우드 플랫폼 블로그: [SourceDeploy & SourceBuild - Github Enterprise Server 연동 기능 제공](https://blog.naver.com/n_cloudplatform/223272473873?trackingCode=blog_bloghome_searchlist)
- 네이버 클라우드 플랫폼 블로그: [Kubernetes 클러스터에 애플리케이션 배포하기 - 네이버 클라우드 플랫폼 Developer Tools (개발자 도구) 활용 실습](https://blog.naver.com/n_cloudplatform/223209131446?trackingCode=blog_bloghome_searchlist)
- API 가이드: [SourceDeploy API 가이드](https://api-fin.ncloud-docs.com/docs/devtools-sourcedeploy)