Files

lizhuoran 3c206e9e06 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

7.9 KiB

Raw Blame History

Docker健康检查和监控指南

本文档描述了Laravel知识库系统的Docker健康检查和自动重启机制的配置和使用方法。

概述

系统实现了完整的健康检查和自动重启机制，包括：

Web应用HTTP健康检查 - 检查应用程序和依赖服务状态
数据库连接健康检查 - 验证MySQL数据库连接
Redis连接健康检查 - 验证Redis缓存服务连接
Meilisearch API健康检查 - 验证搜索引擎服务状态
容器自动重启策略 - 在服务失败时自动恢复
持续监控系统 - 主动监控和故障处理

健康检查配置

1. Web应用健康检查

端点: GET /health

检查项目:

数据库连接状态
Redis缓存连接状态
Meilisearch搜索引擎连接状态
存储目录可写性

响应格式:

{
  "status": "ok|degraded",
  "timestamp": "2024-12-24T10:30:00.000000Z",
  "services": {
    "database": "connected|disconnected",
    "redis": "connected|disconnected|not_configured",
    "meilisearch": "connected|disconnected|not_configured",
    "storage": "writable|not_writable"
  },
  "version": "1.0.0"
}

Docker配置:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost/health"]
  interval: 30s
  timeout: 10s
  retries: 5
  start_period: 60s

2. MySQL数据库健康检查

检查方法: mysqladmin ping

Docker配置:

healthcheck:
  test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p${DB_PASSWORD}"]
  interval: 30s
  timeout: 10s
  retries: 5
  start_period: 30s

3. Redis缓存健康检查

检查方法: redis-cli ping

Docker配置:

healthcheck:
  test: ["CMD", "redis-cli", "ping"]
  interval: 30s
  timeout: 10s
  retries: 5
  start_period: 10s

4. Meilisearch搜索引擎健康检查

检查方法: curl -f http://localhost:7700/health

Docker配置:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:7700/health"]
  interval: 30s
  timeout: 10s
  retries: 5
  start_period: 30s

5. 队列处理器健康检查

检查方法: 自定义脚本检查队列进程和依赖服务

脚本位置: /usr/local/bin/queue-health-check.sh

Docker配置:

healthcheck:
  test: ["CMD", "/usr/local/bin/queue-health-check.sh"]
  interval: 60s
  timeout: 30s
  retries: 3
  start_period: 30s

自动重启策略

所有服务都配置了 restart: unless-stopped 策略：

自动重启: 容器异常退出时自动重启
手动停止: 手动停止的容器不会自动重启
系统重启: 系统重启后自动启动容器（除非手动停止）

监控系统

持续监控脚本

脚本: docker/monitor-services.sh

功能:

持续监控所有服务的健康状态
自动重启不健康的容器
限制重启次数防止无限重启
记录详细的监控日志
发送告警通知

配置参数:

MONITOR_INTERVAL: 监控间隔（默认60秒）
MAX_RESTART_ATTEMPTS: 最大重启尝试次数（默认3次）
RESTART_COOLDOWN: 重启冷却时间（默认300秒）
LOG_FILE: 日志文件路径

服务状态检查脚本

脚本: docker/check-services.sh

功能:

一次性检查所有服务状态
详细的健康状态报告
连接测试和故障诊断

使用方法

1. 启动服务和监控

# 完整启动（包含监控）
./docker/start-with-monitoring.sh

# 启动服务但不启动监控
./docker/start-with-monitoring.sh --no-monitor

# 跳过镜像构建
./docker/start-with-monitoring.sh --skip-build

# 跳过服务就绪等待
./docker/start-with-monitoring.sh --skip-wait

2. 检查服务状态

# 运行完整的健康检查
./docker/check-services.sh

# 查看容器状态
docker-compose ps

# 查看容器健康状态
docker inspect --format='{{.State.Health.Status}}' knowledge_base_app

3. 查看监控日志

# 查看监控日志
tail -f ./storage/logs/monitor.log

# 查看监控输出
tail -f ./storage/logs/monitor-output.log

# 查看容器日志
docker-compose logs -f app
docker-compose logs -f queue

4. 停止监控

# 只停止监控进程
./docker/stop-monitoring.sh

# 停止监控和服务
./docker/stop-monitoring.sh --stop-services

