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/docker-deployment/design.md
+++ b/.kiro/specs/docker-deployment/design.md
@@ -0,0 +1,290 @@
+# Docker部署设计文档
+
+## 概述
+
+本设计文档描述了将Laravel知识库系统Docker化部署到OpenEuler服务器的完整解决方案。系统采用微服务架构，通过Docker容器化技术实现应用的标准化部署和运维。
+
+设计目标：
+- 构建适用于OpenEuler服务器的amd64架构Docker镜像
+- 实现完整的应用栈容器化编排
+- 确保数据持久化和服务高可用性
+- 支持开发和生产环境的不同配置需求
+- 提供便捷的镜像打包和离线部署能力
+
+## 架构
+
+### 整体架构
+
+系统采用多容器架构，包含以下核心组件：
+
+```mermaid
+graph TB
+    subgraph "Docker Host (OpenEuler)"
+        subgraph "Application Stack"
+            nginx[Nginx容器<br/>Web服务器]
+            app[Laravel应用容器<br/>PHP-FPM]
+            queue[队列处理容器<br/>Laravel Queue]
+        end
+        
+        subgraph "Data Layer"
+            mysql[MySQL容器<br/>主数据库]
+            redis[Redis容器<br/>缓存/会话]
+            meilisearch[Meilisearch容器<br/>搜索引擎]
+        end
+        
+        subgraph "Storage"
+            app_data[应用数据卷]
+            db_data[数据库数据卷]
+            search_data[搜索数据卷]
+            logs[日志卷]
+        end
+    end
+    
+    nginx --> app
+    app --> mysql
+    app --> redis
+    app --> meilisearch
+    queue --> mysql
+    queue --> redis
+    
+    app --> app_data
+    mysql --> db_data
+    meilisearch --> search_data
+    nginx --> logs
+    app --> logs
+```
+
+### 网络架构
+
+- **外部网络**: 通过宿主机端口映射提供Web服务访问
+- **内部网络**: 创建专用Docker网络供容器间通信
+- **服务发现**: 通过容器名称进行服务间通信
+
+### 存储架构
+
+- **代码存储**: 项目目录映射到应用容器，支持开发时热重载
+- **数据持久化**: 数据库、搜索引擎、上传文件使用Docker卷持久化
+- **日志管理**: 应用日志映射到宿主机便于监控和调试
+
+## 组件和接口
+
+### Docker镜像组件
+
+#### 1. Laravel应用镜像 (knowledge-base-app)
+- **基础镜像**: php:8.2-fpm-alpine
+- **运行时**: PHP-FPM + Nginx
+- **依赖**: Composer包、NPM构建产物、Pandoc
+- **配置**: PHP扩展、Nginx配置、应用配置
+
+#### 2. 数据库组件 (MySQL)
+- **镜像**: mysql:8.0
+- **配置**: 字符集utf8mb4、时区设置
+- **存储**: 数据目录持久化
+
+#### 3. 缓存组件 (Redis)
+- **镜像**: redis:7-alpine
+- **配置**: 内存限制、持久化策略
+- **用途**: 会话存储、应用缓存、队列存储
+
+#### 4. 搜索组件 (Meilisearch)
+- **镜像**: getmeili/meilisearch:v1.5
+- **配置**: 主密钥、环境模式
+- **存储**: 索引数据持久化
+
+### 服务接口
+
+#### Web服务接口
+- **端口**: 80 (HTTP)
+- **协议**: HTTP/1.1
+- **负载均衡**: Nginx upstream配置
+
+#### 数据库接口
+- **端口**: 3306 (内部)
+- **协议**: MySQL Protocol
+- **连接池**: Laravel数据库连接配置
+
+#### 缓存接口
+- **端口**: 6379 (内部)
+- **协议**: Redis Protocol
+- **连接**: phpredis扩展
+
+#### 搜索接口
+- **端口**: 7700 (内部)
+- **协议**: HTTP REST API
+- **认证**: Master Key
+
+## 数据模型
+
+### 容器配置模型
+
+```yaml
+# docker-compose.yml结构
+services:
+  app:
+    image: knowledge-base-app:latest
+    platform: linux/amd64
+    environment:
+      - APP_ENV=production
+      - DB_HOST=mysql
+      - REDIS_HOST=redis
+      - MEILISEARCH_HOST=http://meilisearch:7700
+    volumes:
+      - ./:/var/www/html
+      - storage_data:/var/www/html/storage
+    depends_on:
+      - mysql
+      - redis
+      - meilisearch
+```
+
+### 环境变量模型
+
+```bash
+# 生产环境变量
+APP_ENV=production
+APP_DEBUG=false
+DB_CONNECTION=mysql
+DB_HOST=mysql
+DB_PORT=3306
+REDIS_HOST=redis
+REDIS_PORT=6379
+MEILISEARCH_HOST=http://meilisearch:7700
+```
+
+### 存储卷模型
+
+```yaml
+volumes:
+  mysql_data:
+    driver: local
+  redis_data:
+    driver: local
+  meilisearch_data:
+    driver: local
+  storage_data:
+    driver: local
+```
+
+## 正确性属性
+
+*属性是应该在系统的所有有效执行中保持为真的特征或行为——本质上是关于系统应该做什么的正式声明。属性作为人类可读规范和机器可验证正确性保证之间的桥梁。*
+
+### 属性1: 镜像架构一致性
+*对于任何*构建的Docker镜像，检查其架构信息应该返回linux/amd64
+**验证: 需求 1.1**
+
+### 属性2: PHP环境完整性
+*对于任何*构建的应用镜像，在容器内执行PHP版本检查应该返回8.2.x版本且包含所有必需扩展
+**验证: 需求 1.2**
+
+### 属性3: 构建产物存在性
+*对于任何*构建的应用镜像，vendor目录和public/js、public/css目录应该存在且包含必要文件
+**验证: 需求 1.3**
+
+### 属性4: 服务启动一致性
+*对于任何*docker-compose启动操作，所有定义的服务容器应该成功启动并达到健康状态
+**验证: 需求 2.1, 2.2, 2.3, 2.4, 2.5**
+
+### 属性5: 数据持久化保证
+*对于任何*容器重启操作，持久化存储中的数据应该保持不变且可访问
+**验证: 需求 3.2, 3.3, 3.4**
+
+### 属性6: 服务连接性
+*对于任何*运行中的服务栈，应用容器应该能够成功连接到所有依赖服务
+**验证: 需求 4.2, 4.3, 4.4**
+
+### 属性7: 健康检查响应性
+*对于任何*运行中的服务，健康检查端点应该在合理时间内返回成功响应
+**验证: 需求 5.1, 5.2, 5.3, 5.4**
+
+### 属性8: 容器自愈能力
+*对于任何*模拟的容器故障，系统应该根据重启策略自动恢复服务
+**验证: 需求 5.5**
+
+### 属性9: 镜像导出完整性
+*对于任何*导出的Docker镜像tar文件，应该包含完整的镜像层和元数据信息
+**验证: 需求 6.1**
+
+### 属性10: 镜像导入兼容性
+*对于任何*导出的镜像tar文件，在OpenEuler环境中导入后应该能够正常运行
+**验证: 需求 6.2**
+
+### 属性11: 压缩效率
+*对于任何*镜像压缩操作，压缩后的文件大小应该显著小于原始大小
+**验证: 需求 6.3**
+
+### 属性12: 完整性验证
+*对于任何*镜像文件，完整性检查应该能够验证文件未被损坏且架构正确
+**验证: 需求 6.4**
+
+### 属性13: 开发环境热重载
+*对于任何*开发环境中的代码修改，应用应该在合理时间内反映更改
+**验证: 需求 7.1**
+
+## 错误处理
+
+### 容器启动失败
+- **检测**: 健康检查失败或容器退出
+- **处理**: 自动重启策略，最大重试次数限制
+- **日志**: 详细错误日志记录到宿主机
+
+### 服务连接失败
+- **检测**: 连接超时或拒绝连接
+- **处理**: 重试机制，降级服务
+- **监控**: 连接状态监控和告警
+
+### 数据持久化失败
+- **检测**: 卷挂载失败或权限错误
+- **处理**: 容器启动前预检查
+- **恢复**: 数据备份和恢复机制
+
+### 镜像构建失败
+- **检测**: 构建过程中的错误退出
+- **处理**: 分阶段构建，错误定位
+- **优化**: 构建缓存和依赖管理
+
+## 测试策略
+
+### 单元测试方法
+
+**容器构建测试**:
+- 验证Dockerfile语法正确性
+- 测试构建过程中的关键步骤
+- 检查构建产物的完整性
+
+**配置文件测试**:
+- 验证docker-compose.yml语法
+- 测试环境变量配置的正确性
+- 检查网络和存储配置
+
+**脚本功能测试**:
+- 测试部署脚本的执行流程
+- 验证健康检查脚本的准确性
+- 测试备份和恢复脚本
+
+### 属性测试方法
+
+**测试框架**: 使用Bash脚本结合Docker命令进行属性测试，每个属性测试运行100次迭代以确保可靠性。
+
+**测试环境**: 
+- 本地Docker环境用于开发测试
+- OpenEuler虚拟机用于兼容性测试
+- CI/CD环境用于自动化测试
+
+**测试数据生成**:
+- 随机生成不同的环境配置
+- 模拟各种故障场景
+- 生成不同规模的测试数据
+
+**属性测试实现要求**:
+- 每个正确性属性必须实现为单独的属性测试
+- 测试必须标注对应的设计文档属性编号
+- 使用格式: `# Feature: docker-deployment, Property X: [属性描述]`
+- 每个属性测试最少运行100次迭代
+- 测试应该覆盖各种输入组合和边界条件
+
+**集成测试**:
+- 端到端部署流程测试
+- 服务间通信测试
+- 数据一致性测试
+- 性能基准测试
--- a/.kiro/specs/docker-deployment/requirements.md
+++ b/.kiro/specs/docker-deployment/requirements.md
@@ -0,0 +1,102 @@
+# Docker部署需求文档
+
+## 介绍
+
+本文档定义了将Laravel知识库系统Docker化部署到OpenEuler服务器的需求。系统需要支持完整的生产环境运行，包括Web应用、数据库、缓存、搜索引擎和队列处理等所有组件。
+
+## 术语表
+
+- **Docker镜像**: 包含应用程序及其运行环境的可执行包
+- **容器编排**: 使用docker-compose管理多个相关容器的技术
+- **知识库系统**: 基于Laravel框架的文档管理和搜索系统
+- **OpenEuler服务器**: 目标部署环境的Linux服务器
+- **生产环境**: 实际运行业务的服务器环境
+- **数据持久化**: 确保容器重启后数据不丢失的机制
+- **健康检查**: 监控容器运行状态的机制
+
+## 需求
+
+### 需求1
+
+**用户故事:** 作为系统管理员，我希望能够构建包含完整运行环境的Docker镜像，以便在OpenEuler服务器上部署知识库系统。
+
+#### 验收标准
+
+1. WHEN 构建Docker镜像时 THEN 系统应构建为linux/amd64架构以确保OpenEuler兼容性
+2. WHEN 构建Docker镜像时 THEN 系统应包含PHP 8.2运行环境和所有必需的扩展
+3. WHEN 构建Docker镜像时 THEN 系统应包含Composer依赖和NPM构建产物
+4. WHEN 构建Docker镜像时 THEN 系统应包含Nginx Web服务器配置
+5. WHEN 构建Docker镜像时 THEN 系统应包含文档转换工具Pandoc
+6. WHEN 构建Docker镜像时 THEN 系统应优化镜像大小并使用多阶段构建
+
+### 需求2
+
+**用户故事:** 作为系统管理员，我希望通过docker-compose编排所有服务，以便一键启动完整的应用栈。
+
+#### 验收标准
+
+1. WHEN 启动服务时 THEN 系统应启动MySQL数据库服务并配置持久化存储
+2. WHEN 启动服务时 THEN 系统应启动Redis缓存服务并配置内存限制
+3. WHEN 启动服务时 THEN 系统应启动Meilisearch搜索引擎并配置数据持久化
+4. WHEN 启动服务时 THEN 系统应启动Laravel应用容器并连接所有依赖服务
+5. WHEN 启动服务时 THEN 系统应启动队列处理容器处理后台任务
+
+### 需求3
+
+**用户故事:** 作为系统管理员，我希望配置数据持久化和目录映射，以便数据在容器重启后不丢失。
+
+#### 验收标准
+
+1. WHEN 配置存储时 THEN 系统应将项目代码目录映射到容器内部
+2. WHEN 配置存储时 THEN 系统应将上传文档存储目录持久化到宿主机
+3. WHEN 配置存储时 THEN 系统应将数据库数据目录持久化到宿主机
+4. WHEN 配置存储时 THEN 系统应将搜索引擎数据目录持久化到宿主机
+5. WHEN 配置存储时 THEN 系统应将日志目录映射到宿主机便于查看
+
+### 需求4
+
+**用户故事:** 作为系统管理员，我希望配置环境变量和网络，以便服务间能够正确通信。
+
+#### 验收标准
+
+1. WHEN 配置网络时 THEN 系统应创建专用Docker网络供服务间通信
+2. WHEN 配置环境时 THEN 系统应设置数据库连接参数指向MySQL容器
+3. WHEN 配置环境时 THEN 系统应设置Redis连接参数指向Redis容器
+4. WHEN 配置环境时 THEN 系统应设置Meilisearch连接参数指向搜索容器
+5. WHEN 配置环境时 THEN 系统应配置应用密钥和调试模式
+
+### 需求5
+
+**用户故事:** 作为系统管理员，我希望实现健康检查和自动重启，以便确保服务的高可用性。
+
+#### 验收标准
+
+1. WHEN 服务运行时 THEN 系统应对Web应用进行HTTP健康检查
+2. WHEN 服务运行时 THEN 系统应对数据库进行连接健康检查
+3. WHEN 服务运行时 THEN 系统应对Redis进行连接健康检查
+4. WHEN 服务运行时 THEN 系统应对Meilisearch进行API健康检查
+5. WHEN 服务异常时 THEN 系统应自动重启失败的容器
+
+### 需求6
+
+**用户故事:** 作为系统管理员，我希望能够导出和导入Docker镜像，以便在离线环境中部署。
+
+#### 验收标准
+
+1. WHEN 导出镜像时 THEN 系统应将构建好的amd64架构镜像打包为tar文件
+2. WHEN 导入镜像时 THEN 系统应能够从tar文件加载镜像到OpenEuler服务器的Docker
+3. WHEN 传输镜像时 THEN 系统应支持压缩以减少文件大小
+4. WHEN 验证镜像时 THEN 系统应提供镜像完整性和架构兼容性检查方法
+5. WHEN 部署镜像时 THEN 系统应提供详细的OpenEuler部署文档和脚本
+
+### 需求7
+
+**用户故事:** 作为开发人员，我希望有开发环境的Docker配置，以便本地开发和测试。
+
+#### 验收标准
+
+1. WHEN 开发环境启动时 THEN 系统应启用代码热重载功能
+2. WHEN 开发环境启动时 THEN 系统应启用调试模式和详细日志
+3. WHEN 开发环境启动时 THEN 系统应映射源代码目录支持实时编辑
+4. WHEN 开发环境启动时 THEN 系统应暴露所有必要的端口供调试
+5. WHEN 开发环境启动时 THEN 系统应包含开发工具和测试数据
--- a/.kiro/specs/docker-deployment/tasks.md
+++ b/.kiro/specs/docker-deployment/tasks.md
@@ -0,0 +1,157 @@
+# Docker部署实施计划
+
+- [x] 1. 创建Docker镜像构建配置
+  - 创建多阶段Dockerfile，优化镜像大小
+  - 配置PHP 8.2-fpm基础环境和必需扩展
+  - 安装Composer依赖和NPM构建工具
+  - 集成Nginx Web服务器配置
+  - 安装Pandoc文档转换工具
+  - 确保构建为linux/amd64架构
+  - _需求: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6_
+
+- [ ]* 1.1 编写属性测试验证镜像架构
+  - **属性1: 镜像架构一致性**
+  - **验证: 需求 1.1**
+
+- [ ]* 1.2 编写属性测试验证PHP环境
+  - **属性2: PHP环境完整性**
+  - **验证: 需求 1.2**
+
+- [ ]* 1.3 编写属性测试验证构建产物
+  - **属性3: 构建产物存在性**
+  - **验证: 需求 1.3**
+
+- [x] 2. 配置生产环境容器编排
+  - 创建生产环境docker-compose.yml文件
+  - 配置MySQL数据库服务和持久化存储
+  - 配置Redis缓存服务和内存限制
+  - 配置Meilisearch搜索引擎和数据持久化
+  - 配置Laravel应用容器和队列处理容器
+  - 设置服务间依赖关系和启动顺序
+  - _需求: 2.1, 2.2, 2.3, 2.4, 2.5_
+
+- [ ]* 2.1 编写属性测试验证服务启动
+  - **属性4: 服务启动一致性**
+  - **验证: 需求 2.1, 2.2, 2.3, 2.4, 2.5**
+
+- [x] 3. 实现数据持久化和目录映射
+  - 配置项目代码目录映射到容器
+  - 设置上传文档存储目录持久化
+  - 配置数据库数据目录持久化
+  - 设置搜索引擎数据目录持久化
+  - 配置日志目录映射到宿主机
+  - _需求: 3.1, 3.2, 3.3, 3.4, 3.5_
+
+- [ ]* 3.1 编写属性测试验证数据持久化
+  - **属性5: 数据持久化保证**
+  - **验证: 需求 3.2, 3.3, 3.4**
+
+- [x] 4. 配置环境变量和网络设置
+  - 创建专用Docker网络配置
+  - 设置数据库连接环境变量
+  - 配置Redis连接参数
+  - 设置Meilisearch连接参数
+  - 配置应用密钥和运行模式
+  - _需求: 4.1, 4.2, 4.3, 4.4, 4.5_
+
+- [ ]* 4.1 编写属性测试验证服务连接
+  - **属性6: 服务连接性**
+  - **验证: 需求 4.2, 4.3, 4.4**
+
+- [x] 5. 实现健康检查和自动重启机制
+  - 配置Web应用HTTP健康检查
+  - 实现数据库连接健康检查
+  - 配置Redis连接健康检查
+  - 设置Meilisearch API健康检查
+  - 配置容器自动重启策略
+  - _需求: 5.1, 5.2, 5.3, 5.4, 5.5_
+
+- [ ]* 5.1 编写属性测试验证健康检查
+  - **属性7: 健康检查响应性**
+  - **验证: 需求 5.1, 5.2, 5.3, 5.4**
+
+- [ ]* 5.2 编写属性测试验证自动重启
+  - **属性8: 容器自愈能力**
+  - **验证: 需求 5.5**
+
+- [x] 6. 创建镜像打包和部署脚本
+  - 编写Docker镜像导出脚本
+  - 实现镜像压缩和完整性检查
+  - 创建OpenEuler服务器部署脚本
+  - 编写镜像导入和验证脚本
+  - 生成详细的部署文档
+  - _需求: 6.1, 6.2, 6.3, 6.4, 6.5_
+
+- [ ]* 6.1 编写属性测试验证镜像导出
+  - **属性9: 镜像导出完整性**
+  - **验证: 需求 6.1**
+
+- [ ]* 6.2 编写属性测试验证镜像导入
+  - **属性10: 镜像导入兼容性**
+  - **验证: 需求 6.2**
+
+- [ ]* 6.3 编写属性测试验证压缩效率
+  - **属性11: 压缩效率**
+  - **验证: 需求 6.3**
+
+- [ ]* 6.4 编写属性测试验证完整性检查
+  - **属性12: 完整性验证**
+  - **验证: 需求 6.4**
+
+- [ ] 7. 配置开发环境支持
+  - 创建开发环境docker-compose.dev.yml
+  - 配置代码热重载功能
+  - 启用调试模式和详细日志
+  - 设置开发工具和测试数据
+  - 配置端口映射供调试使用
+  - _需求: 7.1, 7.2, 7.3, 7.4, 7.5_
+
+- [ ]* 7.1 编写属性测试验证热重载
+  - **属性13: 开发环境热重载**
+  - **验证: 需求 7.1**
+
+- [ ] 8. 创建Nginx配置文件
+  - 编写生产环境Nginx配置
+  - 配置PHP-FPM upstream
+  - 设置静态文件服务
+  - 配置日志格式和路径
+  - 优化性能参数
+  - _需求: 1.4_
+
+- [ ] 9. 编写环境配置模板
+  - 创建生产环境.env模板
+  - 创建开发环境.env模板
+  - 配置数据库连接参数
+  - 设置缓存和搜索服务配置
+  - 添加配置说明文档
+  - _需求: 4.2, 4.3, 4.4, 4.5_
+
+- [ ] 10. 实现启动和管理脚本
+  - 编写一键启动脚本
+  - 创建服务状态检查脚本
+  - 实现日志查看脚本
+  - 编写数据备份脚本
+  - 创建清理和重置脚本
+  - _需求: 2.1, 2.2, 2.3, 2.4, 2.5_
+
+- [ ] 11. 第一次检查点 - 确保所有测试通过
+  - 确保所有测试通过，如有问题请询问用户
+
+- [ ] 12. 创建部署文档
+  - 编写OpenEuler服务器环境准备指南
+  - 创建Docker安装和配置文档
+  - 编写应用部署步骤说明
+  - 添加故障排除指南
+  - 创建运维管理文档
+  - _需求: 6.5_
+
+- [ ] 13. 优化和安全配置
+  - 配置容器安全策略
+  - 设置资源限制和配额
+  - 实现日志轮转和清理
+  - 配置网络安全规则
+  - 添加监控和告警配置
+  - _需求: 2.2, 5.1, 5.2, 5.3, 5.4_
+
+- [ ] 14. 最终检查点 - 确保所有测试通过
+  - 确保所有测试通过，如有问题请询问用户