안녕하세요, 저는 HolySheep AI의 기술 블로그 작가입니다. 오늘은 오픈소스 AI 앱 빌더인 Dify의 UI를 원하는 대로 꾸미는 방법을 초보자도 쉽게 따라할 수 있도록 단계별로 알려드리겠습니다.

Dify란 무엇인가?

Dify는 코딩 없이 AI 챗봇과 애플리케이션을 만들 수 있는 오픈소스 플랫폼입니다. 하지만 기본 제공되는 UI가 마음에 들지 않거나, 회사 브랜드에 맞게 커스터마이징하고 싶을 때가 있습니다. 이 튜토리얼에서는 Docker를 기반으로 Dify의 테마, 로고, 색상 등을 자유롭게 변경하는 방법을 다루겠습니다.

【사전 준비】

1단계: Dify 프로젝트 클론 및 설정

가장 먼저 Dify 레포지토리를 가져오고 설정을 변경할 준비를 하겠습니다. 아래 명령어를 순서대로 실행해주세요.

# Dify 소스 코드 클론
git clone https://github.com/langgenius/dify.git
cd dify/docker


docker-compose.yaml 파일 복사

cp docker-compose.yaml docker-compose.custom.yaml


환경설정 파일 생성

cp .env.example .env

【참고】클론이 완료되면 다음과 같은 폴더 구조가 보입니다:

📁 dify/docker/ ─── 📁 web/ ─── 📁 src/ ─── 📁 styles/

2단계: HolySheep AI API 연결 설정

Dify에서 HolySheep AI를 모델 제공자로 연결하려면 API 설정을 변경해야 합니다. .env 파일을 열어 다음 내용을 추가합니다.

# .env 파일 수정
CODE_EXECUTION_ENDPOINT=https://api.holysheep.ai/v1
CONSOLE_WEB_URL=http://localhost:3000
APP_WEB_URL=http://localhost:3000
CONSOLE_API_URL=http://localhost:3000/api
CONSOLE_CORS_ALLOW_ORIGINS=http://localhost:3000


다크모드/라이트모드 기본 테마 설정

CONSOLE_DEFAULT_THEME=dark

3단계: CSS 파일 직접 수정하여 테마 변경

Dify의 핵심 색상과 스타일을 변경하려면 web/src/components/base 위의 CSS 파일을 수정해야 합니다. 초보자분들도 쉽게 찾을 수 있도록 주요 파일 위치를 안내합니다.

# web/src/styles directory 내부의 전역 CSS 파일 접근

파일 경로: web/src/styles/globals.css


/* globals.css 상단에서 테마 변수 확인 및 수정 */
:root {
  /* 주요 색상 팔레트 변경 */
  --color-primary: #7C3AED;        /*.primary-accent */
  --color-secondary: #10B981;      /* Secondary */
  --color-background: #0F172A;     /* Background */
  --color-surface: #1E293B;        /* Card/Surface */
  --color-text: #F8FAFC;           /* Primary Text */
  --color-text-secondary: #94A3B8; /* Secondary Text */
  
  /* 테두리 및 강조색 */
  --color-border: #334155;
  --color-hover: #475569;
  --color-active: #5B21B6;
  
  /* 폰트 설정 */
  --font-family: 'Pretendard', -apple-system, sans-serif;
}

【스크린샷 힌트】실제로 globals.css를 열어보면 파일 상단에 :root {} 블록이 보입니다. 이 값을 위 예시처럼 수정하면 전체 앱의 색상이 일괄 변경됩니다.

4단계: 라이트 모드 테마 추가 설정

/* 라이트 모드용 추가 변수 */
[data-theme="light"] {
  --color-primary: #7C3AED;
  --color-background: #FFFFFF;
  --color-surface: #F1F5F9;
  --color-text: #0F172A;
  --color-text-secondary: #64748B;
  --color-border: #E2E8F0;
}

/* 다크 모드용 추가 변수 */
[data-theme="dark"] {
  --color-primary: #8B5CF6;
  --color-background: #0F172A;
  --color-surface: #1E293B;
  --color-text: #F8FAFC;
  --color-text-secondary: #94A3B8;
  --color-border: #334155;
}

5단계: 로고 및 브랜드 이미지 변경

로고 이미지를 교체하려면 web/public/images/ 폴더 내의 파일을 변경합니다. 추천 이미지 크기와 파일명을 안내드립니다.

# 로고 이미지 교체 (권장 크기: 40x40px, PNG/SVG)

파일 경로: web/public/favicon.ico → 사용자 로고


파일 경로: web/public/logo.svg → 헤더 로고



임시로 파일 교체 테스트 (실제 환경에서는 빌드 필요)

cp /your/custom/logo.png web/public/logo.png


빌드 실행

cd web
npm run build


Docker 컨테이너 재시작

docker-compose -f docker-compose.custom.yaml down
docker-compose -f docker-compose.custom.yaml up -d

【스크린샷 힌트】Docker Dashboard나 docker ps 명령어로 컨테이너 상태를 확인하면 web 컨테이너가 "healthy" 상태인지 볼 수 있습니다.

6단계: HolySheep AI API 키 연동 확인

