Ubuntu 部署 ThinkPHP 微服务指南：环境安装、Nginx 配置与 Docker 方案

时间：2026-08-23 | 作者：实验室老王 | 阅读：0

前言

在 Ubuntu 上部署 ThinkPHP 微服务，难点通常不在命令本身，而在 Nginx、PHP-FPM、项目目录和数据库这几层能不能准确对接。本文按真实上线流程整理环境安装、站点配置、代码发布、数据库迁移与联调检查点，并补充 Docker 方案，方便你在部署前后快速判断问题出在哪一段。

在 Ubuntu 上部署 ThinkPHP 微服务，真正容易卡住的往往不是“怎么装”，而是组件之间怎么对上：PHP-FPM 要和 Nginx 正常转发，项目依赖要能安装完成，数据库配置还得和服务状态一致。下面按上线顺序把关键步骤拆开，同时补上检查点和常见报错位置，方便你在部署过程中快速定位问题，也能判断自己更适合传统部署还是 Docker 方案。

准备运行环境：先把 PHP、Composer、Nginx 和 MySQL 装齐

一台可运行 ThinkPHP 微服务的 Ubuntu 主机，至少要具备 PHP、Composer、Nginx，以及 MySQL（或其他你偏好的数据库）。其中 php-fpm 是关键组件，后续 Nginx 会通过它来处理 PHP 请求。

安装 PHP 及常用扩展

PHP 扩展尽量一次装全，省得部署到一半再回头补环境：

sudo apt update
sudo apt install php php-cli php-fpm php-mysql php-curl php-json php-zip php-gd php-mbstring php-xml php-pear php-bcmath

如果后面 composer install 报扩展缺失，优先回头检查这一组包是否安装完整。

安装 Composer

ThinkPHP 项目的依赖管理依赖 Composer，安装方式如下：

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

安装完成后，任意目录下执行 composer 能正常响应，就说明工具已经可用。

安装 Nginx 和 MySQL

Nginx 负责接收 HTTP 请求，MySQL 负责项目数据存储，两者都是标准部署里的基础组件。

sudo apt install nginx

sudo apt install mysql-server
sudo mysql_secure_installation

mysql_secure_installation 不建议跳过，它会引导你完成 root 密码、安全策略、匿名用户清理等基础安全设置。

配置 Nginx：让请求正确转到 ThinkPHP 和 PHP-FPM

环境装完后，真正决定服务能不能打开的，通常是 Nginx 配置是否写对。这里建议为每个 ThinkPHP 项目单独建立站点配置文件。

展示 ThinkPHP 在 Ubuntu 上传统部署的核心链路，包括 Web 服务、PHP-FPM、项目代码和数据库之间的关系。 — **ThinkPHP 传统部署链路图**用一张关系图梳理 Nginx、PHP-FPM、项目目录和 MySQL 的连接方式。

创建站点配置文件

sudo nano /etc/nginx/sites-a vailable/your_project

将下面的配置写入文件，并按你的实际目录、域名或 IP、PHP 版本进行调整：

server {
    listen 80;
    server_name your_domain_or_ip;
    root /path/to/your/thinkphp/project;
    index index.php index.html index.htm;

    location / {
        try_files $uri $uri/ /index.php$query_string;
    }

    location ~ .php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; # 根据你的PHP版本调整
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /.ht {
        deny all;
    }
}

其中最容易出错的是 root 路径和 fastcgi_pass 指向的 php-fpm.sock 文件。只要这两处和系统实际情况不一致，后面大概率就会遇到 404、502 或 500。

启用配置并检查语法

sudo ln -s /etc/nginx/sites-a vailable/your_project /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

如果 nginx -t 输出 syntax is ok，说明配置语法通过，可以继续后面的部署工作。

部署项目代码：上传后先安装依赖

服务器环境和 Web 服务准备好之后，就可以把 ThinkPHP 项目代码拉到目标目录。这里假设项目放在 /var/www/your_project 下：

