故障排查

本章节介绍 MatrixHub 部署中的常见问题及排查方法。

---

1. 数据库问题

默认 Docker Compose 部署使用 SQLite。如果出现 database is locked，请确认只有一个 MatrixHub 实例使用该数据库，并确保 ./data/matrixhub 位于本地文件系统。

对于可选的 MySQL 部署，请检查 MySQL 容器的状态和日志：

docker compose -f docker-compose.mysql.yml ps mysql
docker compose -f docker-compose.mysql.yml logs mysql

如果 MySQL 容器已经停止，可以重新启动：

docker compose -f docker-compose.mysql.yml restart mysql

MySQL 版本使用服务名 mysql 连接数据库，账号和密码由 docker-compose.mysql.yml 中的环境变量配置。

---

2. 端口冲突

MatrixHub 默认映射到宿主机端口 3001。如果启动时提示端口已被占用，通过 MATRIXHUB_HTTP_PORT 修改宿主机端口：

MATRIXHUB_HTTP_PORT=3002 docker compose up -d

修改后通过 http://127.0.0.1:3002 访问 MatrixHub。

---

3. 服务健康检查

如果部署完成后无法访问 MatrixHub，可以先检查 API Server 是否正在响应：

curl -i http://localhost:3001/healthz

正常响应为 HTTP 200，响应正文为 OK。该接口只表示 API Server 正在运行，不检查数据库等依赖组件的状态。