# Kvrocks 部署指南

本文档介绍如何使用 Docker + Kvrocks 部署 KatelyaTV。

> **⚠️ 重要提醒**：Kvrocks 部署需要配置管理员账号（`USERNAME` 和 `PASSWORD`），否则会出现"页面显示账号密码登录但无法登录"的问题！

## 🚀 快速开始

### 方案一：无密码部署（推荐用于开发环境）

1. **准备环境变量文件**

```bash
# 复制环境变量示例文件
cp .env.kvrocks.example .env

# 编辑环境变量
nano .env
```

2. **环境变量配置**

```bash
# 数据库配置
NEXT_PUBLIC_STORAGE_TYPE=kvrocks
KVROCKS_URL=redis://kvrocks:6666
# 不设置 Kvrocks 密码
# KVROCKS_PASSWORD=
KVROCKS_DATABASE=0

# 管理员账号配置（必填！）
USERNAME=admin
PASSWORD=your_admin_password

# 用户注册配置
NEXT_PUBLIC_ENABLE_REGISTER=true

# 应用配置
NEXTAUTH_SECRET=your_nextauth_secret_here
NEXTAUTH_URL=http://localhost:3000
```

3. **启动服务**

```bash
docker-compose -f docker-compose.kvrocks.yml up -d
```

### 方案二：密码认证部署（推荐用于生产环境）

1. **准备环境变量文件**

```bash
# 复制环境变量示例文件
cp .env.kvrocks.example .env

# 编辑环境变量
nano .env
```

2. **环境变量配置**

```bash
# 数据库配置
NEXT_PUBLIC_STORAGE_TYPE=kvrocks
KVROCKS_URL=redis://kvrocks:6666
# 设置强密码
KVROCKS_PASSWORD=your_secure_password_here
KVROCKS_DATABASE=0

# 应用配置
NEXTAUTH_SECRET=your_nextauth_secret_here
NEXTAUTH_URL=http://localhost:3000
```

3. **启动服务**

```bash
docker-compose -f docker-compose.kvrocks.auth.yml up -d
```

## 🔧 故障排除

### 问题 1：页面显示账号密码登录但无法登录

**现象：**

- 部署后页面显示用户名+密码登录界面
- 但是只配置了 `PASSWORD` 环境变量
- 无法登录或提示"用户名或密码错误"

**原因：**

- Kvrocks 部署属于多用户模式，需要配置管理员账号
- 缺少 `USERNAME` 环境变量导致系统无法识别管理员

**解决方案：**

```bash
# 在 .env 文件中添加管理员账号配置
USERNAME=admin
PASSWORD=your_admin_password
NEXT_PUBLIC_ENABLE_REGISTER=true
```

### 问题 2：密码认证错误

```
❌ Kvrocks Client Error: [Error]: ERR Client sent AUTH, but no password is set
```

**解决方案：**

- 确保使用正确的 docker-compose 文件
- 检查环境变量 `KVROCKS_PASSWORD` 的设置
- 无密码部署使用：`docker-compose.kvrocks.yml`
- 密码认证部署使用：`docker-compose.kvrocks.auth.yml`

### 问题 3：连接超时

```
❌ Failed to connect to Kvrocks: connect ECONNREFUSED
```

**解决方案：**

1. 检查 Kvrocks 服务是否正常启动

```bash
docker-compose logs kvrocks
```

2. 检查网络连接

```bash
docker-compose exec katelyatv ping kvrocks
```

3. 检查端口映射

```bash
docker-compose ps
```

### 问题 3：数据持久化问题

**解决方案：**

1. 确保数据卷正确挂载

```bash
docker volume ls | grep kvrocks
```

2. 检查数据目录权限

```bash
docker-compose exec kvrocks ls -la /var/lib/kvrocks/data
```

## 📊 健康检查

### 检查服务状态

```bash
# 查看所有服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 检查 Kvrocks 连接
docker-compose exec kvrocks redis-cli -p 6666 ping
```

### 性能监控

```bash
# 查看 Kvrocks 信息
docker-compose exec kvrocks redis-cli -p 6666 info

# 查看内存使用
docker-compose exec kvrocks redis-cli -p 6666 info memory

# 查看连接数
docker-compose exec kvrocks redis-cli -p 6666 info clients
```

## 🔒 安全建议

1. **生产环境必须设置密码**
2. **定期备份数据**
3. **限制网络访问**
4. **监控日志异常**

## 📁 文件结构

```
project/
├── docker-compose.kvrocks.yml         # 无密码部署配置
├── docker-compose.kvrocks.auth.yml    # 密码认证部署配置
├── .env.kvrocks.example               # 环境变量示例
├── docker/
│   └── kvrocks/
│       ├── kvrocks.conf               # 无密码配置文件
│       └── kvrocks.auth.conf          # 密码认证配置文件
└── .env                               # 实际环境变量（需要创建）
```

## 🆘 获取帮助

如果遇到问题，请：

1. 检查日志：`docker-compose logs -f`
2. 验证环境变量：`docker-compose config`
3. 重启服务：`docker-compose restart`
4. 重新构建：`docker-compose up -d --force-recreate`