Docker部署Laravel与PostgreSQL实战教程

作者：归人云淡风轻时间：2026-01-31 来源：正软商城浏览：3

本教程旨在提供一个使用Docker容器化Laravel应用与PostgreSQL数据库的完整指南。我们将详细介绍如何配置Dockerfile以构建PHP-FPM服务，集成Composer和Node.js，并创建docker-compose.yml文件来编排Laravel应用容器和PostgreSQL数据库容器。通过本指南，读者将学习如何构建、运行并管理一个基于Docker的Laravel开发环境，确保环境一致性和部署便捷性。

本文目录

使用Docker容器化Laravel与PostgreSQL：完整实践指南

引言

在现代软件开发中，容器化技术已成为构建、部署和管理应用程序的基石。Docker通过提供轻量级、可移植且自包含的运行环境，极大地简化了开发工作流。本教程将指导您如何使用Docker和Docker Compose，将一个Laravel应用程序与PostgreSQL数据库进行容器化，从而实现一个高效、一致且易于维护的开发环境。

前提条件

在开始之前，请确保您的系统已安装以下软件：

Docker Desktop: 包含Docker Engine和Docker Compose。
一个现有的Laravel项目（或创建一个新项目）。

项目结构

为了保持清晰和组织性，建议您的项目根目录包含以下文件和目录：

your-laravel-project/
├── .env                 # Laravel 环境变量文件
├── Dockerfile           # Laravel 应用的 Docker 构建文件
├── docker-compose.yml   # Docker Compose 编排文件
├── app/
├── bootstrap/
├── config/
├── database/
├── public/
├── resources/
├── routes/
├── storage/
├── tests/
├── vendor/
└── ... (其他Laravel文件)

1. 定义Laravel应用服务（Dockerfile）

Dockerfile用于构建包含Laravel应用及其所有依赖的Docker镜像。我们将基于PHP-FPM官方镜像，并安装必要的系统依赖、PHP扩展、Composer和Node.js。

在项目根目录下创建名为Dockerfile的文件，并添加以下内容：

# 使用官方PHP-FPM运行时作为父镜像
FROM php:7.4-fpm

# 设置工作目录
WORKDIR /app

# 安装系统依赖：Git、Curl、图像处理库、PostgreSQL客户端、压缩工具等
# 注意：Python3及其科学计算库（pandas, scikit-learn, numpy）在此处安装，
# 如果您的Laravel应用不涉及数据科学，可以移除相关行以减小镜像体积。
RUN apt-get update && apt-get install -y \
    git \
    curl \
    libpng-dev \
    libonig-dev \
    libxml2-dev \
    libzip-dev \
    zip \
    unzip \
    vim \
    postgresql-client \
    libpq-dev \
    python3 \
    python3-pip && \
    ln -s /usr/bin/python3 /usr/bin/python

# 安装Python包（可选，如果不需要数据科学工具可移除）
RUN pip3 install --no-cache-dir pandas scikit-learn numpy

# 安装PHP扩展：PostgreSQL PDO、多字节字符串、Exif、进程控制、高精度计算、GD库、Zip
RUN docker-php-ext-install pdo_pgsql mbstring exif pcntl bcmath gd zip
# 启用已安装的GD和Zip扩展
RUN docker-php-ext-enable gd zip

# 安装Node.js和npm（Laravel Mix等前端工具可能需要）
# 这里安装Node.js 16.x版本
RUN curl -fsSL https://deb.nodesource.com/setup_16.x | bash - \
    && apt-get install -y nodejs

# 安装Composer
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

# 将应用程序文件复制到容器中
COPY . .

# 安装Laravel依赖
# 移除旧的vendor目录和composer.lock以确保全新安装
# 使用 composer install --no-dev --optimize-autoloader 优化生产环境的依赖安装
RUN rm -rf vendor composer.lock && composer update && composer install --no-dev --optimize-autoloader

# 设置Laravel目录的权限
# www-data 是 PHP-FPM 进程通常使用的用户和组
RUN chmod -R 775 storage bootstrap/cache && \
    chown -R www-data:www-data /app

# 安装Node.js依赖（如果使用Laravel Mix）
RUN npm install

# 暴露PHP-FPM默认端口9000
EXPOSE 9000

# 启动PHP-FPM服务
CMD ["php-fpm"]

代码解释：