Dify 설치 후 관리자 패널에서 HolySheep AI를 모델 제공자로 등록하는 과정입니다. HolySheep AI는 15개 이상의 AI 모델을 단일 API 키로 통합 제공하므로 매우 편리합니다.

# Dify 콘솔 접속 후 설정 순서:

1. Settings → Model Providers 클릭


2. "Custom" provider 추가 선택


3. Base URL: https://api.holysheep.ai/v1 입력


4. API Key: YOUR_HOLYSHEEP_API_KEY 입력


5. Models 탭에서 사용할 모델 활성화 (gpt-4o, claude-3.5-sonnet 등)


6. 연결 테스트 버튼 클릭 → "Success" 확인

【실제 가격 정보】HolySheep AI를 통해 Dify 연동 시 비용이 매우 경제적입니다:

DeepSeek V3.2 모델의 경우 기존 대비 95% 비용 절감이 가능하여 프로토타입 개발이나大批量 요청 처리에 최적입니다.

커스터마이징 결과 확인 방법

변경 사항을 확인하려면 브라우저에서 다음 과정을 거칩니다:

  1. Dify에 로그인 (기본: http://localhost:3000)
  2. 프로필 아이콘 클릭 → "Settings" 선택
  3. "Theme" 탭에서 다크/라이트 모드 전환 테스트
  4. 새로 만든 챗봇 애플리케이션에서 UI 확인

【스크린샷 힌트】적용 후에도 색상이 안 보인다면 Ctrl+Shift+R (Windows) 또는 Cmd+Shift+R (Mac)으로 하드 리프레시를 시도하세요. 캐시 문제일 수 있습니다.

자주 발생하는 오류와 해결책

오류 1: 로고 변경 후 적용이 안 되는 경우

# 문제: 커스텀 로고가 보이지 않고 기본 로고가 표시됨

해결: Docker 볼륨 마운트 설정 확인 및 캐시 삭제



docker-compose.yaml에서 볼륨 설정 확인

volumes:
  - ./web:/app/web/public:ro  # read-only 마운트
  # 수정 후:
  - ./web/public:/app/web/public


또는 빌드 후 컨테이너 재생성

docker-compose -f docker-compose.custom.yaml down --volumes
docker-compose -f docker-compose.custom.yaml up -d --build

오류 2: CSS 수정 후 색상이 변경되지 않는 경우

# 문제: CSS를 수정해도 UI에 반영이 안 됨

해결: SCSS 컴파일 및 빌드 캐시 삭제


cd web
rm -rf node_modules/.cache
rm -rf .next
npm install
npm run build


빌드 완료 후 컨테이너 재시작

docker-compose -f docker-compose.custom.yaml restart web

오류 3: HolySheep AI API 연결 시 "Invalid API Key" 에러

# 문제: API 키 인증 실패

해결: .env 파일 설정 및 API 키 확인



1. .env 파일에서 올바른 포맷인지 확인


예시 (.env):

CONSOLE_API_URL=http://localhost:3000/api
CODE_EXECUTION_ENDPOINT=https://api.holysheep.ai/v1


2. HolySheep AI 대시보드에서 API 키 확인


https://www.holysheep.ai/dashboard 에서 복사



3. Dify의 Model Providers 설정에서:


- Base URL: https://api.holysheep.ai/v1 (trailing slash 없이)


- API Key: sk-holysheep-xxxxx... 형식



4. 컨테이너 재시작

docker-compose -f docker-compose.custom.yaml restart api

오류 4: 다크모드/라이트모드 전환 시 레이아웃 깨짐

# 문제: 테마 전환 시 스크롤바나 모달이 깨짐

해결: CSS 변수 적용 범위 확장


/* globals.css 최하단에 추가 */
* {
  transition: background-color 0.2s ease, color 0.2s ease;
}

/* 스크롤바 스타일 */
::-webkit-scrollbar {
  width: 8px;
  height: 8px;
}

::-webkit-scrollbar-track {
  background: var(--color-surface);
}

::-webkit-scrollbar-thumb {
  background: var(--color-border);
  border-radius: 4px;
}

::-webkit-scrollbar-thumb:hover {
  background: var(--color-hover);
}

고급 커스터마이징 팁

더 전문적인 커스터마이징을 원하시는 분들을 위해 몇 가지 추가 팁을 드리겠습니다. 이 부분은 선택 사항이며, CSS에 익숙하신 분들만 진행해주세요.

결론

Dify의 UI 커스터마이ezing은 처음에는 복잡해 보이지만, 이 가이드의 단계를 따라하면 누구든 자신만의、品牌形象에 맞는 AI 챗봇을 만들 수 있습니다. HolySheep AI를 통해 API 연결하면 단일 키로 15개 이상의 모델을 손쉽게 전환하며 비용을 최적화할 수 있습니다.

저의 경우, 첫 커스텀 테마 적용 시 로고 파일 경로 문제로 2시간 넘게 헤맸던 경험이 있습니다. 이 가이드의 5단계 로고 교체를 꼼꼼히 따라하시면 그런 불필요한 시간 낭비를 줄일 수 있을 것입니다.

궁금한 점이 있으시면 언제든지 HolySheep AI 커뮤니티에 질문해 주세요. 행복한 코딩 되세요!

👉 HolySheep AI 가입하고 무료 크레딧 받기

관련 리소스

관련 문서