# 停止监控、服务并清理日志
./docker/stop-monitoring.sh --all

5. 手动重启服务

# 重启单个服务
docker-compose restart app

# 重启所有服务
docker-compose restart

# 重新构建并启动
docker-compose up -d --build

监控指标

健康检查状态

healthy: 服务正常运行
unhealthy: 服务健康检查失败
starting: 服务正在启动
no-healthcheck: 服务未配置健康检查

监控日志格式

2024-12-24 10:30:00 [INFO] 开始监控检查 (共5个服务)
2024-12-24 10:30:01 [SUCCESS] MySQL数据库容器健康状态正常
2024-12-24 10:30:02 [SUCCESS] Redis缓存容器健康状态正常
2024-12-24 10:30:03 [SUCCESS] Meilisearch搜索容器健康状态正常
2024-12-24 10:30:04 [SUCCESS] Web应用容器健康状态正常
2024-12-24 10:30:05 [SUCCESS] 队列处理器容器健康状态正常
2024-12-24 10:30:06 [SUCCESS] 所有服务运行正常

重启计数器

监控系统维护每个容器的重启计数器：

位置: ./storage/logs/restart_counters/
格式: {container_name}.count
重置: 容器健康时自动重置

故障排除

常见问题

健康检查失败

# 检查容器日志
docker-compose logs app

# 手动测试健康检查端点
curl -v http://localhost/health

监控进程无法启动

# 检查权限
ls -la docker/monitor-services.sh

# 手动运行监控脚本
./docker/monitor-services.sh

容器重启循环

# 查看重启计数器
cat ./storage/logs/restart_counters/knowledge_base_app.count

# 重置重启计数器
echo "0" > ./storage/logs/restart_counters/knowledge_base_app.count

存储权限问题

# 修复存储目录权限
sudo chown -R $(id -u):$(id -g) ./storage
chmod -R 755 ./storage

调试模式

启用详细日志记录：

# 设置环境变量
export LOG_LEVEL=debug

# 运行监控脚本
./docker/monitor-services.sh --interval 30

生产环境建议

监控配置
- 设置适当的监控间隔（建议60-120秒）
- 配置告警通知（邮件、Slack等）
- 定期检查监控日志
资源限制
- 为容器设置内存和CPU限制
- 监控系统资源使用情况
- 配置日志轮转
备份策略
- 定期备份数据库和搜索索引
- 备份应用配置和上传文件
- 测试恢复流程
安全考虑
- 限制健康检查端点的访问
- 使用强密码和密钥
- 定期更新容器镜像

扩展功能

自定义告警

在 monitor-services.sh 中的 send_alert 函数中添加自定义告警逻辑：

send_alert() {
    local message=$1
    local severity=$2
    
    # 发送邮件告警
    echo "$message" | mail -s "Docker监控告警" admin@example.com
    
    # 发送到Slack
    curl -X POST -H 'Content-type: application/json' \
        --data "{\"text\":\"$message\"}" \
        "$SLACK_WEBHOOK_URL"
}

集成外部监控

可以将健康检查数据发送到外部监控系统：

Prometheus + Grafana
Zabbix
Nagios
DataDog

自动扩缩容

基于健康检查结果实现自动扩缩容：

# 检查负载并调整副本数
if [ $cpu_usage -gt 80 ]; then
    docker-compose up -d --scale app=3
fi

总结

本系统提供了完整的健康检查和自动重启机制，确保服务的高可用性。通过合理配置和使用这些工具，可以大大提高系统的稳定性和可靠性。

定期检查监控日志，及时处理告警，并根据实际情况调整配置参数，是维护系统健康运行的关键。

7.9 KiB Raw Blame History Unescape Escape

Docker健康检查和监控指南

概述

健康检查配置

1. Web应用健康检查

2. MySQL数据库健康检查

3. Redis缓存健康检查

4. Meilisearch搜索引擎健康检查

5. 队列处理器健康检查

自动重启策略

监控系统

持续监控脚本

服务状态检查脚本

使用方法

1. 启动服务和监控

2. 检查服务状态

3. 查看监控日志

4. 停止监控

5. 手动重启服务

监控指标

健康检查状态

监控日志格式

重启计数器

故障排除

常见问题

调试模式

生产环境建议

扩展功能

自定义告警

集成外部监控

自动扩缩容

总结

7.9 KiB

Raw Blame History