交通统计审核
编辑 | blame | 历史 | 原始文档

交通统计报表审核系统 — 打包与部署说明

适用：main 分支（最新更新 2026-09-13）。后端 Spring Boot 2.7（Java 8），前端 Vue 2 + Element UI。
本文档面向开发与部署同事，命令均在 Windows 下验证。

一、项目结构

目录 说明
traffic-audit-server 后端（Spring Boot，Java 8，端口 8090，接口全部在 /api/**）
traffic-audit-web 前端（Vue 2 + Element UI，开发端口 8080，/api 代理到 8090）
docs 运行数据目录（报表模板、汇总大表母版等），**发布必须带上**
package-deploy.py 一键打包脚本（前端构建 → 内嵌进 jar → 组装部署包 → 打 zip）

二、环境要求

组件 版本 说明
JDK 1.8 部署机必须；后端编译/运行
MySQL 5.7 / 8.0 部署机必须，库名 traffic_audit
Maven 3.x / Node.js 14+ — 只有「在部署机上打包」才需要；用一键脚本产出的包部署则不需要
Redis 不需要 代码未使用 Redis（旧说明中的 Redis 配置是遗留项，可忽略）
nginx / IIS 不需要 前端已内嵌进 jar，访问 8090 即可；要前后端分离时才是备选

三、打包（在开发机上执行，推荐一键脚本）

cd D:\文档\ChatGPT\traffic-audit
python package-deploy.py            # 全流程：前端构建 + 后端打包 + 组装 + 压缩
python package-deploy.py --no-build # 跳过前端构建（dist 已是最新时更快）

脚本做了什么：

  1. traffic-audit-web 下 npm run build → dist；
  2. 把 dist 复制进 traffic-audit-server/src/main/resources/static，使 jar 自带前端，再 mvn clean package -DskipTests（跑完自动清空 static，保持仓库干净）；
  3. 组装 deploy/traffic-audit-deploy-YYYYMMDD/；
  4. 压缩为 traffic-audit-deploy-YYYYMMDD.zip（约 70 MB）。

手工等价命令（不想用脚本时）：

cd traffic-audit-web ; npm run build ; cd ..
robocopy traffic-audit-web\dist traffic-audit-server\src\main\resources\static /E
cmd /c "mvn -q clean package -DskipTests -f traffic-audit-server\pom.xml"

注意：手工方式跑完记得删掉 traffic-audit-server/src/main/resources/static 下的内容，否则会污染源码目录。

四、部署包内容

traffic-audit-deploy-YYYYMMDD/
├─ backend/
│  ├─ traffic-audit-server-1.0.0-SNAPSHOT.jar   后端 + 内嵌前端（约 55 MB）
│  ├─ docs/                                     模板与运行数据（必需，勿删）
│  ├─ application.yml                           外部配置（改这里即可，无需重打包）
│  └─ start-backend.cmd / start-backend.sh       启动脚本
├─ frontend/
│  ├─ dist/                                     前端产物（仅 nginx 方案需要）
│  └─ nginx.conf.example                         nginx 配置示例
├─ db/
│  ├─ init.sql                                  建库建表 + 预置账号（必须执行）
│  ├─ sql_city_bus.sql                          城市客运-公交月度表（必须执行）
│  ├─ sql_city_taxi.sql                         城市客运-出租月度表/授权表（必须执行）
│  └─ sql_wyc.sql                               网约车全省总量/订单分市州表（必须执行）
└─ README-部署说明.txt

五、目标机器部署步骤

5.1 初始化数据库（4 个脚本都要执行）

mysql --default-character-set=utf8mb4 -u root -p < db/init.sql
mysql --default-character-set=utf8mb4 -u root -p traffic_audit < db/sql_city_bus.sql
mysql --default-character-set=utf8mb4 -u root -p traffic_audit < db/sql_city_taxi.sql
mysql --default-character-set=utf8mb4 -u root -p traffic_audit < db/sql_wyc.sql
  • 预置账号：admin / admin123（登录后请立即改密码）。
  • 想连数据一起搬：在源机器 mysqldump -u root -p --databases traffic_audit > traffic_audit_full.sql，在目标机器 mysql -u root -p < traffic_audit_full.sql（会覆盖预置账号）。

5.2 改配置 backend/application.yml

配置项 说明
spring.datasource.url 数据库地址（出厂值 127.0.0.1:3306/traffic_audit，按实际改）
spring.datasource.username/password 数据库账号密码（**必改**）
jwt.secret 登录令牌密钥；**必须是 Base64 合法字符且长度是 4 的倍数**（出厂值是一串 32 位十六进制）；填中文或非法字符会导致登录 500（程序已做兜底并打 WARN，但仍建议填规范值）
deepseek.api-key AI 分析用，不用可留空
server.port 默认 8090

外置 application.yml 与 jar 同级即生效（优先级高于 jar 内置配置），改完不用重新打包。

5.3 启动（必须在 backend 目录下）

# Windows：双击 start-backend.cmd；或
cd backend ; java -jar traffic-audit-server-1.0.0-SNAPSHOT.jar

# Linux
cd backend && sh start-backend.sh

成功标志：日志出现 Started TrafficAuditApplication 与 Tomcat started on port(s): 8090。

5.4 访问

浏览器打开 http://<部署机IP>:8090（前端已内嵌，页面与接口同源，无需 nginx），账号 admin / admin123。

六、关键配置（application.yml）与运行数据

配置项 默认值 说明
docs.template-root docs 导入模板下载根目录
city-passenger.template-dir docs/城市客运 城市客运（含《模板_网约车订单.docx》）
passenger.template-dir docs/公路旅客 公路旅客
freight.template-dir docs/货运 货运
energy.template-dir docs/能耗 能耗
investment.template-dir docs/投资/模板 投资
summary.template-dir docs/生成汇总大表 汇总大表母版与版式参照件（导出报表依赖）

docs/生成汇总大表 至少要有：

  • 生成_道路运输量汇总表.xlsx（版式参照件，缺失会退回默认列宽）；
  • 需要导出的各月份母版 YYYY年M月道路运输量汇总表.xlsx（缺哪个月，导那个月就会明确报错）。

七、前端部署（两种方式）

  1. 推荐：jar 内嵌——一键脚本已把 dist 打进 jar，直接访问 http://<IP>:8090 即可，无需额外 Web 服务器。
  2. 备选：nginx 托管 frontend/dist 并把 /api 反代到 8090（配置见 frontend/nginx.conf.example）；上传 100MB 大文件时记得设 client_max_body_size 100m。

前端路由为 hash 模式，刷新/直达不会 404。

八、部署后验证清单

  1. http://<IP>:8090 打开登录页（页面不是空白）；
  2. admin / admin123 能登录，左上角显示「管理员」；
  3. 「数据导入」页能下载模板、能上传 Excel；
  4. 「报表」页查询 + 导出《道路运输量汇总表》，能下载到 xlsx；
  5. 打开导出的 xlsx，核对当月数值是否为最新报表期。

九、常见问题

现象 原因 / 处理
启动报「未找到数据目录 docs」 必须在 backend 目录下启动（jar 与 docs 同级）
导出报「未找到模板文件 xxx」 docs 对应子目录缺模板；从源机器拷贝
导出报「未找到汇总表母版《YYYY年M月…》」 docs/生成汇总大表 缺该月母版
登录接口 500 jwt.secret 填了非法字符（如中文）；改成 32 位十六进制串
页面能开但接口 404 走 nginx 方案时没配 /api 反代；改用 jar 内嵌访问 8090
数据库连接失败 检查 application.yml；确认 4 个 SQL 脚本已执行
端口占用 改 server.port；前端开发端口 8080

十、开发环境日常启动

powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1

后端 8090（mvn spring-boot:run）+ 前端 8080（npm run serve），访问 http://localhost:8080。

十一、变更记录

  • 2026-09-13：新增一键打包脚本 package-deploy.py；jar 改为内嵌前端（部署机不再需要 nginx）；删除 Redis 相关说明（代码未使用）；补 sql_wyc.sql 与 summary.template-dir；补 jwt.secret 取值规则；补部署后验证清单。
  • 2026-08-27：首版（zip 部署包 + nginx 方案）。