CloudBeaver Docker 설치 가이드: DBeaver의 웹 버전으로 다중 DB 관리

---

개요

CloudBeaver는 DBeaver 팀이 개발한 웹 기반 데이터베이스 관리 도구입니다. 데스크톱 앱인 DBeaver의 강력한 기능을 웹 브라우저에서 사용할 수 있으며, PostgreSQL, MySQL, Oracle, SQL Server 등 다양한 데이터베이스를 지원합니다. 팀 협업과 중앙 집중식 DB 관리에 최적화되어 있습니다.

항목	내용
GitHub	https://github.com/dbeaver/cloudbeaver
공식 사이트	https://dbeaver.com/cloudbeaver
Docker Hub	https://hub.docker.com/r/dbeaver/cloudbeaver
라이선스	Apache-2.0 (Community)
개발 언어	Java (백엔드), TypeScript/React (프론트엔드)
데모	https://demo.cloudbeaver.io

---

CloudBeaver란?

CloudBeaver는 2020년 DBeaver 팀이 출시한 웹 기반 데이터베이스 관리 도구입니다. 인기 있는 데스크톱 앱 DBeaver의 웹 버전으로, 브라우저에서 동일한 강력한 기능을 사용할 수 있습니다.

핵심 특징

"브라우저에서 DBeaver의 힘을"
- DBeaver 팀의 웹 솔루션
- 다중 데이터베이스 지원
- 팀 협업 기능
- 모던 React 기반 UI

에디션 비교

기능	Community	Enterprise	AWS
가격	무료	유료	유료
기본 DB 지원	✅	✅	✅
팀 관리	기본	고급	고급
SSO	❌	✅	✅
LDAP	❌	✅	✅
감사 로그	❌	✅	✅
AI 어시스턴트	❌	✅	✅

---

주요 기능

지원 데이터베이스

카테고리	데이터베이스
오픈소스	PostgreSQL, MySQL, MariaDB, SQLite, Firebird
상용	Oracle, SQL Server, DB2
클라우드	Amazon RDS, Azure SQL, Google Cloud SQL
분석	ClickHouse, Trino, Snowflake
NoSQL	MongoDB, Redis (Enterprise)
기타	H2, Derby, HSQLDB

데이터베이스 관리

기능	설명
연결 관리	다중 DB 연결 관리
스키마 브라우저	테이블, 뷰, 인덱스 탐색
테이블 편집	DDL 생성, 수정
데이터 편집	인라인 데이터 수정
ER 다이어그램	관계 시각화
메타데이터	상세 정보 조회

SQL 도구

기능	설명
SQL 에디터	구문 강조, 자동 완성
쿼리 실행	다중 쿼리 실행
결과 뷰어	데이터 필터링, 정렬
쿼리 히스토리	실행 기록
스크립트 관리	SQL 스크립트 저장
실행 계획	쿼리 분석

데이터 관리

기능	설명
데이터 필터	조건 필터링
정렬	다중 컬럼 정렬
내보내기	CSV, JSON, XML, SQL
가져오기	CSV, JSON
대량 편집	다중 행 수정

협업 기능

기능	설명
사용자 관리	계정 생성/관리
역할 기반 접근	권한 설정
연결 공유	팀원과 연결 공유
중앙 관리	연결 정보 중앙화

---

DB 관리 도구 비교

기능	CloudBeaver	phpMyAdmin	Adminer	DbGate
지원 DB	20+	MySQL만	10+	10+
UI 스타일	모던 (React)	클래식	심플	모던
개발사	DBeaver	오픈소스	개인	오픈소스
팀 기능	✅	❌	❌	✅ (Premium)
ER 다이어그램	✅	❌	❌	✅
AI 지원	✅ (Enterprise)	❌	❌	✅ (Premium)
리소스 사용	높음	낮음	매우 낮음	중간
설정 복잡도	중간	낮음	매우 낮음	낮음

선택 가이드

상황	추천
DBeaver 사용자	CloudBeaver
팀 협업 필요	CloudBeaver
엔터프라이즈 환경	CloudBeaver
가벼운 도구	Adminer
MySQL 전용	phpMyAdmin

---

시스템 요구 사항

최소 사양

항목	최소	권장
CPU	2 Core	4 Core
RAM	1GB	2GB+
저장소	500MB	1GB+
Java	11+ (내장)	–

네트워크

• 기본 포트: 8978
• WebSocket 지원 필요

---

Docker 설치

방법 1: 기본 설치

# docker-compose.yml
services:
  cloudbeaver:
    image: dbeaver/cloudbeaver:latest
    container_name: cloudbeaver
    restart: unless-stopped
    ports:
      - "8978:8978"
    volumes:
      - cloudbeaver_data:/opt/cloudbeaver/workspace

volumes:
  cloudbeaver_data:

실행:

mkdir -p ~/cloudbeaver && cd ~/cloudbeaver

