KnowledgeBase/.kiro/specs/swoole-integration/design.md

设计文档 - Swoole 集成

概述

本设计文档详细描述了将 Laravel 知识库系统从传统的 PHP-FPM + Nginx 架构迁移到基于 Swoole 的高性能异步架构的技术方案。通过集成 Laravel Octane 和 Swoole，系统将获得显著的性能提升和更好的并发处理能力。

架构

当前架构 vs 目标架构

当前架构:

请求 → Nginx → PHP-FPM → Laravel 应用

目标架构:

请求 → Swoole HTTP Server → Laravel 应用 (内存驻留)

系统架构图

graph TB
    subgraph "Docker 容器"
        subgraph "应用容器 (新架构)"
            A[Swoole HTTP Server] --> B[Laravel Octane]
            B --> C[Laravel 应用]
            D[队列工作进程] --> C
            E[定时任务] --> C
        end
        
        subgraph "数据层"
            F[MySQL 容器]
            G[Redis 容器]
            H[Meilisearch 容器]
        end
    end
    
    I[客户端请求] --> A
    C --> F
    C --> G
    C --> H
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8

组件和接口

简化的集成方案

核心原则: 最小化代码修改，最大化利用 Laravel Octane 的默认配置和行为。

1. Laravel Octane 包

使用现有组件:

• 直接使用 laravel/octane 包，无需自定义接口
• 使用默认的 Swoole 配置，仅调整必要参数
• 利用 Octane 的内置命令和服务管理

配置方式:

// config/octane.php (Laravel Octane 默认配置文件)
return [
    'server' => 'swoole',
    'host' => env('OCTANE_HOST', '0.0.0.0'),
    'port' => env('OCTANE_PORT', 8000),
    'workers' => env('OCTANE_WORKERS', 4),
    'task_workers' => env('OCTANE_TASK_WORKERS', 2),
    'max_requests' => env('OCTANE_MAX_REQUESTS', 500),
];

2. 现有代码兼容性

无需修改的组件:

• 现有的 Controllers、Models、Services 保持不变
• 队列处理逻辑无需修改
• 数据库连接和缓存逻辑保持原样
• Filament 管理界面无需调整

需要注意的事项:

• 避免使用全局变量和静态变量
• 确保单例服务的正确重置
• 检查文件上传和会话处理

数据模型

简化的配置模型

使用环境变量配置 (无需新建模型类):

# .env 文件中的 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

现有模型保持不变:

• Document 模型
• User 模型
• Group 模型
• DownloadLog 模型

所有现有的 Eloquent 模型和数据库操作保持完全不变，Swoole 集成是透明的。

正确性属性

现在我需要使用 prework 工具来分析验收标准的可测试性：

A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.

服务器启动和运行属性

属性 1: Swoole 服务器启动一致性 对于任何 有效的配置参数，当系统启动时，应该能够检测到 Swoole HTTP 服务器进程在运行并监听指定端口 验证: 需求 1.1

属性 2: HTTP 请求处理一致性 对于任何 有效的 HTTP 请求，Swoole 服务器应该能够处理请求并返回适当的响应 验证: 需求 1.2

属性 3: 内存驻留持久性 对于任何 运行中的 Swoole 服务器，应用进程应该保持内存驻留状态，不会在请求间重新初始化 验证: 需求 1.3

命令行接口属性

属性 4: Artisan 命令执行一致性 对于任何 有效的 Octane 命令参数，php artisan octane 命令应该正确执行相应的服务器操作 验证: 需求 2.1, 2.4, 2.5

属性 5: 端口配置正确性 对于任何 指定的有效端口号，Swoole 服务器应该在该端口上启动并接受连接 验证: 需求 2.2

属性 6: 工作进程数量一致性 对于任何 指定的工作进程数量，Swoole 服务器应该创建相应数量的工作进程 验证: 需求 2.3

Docker 集成属性

属性 7: Swoole 扩展安装完整性 对于任何 构建的 Docker 镜像，应该包含正确安装和配置的 Swoole PHP 扩展 验证: 需求 3.1

属性 8: 容器进程替换正确性 对于任何 启动的应用容器，应该运行 Swoole 进程而不是 PHP-FPM 或 Nginx 进程 验证: 需求 3.2

