From 981137afe9e450beac45a46f191a1a568a829c0f Mon Sep 17 00:00:00 2001
From: katelya <katelya77@gmail.com>
Date: Wed, 3 Sep 2025 21:09:38 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=9B=B4=E6=96=B0=20Kvrocks=20?=
 =?UTF-8?q?=E9=85=8D=E7=BD=AE=EF=BC=8C=E4=BD=BF=E7=94=A8=E9=A2=84=E6=9E=84?=
 =?UTF-8?q?=E5=BB=BA=20Docker=20=E9=95=9C=E5=83=8F=E5=B9=B6=E6=B7=BB?=
 =?UTF-8?q?=E5=8A=A0=E6=95=85=E9=9A=9C=E6=8E=92=E9=99=A4=E6=8C=87=E5=8D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .env.kvrocks.example             |   3 +-
 DOCKER_TROUBLESHOOTING.md        | 124 +++++++++++++++++++++++++++++++
 README.md                        |  17 +++++
 docker-compose.kvrocks.local.yml |  60 +++++++++++++++
 docker-compose.kvrocks.yml       |   2 +-
 5 files changed, 203 insertions(+), 3 deletions(-)
 create mode 100644 DOCKER_TROUBLESHOOTING.md
 create mode 100644 docker-compose.kvrocks.local.yml

diff --git a/.env.kvrocks.example b/.env.kvrocks.example
index 12d236e..e24ad9b 100644
--- a/.env.kvrocks.example
+++ b/.env.kvrocks.example
@@ -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
 
diff --git a/DOCKER_TROUBLESHOOTING.md b/DOCKER_TROUBLESHOOTING.md
new file mode 100644
index 0000000..68f6df5
--- /dev/null
+++ b/DOCKER_TROUBLESHOOTING.md
@@ -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 日
diff --git a/README.md b/README.md
index 1bfb6a5..39b2636 100644
--- a/README.md
+++ b/README.md
@@ -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`
diff --git a/docker-compose.kvrocks.local.yml b/docker-compose.kvrocks.local.yml
new file mode 100644
index 0000000..d6ed402
--- /dev/null
+++ b/docker-compose.kvrocks.local.yml
@@ -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
diff --git a/docker-compose.kvrocks.yml b/docker-compose.kvrocks.yml
index 431188f..9c5b433 100644
--- a/docker-compose.kvrocks.yml
+++ b/docker-compose.kvrocks.yml
@@ -3,7 +3,7 @@ version: '3.8'
 services:
   # KatelyaTV 应用服务
   katelyatv:
-    build: .
+    image: ghcr.io/katelya77/katelyatv:latest
     ports:
       - "3000:3000"
     environment: