# AI-RAG Docker 外挂配置指南

本文档详细说明如何将 AI-RAG 项目打包成 Docker 镜像时，将数据库和存储进行外挂配置，以实现数据持久化和灵活部署。

## 1. 现有 Docker 配置分析

### 1.1 基础镜像信息

- 基础镜像：`ghcr.io/1panel-dev/maxkb-base:python3.11-pg17.6`
- 包含 PostgreSQL 17.6 和 Redis
- 暴露端口：8080
- 卷挂载：`/opt/maxkb`

### 1.2 默认配置

| 环境变量 | 默认值 | 说明 |
|---------|-------|------|
| MAXKB_DB_HOST | 127.0.0.1 | 数据库主机地址 |
| MAXKB_DB_PORT | 5432 | 数据库端口 |
| MAXKB_DB_NAME | maxkb | 数据库名称 |
| MAXKB_DB_USER | ${POSTGRES_USER} | 数据库用户名 |
| MAXKB_DB_PASSWORD | ${POSTGRES_PASSWORD} | 数据库密码 |
| MAXKB_REDIS_HOST | 127.0.0.1 | Redis 主机地址 |
| MAXKB_REDIS_PORT | 6379 | Redis 端口 |
| MAXKB_EMBEDDING_MODEL_PATH | /opt/maxkb-app/model/embedding | 嵌入模型路径 |
| MAXKB_EMBEDDING_MODEL_NAME | /opt/maxkb-app/model/embedding/shibing624_text2vec-base-chinese | 嵌入模型名称 |

### 1.3 镜像打包

1. docker build -f installer/Dockerfile -t maxkb:latest

## 2. 数据库外挂配置

### 2.1 使用外部 PostgreSQL 数据库

#### 步骤 1: 准备外部数据库

1. 安装并启动 PostgreSQL 数据库（建议版本 14+）
2. 创建数据库和用户：

```sql
CREATE DATABASE maxkb;
CREATE USER maxkb_user WITH PASSWORD 'your_strong_password';
GRANT ALL PRIVILEGES ON DATABASE maxkb TO maxkb_user;
```

#### 步骤 2: 配置 Docker 容器

使用 `docker run` 命令时，通过环境变量指定外部数据库配置：
##### 2.1：简单目录挂载
```
docker run -d \
  --name maxkb \
  -p 8080:8080 \
  -v /path/to/maxkb:/opt/maxkb \
  -v /path/to/postgres/data:/var/lib/postgresql/data \
  -v /path/to/redis/data:/data \
  your_maxkb_image:tag
```
##### 2.2：外部数据库挂载
```bash
docker run -d \
  --name maxkb \
  -p 8080:8080 \
  -v /path/to/maxkb:/opt/maxkb \
  -e MAXKB_DB_HOST=your_database_host \
  -e MAXKB_DB_PORT=5432 \
  -e MAXKB_DB_NAME=maxkb \
  -e MAXKB_DB_USER=maxkb_user \
  -e MAXKB_DB_PASSWORD=your_strong_password \
  your_maxkb_image:tag
```

### 2.2 使用外部 Redis

#### 步骤 1: 准备外部 Redis

1. 安装并启动 Redis 服务
2. 配置 Redis 密码（可选）

#### 步骤 2: 配置 Docker 容器

```bash
docker run -d \
  --name maxkb \
  -p 8080:8080 \
  -v /path/to/maxkb:/opt/maxkb \
  -e MAXKB_REDIS_HOST=your_redis_host \
  -e MAXKB_REDIS_PORT=6379 \
  -e MAXKB_REDIS_PASSWORD=your_redis_password \
  your_maxkb_image:tag
```

## 3. 存储外挂配置

### 3.1 基础存储挂载

MaxKB 默认会在 `/opt/maxkb` 目录下创建以下子目录：
- `logs`: 日志文件
- `local`: 本地存储
- `python-packages`: Python 包

#### 挂载方式

```bash
docker run -d \
  --name maxkb \
  -p 8080:8080 \
  -v /path/to/maxkb:/opt/maxkb \
  your_maxkb_image:tag
```

### 3.2 模型文件外挂

#### 步骤 1: 准备模型目录

```bash
mkdir -p /path/to/maxkb/model/embedding
```

#### 步骤 2: 下载模型文件

将嵌入模型文件下载到准备好的目录中，例如：
- `shibing624_text2vec-base-chinese`

#### 步骤 3: 配置 Docker 容器

```bash
docker run -d \
  --name maxkb \
  -p 8080:8080 \
  -v /path/to/maxkb:/opt/maxkb \
  -v /path/to/maxkb/model:/opt/maxkb-app/model \
  -e MAXKB_EMBEDDING_MODEL_PATH=/opt/maxkb-app/model/embedding \
  -e MAXKB_EMBEDDING_MODEL_NAME=/opt/maxkb-app/model/embedding/shibing624_text2vec-base-chinese \
  your_maxkb_image:tag
```

### 3.3 静态文件外挂

如果需要自定义静态文件，可以挂载 `ui/dist` 目录：

```bash
docker run -d \
  --name maxkb \
  -p 8080:8080 \
  -v /path/to/maxkb:/opt/maxkb \
  -v /path/to/ui/dist:/opt/maxkb-app/ui/dist \
  your_maxkb_image:tag
```

## 4. 完整的 Docker Compose 配置

### 4.1 使用外部数据库

