Speedtest-Tracker 项目 Docker 部署指南

项目概述

Speedtest-Tracker 是一个基于 Laravel 框架开发的网络速度测试追踪工具，它能够定期执行网络速度测试并记录结果，帮助用户监控网络性能变化。本文主要介绍如何使用 Docker Compose 部署该项目的开发环境。

Docker Compose 文件解析

服务架构

该 Docker Compose 配置定义了两个主要服务：

1. laravel.test - 主应用服务，基于 PHP 8.3 构建
2. mailpit - 邮件测试服务，用于开发和调试邮件功能

主应用服务配置详解

构建配置

build:
    context: ./docker/8.3
    dockerfile: Dockerfile
    args:
        WWWGROUP: '${WWWGROUP}'

• 使用项目目录下 docker/8.3 中的 Dockerfile 构建镜像
• 构建时传入 WWWGROUP 参数，值从环境变量获取
• 这种设计使得用户可以通过环境变量自定义用户组

网络与端口

extra_hosts:
    - 'host.docker.internal:host-gateway'
ports:
    - '${APP_PORT:-80}:80'
    - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'

• extra_hosts 配置了容器内可访问宿主机的主机名
• 应用端口映射灵活：
  • 主应用端口默认为 80，可通过 APP_PORT 环境变量覆盖
  • Vite 前端开发服务器端口默认为 5173，可通过 VITE_PORT 环境变量覆盖

环境变量

environment:
    WWWUSER: '${WWWUSER}'
    LARAVEL_SAIL: 1
    XDEBUG_MODE: '${SAIL_XDEBUG_MODE:-off}'
    XDEBUG_CONFIG: '${SAIL_XDEBUG_CONFIG:-client_host=host.docker.internal}'

• 支持自定义用户 (WWWUSER)
• 启用了 Laravel Sail 支持
• Xdebug 配置灵活：
  • 模式可通过 SAIL_XDEBUG_MODE 设置，默认为 off
  • 客户端主机默认为 host.docker.internal

数据卷

volumes:
    - '.:/var/www/html'

• 将宿主机当前目录挂载到容器的 /var/www/html
• 这种设计便于开发时代码变更实时生效

Mailpit 邮件服务

mailpit:
    image: 'axllent/mailpit:latest'
    ports:
        - '${FORWARD_MAILPIT_PORT:-1025}:1025'
        - '${FORWARD_MAILPIT_DASHBOARD_PORT:-8025}:8025'

• 使用最新版 Mailpit 镜像
• 提供两个端口映射：
  • SMTP 端口默认为 1025
  • 管理界面端口默认为 8025
• 端口均可通过环境变量自定义

网络配置

networks:
    sail:
        driver: bridge

• 创建名为 sail 的桥接网络
• 所有服务都连接到该网络，便于服务间通信

部署建议

1. 环境准备：

   • 确保已安装 Docker 和 Docker Compose
   • 创建 .env 文件配置必要的环境变量

2. 自定义配置：

   • 端口映射可根据需要调整
   • Xdebug 配置应根据开发环境调整

3. 启动命令：

   docker-compose up -d
   

4. 开发注意事项：

   • 代码变更会实时反映在容器中
   • 邮件功能可通过 Mailpit 的 Web 界面(8025端口)查看

常见问题解决

1. 权限问题：

   • 确保 WWWUSER 和 WWWGROUP 环境变量正确设置
   • 可能需要调整宿主机文件权限

2. 端口冲突：

   • 如果默认端口被占用，通过环境变量修改映射端口

3. Xdebug 连接问题：

   • 检查宿主机防火墙设置
   • 确保 IDE 已配置监听对应端口

通过以上配置，Speedtest-Tracker 项目可以在 Docker 环境中快速部署和开发，充分利用了容器化技术的优势，为开发者提供了便捷的开发环境。