KnowledgeBase/docker/ENVIRONMENT_SETUP.md

# 环境配置设置指南

## 概述

本指南介绍如何配置和设置知识库系统的Docker部署环境，包括生产环境和开发环境的配置。

## 快速开始

### 1. 自动配置（推荐）

使用自动配置脚本快速设置环境：

```bash
# 生产环境配置
./docker/setup-env.sh -e production

# 开发环境配置
./docker/setup-env.sh -e development

# 交互式配置
./docker/setup-env.sh -i
```

### 2. 手动配置

如果需要手动配置，请按照以下步骤：

#### 生产环境

1. 复制环境模板：
   ```bash
   cp .env.production .env
   ```

2. 编辑 `.env` 文件，修改以下关键配置：
   ```bash
   APP_KEY=base64:your-generated-key-here
   DB_PASSWORD=your-secure-database-password
   MEILISEARCH_KEY=your-meilisearch-master-key
   APP_URL=http://your-domain.com
   ```

3. 生成应用密钥：
   ```bash
   php artisan key:generate
   ```

#### 开发环境

1. 复制开发环境模板：
   ```bash
   cp .env.development .env
   ```

2. 编辑配置（开发环境可以使用默认值）

## 配置验证

### 验证环境变量

```bash
# 验证当前环境配置
./docker/validate-env.sh
```

### 验证Docker配置

```bash
# 验证生产环境配置
docker-compose config

# 验证开发环境配置
docker-compose -f docker-compose.dev.yml config
```

## 启动服务

### 生产环境

```bash
# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f
```

### 开发环境

```bash
# 启动开发环境
docker-compose -f docker-compose.dev.yml up -d

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

# 查看日志
docker-compose -f docker-compose.dev.yml logs -f
```

## 网络测试

启动服务后，测试网络连接：

```bash
# 测试容器间网络连接
./docker/test-network.sh
```

## 应用初始化

服务启动后，初始化Laravel应用：

```bash
# 运行数据库迁移
docker exec knowledge_base_app php artisan migrate

# 运行数据库种子
docker exec knowledge_base_app php artisan db:seed

# 创建搜索索引
docker exec knowledge_base_app php artisan scout:import "App\Models\Document"
```

## 环境配置详解

### 网络配置

- **生产环境网络**: `knowledge_base_network` (172.20.0.0/16)
- **开发环境网络**: `knowledge_base_dev_network` (172.21.0.0/16)

### 端口映射

#### 生产环境
- Web应用: 80
- MySQL: 3306
- Redis: 6379
- Meilisearch: 7700

#### 开发环境
- Web应用: 8080
- MySQL: 3307
- Redis: 6380
- Meilisearch: 7701
- PHP-FPM调试: 9000

### 存储卷

#### 生产环境
- 数据库数据: `./storage/mysql`
- Redis数据: `./storage/redis`
- 搜索数据: `./storage/meilisearch`
- 应用存储: `./storage/app`
- 日志文件: `./storage/logs`

#### 开发环境
- 数据库数据: `./storage/dev/mysql`
- Redis数据: `./storage/dev/redis`
- 搜索数据: `./storage/dev/meilisearch`
- 应用存储: `./storage/dev/app`
- 日志文件: `./storage/dev/logs`

## 环境变量说明

### 必需配置

| 变量名 | 说明 | 示例 |
|--------|------|------|
| `APP_KEY` | 应用加密密钥 | `base64:xxx...` |
| `DB_PASSWORD` | 数据库密码 | `secure_password` |
| `MEILISEARCH_KEY` | 搜索引擎密钥 | `master_key_xxx` |

### 可选配置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `APP_NAME` | 知识库系统 | 应用名称 |
| `APP_URL` | http://localhost | 应用URL |
| `DB_DATABASE` | knowledge_base | 数据库名 |
| `DB_USERNAME` | knowledge_user | 数据库用户 |

## 故障排除

### 常见问题

1. **容器启动失败**
   ```bash
   # 查看容器日志
   docker-compose logs [service_name]
   
   # 检查容器状态
   docker-compose ps
   ```

2. **网络连接问题**
   ```bash
   # 测试网络连接
   ./docker/test-network.sh
   
   # 检查网络配置
   docker network ls
   docker network inspect knowledge_base_network
   ```

3. **环境变量问题**
   ```bash
   # 验证环境变量
   ./docker/validate-env.sh
   
   # 查看容器环境变量
   docker exec knowledge_base_app env
   ```

4. **权限问题**
   ```bash
   # 修复存储目录权限
   chmod -R 775 storage
   chmod -R 775 bootstrap/cache
   ```

### 重置环境

如果需要重置环境：

```bash
# 停止所有服务
docker-compose down

# 删除数据卷（注意：这会删除所有数据）
docker-compose down -v

# 重新配置环境
./docker/setup-env.sh -f -e production

# 重新启动服务
docker-compose up -d
```

## 安全建议

### 生产环境

1. **更改默认密码**：确保所有默认密码都已更改
2. **使用强密钥**：使用复杂的APP_KEY和MEILISEARCH_KEY
3. **限制网络访问**：配置防火墙规则
4. **定期备份**：定期备份数据库和文件
5. **监控日志**：监控应用和系统日志

### 开发环境

1. **隔离环境**：不要在生产环境使用开发配置
2. **定期更新**：保持开发环境与生产环境同步
3. **清理数据**：定期清理开发环境数据

## 维护操作

### 备份

```bash
# 备份数据库
docker exec knowledge_base_mysql mysqldump -u root -p knowledge_base > backup.sql

# 备份文件
tar -czf storage_backup.tar.gz storage/
```

### 更新

```bash
# 更新镜像
docker-compose pull

# 重启服务
docker-compose up -d
```

### 监控

```bash
# 查看资源使用情况
docker stats

# 查看服务健康状态
docker-compose ps
```