交通统计审核
编辑 | 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 8.0 部署机必须，库名 traffic_audit；现网/开发机为 8.0.29，表排序规则是 utf8mb4_0900_ai_ci，**目标机装 5.7 会导入失败**
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 准备数据库（两条路线二选一，**不要混着做**）

路线 A：全新空库（要跑 4 个脚本）

init.sql 自带 CREATE DATABASE 与 USE traffic_audit，可独立执行；另外 3 个脚本没有 USE 语句，必须用 -D traffic_audit（或 mysql ... traffic_audit < 文件）指定库：

cd db
mysql --default-character-set=utf8mb4 -u root -p            < init.sql          # 建库 + 24 张基础表 + 预置账号
mysql --default-character-set=utf8mb4 -u root -p -D traffic_audit < sql_city_bus.sql
mysql --default-character-set=utf8mb4 -u root -p -D traffic_audit < sql_city_taxi.sql
mysql --default-character-set=utf8mb4 -u root -p -D traffic_audit < sql_wyc.sql

⚠️ init.sql 是破坏性的：里面的基础表都带 DROP TABLE IF EXISTS。**已有数据的库上千万不要再跑 init.sql**，否则表数据会被清空重建。
4 个脚本共覆盖 29 张表（init.sql 24 张 + 城市客运 3 张 + 网约车 2 张）。

路线 B：把现网/开发机的数据整套搬过去（推荐，不用跑脚本）

先确认两端 MySQL 都是 8.0（本库表排序规则为 utf8mb4_0900_ai_ci，5.7 不识别会导致导入失败），并且**用与服务端同版本的 mysqldump**（不要用 5.7 的客户端去导 8.0 服务端）。

在源机器（本机 MySQL 端口示例 3308，按实际改）：

"C:\Program Files\MySQL\MySQL Server 8.0\bin\mysqldump.exe" ^
  --host=127.0.0.1 --port=3308 --user=root --password=你的密码 ^
  --default-character-set=utf8mb4 --single-transaction --routines --triggers --events ^
  --databases traffic_audit > traffic_audit_full_YYYYMMDD.sql

在目标机器：

mysql --default-character-set=utf8mb4 -u root -p < traffic_audit_full_YYYYMMDD.sql
  • --databases 会把 CREATE DATABASE + USE 一起写进备份，所以目标机器**不用先建库、也不用跑那 4 个脚本**。
  • 备份里包含 sys_user，账号密码与源机器完全一致（本机是 admin / 123456），不会被重置成 admin/admin123。
  • ⚠️ 备份里每张表都带 DROP TABLE IF EXISTS（共 29 张）：**目标库要是已有数据，会被直接覆盖**。请还原到空库，或先自己备份目标库。
  • 本次已生成并**验证过**备份：traffic_audit_full_20260913.sql（45.5 MB，8.0.29 客户端导出）。
    验证方式：把备份库名改成临时库导入，逐表比对 SHOW CREATE TABLE（表结构）与 COUNT(*)（行数）——**29 张表结构与行数均 0 差异**，抽查 wyc_order_monthly 2026-08 数据一致，验证后已删除临时库。

路线 B2：用 Navicat 的「备份 / 还原备份」（.nb3，最贴近日常习惯）

.nb3 是 Navicat 私有备份格式（tar 容器：每张表一份 meta.json + gz 压缩的数据分片 + SHA1 校验 + 总 meta.json），
只能由 Navicat 自己生成、也只能在 Navicat 里用「还原备份」还原——**用 .sql 点「还原备份」一定失败**（那个入口只认 .nb3）。

在源机器（30 秒）：

  1. Navicat → 连接 mysql80 → 选中 traffic_audit → 右键 →「备份…」→ 起个名字 → 确定，等它跑完；
  2. 生成的备份文件在 Navicat 的 profile 目录：D:\文档\Navicat\MySQL\Servers\mysql80\traffic_audit\<时间戳>.nb3
    （本机 8/27 那份就在这里，但它**已过期**：只有 27 张表、缺网约车两张表、数据是 8/27 的，不要用）。

在目标机器：

  1. 先在 Navicat 里建一个连到本机 MySQL 8.0 的连接（**连接名建议与源机器一致，比如 mysql80**），并新建空库 traffic_audit（字符集 utf8mb4）；
  2. 把 .nb3 放到目标机器的对应目录 <Navicat profile>\MySQL\Servers\<连接名>\traffic_audit\（没有就照着建目录）；
  3. 右键该库 →「还原备份」→ 在选择列表里勾选这份备份 → 开始（列表里看不到就重启一次 Navicat）。

三种方式（路线 A 空库 4 脚本 / 路线 B 命令行还原 .sql / 路线 B2 Navicat .nb3）**任选其一**即可，
但**不要叠加**：还原完备份后再跑 init.sql 会把数据清空重建。

注意：docs/ 目录（报表模板、汇总大表母版）**与数据库无关，无论哪条路线都必须一并拷贝**。

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 方案）。

密钥与配置（2026-09-26 起，打包必读）

分层约定

位置 用途 是否进 git 是否进 jar
traffic-audit-server/src/main/resources/application.yml 进 jar 的默认配置，**只有占位符**（${TRAFFIC_DB_PASSWORD:}、${DEEPSEEK_API_KEY:} 等） 否（已 gitignore，用 application.yml.example 做模板） 是（无真实值）
traffic-audit-server/config/application.yml 本机开发真实值（库口令 / JWT / DeepSeek key） 否（已 gitignore） 否
jar 同级的 backend/application.yml 部署机真实值（优先级高于 jar 内置） 否 否（在包外，现场填）
环境变量 TRAFFIC_DB_PASSWORD / TRAFFIC_DB_USER / TRAFFIC_DB_URL / TRAFFIC_JWT_SECRET / DEEPSEEK_API_KEY 覆盖以上任意一项 否 否

打包前自查（30 秒）

# 1) 确认进 jar 的配置没有真实密钥（应只看到 ${...}）
Select-String -Path traffic-audit-server\src\main\resources\application.yml -Pattern "password:|api-key:|secret:"
# 2) 打完包后再验证一次 jar 内部
python -c "import zipfile;print(zipfile.ZipFile('traffic-audit-server/target/traffic-audit-server-1.0.0-SNAPSHOT.jar').read('BOOT-INF/classes/application.yml').decode('utf-8'))" | Select-String "password:|api-key:"

部署机上加/换 DeepSeek key

  1. 打包上传后，编辑 jar 同级的 backend/application.yml：deepseek.api-key: "你的新key"（留空则页面 AI 分析不可用，其余功能正常）；
  2. 重启后端：start-backend.cmd（或 java -jar traffic-audit-server-1.0.0-SNAPSHOT.jar）；
  3. 页面里点一次 AI 分析确认可用；
  4. 不要去改 jar 内部的配置（改了下次发包就丢），也不要把 key 提交进任何仓库文件。

轮换（作废）已泄露的 key

  1. 登录 DeepSeek 控制台 → API Keys → 新建一个 key；
  2. 删除/禁用旧 key（旧 key 立刻失效，此前打包带出去的 jar 里那份即作废）；
  3. 按上面第 1~3 步把新 key 填到部署机的外部配置并重启验证。