从零到一：Todo系统 SpringBoot+Vue3阿里云ECS DockerCompose部署实战（避坑完整版）

Nefertari391

201人浏览 · 2026-07-05 14:25:20

Nefertari391 · 2026-07-05 14:25:20 发布

📖 导读：本文手把手带你完成 SpringBoot3.2 + Vue3 + MySQL8.0 前后端分离Todo待办系统的阿里云ECS全流程部署。全程采用Docker Compose容器化部署，汇总实测所有报错解决方案，解决镜像超时、接口404、端口冲突、Buildx版本过低等高频问题，新手可直接复刻，零部署经验也能一次成功！

一、项目概述与环境说明

1.1 项目简介

本次部署项目为 Todo System待办事项管理系统，是典型的前后端分离入门级实战项目，非常适合新手学习容器化部署、云服务器上线流程。本人全程实测部署，踩平所有部署坑，整理出完整可落地的部署方案。

1.2 技术栈

前端：Vue3 + Vite
后端：Spring Boot 3.2.0 + MyBatis-Plus
数据库：MySQL 8.0
部署方式：Docker Compose 容器化一键部署
服务器：阿里云ECS（CentOS / Ubuntu通用）

1.3 统一工作目录

服务器统一部署路径：/root/myapp/

二、前置准备：本地项目配置与打包

服务器部署前，必须完成本地项目配置修正与打包，90%部署报错均来自本地配置不规范，请严格按照以下步骤操作。

2.1 后端核心配置修正（关键！避坑重点）

修改后端配置文件 application.yml，统一API接口前缀、适配Docker容器网络、配置数据库连接信息。

核心规则：配置全局 context-path: /api，Controller接口路径禁止重复添加/api前缀，否则会出现接口404问题。

server: port: 8080 servlet: context-path: /api 
encoding: charset: UTF-8 enabled: true
force: true 
spring: 
datasource:
 url: jdbc:mysql://mysql:3306/todo_system?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true 
username: root 
password: 123456 
driver-class-name: com.mysql.cj.jdbc.Driver

✅ 正确Controller写法（无/api前缀）

