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 集成不会破坏现有的系统功能，同时提供预期的性能改进。
--- a/.kiro/specs/swoole-integration/requirements.md
+++ b/.kiro/specs/swoole-integration/requirements.md
@@ -0,0 +1,87 @@
+# 需求文档 - Swoole 集成
+
+## 介绍
+
+本规范旨在将现有的 Laravel 知识库系统从传统的 PHP-FPM + Nginx 架构迁移到使用 Swoole 的高性能异步架构。Swoole 是一个高性能的 PHP 异步网络通信引擎，能够显著提升应用性能和并发处理能力。
+
+## 术语表
+
+- **Swoole**: 高性能的 PHP 异步网络通信引擎
+- **Laravel_Octane**: Laravel 官方的高性能应用服务器包，支持 Swoole 和 RoadRunner
+- **PHP_Artisan**: Laravel 的命令行工具
+- **Docker_Container**: 应用程序的容器化运行环境
+- **Hot_Reload**: 代码变更时自动重启服务的功能
+
+## 需求
+
+### 需求 1
+
+**用户故事:** 作为系统管理员，我希望使用 Swoole 替代传统的 PHP-FPM 运行方式，以便获得更高的性能和并发处理能力。
+
+#### 验收标准
+
+1. WHEN 系统启动时 THEN Laravel_Octane SHALL 使用 Swoole 驱动启动 HTTP 服务器
+2. WHEN 接收 HTTP 请求时 THEN Swoole_Server SHALL 处理请求并返回响应
+3. WHEN 系统运行时 THEN Swoole_Server SHALL 维持长连接和内存驻留
+4. WHEN 配置变更时 THEN 系统 SHALL 支持热重载功能
+5. WHEN 监控系统性能时 THEN Swoole_Server SHALL 提供性能指标接口
+
+### 需求 2
+
+**用户故事:** 作为开发人员，我希望通过 php artisan 命令启动 Swoole 服务，以便保持与 Laravel 生态系统的一致性。
+
+#### 验收标准
+
+1. WHEN 执行启动命令时 THEN php artisan octane:start SHALL 启动 Swoole 服务器
+2. WHEN 指定端口参数时 THEN 系统 SHALL 在指定端口上启动服务
+3. WHEN 指定工作进程数时 THEN Swoole_Server SHALL 创建指定数量的工作进程
+4. WHEN 执行停止命令时 THEN php artisan octane:stop SHALL 优雅关闭服务器
+5. WHEN 执行重启命令时 THEN php artisan octane:restart SHALL 重启服务器
+
+### 需求 3
+
+**用户故事:** 作为运维人员，我希望更新 Docker 镜像配置，以便支持 Swoole 运行环境和相关依赖。
+
+#### 验收标准
+
+1. WHEN 构建 Docker 镜像时 THEN 系统 SHALL 安装 Swoole PHP 扩展
+2. WHEN 容器启动时 THEN 系统 SHALL 使用 Swoole 替代 PHP-FPM 和 Nginx
+3. WHEN 配置容器时 THEN 系统 SHALL 暴露 Swoole 服务端口
+4. WHEN 容器运行时 THEN 系统 SHALL 支持进程管理和监控
+5. WHEN 容器重启时 THEN 系统 SHALL 自动恢复 Swoole 服务
+
+### 需求 4
+
+**用户故事:** 作为系统架构师，我希望保持现有的队列处理和后台任务功能，以便确保系统功能完整性。
+
+#### 验收标准
+
+1. WHEN Swoole 服务运行时 THEN 队列处理器 SHALL 继续正常工作
+2. WHEN 处理文档转换任务时 THEN 后台队列 SHALL 正常执行任务
+3. WHEN 系统启动时 THEN 队列监听器 SHALL 自动启动
+4. WHEN 队列任务失败时 THEN 系统 SHALL 记录错误并支持重试
+5. WHEN 监控队列状态时 THEN 系统 SHALL 提供队列健康检查接口
+
+### 需求 5
+
+**用户故事:** 作为质量保证工程师，我希望验证 Swoole 集成后的系统稳定性，以便确保生产环境的可靠性。
+
+#### 验收标准
+
+1. WHEN 系统负载测试时 THEN Swoole_Server SHALL 处理高并发请求而不崩溃
+2. WHEN 长时间运行时 THEN 系统 SHALL 保持内存使用稳定
+3. WHEN 发生异常时 THEN Swoole_Server SHALL 记录详细错误日志
+4. WHEN 进行健康检查时 THEN 系统 SHALL 响应健康检查请求
+5. WHEN 系统重启时 THEN 所有服务 SHALL 在合理时间内恢复正常
+
+### 需求 6
+
+**用户故事:** 作为部署工程师，我希望更新部署脚本和配置，以便支持新的 Swoole 架构部署。
+
+#### 验收标准
+
+1. WHEN 执行部署脚本时 THEN 系统 SHALL 构建包含 Swoole 的新镜像
+2. WHEN 更新 docker-compose 配置时 THEN 系统 SHALL 移除 Nginx 容器依赖
+3. WHEN 配置环境变量时 THEN 系统 SHALL 支持 Swoole 相关配置参数
+4. WHEN 验证部署时 THEN 系统 SHALL 确认 Swoole 服务正常运行
+5. WHEN 回滚部署时 THEN 系统 SHALL 支持回退到之前的架构
--- a/.kiro/specs/swoole-integration/tasks.md
+++ b/.kiro/specs/swoole-integration/tasks.md
@@ -0,0 +1,185 @@
+# 实施计划 - Swoole 集成
+
+## 概述
+
+本实施计划将现有的 Laravel 知识库系统从 PHP-FPM + Nginx 架构迁移到基于 Swoole 的高性能架构。采用最小化代码修改的策略，主要通过安装 Laravel Octane 包和更新配置来实现。
+
+## 任务列表
+
+- [x] 1. 安装和配置 Laravel Octane
+  - 安装 laravel/octane 包
+  - 发布 Octane 配置文件
+  - 配置 Swoole 相关环境变量
+  - _需求: 1.1, 2.1_
+
+- [ ]* 1.1 编写 Octane 启动测试
+  - **属性 1: Swoole 服务器启动一致性**
+  - **验证: 需求 1.1**
+
+- [ ]* 1.2 编写命令行接口测试
+  - **属性 4: Artisan 命令执行一致性**
+  - **验证: 需求 2.1, 2.4, 2.5**
+
+- [x] 2. 更新 Composer 依赖
+  - 添加 laravel/octane 到 composer.json
+  - 安装 Swoole PHP 扩展依赖
+  - 更新 composer 脚本以支持 Swoole 启动
+  - _需求: 1.1, 2.1_
+
+- [ ]* 2.1 编写依赖安装验证测试
+  - **属性 7: Swoole 扩展安装完整性**
+  - **验证: 需求 3.1**
+
+- [ ] 3. 更新 Docker 配置
+  - 修改 Dockerfile 安装 Swoole 扩展
+  - 移除 Nginx 和 PHP-FPM 相关配置
+  - 更新容器启动命令使用 Octane
+  - 调整端口映射配置
+  - _需求: 3.1, 3.2, 3.3_
+
+- [ ]* 3.1 编写 Docker 镜像验证测试
+  - **属性 8: 容器进程替换正确性**
+  - **验证: 需求 3.2**
+
+- [ ]* 3.2 编写端口配置测试
+  - **属性 5: 端口配置正确性**
+  - **属性 9: 容器端口暴露正确性**
+  - **验证: 需求 2.2, 3.3**
+
+- [x] 4. 更新 docker-compose.yml
+  - 移除 Nginx 服务配置
+  - 更新应用服务使用 Swoole 端口
+  - 调整服务依赖关系
+  - 更新健康检查配置
+  - _需求: 3.2, 6.2_
+
+- [ ]* 4.1 编写 docker-compose 配置验证测试
+  - **属性 17: 配置文件更新正确性**
+  - **验证: 需求 6.2**
+
+- [x] 5. 配置环境变量
+  - 更新 .env 文件添加 Octane 配置
+  - 设置 Swoole 工作进程数量
+  - 配置最大请求数和其他性能参数
+  - _需求: 1.4, 2.2, 2.3, 6.3_
+
+- [ ]* 5.1 编写环境变量配置测试
+  - **属性 6: 工作进程数量一致性**
+  - **属性 18: 环境变量配置生效性**
+  - **验证: 需求 2.3, 6.3**
+
+- [x] 6. 验证队列系统兼容性
+  - 测试现有队列任务在 Swoole 环境下的运行
+  - 验证文档转换队列功能
+  - 确认队列监听器自动启动
+  - _需求: 4.1, 4.2, 4.3_
+
+- [ ]* 6.1 编写队列兼容性测试
+  - **属性 10: 队列处理兼容性**
+  - **属性 11: 队列监听器自动启动**
+  - **验证: 需求 4.1, 4.2, 4.3**
+
+- [ ]* 6.2 编写队列错误处理测试
+  - **属性 12: 队列错误处理一致性**
+  - **验证: 需求 4.4**
+
+- [ ] 7. 更新部署脚本
+  - 修改 Docker 镜像构建脚本
+  - 更新部署验证脚本
+  - 调整健康检查脚本
+  - _需求: 6.1, 6.4_
+
+- [ ]* 7.1 编写部署脚本验证测试
+  - **属性 16: 部署脚本镜像构建正确性**
+  - **验证: 需求 6.1**
+
+- [ ] 8. 第一次检查点 - 确保所有测试通过
+  - 确保所有测试通过，如有问题请询问用户
+
+- [ ] 9. 性能和稳定性测试
+  - 配置负载测试环境
+  - 执行并发请求测试
+  - 监控内存使用情况
+  - 验证长时间运行稳定性
+  - _需求: 5.1, 5.2_
+
+- [ ]* 9.1 编写性能测试
+  - **属性 13: 高并发处理稳定性**
+  - **属性 14: 内存使用稳定性**
+  - **验证: 需求 5.1, 5.2**
+
+- [ ] 10. 健康检查和监控
+  - 实现 Swoole 服务健康检查接口
+  - 配置系统监控和告警
+  - 验证错误日志记录功能
+  - _需求: 5.3, 5.4_
+
+- [ ]* 10.1 编写健康检查测试
+  - **属性 15: 健康检查响应一致性**
+  - **验证: 需求 5.4**
+
+- [ ] 11. 文档更新
+  - 更新部署指南
+  - 更新运维文档
+  - 创建 Swoole 配置说明
+  - _需求: 6.4_
+
+- [ ] 12. 回滚机制准备
+  - 准备回滚到原架构的脚本
+  - 测试回滚流程
+  - 文档化回滚步骤
+  - _需求: 6.5_
+
+- [ ]* 12.1 编写回滚功能测试
+  - 验证回滚机制的正确性
+  - _需求: 6.5_
+
+- [ ] 13. 最终检查点 - 确保所有测试通过
+  - 确保所有测试通过，如有问题请询问用户
+
+## 实施注意事项
+
+### 最小化代码修改原则
+
+1. **保持现有代码不变**: 所有 Controllers、Models、Services 保持原样
+2. **利用 Laravel Octane 默认配置**: 避免自定义复杂的配置逻辑
+3. **渐进式迁移**: 先在开发环境验证，再部署到生产环境
+4. **保留回滚能力**: 确保可以快速回退到原有架构
+
+### 关键配置参数
+
+```bash
+# 核心 Swoole 配置
+OCTANE_SERVER=swoole
+OCTANE_HOST=0.0.0.0
+OCTANE_PORT=8000
+OCTANE_WORKERS=4
+OCTANE_TASK_WORKERS=2
+OCTANE_MAX_REQUESTS=500
+```
+
+### 验证检查清单
+
+- [ ] Swoole 扩展正确安装
+- [ ] Octane 命令正常工作
+- [ ] HTTP 请求正确处理
+- [ ] 队列任务正常执行
+- [ ] 数据库连接稳定
+- [ ] 缓存系统正常
+- [ ] 搜索功能可用
+- [ ] 文件上传下载正常
+- [ ] 性能指标符合预期
+
+### 性能预期
+
+- **响应时间**: 比原架构提升 30-50%
+- **并发处理**: 支持更高的并发连接数
+- **内存使用**: 更高效的内存利用
+- **CPU 使用**: 更好的 CPU 利用率
+
+### 风险缓解
+
+1. **充分测试**: 在开发环境完整测试所有功能
+2. **分阶段部署**: 先部署到测试环境，再到生产环境
+3. **监控告警**: 部署后密切监控系统指标
+4. **快速回滚**: 准备好快速回滚方案