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>
2026-02-28 15:51:19 +08:00
parent acf549c43c
commit 3c206e9e06
90 changed files with 12731 additions and 1255 deletions
--- a/.kiro/specs/swoole-integration/design.md
+++ b/.kiro/specs/swoole-integration/design.md
@@ -0,0 +1,300 @@
+# 设计文档 - Swoole 集成
+
+## 概述
+
+本设计文档详细描述了将 Laravel 知识库系统从传统的 PHP-FPM + Nginx 架构迁移到基于 Swoole 的高性能异步架构的技术方案。通过集成 Laravel Octane 和 Swoole，系统将获得显著的性能提升和更好的并发处理能力。
+
+## 架构
+
+### 当前架构 vs 目标架构
+
+**当前架构:**
+```
+请求 → Nginx → PHP-FPM → Laravel 应用
+```
+
+**目标架构:**
+```
+请求 → Swoole HTTP Server → Laravel 应用 (内存驻留)
+```
+
+### 系统架构图
+
+```mermaid
+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 的内置命令和服务管理
+
+**配置方式:**
+```php
+// 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 管理界面无需调整
+
+**需要注意的事项:**
+- 避免使用全局变量和静态变量
+- 确保单例服务的正确重置
+- 检查文件上传和会话处理
+
+## 数据模型
+
+### 简化的配置模型
+
+**使用环境变量配置 (无需新建模型类):**
+
+```bash
+# .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 现有的日志系统
+- 保持现有的错误报告和监控
+
+**最小化自定义错误处理:**
+```php
+// 仅在必要时添加 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}**`
+- 生成合适的测试数据来验证属性
+- 验证系统在各种输入条件下的行为一致性
+
+### 测试环境配置
+
+```php
+// 测试配置示例
+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 集成不会破坏现有的系统功能，同时提供预期的性能改进。