Docker + Kvrocks 部署故障排除指南

🐛 常见问题及解决方案

问题一：`failed to read dockerfile: open Dockerfile: no such file or directory`

症状：

docker compose -f docker-compose.kvrocks.yml up -d
# 报错：failed to read dockerfile: open Dockerfile: no such file or directory

原因：

使用了旧版本的 docker-compose.kvrocks.yml 文件
旧版本使用 build: . 需要完整源代码和 Dockerfile
但部署文档只让下载配置文件，没有下载源代码

解决方案：

方案一：使用预构建镜像（推荐）

# 重新下载最新版本的配置文件
curl -O https://raw.githubusercontent.com/katelya77/KatelyaTV/main/docker-compose.kvrocks.yml

# 启动服务
docker compose -f docker-compose.kvrocks.yml up -d

最新版本使用 image: ghcr.io/katelya77/katelyatv:latest，无需本地构建。

方案二：本地构建

如果想要从源代码构建：

# 克隆完整源代码
git clone https://github.com/katelya77/KatelyaTV.git
cd KatelyaTV

# 使用本地构建版本
docker compose -f docker-compose.kvrocks.local.yml up -d

问题二：Kvrocks 连接失败

症状：

# 应用日志显示连接 Kvrocks 失败
Error: connect ECONNREFUSED

解决方案：

检查 .env 文件中的 KVROCKS_URL 是否正确：
```
KVROCKS_URL=redis://kvrocks:6666
```

确保 Kvrocks 服务正常运行：

docker compose -f docker-compose.kvrocks.yml ps

测试 Kvrocks 连接：

docker compose -f docker-compose.kvrocks.yml exec kvrocks redis-cli -h localhost -p 6666 ping

问题三：环境变量配置错误

常见错误：

NEXTAUTH_SECRET 未设置
KVROCKS_PASSWORD 不匹配

解决方案：检查 .env 文件，确保所有必要变量都已正确配置：

# 必须配置的变量
NEXT_PUBLIC_STORAGE_TYPE=kvrocks
KVROCKS_URL=redis://kvrocks:6666
KVROCKS_PASSWORD=your_secure_password_here
NEXTAUTH_SECRET=your_nextauth_secret_here
NEXTAUTH_URL=http://localhost:3000

🔧 调试命令

# 查看服务状态
docker compose -f docker-compose.kvrocks.yml ps

# 查看应用日志
docker compose -f docker-compose.kvrocks.yml logs -f katelyatv

# 查看 Kvrocks 日志
docker compose -f docker-compose.kvrocks.yml logs -f kvrocks

# 进入容器调试
docker compose -f docker-compose.kvrocks.yml exec katelyatv sh

# 重建服务
docker compose -f docker-compose.kvrocks.yml up -d --force-recreate

📞 获取帮助

如果以上方案都无法解决问题，请：

提供完整的错误日志
说明使用的配置文件版本
提供系统环境信息（操作系统、Docker 版本等）

文档版本：v0.6.0-katelya
更新日期：2025 年 9 月 3 日

2.8 KiB Raw Blame History Unescape Escape