cd /var/www
git clone https://github.com/your_username/your_project.git
cd your_project
composer install

composer install 可能因为网络问题耗时较长，这属于正常现象。如果直接报错，先看是不是 PHP 扩展缺失，再看 Composer 是否已正确安装。

配置数据库：补齐 .env 并执行迁移

代码部署完成后，还需要把项目连接到数据库。通常只要把根目录下的 .env 文件配置正确，项目就能正常读写数据。

展示从项目代码落地到数据库可用的部署检查流程，突出 composer 安装、.env 配置、迁移执行和访问验证。 — **项目部署检查清单**这张图适合放在数据库与联调章节之后，用来概括部署完成前必须逐项核对的四个检查点。

填写数据库连接信息

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password

这里的数据库名、用户名和密码，要与 MySQL 里实际创建的账号保持一致。

执行迁移命令

php artisan migrate

如果这一步失败，优先检查两件事：一是 .env 信息是否写错，二是 MySQL 服务是否已经启动。源文使用的是 php artisan migrate 这个命令，实际执行前可结合你的项目框架命令体系再次确认。

启动 PHP-FPM 并完成联调

Nginx 配好、代码也部署完之后，还要确认 PHP-FPM 服务本身在运行，否则 PHP 请求无法被处理。

sudo systemctl start php7.4-fpm
sudo systemctl enable php7.4-fpm

如果你的系统安装的是其他版本，例如 php8.1-fpm，这里的服务名也要同步修改。

访问服务并检查报错位置

打开浏览器，输入服务器 IP 或绑定域名。如果能看到 ThinkPHP 页面，说明部署已经基本成功。

若出现白屏或 500 错误，优先检查以下两项：

php-fpm.sock 路径是否与 Nginx 配置一致
项目目录权限是否允许 Nginx 和 PHP-FPM 访问

从排错经验看，这两类问题最常见。

可选项：防火墙放行与 Docker 部署

如果你的服务器启用了 UFW，还需要确认 80 和 443 端口已经放行。除此之外，如果你不想手动维护本机环境，也可以直接使用 Docker 方案。

对比手动部署与 Docker 部署的组成差异，帮助读者判断测试环境和生产环境分别适合哪种方式。 — **手动部署与 Docker 方案对比**把传统部署与 Docker 方案放在同一张图里，对照看更容易判断哪种方式更适合当前场景。

放行 HTTP 与 HTTPS

sudo ufw allow 'Nginx Full'

这条命令会同时开放 80 和 443 端口，适合已经启用 UFW 的 Ubuntu 主机。

使用 Docker 快速搭建运行环境

如果目标是开发、测试，或者你希望把运行环境封装得更统一，Docker 会更省事。源文给出了一套基础可用的 Dockerfile 和 docker-compose.yml。

Dockerfile

FROM php:7.4-fpm
RUN apt-get update && apt-get install -y libpng-dev libjpeg-dev libpq-dev zip unzip git && docker-php-ext-configure gd --with-freetype --with-jpeg && docker-php-ext-install gd pdo_mysql zip opcache
WORKDIR /var/www/html
COPY . /var/www/html
RUN composer install
CMD ["php-fpm"]

docker-compose.yml

version: '3'
services:
  app:
    build: .
    volumes:
      - .:/var/www/html
    environment:
      - DB_CONNECTION=mysql
      - DB_HOST=db
      - DB_PORT=3306
      - DB_DATABASE=your_database
      - DB_USERNAME=your_username
      - DB_PASSWORD=your_password
    depends_on:
      - db
  web:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - app
  db:
    image: mysql:5.7
    environment:
      - MYSQL_DATABASE=your_database
      - MYSQL_USER=your_username
      - MYSQL_PASSWORD=your_password
      - MYSQL_ROOT_PASSWORD=your_root_password
    volumes:
      - db_data:/var/lib/mysql
volumes:
  db_data:

启动方式：