Skip to main content

설치

apt-key로 keyserver.ubuntu.com에서 GPG 키를 가져올 수 없습니다

apt-keyAdvanced package tool (APT)에서 더 이상 사용이 권장되지 않는 기능입니다. 대신 gpg 명령을 사용하십시오. 자세한 내용은 설치 가이드를 참조하십시오.

gpg로 keyserver.ubuntu.com에서 GPG 키를 가져오지 못하는 경우

  1. gpg가 설치되어 있는지 확인하세요:

apt-get으로 ClickHouse 리포지토리에서 deb 패키지를 가져올 수 없는 경우

  1. 방화벽 설정을 확인하세요.
  2. 어떤 이유로든 리포지토리에 접근할 수 없는 경우, 설치 가이드 문서의 안내에 따라 패키지를 다운로드한 뒤 sudo dpkg -i <packages> 명령으로 수동 설치하세요. tzdata 패키지도 필요합니다.

apt-get으로 ClickHouse 리포지토리의 deb 패키지를 업데이트할 수 없습니다

이 문제는 GPG 키가 변경된 경우 발생할 수 있습니다. 리포지토리 구성을 업데이트하려면 setup 페이지의 안내를 따르십시오.

apt-get update 실행 시 다양한 경고가 표시됩니다

표시되는 경고 메시지는 다음 중 하나입니다:
위 문제를 해결하려면 다음 스크립트를 사용하세요:

잘못된 서명으로 인해 Yum으로 패키지를 가져올 수 없음

가능한 원인: 캐시가 잘못되었거나, 2022-09에 GPG 키가 업데이트된 이후 손상되었을 수 있습니다. 해결 방법은 Yum의 캐시와 lib 디렉터리를 정리하는 것입니다:
이후 설치 가이드를 따르십시오

서버에 연결하기

발생할 수 있는 문제:
  • 서버가 실행되고 있지 않습니다.
  • 예기치 않거나 잘못된 구성 매개변수.

서버가 실행되고 있지 않습니다

서버가 실행 중인지 확인

서버가 실행 중이 아니면 다음 명령으로 시작하세요:

로그 확인

기본적으로 clickhouse-server의 기본 로그는 /var/log/clickhouse-server/clickhouse-server.log에 있습니다. 서버가 성공적으로 시작되면 다음 문자열이 표시됩니다:
  • <Information> Application: starting up. — 서버가 시작되었습니다.
  • <Information> Application: Ready for connections. — 서버가 실행 중이며 연결을 받을 준비가 되었습니다.
clickhouse-server가 구성 오류로 시작에 실패한 경우, 오류 설명과 함께 <Error> 문자열이 표시됩니다. 예시는 다음과 같습니다:
파일 끝에 오류가 보이지 않으면 다음 문자열이 나오는 지점부터 파일 전체를 살펴보십시오:
서버에서 clickhouse-server의 두 번째 인스턴스를 시작하려고 하면 다음과 같은 로그가 표시됩니다:

system.d 로그 보기

clickhouse-server 로그에서 유용한 정보를 찾지 못했거나 로그가 전혀 없는 경우, 다음 명령으로 system.d 로그를 확인할 수 있습니다:

대화형 모드로 clickhouse-server 시작하기

이 명령은 자동 시작 스크립트의 기본 매개변수를 사용해 server를 대화형 앱으로 시작합니다. 이 모드에서는 clickhouse-server가 모든 이벤트 메시지를 콘솔에 출력합니다.

구성 매개변수

다음을 확인하십시오:
  1. Docker 설정:
    • IPv6 네트워크에서 Docker로 ClickHouse를 실행하는 경우 network=host가 설정되어 있는지 확인하십시오.
  2. 엔드포인트 설정.
    • listen_hosttcp_port 설정을 확인하십시오.
    • ClickHouse 서버는 기본적으로 localhost에서의 연결만 허용합니다.
  3. HTTP 프로토콜 설정:
    • HTTP API의 프로토콜 설정을 확인하십시오.
  4. 보안 연결 설정.
    • 다음을 확인하십시오:
    • 연결할 때 올바른 매개변수를 사용하십시오. 예를 들어 clickhouse_client에서는 port_secure 매개변수를 사용하십시오.
  5. 사용자 설정:
    • 사용자 이름이나 비밀번호가 잘못되었을 수 있습니다.

쿼리 처리

ClickHouse가 쿼리를 처리하지 못하면 클라이언트에 오류 설명을 보냅니다. clickhouse-client에서는 콘솔에서 오류 설명을 확인할 수 있습니다. HTTP 인터페이스를 사용하는 경우 ClickHouse는 응답 본문에 오류 설명을 보냅니다. 예시는 다음과 같습니다:
stack-trace 매개변수를 사용해 clickhouse-client를 시작하면 ClickHouse는 오류 설명과 함께 서버 스택 트레이스를 반환합니다. 연결이 끊어졌다는 메시지가 표시될 수 있습니다. 이 경우 쿼리를 다시 실행할 수 있습니다. 쿼리를 실행할 때마다 연결이 끊어진다면 서버 로그에서 오류를 확인하십시오.

쿼리 처리 효율성

ClickHouse가 너무 느리게 작동하는 경우, 쿼리와 관련된 서버 리소스 및 네트워크 부하를 프로파일링해야 합니다. clickhouse-benchmark 유틸리티를 사용해 쿼리를 프로파일링할 수 있습니다. 이 유틸리티는 초당 처리되는 쿼리 수, 초당 처리되는 행 수, 그리고 쿼리 처리 시간의 백분위수를 보여줍니다.
마지막 수정일 2026년 7월 3일