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

# 문제 해결

> 설치 문제 해결 가이드

<div id="installation">
  ## 설치
</div>

<div id="cant-import-gpg-keys-from-keyserverubuntucom-with-apt-key">
  ### apt-key로 keyserver.ubuntu.com에서 GPG 키를 가져올 수 없습니다
</div>

`apt-key`는 [Advanced package tool (APT)에서 더 이상 사용이 권장되지 않는 기능입니다](https://manpages.debian.org/bookworm/apt/apt-key.8.en.html). 대신 `gpg` 명령을 사용하십시오. 자세한 내용은 [설치 가이드](/docs/ko/get-started/setup/install)를 참조하십시오.

<div id="cant-import-gpg-keys-from-keyserverubuntucom-with-gpg">
  ### gpg로 keyserver.ubuntu.com에서 GPG 키를 가져오지 못하는 경우
</div>

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

```shell theme={null}
sudo apt-get install gnupg
```

<div id="cant-get-deb-packages-from-clickhouse-repository-with-apt-get">
  ### apt-get으로 ClickHouse 리포지토리에서 deb 패키지를 가져올 수 없는 경우
</div>

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

<div id="cant-update-deb-packages-from-clickhouse-repository-with-apt-get">
  ### apt-get으로 ClickHouse 리포지토리의 deb 패키지를 업데이트할 수 없습니다
</div>

이 문제는 GPG 키가 변경된 경우 발생할 수 있습니다.

리포지토리 구성을 업데이트하려면 [setup](/docs/ko/get-started/setup/self-managed/debian-ubuntu) 페이지의 안내를 따르십시오.

<div id="you-get-different-warnings-with-apt-get-update">
  ### `apt-get update` 실행 시 다양한 경고가 표시됩니다
</div>

표시되는 경고 메시지는 다음 중 하나입니다:

```shell theme={null}
N: Skipping acquire of configured file 'main/binary-i386/Packages' as repository 'https://packages.clickhouse.com/deb stable InRelease' doesn't support architecture 'i386'
```

```shell theme={null}
E: Failed to fetch https://packages.clickhouse.com/deb/dists/stable/main/binary-amd64/Packages.gz  File has unexpected size (30451 != 28154). Mirror sync in progress?
```

```shell theme={null}
E: Repository 'https://packages.clickhouse.com/deb stable InRelease' changed its 'Origin' value from 'Artifactory' to 'ClickHouse'
E: Repository 'https://packages.clickhouse.com/deb stable InRelease' changed its 'Label' value from 'Artifactory' to 'ClickHouse'
N: Repository 'https://packages.clickhouse.com/deb stable InRelease' changed its 'Suite' value from 'stable' to ''
N: This must be accepted explicitly before updates for this repository can be applied. See apt-secure(8) manpage for details.
```

```shell theme={null}
Err:11 https://packages.clickhouse.com/deb stable InRelease
400  Bad Request [IP: 172.66.40.249 443]
```

위 문제를 해결하려면 다음 스크립트를 사용하세요:

```shell theme={null}
sudo rm /var/lib/apt/lists/packages.clickhouse.com_* /var/lib/dpkg/arch /var/lib/apt/lists/partial/packages.clickhouse.com_*
sudo apt-get clean
sudo apt-get autoclean
```

<div id="cant-get-packages-with-yum-because-of-wrong-signature">
  ### 잘못된 서명으로 인해 Yum으로 패키지를 가져올 수 없음
</div>

가능한 원인: 캐시가 잘못되었거나, 2022-09에 GPG 키가 업데이트된 이후 손상되었을 수 있습니다.

해결 방법은 Yum의 캐시와 lib 디렉터리를 정리하는 것입니다:

```shell theme={null}
sudo find /var/lib/yum/repos/ /var/cache/yum/ -name 'clickhouse-*' -type d -exec rm -rf {} +
sudo rm -f /etc/yum.repos.d/clickhouse.repo
```

이후 [설치 가이드](/docs/ko/get-started/setup/self-managed/redhat)를 따르십시오

<div id="connecting-to-the-server">
  ## 서버에 연결하기
</div>

발생할 수 있는 문제:

* 서버가 실행되고 있지 않습니다.
* 예기치 않거나 잘못된 구성 매개변수.

<div id="server-is-not-running">
  ### 서버가 실행되고 있지 않습니다
</div>

<div id="check-if-server-is-running">
  #### 서버가 실행 중인지 확인
</div>

```shell theme={null}
sudo service clickhouse-server status
```

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

```shell theme={null}
sudo service clickhouse-server start
```

<div id="check-the-logs">
  #### 로그 확인
</div>

기본적으로 `clickhouse-server`의 기본 로그는 `/var/log/clickhouse-server/clickhouse-server.log`에 있습니다.

서버가 성공적으로 시작되면 다음 문자열이 표시됩니다:

* `<Information> Application: starting up.` — 서버가 시작되었습니다.
* `<Information> Application: Ready for connections.` — 서버가 실행 중이며 연결을 받을 준비가 되었습니다.

`clickhouse-server`가 구성 오류로 시작에 실패한 경우, 오류 설명과 함께 `<Error>` 문자열이 표시됩니다. 예시는 다음과 같습니다:

```plaintext theme={null}
2019.01.11 15:23:25.549505 [ 45 ] {} <Error> ExternalDictionaries: Failed reloading 'event2id' external dictionary: Poco::Exception. Code: 1000, e.code() = 111, e.displayText() = Connection refused, e.what() = Connection refused
```

파일 끝에 오류가 보이지 않으면 다음 문자열이 나오는 지점부터 파일 전체를 살펴보십시오:

```plaintext theme={null}
<Information> Application: starting up.
```

서버에서 `clickhouse-server`의 두 번째 인스턴스를 시작하려고 하면 다음과 같은 로그가 표시됩니다:

```plaintext theme={null}
2019.01.11 15:25:11.151730 [ 1 ] {} <Information> : Starting ClickHouse 19.1.0 with revision 54413
2019.01.11 15:25:11.154578 [ 1 ] {} <Information> Application: starting up
2019.01.11 15:25:11.156361 [ 1 ] {} <Information> StatusFile: Status file ./status already exists - unclean restart. Contents:
PID: 8510
Started at: 2019-01-11 15:24:23
Revision: 54413

2019.01.11 15:25:11.156673 [ 1 ] {} <Error> Application: DB::Exception: Cannot lock file ./status. Another server instance in same directory is already running.
2019.01.11 15:25:11.156682 [ 1 ] {} <Information> Application: shutting down
2019.01.11 15:25:11.156686 [ 1 ] {} <Debug> Application: Uninitializing subsystem: Logging Subsystem
2019.01.11 15:25:11.156716 [ 2 ] {} <Information> BaseDaemon: Stop SignalListener thread
```

<div id="see-systemd-logs">
  #### system.d 로그 보기
</div>

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

```shell theme={null}
sudo journalctl -u clickhouse-server
```

<div id="start-clickhouse-server-in-interactive-mode">
  #### 대화형 모드로 clickhouse-server 시작하기
</div>

```shell theme={null}
sudo -u clickhouse /usr/bin/clickhouse-server --config-file /etc/clickhouse-server/config.xml
```

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

<div id="configuration-parameters">
  ### 구성 매개변수
</div>

다음을 확인하십시오:

1. Docker 설정:

   * IPv6 네트워크에서 Docker로 ClickHouse를 실행하는 경우 `network=host`가 설정되어 있는지 확인하십시오.

2. 엔드포인트 설정.
   * [listen\_host](/docs/ko/reference/settings/server-settings/settings#listen_host) 및 [tcp\_port](/docs/ko/reference/settings/server-settings/settings#tcp_port) 설정을 확인하십시오.
   * ClickHouse 서버는 기본적으로 localhost에서의 연결만 허용합니다.

3. HTTP 프로토콜 설정:

   * HTTP API의 프로토콜 설정을 확인하십시오.

4. 보안 연결 설정.

   * 다음을 확인하십시오:
     * [tcp\_port\_secure](/docs/ko/reference/settings/server-settings/settings#tcp_port_secure) 설정
     * [SSL certificates](/docs/ko/reference/settings/server-settings/settings#openssl) 설정
   * 연결할 때 올바른 매개변수를 사용하십시오. 예를 들어 `clickhouse_client`에서는 `port_secure` 매개변수를 사용하십시오.

5. 사용자 설정:

   * 사용자 이름이나 비밀번호가 잘못되었을 수 있습니다.

<div id="query-processing">
  ## 쿼리 처리
</div>

ClickHouse가 쿼리를 처리하지 못하면 클라이언트에 오류 설명을 보냅니다. `clickhouse-client`에서는 콘솔에서 오류 설명을 확인할 수 있습니다. HTTP 인터페이스를 사용하는 경우 ClickHouse는 응답 본문에 오류 설명을 보냅니다. 예시는 다음과 같습니다:

```shell theme={null}
$ curl 'http://localhost:8123/' --data-binary "SELECT a"
Code: 47, e.displayText() = DB::Exception: Unknown identifier: a. Note that there are no tables (FROM clause) in your query, context: required_names: 'a' source_tables: table_aliases: private_aliases: column_aliases: public_columns: 'a' masked_columns: array_join_columns: source_columns: , e.what() = DB::Exception
```

`stack-trace` 매개변수를 사용해 `clickhouse-client`를 시작하면 ClickHouse는 오류 설명과 함께 서버 스택 트레이스를 반환합니다.

연결이 끊어졌다는 메시지가 표시될 수 있습니다. 이 경우 쿼리를 다시 실행할 수 있습니다. 쿼리를 실행할 때마다 연결이 끊어진다면 서버 로그에서 오류를 확인하십시오.

<div id="efficiency-of-query-processing">
  ## 쿼리 처리 효율성
</div>

ClickHouse가 너무 느리게 작동하는 경우, 쿼리와 관련된 서버 리소스 및 네트워크 부하를 프로파일링해야 합니다.

`clickhouse-benchmark` 유틸리티를 사용해 쿼리를 프로파일링할 수 있습니다. 이 유틸리티는 초당 처리되는 쿼리 수, 초당 처리되는 행 수, 그리고 쿼리 처리 시간의 백분위수를 보여줍니다.