lizhuoran
3c206e9e06
- 添加 Dockerfile 与多套 docker-compose 配置（开发/生产环境） - 集成 Laravel Octane (Swoole) 提升性能 - 新增健康检查、监控脚本及部署文档 - 新增 Docker 镜像离线导入包（MySQL/Redis/Meilisearch） - 优化文档转换、预览服务及队列任务 - 添加 CreateAdminUser 命令与路由健康检查接口 - 新增 Swoole 队列兼容性测试套件 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
290 lines
8.1 KiB
Markdown
290 lines
8.1 KiB
Markdown
# 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次迭代
|
||
- 测试应该覆盖各种输入组合和边界条件
|
||
|
||
**集成测试**:
|
||
- 端到端部署流程测试
|
||
- 服务间通信测试
|
||
- 数据一致性测试
|
||
- 性能基准测试 |