前后端分离项目部署实战：从服务器配置到Nginx反向代理全流程

发布时间：2026/7/30 4:04:57

1. 项目概述：为什么前后端分离部署是“必选项”？

如果你是一名开发者，最近在折腾一个自己的项目，或者团队里正准备把老旧的单体应用拆开，那你大概率绕不开“前后端分离”这个话题。这早就不是什么新鲜概念了，但真到了要把它部署上线，让用户能稳定访问的时候，很多人还是会卡壳。我见过不少项目，开发时前端用Vue、React写得飞起，后端Spring Boot接口也调得顺畅，结果一到部署环节，不是跨域问题满天飞，就是静态资源加载不出来，再不就是Nginx配置写错导致接口404。最后只能草草把前端代码打包扔进后端项目的static目录里，又回到了“伪分离”的老路。

所以，今天我们不聊为什么前后端分离好，这已经是共识。我们直接切入最实际的环节：如何把一个典型的前后端分离项目，从你本地开发环境，一步步、稳稳妥妥地部署到一台云服务器上，让它能7x24小时对外服务。这整个过程，就像给房子做精装修，水电管线（网络、代理）、软装布置（应用部署）、安防监控（进程守护）一个都不能少。无论你用的是经典的“Spring Boot + Vue”组合，还是“Nest.js + React”，甚至是更新的技术栈，其部署的核心思想和流程都是相通的。本教程的目标，就是给你一份能“抄作业”的详细清单，涵盖从服务器准备、环境安装、到应用部署、配置优化及问题排查的全链路，让你避开我踩过的那些坑。

2. 核心架构与部署方案选型

在动手之前，我们得先搞清楚我们要部署的东西到底是什么结构，以及有哪些主流的部署方式。这决定了后续所有操作的路径。

2.1 前后端分离项目典型结构解析

一个标准的前后端分离项目，在部署视角下，可以清晰地看作两个独立的应用：

前端应用：通常是一个单页应用（SPA），使用Vue、React、Angular等框架开发。它的最终产物，是通过npm run build或yarn build生成的一堆静态文件：index.html、JavaScript、CSS、图片字体等。这个应用没有独立的Web服务器（开发时的dev-server只是为了调试），它需要被托管在一个HTTP服务器（如Nginx、Apache）上，由服务器把这些静态文件发送给用户的浏览器。
后端应用：提供RESTful API或GraphQL接口的服务端程序，使用Spring Boot、Express、Django、Nest.js等框架开发。它的产物通常是一个可执行的JAR包（Java）、一组Node.js文件、或者一个Python应用。这个应用必须运行在一个应用服务器或运行时环境中，比如Java需要JRE，Node.js需要Node环境，Python需要Python解释器。它监听一个网络端口（如8080），等待前端发来的HTTP请求。

关键关系：用户浏览器只直接与前端托管服务器通信，加载静态页面和脚本。前端脚本在浏览器中运行后，再通过Ajax请求去调用后端API服务器的接口。这就引出了部署的核心问题：如何让浏览器中的前端代码，能正确找到并访问到运行在另一个地方的后端服务？答案就是反向代理。

2.2 主流部署方案对比与选型

方案没有绝对的好坏，只有适合与否。下面这张表对比了三种最常见的部署方式：

方案	描述	优点	缺点	适用场景
传统服务器部署	购买云服务器（ECS），手动安装Nginx、Java、Node.js、数据库等所有环境，上传前后端代码并启动。	1.完全可控，深度定制化。 2.成本透明，按需配置服务器。 3.学习曲线直接，理解整个技术栈。	1.运维繁琐，需手动管理环境、更新、备份。 2.环境一致性难保证，“在我机器上好好的”。 3.伸缩性差，流量突增时手动扩容慢。	中小型项目、学习实践、对成本敏感且有一定运维能力的团队。
容器化部署	使用Docker将前后端应用及其依赖打包成镜像，通过Docker Compose或K8s编排部署。	1.环境一致性极强，镜像即环境。 2.隔离性好，应用互不干扰。 3.易于CI/CD，与流水线无缝集成。 4.伸缩便捷。	1.学习成本高，需掌握Docker和编排工具。 2.镜像管理需要额外仓库（如Harbor）。 3. 轻微的性能开销。	中大型项目、微服务架构、追求敏捷交付和DevOps的团队。
Serverless/平台即服务	前端部署到Vercel、Netlify；后端部署到云函数（AWS Lambda、阿里云FC）、或PaaS（Heroku、Railway）。	1.免运维，专注业务代码。 2.自动伸缩，无需关心服务器。 3.按量计费，成本可能更低。	1.厂商锁定（Vendor Lock-in）风险。 2.冷启动问题可能导致延迟。 3. 对本地资源、特定系统调用有限制。	原型验证、轻量级API、事件驱动型应用、初创团队。

