feat: 新增 Docker 部署支持、Swoole/Octane 集成及相关优化
- 添加 Dockerfile 与多套 docker-compose 配置（开发/生产环境） - 集成 Laravel Octane (Swoole) 提升性能 - 新增健康检查、监控脚本及部署文档 - 新增 Docker 镜像离线导入包（MySQL/Redis/Meilisearch） - 优化文档转换、预览服务及队列任务 - 添加 CreateAdminUser 命令与路由健康检查接口 - 新增 Swoole 队列兼容性测试套件 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
288
docker/ENVIRONMENT_VARIABLES.md
Normal file
288
docker/ENVIRONMENT_VARIABLES.md
Normal file
@@ -0,0 +1,288 @@
|
||||
# 环境变量配置文档
|
||||
|
||||
## 概述
|
||||
|
||||
本文档详细说明了知识库系统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. **文档化所有环境变量**
|
||||
Reference in New Issue
Block a user