@RequestMapping("/auth") public class AuthController { // 接口逻辑 }

❌ 错误写法（重复前缀，导致路径/api/api/xxx 404）

@RequestMapping("/api/auth") public class AuthController { // 接口逻辑 }

2.2 本地项目打包构建

2.2.1 后端打包（Maven）

进入后端项目目录，执行打包命令，跳过测试加快打包速度

cd D:\Code\java\大三下\backend 
mvn clean package -DskipTests

2.2.2 前端打包（NPM）

进入前端目录，安装依赖并打包生成dist静态文件

cd D:\Code\java\大三下\frontend 
npm install npm run build

2.3 项目打包上传服务器

将前后端项目整体压缩，通过SCP命令上传至阿里云ECS服务器指定目录

cd D:\Code\java\大三下 Compress-Archive -Path .\backend, .\frontend -DestinationPath .\todo-system.zip -Force 
scp .\todo-system.zip root@39.105.55.68:/root/myapp/

三、服务器端部署全流程

3.1 环境清理（重新部署必做）

若服务器存在旧项目、旧容器、旧镜像，先彻底清理，避免端口冲突、配置覆盖问题

cd /root/myapp/backend 
docker-compose down -v --remove-orphans 
cd /root/myapp rm -rf backend frontend dist 
docker image prune -f

3.2 解压项目文件

cd /root/myapp unzip -o todo-system.zip

3.3 部署前配置校验（关键自检）

启动服务前执行以下命令校验配置，规避90%部署报错

cat backend/src/main/resources/application.yml | grep context-path grep -r "@RequestMapping" backend/src/main/java/com/example/todosystem/controller/*.java 
cat backend/nginx.conf | grep proxy_pass

3.4 数据库初始化（可选）

项目如需初始化数据表、基础数据，执行以下命令导入SQL脚本

docker exec -i todo-mysql mysql -uroot -p123456 todo_system < /root/myapp/backend/init.sql

3.5 Docker Compose 启动服务

避坑说明：低版本Docker存在Buildx兼容问题，摒弃 docker-compose build，采用原生 docker build 构建镜像

cd /root/myapp/backend 
docker build -t backend-app . 
docker-compose up -d sleep 30

四、部署结果验证

4.1 查看容器运行状态

所有容器状态为 Up 即为启动成功

docker-compose ps

4.2 查看项目启动日志

出现 Started Application in X seconds 说明后端启动正常

docker logs todo-app --tail 50

4.3 后端API接口测试

通过curl测试注册、登录接口，正常返回Token则接口通信正常

curl http://localhost/api/auth/register -X POST \ -H "Content-Type: application/json" \ -d '{"loginName":"admin","password":"admin123","nickname":"管理员"}' 
curl http://localhost/api/auth/login -X POST \ -H "Content-Type: application/json" \ -d '{"loginName":"admin","password":"admin123"}'

4.4 前端页面访问

浏览器访问服务器公网IP：http://39.105.55.68，正常展示Todo系统登录页面即为部署完成。

注意：需提前在阿里云安全组开放80端口、3306端口，否则无法外网访问。

五、高频报错问题解决方案（实测避坑）

5.1 报错：Buildx版本过低

报错信息：compose build requires buildx 0.17.0 or later

原因：服务器Docker版本较低，内置Buildx工具不兼容新版Compose构建规则

解决方案：放弃compose自动构建，使用原生docker build构建镜像

docker build -t backend-app . 
docker-compose up -d

5.2 报错：Docker镜像下载超时

报错信息：dial tcp xxx i/o timeout

原因：国外镜像源访问缓慢、超时

解决方案：配置DaoCloud国内镜像加速器

sudo tee /etc/docker/daemon.json 
<<'EOF' 
{ "registry-mirrors": [ "https://docker.m.daocloud.io", "https://huecker.io" ] } 
EOF 
sudo systemctl daemon-reload 
sudo systemctl restart docker

5.3 报错：接口404 无静态资源

报错信息：No static resource auth/login

根本原因：全局配置/api + Controller重复/api，路径嵌套错误

解决方案：

方案一（推荐）：删除Controller类上的/api前缀，重新打包部署

方案二（临时应急）：Nginx重写路径

location /api { rewrite ^/api/(.*) /$1 break; proxy_pass http://app:8080; }

5.4 报错：数据库数据表不存在

报错信息：Table 'todo_system.t_user' doesn't exist

解决方案：手动导入初始化SQL

docker exec -i todo-mysql mysql -uroot -p123456 todo_system < /root/myapp/backend/init.sql

5.5 报错：YAML配置解析失败

原因：yml重复key、缩进错误

解决方案：修正配置文件

vim /root/myapp/backend/src/main/resources/application.yml

5.6 报错：端口被占用

报错信息：port is already allocated

解决方案：关闭占用端口容器

netstat -tlnp | grep -E ":80 |:3306 " docker stop 容器ID

六、常用运维命令速查手册

6.1 容器生命周期管理

docker-compose ps 
docker logs todo-app -f 
docker restart todo-app 
docker exec -it todo-app bash 
docker-compose down

6.2 数据库运维命令

docker exec -it todo-mysql mysql -uroot -p123456 
docker exec todo-mysql mysqldump -uroot -p123456 todo_system > backup.sql

七、部署自检清单

✅ 所有容器状态为Up
✅ 启动日志无致命ERROR
✅ 前端页面外网可访问
✅ 后端API正常返回数据
✅ 阿里云安全组开放80、3306端口
✅ 数据库表结构初始化完成

八、项目快速回滚方案

cd /root/myapp/backend docker-compose down cd /root/myapp mv backend backend.new mv backend.old backend cd backend docker-compose up -d

九、总结

本次Todo前后端分离项目部署，全程基于Docker Compose容器化实现，规避了传统部署的环境依赖、配置混乱问题。部署核心难点集中在本地API路径配置、Docker镜像加速、容器网络通信三点。

本文汇总的所有报错解决方案均为实测验证，新手只需严格按照流程操作，即可一次性完成阿里云ECS线上部署。后续可基于本项目，拓展HTTPS配置、自动化部署、监控告警等进阶功能。

如果部署过程中遇到其他未知问题，欢迎评论区留言交流！

AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

Gliding Horse 时间感知系统：让 AI Agent 真正“感知“时间流逝

AI Agent技术社区

海外80%头部网红没有经纪人：AI Agent如何终结“散对散”的生态混乱？

AI Agent技术社区

构建企业级中后台解决方案：Vue Vben Admin 5.0架构设计与性能优化指南

Vue Vben Admin 5.0是一个基于Vue 3、TypeScript和Vite的企业级中后台前端解决方案，采用Monorepo架构设计，支持多UI框架适配和完整的权限管理体系。该框架为技术决策者提供了高性能、可扩展的前端架构实现方案，通过现代化的技术栈和工程化实践，显著提升企业应用开发效率。## 技术架构解析：Monorepo模块化设计Vue Vben Admin采用先进的Mon