属性 9: 容器端口暴露正确性 对于任何 配置的 Swoole 服务端口，容器应该正确暴露该端口供外部访问 验证: 需求 3.3

队列处理属性

属性 10: 队列处理兼容性 对于任何 队列任务，在 Swoole 环境下应该能够正常处理，与传统环境行为一致 验证: 需求 4.1, 4.2

属性 11: 队列监听器自动启动 对于任何 系统启动，队列监听器应该自动启动并保持运行状态 验证: 需求 4.3

属性 12: 队列错误处理一致性 对于任何 失败的队列任务，系统应该记录错误信息并按配置进行重试 验证: 需求 4.4

系统稳定性属性

属性 13: 高并发处理稳定性 对于任何 高并发请求负载，Swoole 服务器应该保持稳定运行而不崩溃 验证: 需求 5.1

属性 14: 内存使用稳定性 对于任何 长时间运行的系统，内存使用应该保持在合理范围内，不出现持续增长 验证: 需求 5.2

属性 15: 健康检查响应一致性 对于任何 健康检查请求，系统应该返回正确的健康状态信息 验证: 需求 5.4

部署和配置属性

属性 16: 部署脚本镜像构建正确性 对于任何 执行的部署脚本，应该生成包含 Swoole 配置的有效 Docker 镜像 验证: 需求 6.1

属性 17: 配置文件更新正确性 对于任何 更新的 docker-compose 配置，应该正确移除 Nginx 依赖并配置 Swoole 服务 验证: 需求 6.2

属性 18: 环境变量配置生效性 对于任何 设置的 Swoole 相关环境变量，应该在系统运行时正确生效 验证: 需求 6.3

错误处理

简化的错误处理策略

利用 Laravel Octane 内置错误处理:

• 使用 Octane 的默认异常处理机制
• 利用 Laravel 现有的日志系统
• 保持现有的错误报告和监控

最小化自定义错误处理:

// 仅在必要时添加 Swoole 特定的错误处理
// 在 app/Exceptions/Handler.php 中添加
public function register()
{
    $this->reportable(function (Throwable $e) {
        if (app()->bound('octane')) {
            // 记录 Swoole 相关错误
            Log::channel('swoole')->error('Swoole error: ' . $e->getMessage());
        }
    });
}

依赖现有机制:

• 使用现有的队列失败处理
• 保持现有的数据库连接错误处理
• 利用现有的缓存错误恢复机制

测试策略

双重测试方法

本项目将采用单元测试和基于属性的测试相结合的方法：

• 单元测试: 验证具体的功能实现和边界条件
• 基于属性的测试: 验证系统在各种输入下的通用属性

单元测试覆盖

单元测试将覆盖：

• Octane 配置加载和验证
• Swoole 服务器启动和停止
• 命令行接口功能
• 错误处理逻辑
• 队列集成功能

基于属性的测试

将使用 Pest 作为基于属性的测试框架，配置每个属性测试运行最少 100 次迭代。

每个基于属性的测试必须：

• 使用注释明确标识对应的设计文档属性
• 使用格式: **Feature: swoole-integration, Property {number}: {property_text}**
• 生成合适的测试数据来验证属性
• 验证系统在各种输入条件下的行为一致性

测试环境配置

// 测试配置示例
return [
    'octane' => [
        'server' => 'swoole',
        'host' => '127.0.0.1',
        'port' => 8000,
        'workers' => 2,
        'task_workers' => 1,
        'max_requests' => 100,
    ],
    'swoole' => [
        'options' => [
            'log_file' => storage_path('logs/swoole.log'),
            'log_level' => SWOOLE_LOG_INFO,
        ],
    ],
];

性能测试

除了功能测试外，还需要进行性能测试：

• 并发请求处理能力测试
• 内存使用监控测试
• 响应时间分布测试
• 长时间运行稳定性测试

集成测试

集成测试将验证：

• Docker 容器间的通信
• 数据库连接池管理
• 缓存系统集成
• 搜索服务集成
• 队列系统集成

这些测试确保 Swoole 集成不会破坏现有的系统功能，同时提供预期的性能改进。