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)

# 应用配置
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)

# 应用配置
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)

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)

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. 限制环境变量的访问权限

环境变量验证

启动前检查

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

#!/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未设置:

   php artisan key:generate
   

2. 数据库连接失败:

   • 检查DB_HOST是否为容器名
   • 验证数据库密码
   • 确认MySQL容器已启动

3. Redis连接失败:

   • 检查REDIS_HOST是否为容器名
   • 验证Redis容器状态

4. Meilisearch连接失败:

   • 检查MEILISEARCH_HOST格式
   • 验证MEILISEARCH_KEY

调试命令

# 查看容器环境变量
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. 文档化所有环境变量