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>
This commit is contained in:
290
.kiro/specs/docker-deployment/design.md
Normal file
290
.kiro/specs/docker-deployment/design.md
Normal file
@@ -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次迭代
|
||||
- 测试应该覆盖各种输入组合和边界条件
|
||||
|
||||
**集成测试**:
|
||||
- 端到端部署流程测试
|
||||
- 服务间通信测试
|
||||
- 数据一致性测试
|
||||
- 性能基准测试
|
||||
Reference in New Issue
Block a user