2026 Dify 자체 호스팅 플러그인 설치 실패? 먼저 Plugin Daemon 확인

플러그인 설치가 멈추거나 관리 화면에서 요청 오류가 보이면, Daemon이 실제로 중단된 것인지부터 단정하지 마세요.

가장 빠른 점검 순서: API 컨테이너에서 Plugin Daemon의 서비스 이름을 확인하고 연결을 검사한 뒤, 주소·키와 두 서비스의 이미지 및 Compose 설정 버전을 대조하세요. 컨테이너 IP를 임의로 고정하거나 다른 버전의 포트 설정을 복사하면 원인을 가릴 수 있습니다.

이 글은 Dify 플러그인을 설치하거나 관리하는 도중 오류가 발생한 자체 호스팅 사용자에게 적합합니다.
Compose 파일을 직접 수정했거나 업그레이드 뒤 요청 오류가 시작된 개발자도 점검 순서대로 따라갈 수 있습니다.
팀의 장기 운영 환경을 검토하는 담당자에게는 서버 변경이 실제 해결책인지 판단하는 기준을 제공합니다.

마지막 업데이트: 2026년 10월 31일. Dify 버전과 배포 파일은 공식 릴리스 기록 및 해당 버전의 배포 자료를 기준으로 확인했습니다. 공식 릴리스 기록에는 2026년 10월 23일 공개된 1.18.0이 올라와 있습니다.

Dify 자체 호스팅 플러그인 설치 실패: 오류 문구보다 통신 경로부터 확인하세요

플러그인 설치 실패, 플러그인 관리 화면의 로딩 오류, API 요청 거부는 같은 현상처럼 보여도 원인이 다를 수 있습니다. 설치 작업이 실패했다는 사실만으로 Plugin Daemon이 종료됐다고 결론 내리면 안 됩니다. 반대로 관리 화면이 열려도 API에서 Daemon으로 보내는 요청까지 정상이라고 볼 수는 없습니다.

먼저 오류가 발생한 위치와 시간대를 기록하세요. 설치 버튼을 누른 직후 나타난 화면 메시지, API 로그의 요청 결과, Daemon 로그의 시작 또는 초기화 메시지를 함께 비교합니다. 로그에서 SDK 관련 경고가 눈에 띄더라도, 그것만으로 연결 실패가 입증되지는 않습니다. Daemon의 상태와 API 요청 결과가 같은 시점에 맞물리는지 확인해야 합니다.

Dify 1.18.0을 기준으로 배포 파일을 검토할 때는 공식 Docker 배포 설명과 해당 버전의 Compose 설정을 함께 확인하세요. 이전 배포 사례의 설정을 현재 구성에 그대로 덮어쓰지 말고, 실제로 실행 중인 파일과 릴리스 문서를 먼저 대조해야 합니다.

API에서 Plugin Daemon까지 이름이 해석되고 요청이 도착하나요?

Docker Compose에서는 같은 네트워크에 연결된 서비스가 서비스 이름으로 서로를 찾을 수 있습니다. 컨테이너 IP는 재생성이나 배포 변경 뒤 달라질 수 있으므로, 한 번 알아낸 IP를 영구 주소처럼 설정하지 마세요. Compose 네트워크 문서에 설명된 서비스 이름 기반 접근을 현재 파일의 실제 서비스 이름과 비교하는 편이 안전합니다.

Dify API 서비스가 api, Daemon 서비스가 plugin_daemon으로 정의되어 있는 배포 구성이라면, API 컨테이너 안에서 이름 해석을 확인할 수 있습니다. 이 이름은 실행 중인 Compose 파일에서 먼저 검증하세요.

docker compose ps
docker compose exec api sh -lc 'getent hosts plugin_daemon'

명령 출력에 주소가 나타나면 이름 해석은 되는 것입니다. 출력이 없거나 이름을 찾을 수 없다는 결과가 나오면, 두 서비스가 같은 네트워크에 연결됐는지와 Compose 파일에 적힌 서비스 이름이 실제 이름과 일치하는지 확인하세요. 서비스 이름으로 해석되더라도 연결이 보장되는 것은 아니므로 다음 단계에서 Daemon의 상태와 포트도 확인해야 합니다.

공식 Compose 파일에 정의된 Daemon의 내부 포트와 API 쪽 주소를 대조하세요. 파일에 표시된 포트가 이 배포에서 사용하는 값입니다. API 컨테이너에서 해당 호스트와 포트에 접속할 수 있는지 검사하되, 값은 실행 중인 설정에서 가져오세요. 예를 들어 nc -vz <서비스 이름> <설정 파일의 내부 포트>처럼 확인할 수 있습니다. 여기서 꺾쇠 괄호 부분은 그대로 입력하는 문자열이 아니라 현재 설정에 맞춰 바꿀 자리입니다.

localhost, 주소, 키가 서로 다른 배포 방식을 가리키나요?

컨테이너 안에서 localhost는 그 명령을 실행한 컨테이너 자신을 가리킵니다. 따라서 API 컨테이너 설정에 localhost가 들어 있다고 해서 Plugin Daemon까지 가리키는 것은 아닙니다. 주소가 올바른지 판단하려면 설정을 작성한 컨테이너의 위치와 실제 Daemon 서비스의 네트워크 위치를 함께 보세요.

Dify의 배포 방식에 따라 API 주소, Daemon의 내부 접근 주소, 인증에 필요한 키가 달라질 수 있습니다. 전체 컨테이너 배포의 설정과 개발용 미들웨어 설정을 뒤섞지 말고, 같은 배포 방식의 환경 변수 템플릿을 기준으로 비교하세요. Plugin Daemon 환경 변수 템플릿과 1.18.0 환경 변수 예시를 각각 현재 배포 파일과 대조하면 이름이나 설정 항목이 빠졌는지 확인하기 쉽습니다.

