KnowledgeBase/docs/SWOOLE_CONFIGURATION.md

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)

# 开发环境优化配置
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)

# 生产环境优化配置
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 以上

启动命令

基本启动

# 使用默认配置启动
php artisan octane:start

# 指定参数启动
php artisan octane:start --workers=4 --task-workers=2 --port=8000

开发模式启动

# 启用文件监控
php artisan octane:start --watch

# 指定日志级别
php artisan octane:start --log-level=debug

生产模式启动

# 生产环境启动
php artisan octane:start --workers=8 --task-workers=4 --max-requests=1000

监控和管理

服务器状态

# 查看服务器状态
php artisan octane:status

# 停止服务器
php artisan octane:stop

# 重启服务器
php artisan octane:restart

# 重新加载服务器（优雅重启）
php artisan octane:reload

配置验证

# 查看当前 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. 配置不生效: 清除配置缓存后重启服务

调试命令

# 检查 Swoole 扩展
php -m | grep swoole

# 测试配置
php artisan octane:start --workers=1 --max-requests=1

# 查看详细日志
php artisan octane:start --log-level=debug

更新历史

• 2024-12-29: 初始配置，添加所有环境变量支持
• 支持开发、生产环境的差异化配置
• 添加高级配置选项支持