最近在打开 Kuboard 时，遇到如下报错页面：

{
"message": "Failed to connect to the database.",
"type": "Internal Server Error"
}

这个问题导致 Kuboard 无法访问任何页面。下面记录整个排查和解决过程，希望对遇到类似问题的有所帮助。
一、初步分析

从报错来看，Kuboard 提示无法连接数据库，而 Kuboard 使用的数据库是 etcd。
因此首先需要确认 etcd 的运行状态。

进入Kuboard容器后执行以下命令查看 etcd 状态：

> etcdctl endpoint status --write-out=table

输出如下：
+----------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------------------------------+
| ENDPOINT | ID | VERSION | DB SIZE | IS LEADER | IS LEARNER | RAFT TERM | RAFT INDEX | RAFT APPLIED INDEX | ERRORS |
+----------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------------------------------+
| 127.0.0.1:2379 | 59a9c584ea2c3f35 | 3.4.14 | 2.1 GB | true | false | 2 | 6181988 | 6181988 | alarm:NOSPACE |
+----------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------------------------------+
可以看到 DB SIZE 已经达到 2.1 GB，并且出现 alarm:NOSPACE 警告，这意味着 etcd 数据库空间已满。

二、查看日志确认问题

进入 Kuboard 容器查看日志，可以发现明显的错误信息：
{"level":"warn","ts":"2025-10-10T10:30:36.096+0800","caller":"clientv3/retry_interceptor.go:61",
"msg":"retrying of unary invoker failed",
"target":"endpoint://client-214e73fd-ea50-45ad-9528-cf3863fe3916/127.0.0.1:2379",
"attempt":0,
"error":"rpc error: code = ResourceExhausted desc = etcdserver: mvcc: database space exceeded"}

time="2025-10-10T02:30:36Z" level=error msg="Storage health check failed: create auth request: etcdserver: mvcc: database space exceeded"
从日志可以确认，etcd 的数据库空间已经耗尽，导致 Kuboard 无法写入数据，从而报错连接数据库失败。
三、解决步骤

  1. 查看当前 revision
    进入容器后执行：
ETCDCTL_API=3 etcdctl endpoint status --write-out=json | jq -r '.[0].Status.header.revision'

输出示例：6150910
这就是当前 etcd 的最新 revision。
2. 压缩数据库

使用 compact 命令压缩数据库，删除历史版本：

ETCDCTL_API=3 etcdctl compact 6150910

执行成功后输出compacted revision 6150910
3. 碎片整理（Defrag）

压缩完成后，为了释放磁盘空间，执行碎片整理：

ETCDCTL_API=3 etcdctl defrag

输出：Finished defragmenting etcd member[127.0.0.1:2379]
4. 检查状态

再次查看 etcd 状态，确认 DB SIZE 已明显下降：

ETCDCTL_API=3 etcdctl endpoint status --write-out=table

+----------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
| ENDPOINT | ID | VERSION | DB SIZE | IS LEADER | IS LEARNER | RAFT TERM | RAFT INDEX | RAFT APPLIED INDEX | ERRORS |
+----------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
| 127.0.0.1:2379 | 59a9c584ea2c3f35 | 3.4.14 | 111 kB | true | false | 2 | 6182370 | 6182370 | |
+----------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
至此，etcd 数据库空间问题得到解决。
5. 清理告警（可选）

查看 etcd 告警：

ETCDCTL_API=3 etcdctl alarm list

如果之前有 NOSPACE 告警，会自动消失。
四、结果验证

完成压缩和碎片整理后，重新访问 Kuboard：

页面可以正常打开

数据库连接正常

日志中不再出现 ResourceExhausted 报错
五、总结

本次 Kuboard 无法连接数据库的根本原因是 etcd 数据库空间耗尽。

解决方案总结：

查看 etcd 状态，确认 DB SIZE 和 alarm。

获取最新 revision。

执行 etcdctl compact 压缩数据库。

执行 etcdctl defrag 释放磁盘空间。

验证 Kuboard 是否恢复正常。

💡 小技巧

定期检查 etcd 数据库大小，避免空间耗尽。

对于历史数据量大的集群，可以考虑定期压缩和碎片整理。

配置合理的 etcd 数据目录磁盘大小，防止生产环境中因空间不足导致服务不可用。