FROM php:7.4-fpm: 选择PHP 7.4 FPM作为基础镜像，它包含了运行PHP应用程序所需的环境。
WORKDIR /app: 将容器内的工作目录设置为/app。所有后续命令都将在此目录下执行。
RUN apt-get update && apt-get install -y ...: 安装必要的系统软件包，包括Git、Curl、图像处理库、PostgreSQL客户端库（postgresql-client, libpq-dev）等。
RUN docker-php-ext-install ...: 安装并启用Laravel常用的PHP扩展，如pdo_pgsql（用于PostgreSQL连接）、mbstring、gd（图像处理）和zip。
RUN curl -fsSL ... | bash - && apt-get install -y nodejs: 安装Node.js和npm，这对于使用Laravel Mix编译前端资源非常重要。
RUN curl -sS ... | php -- ...: 安装Composer，用于管理PHP依赖。
COPY . .: 将宿主机当前目录（即Laravel项目根目录）下的所有文件复制到容器的/app目录。
RUN rm -rf vendor composer.lock && composer update && composer install --no-dev --optimize-autoloader: 清理旧的依赖，然后通过composer update更新composer.lock文件，最后执行composer install安装项目依赖。--no-dev用于跳过开发环境依赖，--optimize-autoloader用于优化自动加载。
RUN chmod -R 775 storage bootstrap/cache && chown -R www-data:www-data /app: 设置storage和bootstrap/cache目录的写入权限，并更改整个/app目录的所有者为www-data用户，确保PHP-FPM进程有足够的权限。
RUN npm install: 安装Node.js项目依赖。
EXPOSE 9000: 声明容器将监听9000端口，这是PHP-FPM的默认端口。
CMD ["php-fpm"]: 定义容器启动时执行的默认命令，即启动PHP-FPM服务。

2. 编排服务（docker-compose.yml）

docker-compose.yml文件用于定义和运行多容器Docker应用程序。我们将定义两个服务：一个用于Laravel应用（laravel-app），另一个用于PostgreSQL数据库（postgres-db）。

在项目根目录下创建名为docker-compose.yml的文件，并添加以下内容：

version: '3.8' # 推荐使用较新的Compose文件格式版本

services:
  # Laravel 应用服务
  laravel-app:
    container_name: laravel-app-container # 指定容器名称
    build:
      context: . # Dockerfile 所在的上下文路径
      dockerfile: Dockerfile # 指定 Dockerfile 文件名
    command: 'php artisan serve --host=0.0.0.0 --port=8000' # 启动Laravel开发服务器
    restart: unless-stopped # 容器异常退出时自动重启
    volumes:
      - .:/app # 将宿主机当前目录挂载到容器的 /app 目录，实现代码同步
    ports:
      - "8000:8000" # 将宿主机的 8000 端口映射到容器的 8000 端口
    depends_on:
      - postgres-db # 声明此服务依赖于 postgres-db 服务
    networks:
      - app-network # 将此服务连接到 app-network 网络

  # PostgreSQL 数据库服务
  postgres-db:
    container_name: postgres-db-container # 指定容器名称
    image: postgres:13 # 使用官方 PostgreSQL 13 镜像
    restart: unless-stopped # 容器异常退出时自动重启
    environment: # 设置 PostgreSQL 环境变量
      POSTGRES_DB: laravel_db # 数据库名称
      POSTGRES_USER: laravel_user # 数据库用户
      POSTGRES_PASSWORD: secret # 数据库密码
      # POSTGRES_HOST_AUTH_METHOD: "trust" # 生产环境不推荐，仅用于开发简化认证
    volumes:
      - postgres_data:/var/lib/postgresql/data # 挂载数据卷，实现数据持久化
    ports:
      - "5432:5432" # 将宿主机的 5432 端口映射到容器的 5432 端口
    networks:
      - app-network # 将此服务连接到 app-network 网络

# 定义网络，使服务之间可以互相通信
networks:
  app-network:
    driver: bridge # 使用桥接网络驱动

# 定义数据卷，用于 PostgreSQL 数据的持久化存储
volumes:
  postgres_data:
    driver: local # 使用本地驱动

代码解释：

version: '3.8': 指定Docker Compose文件格式版本。
services: 定义了两个服务。
- laravel-app:
  - build: 指示Docker Compose根据当前目录下的Dockerfile构建镜像。
  - command: 'php artisan serve --host=0.0.0.0 --port=8000': 覆盖Dockerfile中的CMD，直接使用Laravel自带的开发服务器启动应用。这在开发环境中非常方便。
  - volumes: - .:/app: 将宿主机项目根目录挂载到容器的/app目录。这意味着您在宿主机上修改代码，容器内会立即同步，无需重新构建镜像。
  - ports: - "8000:8000": 将宿主机的8000端口映射到容器的8000端口，您可以通过http://localhost:8000访问Laravel应用。
  - depends_on: - postgres-db: 声明laravel-app服务依赖于postgres-db服务，Docker Compose会确保postgres-db先启动。
  - networks: - app-network: 将laravel-app服务连接到名为app-network的自定义网络。
- postgres-db:
  - image: postgres:13: 使用官方的PostgreSQL 13镜像。
  - environment: 设置PostgreSQL的环境变量，包括数据库名、用户名和密码。这些信息将用于Laravel应用的数据库连接。
  - volumes: - postgres_data:/var/lib/postgresql/data: 使用一个命名卷postgres_data来持久化PostgreSQL的数据。这样即使容器被删除，数据也不会丢失。
  - ports: - "5432:5432": 将宿主机的5432端口映射到容器的5432端口，允许您从宿主机连接到数据库。
  - networks: - app-network: 将postgres-db服务连接到app-network网络。
networks: 定义了一个名为app-network的桥接网络，允许laravel-app和postgres-db服务通过服务名互相通信。
volumes: 定义了一个命名卷postgres_data，用于PostgreSQL的数据持久化。