feat: 更新 Kvrocks 配置，使用预构建 Docker 镜像并添加故障排除指南

2025-09-03 21:09:38 +08:00
parent ae22119708
commit 981137afe9
5 changed files with 203 additions and 3 deletions
@@ -6,8 +6,7 @@
 NEXT_PUBLIC_STORAGE_TYPE=kvrocks

 # Kvrocks 连接配置
-KVROCKS_URL=redis://localhost:6666
-# KVROCKS_URL=redis://kvrocks:6666  # Docker 部署时使用此配置
+KVROCKS_URL=redis://kvrocks:6666
 KVROCKS_PASSWORD=your_secure_password_here
 KVROCKS_DATABASE=0

@@ -0,0 +1,124 @@
+# Docker + Kvrocks 部署故障排除指南
+
+## 🐛 常见问题及解决方案
+
+### 问题一：`failed to read dockerfile: open Dockerfile: no such file or directory`
+
+**症状**：
+
+```bash
+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
+- 但部署文档只让下载配置文件，没有下载源代码
+
+**解决方案**：
+
+#### 方案一：使用预构建镜像（推荐）
+
+```bash
+# 重新下载最新版本的配置文件
+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`，无需本地构建。
+
+#### 方案二：本地构建
+
+如果想要从源代码构建：
+
+```bash
+# 克隆完整源代码
+git clone https://github.com/katelya77/KatelyaTV.git
+cd KatelyaTV
+
+# 使用本地构建版本
+docker compose -f docker-compose.kvrocks.local.yml up -d
+```
+
+### 问题二：Kvrocks 连接失败
+
+**症状**：
+
+```bash
+# 应用日志显示连接 Kvrocks 失败
+Error: connect ECONNREFUSED
+```
+
+**解决方案**：
+
+1. 检查 `.env` 文件中的 `KVROCKS_URL` 是否正确：
+
+   ```bash
+   KVROCKS_URL=redis://kvrocks:6666
+   ```
+
+2. 确保 Kvrocks 服务正常运行：
+
+   ```bash
+   docker compose -f docker-compose.kvrocks.yml ps
+   ```
+
+3. 测试 Kvrocks 连接：
+   ```bash
+   docker compose -f docker-compose.kvrocks.yml exec kvrocks redis-cli -h localhost -p 6666 ping
+   ```
+
+### 问题三：环境变量配置错误
+
+**常见错误**：
+
+- `NEXTAUTH_SECRET` 未设置
+- `KVROCKS_PASSWORD` 不匹配
+
+**解决方案**：
+检查 `.env` 文件，确保所有必要变量都已正确配置：
+
+```bash
+# 必须配置的变量
+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
+```
+
+## 🔧 调试命令
+
+```bash
+# 查看服务状态
+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
+```
+
+## 📞 获取帮助
+
+如果以上方案都无法解决问题，请：
+
+1. 提供完整的错误日志
+2. 说明使用的配置文件版本
+3. 提供系统环境信息（操作系统、Docker 版本等）
+
+---
+
+**文档版本**：v0.6.0-katelya  
+**更新日期**：2025 年 9 月 3 日
@@ -391,6 +391,8 @@ curl -O https://raw.githubusercontent.com/katelya77/KatelyaTV/main/.env.kvrocks.
 cp .env.kvrocks.example .env
 ```

+> **📌 重要说明**：此配置使用预构建的 Docker 镜像 (`ghcr.io/katelya77/katelyatv:latest`)，无需下载源代码。镜像会自动从 GitHub Container Registry 拉取。
+
 #### 第二步：配置环境变量

 ```bash
@@ -434,6 +436,21 @@ docker compose -f docker-compose.kvrocks.yml exec kvrocks redis-cli -h localhost
 docker compose -f docker-compose.kvrocks.yml logs -f
 ```

+### 🔧 高级选项：本地构建
+
+如果你想要从源代码本地构建而不是使用预构建镜像，可以：
+
+```bash
+# 克隆完整源代码
+git clone https://github.com/katelya77/KatelyaTV.git
+cd KatelyaTV
+
+# 使用本地构建版本的配置
+docker compose -f docker-compose.kvrocks.local.yml up -d
+```
+
+> **注意**：本地构建需要下载完整源代码，首次构建时间较长，但可以自定义修改代码。
+
 #### 第五步：访问应用

 1. 浏览器访问：`http://你的服务器IP:3000`
@@ -0,0 +1,60 @@
+version: '3.8'
+
+services:
+  # KatelyaTV 应用服务（本地构建版本）
+  katelyatv:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      # 数据库配置 - 使用 Kvrocks
+      NEXT_PUBLIC_STORAGE_TYPE: kvrocks
+      KVROCKS_URL: redis://kvrocks:6666
+      KVROCKS_PASSWORD: ${KVROCKS_PASSWORD:-}
+      KVROCKS_DATABASE: 0
+      
+      # 其他必要的环境变量
+      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}
+      NEXTAUTH_URL: ${NEXTAUTH_URL:-http://localhost:3000}
+    depends_on:
+      - kvrocks
+    restart: unless-stopped
+    networks:
+      - katelyatv-network
+
+  # Kvrocks 数据库服务
+  kvrocks:
+    image: apache/kvrocks:latest
+    ports:
+      - "6666:6666"
+    environment:
+      # Kvrocks 配置
+      KVROCKS_BIND: 0.0.0.0
+      KVROCKS_PORT: 6666
+      KVROCKS_DIR: /var/lib/kvrocks/data
+      KVROCKS_LOG_LEVEL: info
+      # 可选：设置密码
+      KVROCKS_REQUIREPASS: ${KVROCKS_PASSWORD:-}
+    volumes:
+      # 持久化数据存储
+      - kvrocks-data:/var/lib/kvrocks/data
+      # 可选：挂载配置文件
+      - ./docker/kvrocks/kvrocks.conf:/etc/kvrocks/kvrocks.conf:ro
+    restart: unless-stopped
+    networks:
+      - katelyatv-network
+    healthcheck:
+      test: ["CMD", "redis-cli", "-h", "localhost", "-p", "6666", "ping"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+
+volumes:
+  # Kvrocks 数据卷
+  kvrocks-data:
+    driver: local
+
+networks:
+  katelyatv-network:
+    driver: bridge
@@ -3,7 +3,7 @@ version: '3.8'
 services:
  # KatelyaTV 应用服务
  katelyatv:
-    build: .
+    image: ghcr.io/katelya77/katelyatv:latest
    ports:
      - "3000:3000"
    environment: