KnowledgeBase/docker/ENVIRONMENT_VARIABLES.md

# 环境变量配置文档

## 概述

本文档详细说明了知识库系统Docker部署所需的环境变量配置，包括生产环境和开发环境的不同设置。

## 环境变量分类

### 应用基础配置

| 变量名 | 生产环境默认值 | 开发环境默认值 | 说明 |
|--------|----------------|----------------|------|
| `APP_NAME` | "知识库系统" | "知识库系统-开发" | 应用名称 |
| `APP_ENV` | production | local | 应用环境 |
| `APP_KEY` | 必须设置 | 必须设置 | 应用加密密钥 |
| `APP_DEBUG` | false | true | 调试模式 |
| `APP_URL` | http://your-domain.com | http://localhost:8000 | 应用URL |

### 数据库配置

| 变量名 | 生产环境默认值 | 开发环境默认值 | 说明 |
|--------|----------------|----------------|------|
| `DB_CONNECTION` | mysql | mysql | 数据库类型 |
| `DB_HOST` | mysql | mysql | 数据库主机（容器名） |
| `DB_PORT` | 3306 | 3306 | 数据库端口 |
| `DB_DATABASE` | knowledge_base | knowledge_base_dev | 数据库名 |
| `DB_USERNAME` | knowledge_user | dev_user | 数据库用户名 |
| `DB_PASSWORD` | 必须设置 | dev_password | 数据库密码 |

### Redis配置

| 变量名 | 生产环境默认值 | 开发环境默认值 | 说明 |
|--------|----------------|----------------|------|
| `REDIS_CLIENT` | phpredis | phpredis | Redis客户端 |
| `REDIS_HOST` | redis | redis | Redis主机（容器名） |
| `REDIS_PORT` | 6379 | 6379 | Redis端口 |
| `REDIS_PASSWORD` | 空 | 空 | Redis密码 |
| `CACHE_STORE` | redis | redis | 缓存驱动 |
| `SESSION_DRIVER` | redis | redis | 会话驱动 |
| `QUEUE_CONNECTION` | redis | redis | 队列驱动 |

### Meilisearch配置

| 变量名 | 生产环境默认值 | 开发环境默认值 | 说明 |
|--------|----------------|----------------|------|
| `SCOUT_DRIVER` | meilisearch | meilisearch | 搜索驱动 |
| `MEILISEARCH_HOST` | http://meilisearch:7700 | http://meilisearch:7700 | 搜索引擎地址 |
| `MEILISEARCH_KEY` | 必须设置 | dev-master-key | 搜索引擎密钥 |

### 日志配置

| 变量名 | 生产环境默认值 | 开发环境默认值 | 说明 |
|--------|----------------|----------------|------|
| `LOG_CHANNEL` | stack | stack | 日志通道 |
| `LOG_LEVEL` | info | debug | 日志级别 |

### 邮件配置

| 变量名 | 生产环境默认值 | 开发环境默认值 | 说明 |
|--------|----------------|----------------|------|
| `MAIL_MAILER` | smtp | log | 邮件驱动 |
| `MAIL_HOST` | 必须设置 | - | SMTP主机 |
| `MAIL_PORT` | 587 | - | SMTP端口 |
| `MAIL_USERNAME` | 必须设置 | - | SMTP用户名 |
| `MAIL_PASSWORD` | 必须设置 | - | SMTP密码 |
| `MAIL_ENCRYPTION` | tls | - | 加密方式 |

## 环境文件配置

### 生产环境 (.env.production)

```bash
# 应用配置
APP_NAME="知识库系统"
APP_ENV=production
APP_KEY=base64:your-app-key-here-change-this-in-production
APP_DEBUG=false
APP_URL=http://your-domain.com

# 数据库配置
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=knowledge_base
DB_USERNAME=knowledge_user
DB_PASSWORD=secure_password_change_this_in_production

# Redis配置
REDIS_CLIENT=phpredis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=

# Meilisearch配置
SCOUT_DRIVER=meilisearch
MEILISEARCH_HOST=http://meilisearch:7700
MEILISEARCH_KEY=your-master-key-change-this-in-production

# 邮件配置
MAIL_MAILER=smtp
MAIL_HOST=your-smtp-host.com
MAIL_PORT=587
MAIL_USERNAME=your-email@domain.com
MAIL_PASSWORD=your-email-password-change-this
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="noreply@your-domain.com"
MAIL_FROM_NAME="${APP_NAME}"
```

### 开发环境 (.env.development)