我的选择与建议：对于绝大多数初次尝试部署或个人项目，我强烈推荐从传统服务器部署开始。理由很简单：它能让你最透彻地理解从代码到服务的完整链条，每一个环节都亲手摸过，以后遇到问题你才知道从哪儿下手。容器化和Serverless是更高级的抽象，它们解决的是传统部署的痛点，但如果你连痛点都没亲身经历过，直接上高级工具反而会云里雾里。本教程也将以一台全新的Linux云服务器为舞台，演示传统部署的完整过程。掌握了这个，再学Docker就是水到渠成。

3. 服务器准备与基础环境搭建

假设我们已经购买了一台Ubuntu 22.04 LTS的云服务器（CentOS/RHEL系命令略有不同）。拿到服务器的公网IP（例如123.123.123.123）和root密码后，我们开始“装修”的第一步。

3.1 初始服务器安全配置

安全是第一步，绝不能省略。直接用root用户操作是危险的。

# 1. 使用SSH密钥登录（比密码更安全） # 本地生成密钥对（如果还没有）: ssh-keygen -t rsa -b 4096 # 将公钥上传到服务器: ssh-copy-id root@你的服务器IP # 2. 登录服务器 ssh root@123.123.123.123 # 3. 创建新的普通用户（例如 deploy） adduser deploy # 按照提示设置密码和相关信息 # 4. 给新用户添加sudo权限 usermod -aG sudo deploy # 5. 切换到新用户，后续操作都尽量在此用户下进行 su - deploy

3.2 基础软件安装与配置

我们将安装项目运行所必需的环境：Nginx（Web服务器/反向代理）、后端运行时（这里以Java和Node.js为例）、数据库（MySQL）、以及版本控制工具Git。

# 更新系统包列表 sudo apt update && sudo apt upgrade -y # 安装Nginx sudo apt install nginx -y # 启动并设置开机自启 sudo systemctl start nginx sudo systemctl enable nginx # 此时访问 http://你的服务器IP，应该能看到Nginx欢迎页 # 安装Java (以OpenJDK 17为例，Spring Boot 3.x需要至少JDK 17) sudo apt install openjdk-17-jdk -y # 验证安装 java -version # 安装Node.js (通过NodeSource仓库安装LTS版本) curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt install -y nodejs # 验证安装 node --version npm --version # 安装MySQL sudo apt install mysql-server -y # 运行安全安装脚本，设置root密码、移除匿名用户、禁止远程root登录等 sudo mysql_secure_installation # 登录MySQL，为你的项目创建数据库和用户 sudo mysql # 在MySQL提示符下执行： # CREATE DATABASE your_project_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; # CREATE USER 'your_project_user'@'localhost' IDENTIFIED BY 'StrongPassword123!'; # GRANT ALL PRIVILEGES ON your_project_db.* TO 'your_project_user'@'localhost'; # FLUSH PRIVILEGES; # EXIT; # 安装Git sudo apt install git -y

注意：生产环境的MySQL配置远不止这些，还需要考虑调整innodb_buffer_pool_size、连接数、二进制日志等。这里只是保证服务能跑起来。务必使用强密码，且不要使用root用户直接连接应用。

4. 前端项目部署详解

前端项目部署的核心，是将构建好的静态文件放到Nginx能够服务的目录下，并正确配置Nginx。

4.1 本地构建与文件上传

首先，在你的本地开发机完成前端项目的构建。

# 进入你的前端项目根目录 cd /path/to/your-frontend-project # 安装依赖（如果node_modules不存在） npm install # 执行构建，生成dist（或build）文件夹 npm run build

构建成功后，项目根目录下会生成一个dist文件夹（Vue CLI默认）或build文件夹（Create React App默认），里面就是我们要部署的静态资源。

接下来，将dist文件夹上传到服务器。有多种方式：

使用scp命令（简单直接）：

# 从本地上传整个dist目录到服务器的/home/deploy目录下 scp -r ./dist deploy@123.123.123.123:/home/deploy/

使用Git（适合自动化）：在服务器上克隆仓库，然后执行构建。但需要服务器有Node环境，且构建可能消耗资源。
使用CI/CD工具（如Jenkins, GitHub Actions）：这是更专业的做法，自动化构建、测试、部署。

