一、前言
开发完成只是家政上门服务系统落地的第一步,从本地开发环境到生产环境的部署上线,中间涉及服务器选型、环境配置、数据库初始化、服务编排、域名备案、小程序发布等一系列环节。很多开发者在本地跑通了代码,却在部署阶段踩各种坑。本文以一套典型的家政上门服务系统(Spring Boot 后端 + 微信小程序前端 + MySQL 数据库 + Redis 缓存)为例,完整梳理从源码到上线的实操步骤。
二、项目结构概览
在开始部署之前,先明确整个项目的目录结构:
- backend/:Spring Boot 后端服务,包含用户端 API、师傅端 API、管理后台 API
- miniprogram/:微信小程序源码(用户端 + 师傅端)
- admin-web/:管理后台前端(Vue 3 + Element Plus)
- sql/:数据库初始化脚本和增量迁移脚本
- docker/:Docker 编排配置文件
- docs/:部署文档和接口文档
三、服务器与环境准备
3.1 云服务器选型建议
家政上门服务系统的初期流量通常不大,建议按以下配置起步:
- 应用服务器:2核4G,CentOS 7.9 或 Ubuntu 20.04,用于部署后端服务和 Nginx
- 数据库服务器:2核4G,独立部署 MySQL 8.0(初期也可与应用服务器合并)
- 缓存服务器:可与数据库服务器合并部署 Redis 6.x
- 对象存储:使用云服务商的 OSS 存放服务照片、头像等文件
3.2 基础环境安装
在服务器上依次安装以下基础组件:
- JDK 17(后端运行环境)
- MySQL 8.0(主数据库)
- Redis 7.x(缓存与分布式锁)
- Nginx 1.24+(反向代理与静态资源服务)
- Node.js 18.x(管理后台前端构建,构建完成后可不保留)
- Docker 与 Docker Compose(可选,用于容器化部署)
四、数据库初始化
4.1 创建数据库与用户
CREATE DATABASE home_service DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'home_service_app'@'%' IDENTIFIED BY 'your_secure_password_here'; GRANT ALL PRIVILEGES ON home_service.* TO 'home_service_app'@'%'; FLUSH PRIVILEGES;
4.2 执行初始化脚本
将 sql/ 目录下的初始化脚本按顺序执行:
schema.sql:建表语句,包含用户表、师傅表、服务项表、订单表、评价表、打卡记录表等核心业务表seed_data.sql:基础数据填充,包含服务分类、默认角色权限等index.sql:索引优化脚本,为高频查询字段建立索引
五、后端服务配置与启动
5.1 配置文件调整
修改 application-prod.yml 中的关键配置项:
- 数据库连接地址、用户名、密码
- Redis 连接地址和密码
- OSS 的 AccessKey、SecretKey、Bucket 名称
- 微信支付的商户号、API 密钥、证书路径
- 微信小程序的 AppID 和 AppSecret
- 短信服务的 AccessKey 和签名配置
5.2 使用 Docker Compose 编排部署
以下是一个 Docker Compose 配置文件,将后端服务、MySQL、Redis、Nginx 统一编排管理:
version'3.8' services mysql imagemysql8.0 container_namehome-service-mysql environment MYSQL_ROOT_PASSWORD$MYSQL_ROOT_PASSWORD MYSQL_DATABASEhome_service MYSQL_USERhome_service_app MYSQL_PASSWORD$MYSQL_APP_PASSWORD volumes mysql_data:/var/lib/mysql ./sql:/docker-entrypoint-initdb.d ports "3306:3306" command--character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci restartalways redis imageredis7-alpine container_namehome-service-redis commandredis-server --requirepass $REDIS_PASSWORD --appendonly yes volumes redis_data:/data ports "6379:6379" restartalways backend imageopenjdk17-slim container_namehome-service-backend working_dir/app volumes ./backend:/app commandjava -jar -Xms512m -Xmx1024m -Dspring.profiles.active=prod -Dspring.config.location=/app/config/ app.jar environment SPRING_DATASOURCE_URL=jdbc:mysql://mysql:3306/home_service?useUnicode=true&characterEncoding=utf8mb4&serverTimezone=Asia/Shanghai SPRING_REDIS_HOST=redis SPRING_REDIS_PASSWORD=$REDIS_PASSWORD depends_on mysql redis restartalways nginx imagenginx1.24-alpine container_namehome-service-nginx volumes ./nginx/nginx.conf:/etc/nginx/nginx.conf ./nginx/certs:/etc/nginx/certs ./admin-web/dist:/usr/share/nginx/html/admin ports "80:80" "443:443" depends_on backend restartalways volumes mysql_data redis_data
将上述配置保存为 docker-compose.yml,在项目根目录执行 docker-compose up -d 即可一键启动所有服务。敏感配置通过 .env 文件注入,避免明文写入配置文件。
5.3 启动验证
服务启动后,通过以下命令检查各容器运行状态:
docker-compose ps
确认所有服务状态为 Up 后,访问 http://服务器IP/health 检查后端服务健康状态。如果返回 {"status":"UP"},说明后端服务启动成功。
六、Nginx 反向代理配置
Nginx 负责三件事:将 API 请求转发到后端服务、托管管理后台前端静态文件、配置 HTTPS。
upstream backend_server { server backend:8080; } server { listen 80; server_name your-domain.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl; server_name your-domain.com; ssl_certificate /etc/nginx/certs/your-domain.com.pem; ssl_certificate_key /etc/nginx/certs/your-domain.com.key; location /api/ { proxy_pass http://backend_server/; 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; } location /admin/ { alias /usr/share/nginx/html/admin/; try_files $uri $uri/ /admin/index.html; } }
七、微信小程序发布流程
7.1 小程序端配置
修改小程序源码中的环境配置:
- 将 API 基础地址从本地开发地址改为生产环境的
https://your-domain.com/api/ - 确认
app.json中的requiredPrivateInfos和permission配置正确(涉及地理位置权限) - 检查所有页面是否适配了小程序的隐私协议弹窗
7.2 微信公众平台配置
登录微信公众平台,完成以下配置:
- 服务器域名:在"开发管理 → 开发设置"中,将
https://your-domain.com添加到 request 合法域名、uploadFile 合法域名、downloadFile 合法域名 - 类目资质:家政服务属于生活服务类目,需要提交相应的营业执照和服务资质
- 隐私协议:配置小程序的隐私政策,明确告知用户数据采集范围(位置信息、手机号等)
7.3 提交审核与发布
使用微信开发者工具上传代码,填写版本号与更新说明,提交审核。审核通过后点击"发布"即可上线。
八、管理后台前端部署
管理后台前端使用 Vite 构建,构建产物为纯静态文件:
cd admin-web npm install npm run build
构建完成后,dist/ 目录下的文件即为生产环境的静态资源。由于 Docker Compose 中已将 ./admin-web/dist 挂载到 Nginx 容器内,构建完成后刷新即可生效。
九、上线后的关键检查项
9.1 功能验证
- 用户端:注册登录、浏览服务、下单支付、查看订单、提交评价
- 师傅端:登录、接单、到达打卡、完成打卡、上传凭证
- 管理后台:师傅审核、订单管理、服务项管理、数据看板
9.2 安全加固
- 修改服务器默认的 SSH 端口,禁用密码登录,仅允许密钥登录
- 配置防火墙规则,仅开放 80、443 端口,数据库和 Redis 端口不对外暴露
- MySQL 的 root 账号设置强密码,应用使用独立账号连接
- Redis 开启密码认证,禁止外网直接访问
9.3 监控与日志
- 配置 Nginx 的访问日志和错误日志,按天轮转
- 后端服务接入日志采集(如 ELK 或云服务商的日志服务),便于排查线上问题
- 配置服务器资源监控告警(CPU、内存、磁盘、带宽),设置阈值告警
十、常见问题排查
10.1 后端服务启动失败
常见原因包括:数据库连接配置错误(检查 URL、用户名、密码)、Redis 连接超时(检查网络和防火墙)、配置文件路径不对(检查 -Dspring.config.location 参数)。通过 docker-compose logs backend 查看具体报错信息。
10.2 小程序请求失败
检查微信公众平台的域名白名单是否配置正确,确认域名已备案且 HTTPS 证书有效。小程序要求所有网络请求必须使用 HTTPS,且证书不能是自签名的。
10.3 图片上传失败
检查 OSS 的 AccessKey 和 Bucket 配置是否正确,确认 Bucket 的跨域规则(CORS)已允许小程序域名的请求。同时检查 Nginx 的 client_max_body_size 配置,默认 1MB 可能不够,建议调整为 10MB。
十一、总结
家政上门服务系统的部署上线,核心流程可以概括为:准备服务器 → 安装基础环境 → 初始化数据库 → 配置后端服务 → 编排容器启动 → 配置 Nginx 代理 → 发布小程序 → 部署管理后台 → 上线验证。使用 Docker Compose 编排可以大幅简化多服务的部署和运维工作,建议在生产环境中优先采用。上线后重点关注安全加固和监控告警,确保系统稳定运行。