```bash
# 应用配置
APP_NAME="知识库系统-开发"
APP_ENV=local
APP_KEY=base64:your-dev-app-key-here
APP_DEBUG=true
APP_URL=http://localhost:8000

# 数据库配置
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=knowledge_base_dev
DB_USERNAME=dev_user
DB_PASSWORD=dev_password

# Redis配置
REDIS_CLIENT=phpredis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=

# Meilisearch配置
SCOUT_DRIVER=meilisearch
MEILISEARCH_HOST=http://meilisearch:7700
MEILISEARCH_KEY=dev-master-key

# 邮件配置（开发环境使用日志）
MAIL_MAILER=log
MAIL_FROM_ADDRESS="dev@knowledge-base.local"
MAIL_FROM_NAME="${APP_NAME}"

# 开发工具配置
TELESCOPE_ENABLED=true
DEBUGBAR_ENABLED=true
XDEBUG_MODE=develop,debug
XDEBUG_CONFIG=client_host=host.docker.internal client_port=9003
```

## Docker Compose环境变量

### 生产环境 (docker-compose.yml)

```yaml
environment:
  # 从.env文件读取或使用默认值
  APP_NAME: ${APP_NAME:-知识库系统}
  APP_ENV: ${APP_ENV:-production}
  APP_KEY: ${APP_KEY}
  APP_DEBUG: ${APP_DEBUG:-false}
  APP_URL: ${APP_URL:-http://localhost}
  
  # 数据库配置
  DB_CONNECTION: mysql
  DB_HOST: mysql
  DB_PORT: 3306
  DB_DATABASE: ${DB_DATABASE:-knowledge_base}
  DB_USERNAME: ${DB_USERNAME:-knowledge_user}
  DB_PASSWORD: ${DB_PASSWORD:-secure_password}
```

### 开发环境 (docker-compose.dev.yml)

```yaml
environment:
  # 开发环境特定配置
  APP_NAME: ${APP_NAME:-知识库系统-开发}
  APP_ENV: ${APP_ENV:-local}
  APP_DEBUG: ${APP_DEBUG:-true}
  LOG_LEVEL: debug
  
  # 开发工具配置
  TELESCOPE_ENABLED: true
  DEBUGBAR_ENABLED: true
```

## 安全注意事项

### 必须更改的默认值

生产环境部署前必须更改以下默认值：

1. **APP_KEY**: 使用 `php artisan key:generate` 生成
2. **DB_PASSWORD**: 设置强密码
3. **MEILISEARCH_KEY**: 设置复杂的主密钥
4. **MAIL_PASSWORD**: 设置邮件服务密码

### 敏感信息保护

1. **不要将敏感信息提交到版本控制**
2. **使用Docker secrets管理敏感数据**
3. **定期轮换密钥和密码**
4. **限制环境变量的访问权限**

## 环境变量验证

### 启动前检查

创建验证脚本检查必要的环境变量：

```bash
#!/bin/bash
# validate-env.sh

required_vars=(
    "APP_KEY"
    "DB_PASSWORD"
    "MEILISEARCH_KEY"
)

for var in "${required_vars[@]}"; do
    if [ -z "${!var}" ]; then
        echo "错误: 环境变量 $var 未设置"
        exit 1
    fi
done

echo "环境变量验证通过"
```

### 运行时检查

Laravel应用启动时会自动验证关键配置：

- 数据库连接
- Redis连接
- Meilisearch连接
- 应用密钥格式

## 故障排除

### 常见问题

1. **APP_KEY未设置**:
   ```bash
   php artisan key:generate
   ```

2. **数据库连接失败**:
   - 检查DB_HOST是否为容器名
   - 验证数据库密码
   - 确认MySQL容器已启动

3. **Redis连接失败**:
   - 检查REDIS_HOST是否为容器名
   - 验证Redis容器状态

4. **Meilisearch连接失败**:
   - 检查MEILISEARCH_HOST格式
   - 验证MEILISEARCH_KEY

### 调试命令

```bash
# 查看容器环境变量
docker exec knowledge_base_app env

# 测试数据库连接
docker exec knowledge_base_app php artisan tinker
>>> DB::connection()->getPdo();

# 测试Redis连接
docker exec knowledge_base_app php artisan tinker
>>> Redis::ping();

# 测试Meilisearch连接
docker exec knowledge_base_app php artisan scout:status
```

## 最佳实践

1. **使用环境特定的配置文件**
2. **为不同环境设置不同的密钥**
3. **定期备份环境配置**
4. **使用配置管理工具**
5. **监控配置变更**
6. **文档化所有环境变量**