키가 비어 있거나 API와 Daemon 사이에서 값이 다르면 요청이 거부될 수 있습니다. 다만 키를 로그나 공개 게시물에 그대로 복사하지 마세요. 두 설정이 같은 값을 참조하는지만 로컬에서 비교하고, 출력에 비밀 값이 포함될 수 있는 명령 결과는 공유 전에 가리세요.

업그레이드 뒤라면 이미지와 Compose 설정이 같은 릴리스인가요?

Compose 파일을 직접 편집한 뒤에는 실행 중인 이미지와 설정 파일의 출처를 따로 확인해야 합니다. 파일만 새 버전으로 바꾸고 오래된 이미지가 남아 있거나, 이미지 태그만 바꾸고 새 환경 변수를 반영하지 않으면 API와 Daemon의 동작이 맞지 않을 수 있습니다.

다음처럼 현재 Compose 구성에서 서비스 이미지 목록을 확인합니다.

docker compose config --images
docker compose images

출력된 이미지 태그를 공식 릴리스 자료와 대조하세요. latest 같은 움직이는 태그를 사용하는 경우에는 그 문구만으로 두 서비스가 동일한 버전이라고 단정하지 말고, 실제로 내려받아 실행 중인 이미지가 무엇인지 확인해야 합니다. 운영 환경의 파일을 바꾸기 전에는 현재 설정을 보관하고, 수정한 항목과 변경 이유를 기록하세요.

Docker는 서비스 시작 순서를 지정할 수 있지만, 먼저 시작됐다는 사실만으로 상대 서비스가 요청을 받을 준비를 마쳤다고 보장되지는 않습니다. Compose 시작 순서 문서를 참고해 의존성과 준비 상태 확인을 구분하세요. Daemon 로그의 준비 완료 여부와 API에서 보낸 실제 요청 결과를 함께 봐야 연결 문제와 시작 시점 문제를 나눌 수 있습니다.

플러그인 SDK 경고가 보이면 연결 오류와 초기화 오류를 구분하세요

로그 한 줄보다 여러 증거가 서로 일치하는지가 중요합니다. Daemon이 실행 중이고 API에서 서비스 이름을 해석하며 내부 포트 연결도 성공하는데 특정 플러그인만 시작하지 못한다면, 전체 Daemon 연결보다 해당 플러그인의 초기화 과정에 초점을 맞추세요. 반대로 API 로그에 연결 거부가 있고 Daemon 로그에도 요청이 도착하지 않는다면, 네트워크 경로와 서비스 상태부터 다시 확인하는 편이 합리적입니다.

지원 요청이나 커뮤니티 글은 재현할 조건을 찾는 단서로만 사용하세요. 다른 배포 방식의 오류 메시지나 자동 생성된 답변을 근거로 설정을 바꾸지 마세요. 사용 중인 버전, Compose 파일, 요청 시각과 관련 서비스 로그를 맞춰서 원인을 좁혀야 합니다.

복구 확인과 장기 운영 판단을 분리하세요

아래 항목을 모두 확인한 뒤에만 복구로 판단하세요. 일부만 통과했다면 실패한 지점으로 돌아가고, 서버를 교체하는 것으로 설정 오류를 덮지 마세요.

• [ ] API 컨테이너에서 Compose 파일에 정의된 Daemon 서비스 이름이 해석됩니다.
• [ ] API 컨테이너에서 설정에 지정된 Daemon 내부 주소와 포트로 연결됩니다.
• [ ] API와 Daemon의 주소 및 인증 키가 같은 배포 방식의 설정을 참조합니다.
• [ ] 실행 이미지와 환경 변수, Compose 설정을 같은 Dify 릴리스 기준으로 대조했습니다.
• [ ] 플러그인 설치와 관리 화면의 요청을 다시 실행하고, 관련 로그에서 성공 여부를 확인했습니다.
• [ ] 사용한 이미지 태그와 변경 전후 설정, 결과 로그를 보관했습니다.

검사를 통과했는데도 서비스가 불안정하다면, 그때는 자원 사용량과 서비스 배치를 별도로 살펴보세요. 플러그인 설치 요청이 실패한다는 사실만으로 CPU나 메모리가 부족하다고 결론 내릴 수는 없습니다. 여러 애플리케이션과 지식 베이스를 장기간 운영할 계획이라면 서비스 수, 데이터 증가량, 백업 위치를 기준으로 메모리와 저장 공간을 산정하세요. 서버 메모리와 디스크 점검 안내를 참고해 현재 배치의 요구량을 정리할 수 있습니다.

작은 개발 환경이거나 부하가 가벼운 단기 테스트라면 기존 VPS나 클라우드 인스턴스를 계속 사용하는 편이 경제적일 수 있습니다. 반대로 공유 환경의 자원 경합, CPU 할당의 불확실성, 저장 장치나 시스템 구성의 제약이 실제 운영 부담으로 이어진다면 OSFP Cloud의 독립 AMD 물리 서버를 검토할 수 있습니다. 독립 서버는 Plugin Daemon의 잘못된 주소나 키를 자동으로 고쳐 주지는 않습니다. 연결과 버전 문제가 해결된 뒤에도 안정적인 전용 자원이 필요할 때, OSFP Cloud의 서버 안내에서 현재 제공 조건을 확인하고 실제 운영 요구와 비교하세요.