# docker-compose.yml 생성 후
docker compose up -d

# 로그 확인
docker compose logs -f cloudbeaver

접속: http://localhost:8978

방법 2: PostgreSQL과 함께

# docker-compose.yml
services:
  cloudbeaver:
    image: dbeaver/cloudbeaver:latest
    container_name: cloudbeaver
    restart: unless-stopped
    ports:
      - "8978:8978"
    volumes:
      - cloudbeaver_data:/opt/cloudbeaver/workspace
    depends_on:
      - postgres
    networks:
      - db_network

  postgres:
    image: postgres:16-alpine
    container_name: postgres
    restart: unless-stopped
    environment:
      - POSTGRES_USER=admin
      - POSTGRES_PASSWORD=adminpassword
      - POSTGRES_DB=myapp
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - db_network

volumes:
  cloudbeaver_data:
  postgres_data:

networks:
  db_network:

방법 3: 다중 데이터베이스 환경

# docker-compose.yml
services:
  cloudbeaver:
    image: dbeaver/cloudbeaver:latest
    container_name: cloudbeaver
    restart: unless-stopped
    ports:
      - "8978:8978"
    volumes:
      - cloudbeaver_data:/opt/cloudbeaver/workspace
    networks:
      - db_network

  mysql:
    image: mysql:8
    container_name: mysql
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=mysqlpass
      - MYSQL_DATABASE=myapp
    volumes:
      - mysql_data:/var/lib/mysql
    networks:
      - db_network

  postgres:
    image: postgres:16-alpine
    container_name: postgres
    restart: unless-stopped
    environment:
      - POSTGRES_USER=admin
      - POSTGRES_PASSWORD=postgrespass
      - POSTGRES_DB=myapp
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - db_network

  mariadb:
    image: mariadb:11
    container_name: mariadb
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=mariadbpass
    volumes:
      - mariadb_data:/var/lib/mysql
    networks:
      - db_network

volumes:
  cloudbeaver_data:
  mysql_data:
  postgres_data:
  mariadb_data:

networks:
  db_network:

방법 4: Traefik 연동

# docker-compose.yml
services:
  cloudbeaver:
    image: dbeaver/cloudbeaver:latest
    container_name: cloudbeaver
    restart: unless-stopped
    environment:
      - CB_SERVER_URL=https://db.example.com
    volumes:
      - cloudbeaver_data:/opt/cloudbeaver/workspace
    networks:
      - db_network
      - traefik_network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.cloudbeaver.rule=Host(`db.example.com`)"
      - "traefik.http.routers.cloudbeaver.entrypoints=websecure"
      - "traefik.http.routers.cloudbeaver.tls.certresolver=letsencrypt"
      - "traefik.http.services.cloudbeaver.loadbalancer.server.port=8978"

volumes:
  cloudbeaver_data:

networks:
  db_network:
  traefik_network:
    external: true

방법 5: 특정 버전 사용

안정성을 위해 특정 버전을 지정합니다:

services:
  cloudbeaver:
    image: dbeaver/cloudbeaver:24.3.0
    # ...

---

초기 설정

1) 첫 접속

브라우저에서 http://localhost:8978 접속

2) 초기 설정 마법사

Step 1: Server Configuration

• Server Name: 서버 이름 (예: My Database Server)
• Server URL: 외부 URL 확인

Step 2: Administrator Credentials

• Administrator login: admin
• Administrator password: 안전한 비밀번호 설정

Step 3: 옵션

• Anonymous access: 비활성화 권장
• Authentication: 로컬 인증 선택

3) 초기 연결 정리

보안을 위해 기본 SQLite 샘플 연결을 삭제합니다:

1. Administration → Connection Management
2. SQLite – Chinook (Sample) 선택
3. Delete 클릭

---

데이터베이스 연결

연결 추가

1. 상단 Connection 메뉴 클릭
2. New Connection 선택
3. 데이터베이스 타입 선택 (예: PostgreSQL)
4. 연결 정보 입력:

필드	예시 값
Host	postgres (컨테이너명)
Port	5432
Database	myapp
User	admin
Password	adminpassword

5. Test Connection 클릭하여 확인
6. Create 클릭

MySQL 연결 문제 해결

MySQL 8.0+에서 연결 오류가 발생하면:

-- MySQL에서 실행
ALTER USER 'username'@'%' IDENTIFIED WITH mysql_native_password BY 'password';
FLUSH PRIVILEGES;

또는 CloudBeaver에서 드라이버 속성 추가:

• allowPublicKeyRetrieval: true

---

사용자 관리

사용자 생성

1. Administration → Users
2. Add User
3. 정보 입력:
   • User ID: 사용자 ID
   • Password: 비밀번호
   • Role: 역할 선택

역할 (Roles)

역할	권한
admin	모든 권한
user	연결 사용, 쿼리 실행

