> ## 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>

[Advanced package tool (APT) 中的 `apt-key` 功能已被弃用](https://manpages.debian.org/bookworm/apt/apt-key.8.en.html)。请改用 `gpg` 命令。请参阅[安装指南](/docs/zh/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/zh/get-started/setup/install)中的说明下载软件包，并使用 `sudo dpkg -i <packages>` 命令手动安装。你还需要安装 `tzdata` 软件包。

<div id="cant-update-deb-packages-from-clickhouse-repository-with-apt-get">
  ### 无法通过 apt-get 从软件源更新 deb 软件包
</div>

更换 GPG 密钥后，可能会出现此问题。

请按照 [setup](/docs/zh/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/zh/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`。

如果 server 成功启动，你应该会看到以下内容：

* `<Information> Application: starting up.` — server 已启动。
* `<Information> Application: Ready for connections.` — server 正在运行，并已准备好接受连接。

如果 `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
```

此命令会以交互式应用的方式启动服务器，并使用自动启动脚本的标准参数。在这种模式下，`clickhouse-server` 会在控制台打印所有事件消息。

<div id="configuration-parameters">
  ### 配置参数
</div>

检查：

1. Docker 设置：

   * 如果您在 IPv6 网络中的 Docker 容器里运行 ClickHouse，请确保已设置 `network=host`。

2. 端点设置。
   * 检查 [listen\_host](/docs/zh/reference/settings/server-settings/settings#listen_host) 和 [tcp\_port](/docs/zh/reference/settings/server-settings/settings#tcp_port) 设置。
   * 默认情况下，ClickHouse server 仅接受来自 localhost 的连接。

3. HTTP protocol 设置：

   * 检查 HTTP API 的协议设置。

4. 安全连接设置。

   * 检查：
     * [tcp\_port\_secure](/docs/zh/reference/settings/server-settings/settings#tcp_port_secure) 设置。
     * [SSL certificates](/docs/zh/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` 工具来分析查询。它会显示每秒处理的查询数、每秒处理的行数，以及查询处理时间的各分位数。