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:
108
docs/OCTANE_INSTALLATION.md
Normal file
108
docs/OCTANE_INSTALLATION.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# Laravel Octane 安装文档
|
||||
|
||||
## 概述
|
||||
|
||||
本文档记录了在知识库系统中安装和配置 Laravel Octane 的过程。Laravel Octane 通过 Swoole 提供高性能的 PHP 应用服务器。
|
||||
|
||||
## 安装步骤
|
||||
|
||||
### 1. 安装 Laravel Octane 包
|
||||
|
||||
```bash
|
||||
composer require laravel/octane
|
||||
```
|
||||
|
||||
### 2. 发布配置文件
|
||||
|
||||
```bash
|
||||
php artisan octane:install --server=swoole
|
||||
```
|
||||
|
||||
### 3. 环境变量配置
|
||||
|
||||
在 `.env` 文件中添加以下 Swoole 相关配置：
|
||||
|
||||
```bash
|
||||
# Octane/Swoole 配置
|
||||
OCTANE_SERVER=swoole
|
||||
OCTANE_HOST=0.0.0.0
|
||||
OCTANE_PORT=8000
|
||||
OCTANE_WORKERS=4
|
||||
OCTANE_TASK_WORKERS=2
|
||||
OCTANE_MAX_REQUESTS=500
|
||||
OCTANE_WATCH=false
|
||||
```
|
||||
|
||||
### 4. 配置文件更新
|
||||
|
||||
- `config/octane.php`: 默认服务器设置为 `swoole`
|
||||
- `composer.json`: 添加了 `dev-octane` 脚本支持
|
||||
|
||||
## 验证安装
|
||||
|
||||
### 检查配置
|
||||
|
||||
```bash
|
||||
php artisan config:show octane.server
|
||||
```
|
||||
|
||||
应该显示: `swoole`
|
||||
|
||||
### 检查命令可用性
|
||||
|
||||
```bash
|
||||
php artisan octane:status
|
||||
```
|
||||
|
||||
应该显示: `Octane server is not running.`
|
||||
|
||||
### 运行测试
|
||||
|
||||
```bash
|
||||
php artisan test tests/Feature/OctaneInstallationTest.php
|
||||
```
|
||||
|
||||
## 使用方法
|
||||
|
||||
### 启动 Octane 服务器
|
||||
|
||||
```bash
|
||||
php artisan octane:start
|
||||
```
|
||||
|
||||
### 带监听文件变化启动
|
||||
|
||||
```bash
|
||||
php artisan octane:start --watch
|
||||
```
|
||||
|
||||
### 使用 Composer 脚本启动开发环境
|
||||
|
||||
```bash
|
||||
composer run dev-octane
|
||||
```
|
||||
|
||||
### 停止服务器
|
||||
|
||||
```bash
|
||||
php artisan octane:stop
|
||||
```
|
||||
|
||||
### 重启服务器
|
||||
|
||||
```bash
|
||||
php artisan octane:restart
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **Swoole 扩展**: 在生产环境中需要安装 Swoole PHP 扩展
|
||||
2. **内存驻留**: 应用会保持在内存中，需要注意内存泄漏
|
||||
3. **全局变量**: 避免使用全局变量和静态变量
|
||||
4. **配置缓存**: 建议在生产环境中使用配置缓存
|
||||
|
||||
## 下一步
|
||||
|
||||
- 更新 Docker 配置以支持 Swoole
|
||||
- 配置生产环境部署脚本
|
||||
- 进行性能测试和优化
|
||||
180
docs/SWOOLE_CONFIGURATION.md
Normal file
180
docs/SWOOLE_CONFIGURATION.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# Swoole 配置说明
|
||||
|
||||
## 概述
|
||||
|
||||
本文档描述了 Laravel Octane + Swoole 集成的环境变量配置。这些配置已经添加到所有环境配置文件中，支持不同环境下的优化设置。
|
||||
|
||||
## 环境变量配置
|
||||
|
||||
### 核心 Swoole 配置
|
||||
|
||||
| 环境变量 | 默认值 | 说明 |
|
||||
|---------|--------|------|
|
||||
| `OCTANE_SERVER` | `swoole` | 指定使用 Swoole 作为 Octane 服务器 |
|
||||
| `OCTANE_HOST` | `0.0.0.0` | 服务器绑定的 IP 地址 |
|
||||
| `OCTANE_PORT` | `8000` | 服务器监听端口 |
|
||||
| `OCTANE_WORKERS` | `4` | 工作进程数量 |
|
||||
| `OCTANE_TASK_WORKERS` | `2` | 任务工作进程数量 |
|
||||
| `OCTANE_MAX_REQUESTS` | `500` | 工作进程处理的最大请求数 |
|
||||
| `OCTANE_WATCH` | `false` | 是否启用文件监控自动重启 |
|
||||
| `OCTANE_HTTPS` | `false` | 是否强制使用 HTTPS |
|
||||
|
||||
### 高级配置
|
||||
|
||||
| 环境变量 | 默认值 | 说明 |
|
||||
|---------|--------|------|
|
||||
| `OCTANE_GARBAGE_COLLECTION` | `50` | 垃圾回收阈值（MB） |
|
||||
| `OCTANE_MAX_EXECUTION_TIME` | `30` | 最大执行时间（秒） |
|
||||
| `OCTANE_CACHE_ROWS` | `1000` | Swoole 缓存表行数 |
|
||||
| `OCTANE_CACHE_BYTES` | `10000` | 每行缓存字节数 |
|
||||
|
||||
## 不同环境的配置
|
||||
|
||||
### 开发环境 (.env.development)
|
||||
|
||||
```bash
|
||||
# 开发环境优化配置
|
||||
OCTANE_WORKERS=2 # 较少的工作进程
|
||||
OCTANE_TASK_WORKERS=1 # 较少的任务进程
|
||||
OCTANE_MAX_REQUESTS=100 # 较少的最大请求数
|
||||
OCTANE_WATCH=true # 启用文件监控
|
||||
OCTANE_GARBAGE_COLLECTION=25 # 较低的垃圾回收阈值
|
||||
OCTANE_MAX_EXECUTION_TIME=60 # 较长的执行时间用于调试
|
||||
```
|
||||
|
||||
### 生产环境 (.env.production)
|
||||
|
||||
```bash
|
||||
# 生产环境优化配置
|
||||
OCTANE_WORKERS=8 # 更多的工作进程
|
||||
OCTANE_TASK_WORKERS=4 # 更多的任务进程
|
||||
OCTANE_MAX_REQUESTS=1000 # 更多的最大请求数
|
||||
OCTANE_WATCH=false # 禁用文件监控
|
||||
OCTANE_GARBAGE_COLLECTION=100 # 较高的垃圾回收阈值
|
||||
OCTANE_MAX_EXECUTION_TIME=30 # 标准执行时间
|
||||
```
|
||||
|
||||
## 性能调优建议
|
||||
|
||||
### 工作进程数量
|
||||
|
||||
- **开发环境**: 2-4 个进程，避免资源浪费
|
||||
- **生产环境**: CPU 核心数的 1-2 倍，通常 4-8 个进程
|
||||
- **高负载环境**: 可以增加到 CPU 核心数的 2-4 倍
|
||||
|
||||
### 最大请求数
|
||||
|
||||
- **开发环境**: 100-500 请求后重启，便于内存清理
|
||||
- **生产环境**: 500-2000 请求后重启，平衡性能和内存使用
|
||||
- **内存敏感**: 降低到 200-500，频繁重启释放内存
|
||||
|
||||
### 垃圾回收阈值
|
||||
|
||||
- **开发环境**: 25-50MB，及时清理内存
|
||||
- **生产环境**: 50-100MB，减少垃圾回收频率
|
||||
- **大内存服务器**: 可以设置到 200MB 以上
|
||||
|
||||
## 启动命令
|
||||
|
||||
### 基本启动
|
||||
|
||||
```bash
|
||||
# 使用默认配置启动
|
||||
php artisan octane:start
|
||||
|
||||
# 指定参数启动
|
||||
php artisan octane:start --workers=4 --task-workers=2 --port=8000
|
||||
```
|
||||
|
||||
### 开发模式启动
|
||||
|
||||
```bash
|
||||
# 启用文件监控
|
||||
php artisan octane:start --watch
|
||||
|
||||
# 指定日志级别
|
||||
php artisan octane:start --log-level=debug
|
||||
```
|
||||
|
||||
### 生产模式启动
|
||||
|
||||
```bash
|
||||
# 生产环境启动
|
||||
php artisan octane:start --workers=8 --task-workers=4 --max-requests=1000
|
||||
```
|
||||
|
||||
## 监控和管理
|
||||
|
||||
### 服务器状态
|
||||
|
||||
```bash
|
||||
# 查看服务器状态
|
||||
php artisan octane:status
|
||||
|
||||
# 停止服务器
|
||||
php artisan octane:stop
|
||||
|
||||
# 重启服务器
|
||||
php artisan octane:restart
|
||||
|
||||
# 重新加载服务器（优雅重启）
|
||||
php artisan octane:reload
|
||||
```
|
||||
|
||||
### 配置验证
|
||||
|
||||
```bash
|
||||
# 查看当前 Octane 配置
|
||||
php artisan config:show octane
|
||||
|
||||
# 清除配置缓存
|
||||
php artisan config:clear
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
### 内存管理
|
||||
|
||||
1. **避免内存泄漏**: 确保在请求结束后清理大对象
|
||||
2. **监控内存使用**: 定期检查工作进程的内存使用情况
|
||||
3. **合理设置最大请求数**: 防止内存累积过多
|
||||
|
||||
### 开发注意事项
|
||||
|
||||
1. **全局变量**: 避免使用全局变量，它们会在请求间保持状态
|
||||
2. **静态变量**: 小心使用静态变量，可能导致数据污染
|
||||
3. **单例服务**: 确保单例服务能正确重置状态
|
||||
|
||||
### 生产部署
|
||||
|
||||
1. **进程监控**: 使用 Supervisor 或类似工具监控 Octane 进程
|
||||
2. **负载均衡**: 在多服务器环境中配置负载均衡
|
||||
3. **健康检查**: 实现健康检查接口监控服务状态
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **端口被占用**: 检查端口是否被其他服务占用
|
||||
2. **权限问题**: 确保有足够权限绑定指定端口
|
||||
3. **内存不足**: 调整工作进程数量或增加服务器内存
|
||||
4. **配置不生效**: 清除配置缓存后重启服务
|
||||
|
||||
### 调试命令
|
||||
|
||||
```bash
|
||||
# 检查 Swoole 扩展
|
||||
php -m | grep swoole
|
||||
|
||||
# 测试配置
|
||||
php artisan octane:start --workers=1 --max-requests=1
|
||||
|
||||
# 查看详细日志
|
||||
php artisan octane:start --log-level=debug
|
||||
```
|
||||
|
||||
## 更新历史
|
||||
|
||||
- **2024-12-29**: 初始配置，添加所有环境变量支持
|
||||
- 支持开发、生产环境的差异化配置
|
||||
- 添加高级配置选项支持
|
||||
Reference in New Issue
Block a user