연결 권한 설정

1. Administration → Connection Management
2. 연결 선택 → Edit
3. Access 탭에서 사용자/역할 권한 설정

---

SQL 에디터 사용

쿼리 실행

1. 연결 선택
2. SQL Editor 아이콘 클릭 (또는 우클릭 → SQL Editor)
3. SQL 입력
4. Execute (Ctrl+Enter) 클릭

자동 완성

• 테이블명, 컬럼명 자동 완성
• Ctrl+Space로 수동 트리거

키보드 단축키

단축키	기능
Ctrl+Enter	쿼리 실행
Ctrl+Shift+E	전체 스크립트 실행
Ctrl+Space	자동 완성
Ctrl+/	주석 토글
Ctrl+S	스크립트 저장

---

데이터 내보내기/가져오기

내보내기

1. 테이블 우클릭 → Export Data
2. 형식 선택:
   • CSV
   • JSON
   • XML
   • SQL Insert
3. 옵션 설정
4. Export 클릭

가져오기

1. 테이블 우클릭 → Import Data
2. 파일 선택
3. 매핑 확인
4. Import 클릭

---

설정 및 커스터마이징

워크스페이스 설정

설정 파일 위치: /opt/cloudbeaver/workspace/.data/.cloudbeaver.conf

{
    "server": {
        "serverPort": 8978,
        "serverName": "CloudBeaver",
        "expireSessionAfterPeriod": 1800000
    },
    "app": {
        "anonymousAccessEnabled": false,
        "supportsCustomConnections": true,
        "defaultNavigatorSettings": {
            "showSystemObjects": false,
            "showUtilityObjects": false
        }
    }
}

세션 타임아웃 변경

{
    "server": {
        "expireSessionAfterPeriod": 3600000
    }
}

---

백업

워크스페이스 백업

# 볼륨 백업
docker run --rm \
  -v cloudbeaver_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/cloudbeaver-backup.tar.gz -C /data .

복원

docker run --rm \
  -v cloudbeaver_data:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/cloudbeaver-backup.tar.gz -C /data

---

업데이트

cd ~/cloudbeaver

# 최신 이미지
docker compose pull

# 재시작
docker compose up -d

# 로그 확인
docker compose logs -f cloudbeaver

버전 확인

docker exec cloudbeaver cat /opt/cloudbeaver/conf/product.conf | grep version

---

트러블슈팅

일반적인 문제

WebSocket 연결 실패:

리버스 프록시 사용 시 WebSocket을 허용해야 합니다.

Nginx:

location / {
    proxy_pass http://cloudbeaver:8978;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

메모리 부족:

services:
  cloudbeaver:
    environment:
      - JAVA_OPTS=-Xmx2g

연결 타임아웃:

// .cloudbeaver.conf
{
    "server": {
        "database": {
            "pool": {
                "maxIdleTime": 600000
            }
        }
    }
}

로그 확인

# 컨테이너 로그
docker logs cloudbeaver -f

# 애플리케이션 로그
docker exec cloudbeaver cat /opt/cloudbeaver/workspace/.data/logs/cloudbeaver.log

---

보안

익명 접근 비활성화

초기 설정에서 Anonymous access를 비활성화하거나:

{
    "app": {
        "anonymousAccessEnabled": false
    }
}

HTTPS 사용

Traefik 또는 Nginx 리버스 프록시로 HTTPS를 적용합니다.

IP 제한

Traefik:

labels:
  - "traefik.http.middlewares.cloudbeaver-whitelist.ipwhitelist.sourcerange=192.168.1.0/24"
  - "traefik.http.routers.cloudbeaver.middlewares=cloudbeaver-whitelist"

---

사용 사례

1. 팀 데이터베이스 관리

• 중앙 집중식 연결 관리
• 역할 기반 접근 제어
• 연결 정보 공유

2. 원격 DB 접근

• 브라우저만으로 접근
• VPN 없이 안전한 접근
• 어디서나 동일한 환경

3. DBeaver 사용자

• 익숙한 인터페이스
• 데스크톱과 웹 연동
• 동일한 경험

---

마무리

CloudBeaver는 DBeaver 팀이 만든 강력한 웹 기반 데이터베이스 관리 도구입니다. 브라우저만 있으면 어디서든 다양한 데이터베이스를 관리할 수 있으며, 팀 협업 기능으로 엔터프라이즈 환경에 적합합니다.

핵심 장점

장점	설명
DBeaver 기반	검증된 DB 도구
다중 DB	20개 이상 DB 지원
웹 기반	설치 없이 브라우저로
팀 협업	사용자 관리, 연결 공유
모던 UI	React 기반 현대적 인터페이스

이런 분께 추천

DBeaver 사용자
팀 DB 관리가 필요한 분
웹 기반 도구를 원하는 분
엔터프라이즈 환경
다양한 DB를 사용하는 분

---