```yaml
version: '3.8'

services:
  maxkb:
    image: your_maxkb_image:tag
    container_name: maxkb
    ports:
      - "8080:8080"
    volumes:
      - /path/to/maxkb:/opt/maxkb
      - /path/to/maxkb/model:/opt/maxkb-app/model
    environment:
      - MAXKB_DB_HOST=postgres
      - MAXKB_DB_PORT=5432
      - MAXKB_DB_NAME=maxkb
      - MAXKB_DB_USER=maxkb_user
      - MAXKB_DB_PASSWORD=your_strong_password
      - MAXKB_REDIS_HOST=redis
      - MAXKB_REDIS_PORT=6379
      - MAXKB_REDIS_PASSWORD=your_redis_password
      - MAXKB_EMBEDDING_MODEL_PATH=/opt/maxkb-app/model/embedding
      - MAXKB_EMBEDDING_MODEL_NAME=/opt/maxkb-app/model/embedding/shibing624_text2vec-base-chinese
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:14-alpine
    container_name: postgres
    ports:
      - "5432:5432"
    volumes:
      - /path/to/postgres/data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=maxkb
      - POSTGRES_USER=maxkb_user
      - POSTGRES_PASSWORD=your_strong_password

  redis:
    image: redis:7-alpine
    container_name: redis
    ports:
      - "6379:6379"
    volumes:
      - /path/to/redis/data:/data
    command: redis-server --requirepass your_redis_password
```

### 4.2 使用内置数据库（仅挂载存储）

```yaml
version: '3.8'

services:
  maxkb:
    image: your_maxkb_image:tag
    container_name: maxkb
    ports:
      - "8080:8080"
    volumes:
      - /path/to/maxkb:/opt/maxkb
      - /path/to/maxkb/model:/opt/maxkb-app/model
      - /path/to/postgres/data:/var/lib/postgresql/data
      - /path/to/redis/data:/data
    environment:
      - MAXKB_EMBEDDING_MODEL_PATH=/opt/maxkb-app/model/embedding
      - MAXKB_EMBEDDING_MODEL_NAME=/opt/maxkb-app/model/embedding/shibing624_text2vec-base-chinese
```

## 5. 数据迁移和备份

### 5.1 数据库备份

#### 使用外部数据库

直接备份外部 PostgreSQL 数据库：

```bash
pg_dump -h your_database_host -U maxkb_user -d maxkb > maxkb_backup.sql
```

#### 使用内置数据库

```bash
docker exec -t maxkb pg_dump -U postgres -d maxkb > maxkb_backup.sql
```

### 5.2 数据库恢复

#### 使用外部数据库

```bash
psql -h your_database_host -U maxkb_user -d maxkb < maxkb_backup.sql
```

#### 使用内置数据库

```bash
cat maxkb_backup.sql | docker exec -i maxkb psql -U postgres -d maxkb
```

### 5.3 存储备份

备份挂载的存储目录：

```bash
rsync -av /path/to/maxkb /path/to/backup/maxkb
```

## 6. 注意事项

1. **权限设置**：确保挂载目录的权限正确，容器内进程需要有读写权限
2. **路径一致性**：确保环境变量中指定的路径与挂载路径一致
3. **首次启动**：首次启动时，系统会自动执行数据库迁移，创建所需的表结构
4. **模型文件**：确保模型文件的完整性和正确性，避免模型加载失败
5. **版本兼容性**：不同版本的 MaxKB 可能有不同的数据库结构，升级时需要注意
6. **性能优化**：对于生产环境，建议使用外部数据库和 Redis，以获得更好的性能
7. **网络配置**：如果使用外部数据库，确保网络连接畅通，防火墙规则允许访问
8. **备份策略**：定期备份数据库和存储目录，以防数据丢失

## 7. 故障排查

### 7.1 数据库连接失败

- 检查数据库服务是否运行
- 检查网络连接是否畅通
- 检查数据库用户名和密码是否正确
- 检查数据库是否存在

### 7.2 存储挂载问题

- 检查挂载目录权限
- 检查目录是否存在
- 检查文件系统权限

### 7.3 模型加载失败

- 检查模型文件是否完整
- 检查模型路径配置是否正确
- 检查模型文件权限

## 8. 最佳实践

1. **生产环境**：使用外部数据库和 Redis，实现更好的性能和可靠性
2. **开发环境**：可以使用内置数据库，方便快速启动和测试
3. **数据持久化**：始终挂载 `/opt/maxkb` 目录，确保数据不会丢失
4. **定期备份**：建立定期备份机制，确保数据安全
5. **监控**：监控数据库和存储使用情况，及时发现问题
6. **版本管理**：使用 Docker 标签管理不同版本的镜像，方便回滚
7. **配置管理**：使用环境变量或配置文件管理配置，避免硬编码

## 9. 示例部署命令

### 9.1 基本部署（使用内置数据库）

```bash
docker run -d \
  --name maxkb \
  -p 8080:8080 \
  -v /data/maxkb:/opt/maxkb \
  your_maxkb_image:tag
```

### 9.2 完整部署（使用外部数据库）

```bash
docker run -d \
  --name maxkb \
  -p 8080:8080 \
  -v /data/maxkb:/opt/maxkb \
  -v /data/maxkb/model:/opt/maxkb-app/model \
  -e MAXKB_DB_HOST=192.168.1.100 \
  -e MAXKB_DB_PORT=5432 \
  -e MAXKB_DB_NAME=maxkb \
  -e MAXKB_DB_USER=maxkb_user \
  -e MAXKB_DB_PASSWORD=your_strong_password \
  -e MAXKB_REDIS_HOST=192.168.1.100 \
  -e MAXKB_REDIS_PORT=6379 \
  -e MAXKB_REDIS_PASSWORD=your_redis_password \
  your_maxkb_image:tag
```

通过以上配置，您可以灵活地将 MaxKB 部署在 Docker 容器中，并实现数据库和存储的外挂，确保数据持久化和系统可靠性。