我们先用scp，简单明了。

4.2 Nginx配置与反向代理设置

这是前端部署最关键的一步。我们需要配置Nginx，让它：

托管我们上传的静态文件。
将API请求转发到后端服务器。

# 在服务器上，将上传的dist文件夹移动到Nginx的默认站点目录 sudo mv /home/deploy/dist /var/www/html/your-frontend-app # 创建一个新的Nginx配置文件 sudo vim /etc/nginx/sites-available/your-project

将以下配置写入文件。请仔细阅读注释，理解每一行的作用：

server { listen 80; server_name your-domain.com www.your-domain.com; # 如果没有域名，可以用服务器IP，但更推荐用IP访问后端，前端用域名或IP均可 root /var/www/html/your-frontend-app; # 静态文件根目录 index index.html; # 开启gzip压缩，提升传输效率 gzip on; gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript; # 核心配置：处理前端路由（如Vue Router的history模式） # 当请求的不是一个真实存在的文件或目录时，将请求重写到index.html，由前端路由接管 location / { try_files $uri $uri/ /index.html; } # 反向代理配置：将所有以 /api/ 开头的请求转发到后端应用 location /api/ { # 后端应用运行在localhost的8080端口 proxy_pass http://localhost:8080; # 传递原始请求头，这对鉴权等非常重要 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } # 可选：代理WebSocket连接（如果你的应用用了WebSocket） # location /ws/ { # proxy_pass http://localhost:8080; # proxy_http_version 1.1; # proxy_set_header Upgrade $http_upgrade; # proxy_set_header Connection "upgrade"; # } }

关键点解析：
try_files $uri $uri/ /index.html;这是支持SPA前端路由（history模式）的灵魂语句。没有它，你刷新非首页的页面就会得到Nginx的404错误。
location /api/这里定义了反向代理的规则。所有前端发往/api/users、/api/login的请求，都会被Nginx透明地转发到http://localhost:8080/api/users和http://localhost:8080/api/login。这样，前端代码里的API基地址直接写成/api即可，完美解决跨域问题（因为对于浏览器来说，所有请求都是发给同一个域名/端口的）。
proxy_set_header这几行至关重要，它们将用户的真实IP、协议等信息传递给后端，否则后端日志里看到的客户端IP可能全是127.0.0.1。

启用站点配置并测试：

# 创建符号链接，启用该站点 sudo ln -s /etc/nginx/sites-available/your-project /etc/nginx/sites-enabled/ # 测试Nginx配置语法是否正确 sudo nginx -t # 如果显示 `syntax is ok` 和 `test is successful`，则重启Nginx sudo systemctl reload nginx

现在，访问你的服务器IP或域名，应该能看到前端页面了。但点击任何需要调用后端接口的按钮，都会失败，因为后端服务还没启动。

5. 后端项目部署详解

后端部署的核心是让应用作为一个常驻进程运行起来，并确保它崩溃后能自动重启。

5.1 应用打包与上传

以Spring Boot为例，在本地使用Maven或Gradle打包。

# 在本地后端项目根目录 ./mvnw clean package -DskipTests # 或者使用Gradle ./gradlew bootJar

打包后，在target目录下会生成一个可执行的JAR文件，例如your-backend-app-0.0.1-SNAPSHOT.jar。

将这个JAR文件上传到服务器：

scp ./target/your-backend-app-0.0.1-SNAPSHOT.jar deploy@123.123.123.123:/home/deploy/app/

在服务器上，建议为应用创建一个专属目录，比如/home/deploy/app，并将JAR包、配置文件、日志目录都放在这里，方便管理。

5.2 使用Systemd守护进程

最可靠的方式是使用Systemd来管理你的Java应用。它提供开机自启、自动重启、日志集成等功能。

# 在服务器上创建Systemd服务单元文件 sudo vim /etc/systemd/system/your-backend.service

写入以下内容（根据你的实际情况修改）：

[Unit] Description=Your Backend Application Service After=network.target mysql.service # 表示在网络和MySQL服务启动后再启动本服务 [Service] Type=simple User=deploy # 使用非root用户运行，更安全 WorkingDirectory=/home/deploy/app # JAR包所在的目录 ExecStart=/usr/bin/java -Xms256m -Xmx512m -jar your-backend-app-0.0.1-SNAPSHOT.jar # 重要参数说明： # -Xms256m 初始堆内存 # -Xmx512m 最大堆内存 # -jar 后面是你的JAR包名 # 如果你的应用有额外的配置文件，可以使用 --spring.config.location=file:/path/to/application-prod.yml SuccessExitStatus=143 # Spring Boot应用在收到终止信号时通常返回143 Restart=always # 总是重启 RestartSec=10 # 重启前等待10秒 StandardOutput=journal # 输出到系统日志 StandardError=journal [Install] WantedBy=multi-user.target

实操心得：User=deploy这一行非常重要。永远不要用root用户直接运行你的应用。这能最大程度限制应用被入侵后的影响范围。同时，确保/home/deploy/app目录的所属权和权限正确（chown -R deploy:deploy /home/deploy/app）。

启动并启用服务：

# 重新加载Systemd配置 sudo systemctl daemon-reload # 启动服务 sudo systemctl start your-backend # 设置开机自启 sudo systemctl enable your-backend # 查看服务状态和日志 sudo systemctl status your-backend sudo journalctl -u your-backend -f # 实时查看日志

如果状态显示active (running)，并且日志中没有明显的错误，那么后端API应该已经在localhost:8080运行起来了。

5.3 后端配置文件（以Spring Boot为例）

你的应用在本地开发时可能用application.yml，部署时需要区分环境。通常我们会准备一个application-prod.yml。

# application-prod.yml server: port: 8080 address: 127.0.0.1 # 只监听本地回环地址，通过Nginx反向代理访问，更安全 spring: datasource: url: jdbc:mysql://localhost:3306/your_project_db?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai username: your_project_user password: StrongPassword123! driver-class-name: com.mysql.cj.jdbc.Driver jpa: hibernate: ddl-auto: validate # 生产环境绝对不要用 update 或 create！用validate或none。 show-sql: false # 生产环境关闭SQL日志 # 自定义配置，如文件上传路径 file: upload-dir: /home/deploy/app/uploads # 日志配置 logging: file: name: /home/deploy/app/logs/app.log level: com.yourcompany: INFO

将这个配置文件也上传到服务器的/home/deploy/app目录，并在Systemd服务的ExecStart命令中通过--spring.config.location指定它。

6. 全链路联调与测试

现在，前端（Nginx:80）、后端（Java:8080）、数据库（MySQL:3306）都已就位。是时候进行端到端的测试了。

测试前端静态资源：直接访问http://你的服务器IP，确保页面加载正常，CSS、JS、图片等资源没有404错误。
测试后端API直接访问：在服务器本地，用curl测试后端是否正常响应。
```
curl http://localhost:8080/api/health
```
如果返回预期的JSON数据或状态码，说明后端独立运行正常。
测试Nginx反向代理：这是最关键的一步。访问http://你的服务器IP/api/health。这个请求应该被Nginx接收到，并转发给后端的localhost:8080/api/health，最后将响应返回给浏览器或curl。如果这里出错，最常见的是502 Bad Gateway或504 Gateway Timeout，问题通常出在Nginx配置（proxy_pass地址不对）或后端服务没启动。
测试前端调用后端：在前端页面进行登录、查询等操作，打开浏览器的开发者工具（F12）的“网络(Network)”标签页，查看发起的API请求状态码是否为200，响应数据是否正确。
检查跨域问题：理论上，通过Nginx反向代理，前端请求/api就是请求自己的域名，不存在跨域。如果你在控制台看到CORS错误，请检查：
- Nginx配置中location /api/的proxy_pass是否正确。
- 后端代码中是否错误地配置了CORS（在生产环境下，如果用了反向代理，后端通常可以移除CORS配置，因为请求来源变成了Nginx，是同源的。或者将CORS配置为允许Nginx的域名/IP）。

7. 部署进阶：安全、性能与监控

基础部署完成只是第一步，要让服务稳定可靠，还需要做更多工作。

7.1 配置HTTPS（使用Let‘s Encrypt免费SSL证书）

HTTP是明文的，极不安全。我们必须上HTTPS。

# 安装Certbot客户端和Nginx插件 sudo apt install certbot python3-certbot-nginx -y # 获取并安装证书（假设你的域名DNS已解析到该服务器） sudo certbot --nginx -d your-domain.com -d www.your-domain.com

Certbot会自动修改你的Nginx配置，将HTTP重定向到HTTPS，并配置好SSL证书。证书每90天会自动续期。

7.2 Nginx性能与安全调优

在/etc/nginx/nginx.conf的http块中，可以添加一些全局优化：

http { # 隐藏Nginx版本号，增加安全性 server_tokens off; # 客户端请求体最大大小，防止过大请求攻击 client_max_body_size 10m; # 优化文件传输 sendfile on; tcp_nopush on; tcp_nodelay on; keepalive_timeout 65; # 限制连接频率，防CC攻击（需在对应的server或location中配置） # limit_req_zone $binary_remote_addr zone=one:10m rate=10r/s; # limit_req zone=one burst=20 nodelay; # 包含站点配置 include /etc/nginx/sites-enabled/*; }

7.3 应用进程监控与日志管理

监控Systemd服务：使用systemctl status your-backend定期检查服务状态。可以配置简单的监控脚本，当服务挂掉时发送告警（通过邮件、钉钉、企业微信等）。

日志轮转：应用日志（/home/deploy/app/logs/app.log）会不断增长，需要配置logrotate。

sudo vim /etc/logrotate.d/your-backend-app

内容如下：

/home/deploy/app/logs/*.log { daily missingok rotate 30 # 保留30天的日志 compress delaycompress notifempty create 0640 deploy deploy sharedscripts postrotate systemctl reload your-backend > /dev/null 2>&1 || true endscript }

使用Supervisor（备选）：如果你部署的是Python、Node.js等非Java应用，Systemd配置可能稍复杂。Supervisor是一个更通用的进程管理工具，配置起来也很直观。

8. 常见问题与故障排查实录

部署路上坑无数，这里记录几个我踩过且高频出现的问题。

8.1 前端页面刷新404（SPA路由问题）

现象：首页能打开，但点击内部链接或手动刷新非首页的URL时，显示Nginx 404页面。原因：Nginx把/about这样的路径当成了一个实际的文件或目录请求去查找，当然找不到。解决：确保Nginx配置中，处理根路径的location /块里包含了try_files $uri $uri/ /index.html;这条指令。Vue Router的history模式和React Router的BrowserRouter都依赖这个。

8.2 502 Bad Gateway / 504 Gateway Timeout

现象：浏览器访问/api接口返回502或504错误。排查步骤：

检查后端服务是否运行：sudo systemctl status your-backend。如果没运行，查看日志journalctl -u your-backend找原因。
检查Nginx配置：确认proxy_pass http://localhost:8080;中的端口号与后端应用实际监听的端口一致。
检查网络连通性：在服务器上执行curl http://localhost:8080/api/health，看后端本身是否正常响应。如果不通，问题在后端。
检查防火墙：Ubuntu默认的ufw防火墙可能阻止了端口。确保后端端口（如8080）允许本地访问，或者直接暂时关闭防火墙测试：sudo ufw disable（测试完记得开启并配置规则！）。

504超时：可能是后端处理请求太慢。可以适当增加Nginx的代理超时时间：

location /api/ { proxy_pass http://localhost:8080; proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 120s; # 根据你的接口最大耗时调整 # ... 其他header设置 }

8.3 静态资源（CSS/JS/图片）加载失败

现象：页面能打开，但样式错乱，控制台报资源404。排查：

检查Nginx配置中的root指令路径是否正确指向了包含index.html的构建输出目录（如/var/www/html/your-frontend-app）。
检查构建产物的路径。有些前端项目构建后，资源文件可能带有哈希值并放在static或assets子目录下。确保Nginx的root配置指向的是包含这些子目录的父级目录。
在前端项目的构建配置中（如Vue的vue.config.js或React的package.json中的homepage字段），检查publicPath设置。如果部署在非根路径（如/admin/），需要在这里和Nginx的root配置中做相应调整。

8.4 数据库连接失败

现象：后端启动失败，日志显示Access denied for user或Cannot create connection to database server。排查：

确认数据库服务运行：sudo systemctl status mysql。
检查连接参数：确认application-prod.yml中的数据库URL、用户名、密码完全正确。特别注意密码中的特殊字符是否需要转义。
检查用户权限：登录MySQL，确认你创建的用户和数据库存在，且用户对该数据库有全部权限，并且允许从localhost连接。
检查MySQL绑定地址：生产环境MySQL默认只监听127.0.0.1，这是对的。确保你的连接字符串里也是localhost或127.0.0.1，而不是服务器的公网IP。

部署是一个系统工程，一次成功可能意味着你运气好，但更常见的是需要反复调试。我的建议是：分段验证，日志为王。每完成一步，就立刻验证这一步是否成功，并善用journalctl、Nginx的error.log（/var/log/nginx/error.log）和浏览器开发者工具，它们能提供绝大部分问题的线索。当你亲手把第一个前后端分离项目部署上线，并稳定运行起来后，你对整个Web应用架构的理解，会深刻得多。