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

> 适用：main 分支（最新更新 2026-10-05）。后端 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 即可；要前后端分离时才是备选 |

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

```powershell
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-v1.0.0/`；
4. 压缩为 `traffic-audit-deploy-YYYYMMDD-v1.0.0.zip`（约 70 MB）。

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

```powershell
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` 下的内容，否则会污染源码目录。

### 版本管理与发布（2026-10-05 起）

采用方案 A：后端 jar 使用固定文件名，版本号由 `pom.xml` 单一来源生成，发布包名和 git tag 带版本。

- 单一版本源：`traffic-audit-server/pom.xml` 的 `<version>`，例如 `1.0.0`
- 构建产物固定为 `traffic-audit-server/target/traffic-audit-server.jar`
- 构建时自动把版本写进：
  - `BOOT-INF/classes/app-version.properties`
  - `META-INF/MANIFEST.MF` 的 `Implementation-Version`
- 发布包命名：`traffic-audit-deploy-YYYYMMDD-v1.0.0(.zip)`
- git tag 命名：`v1.0.0`
- 页面版本：后端 `GET /api/version`，登录页和页头显示 `V1.0.0`
- `pack-deploy.ps1` 会校验 `pom.xml`、jar 内 `app-version.properties`、jar 清单三者版本一致，不一致直接中止打包

发新版本流程：

1. 先改 `traffic-audit-server/pom.xml` 的 `<version>`，例如 `1.0.1`
2. 运行 `pack-deploy.ps1` 打包
3. 提交代码并打 git tag：`git tag -a v1.0.1 -m "v1.0.1"`
4. 服务器停止服务，替换 `traffic-audit-server.jar`，再启动服务

旧服务器首次升级（只需做一次）：已有 `trafficAudit.xml` 通常仍写死旧 jar 名 `traffic-audit-server-1.0.0-SNAPSHOT.jar`，把 `<arguments>` 改成固定文件名：

```xml
<arguments>-Dfile.encoding=UTF-8 -jar "%BASE%\traffic-audit-server.jar"</arguments>
```

以后每次发布只替换 jar 并重启服务，不再修改 `trafficAudit.xml`。

## 四、部署包内容

```
traffic-audit-deploy-YYYYMMDD-v1.0.0/
├─ backend/
│  ├─ traffic-audit-server.jar                   后端 + 内嵌前端（约 55 MB，固定文件名）
│  ├─ docs/                                     模板与运行数据（必需，勿删）
│  ├─ application.yml                           外部配置（改这里即可，无需重打包）
│  ├─ start-backend.cmd / start-backend.sh      启动脚本（人工双击/命令行）
│  ├─ trafficAudit.exe                          WinSW 服务包装器（2.12.0 x64，自包含 .NET 6）
│  ├─ trafficAudit.xml                          WinSW 服务配置（自动/延迟启动、失败重启、日志滚动）
│  ├─ install-service.cmd                       双击入口：注册开机自启服务（自动请求管理员权限）
│  ├─ install-service.ps1                       上面那个 cmd 实际调用的脚本（注册/查看/重启/删除）
│  ├─ start-backend-service.cmd                 备选：非交互启动器（无 pause、写 app.log）
│  ├─ install-autostart.ps1                     备选：注册/查看/删除 Windows 开机自启计划任务
│  └─ web/                                     前端静态文件（由 dist 自动同步，8090 单端口模式必需）
├─ frontend/
│  ├─ dist/                                     前端产物（仅 nginx 方案需要）
│  └─ nginx.conf.example                         nginx 配置示例
├─ db/
│  ├─ init.sql                                  建库建表 + 预置账号（必须执行）
│  ├─ sql_city_bus.sql                          城市客运-公交月度表（必须执行）
│  ├─ sql_city_taxi.sql                         城市客运-出租月度表/授权表（必须执行）
│  ├─ sql_wyc.sql                               网约车全省总量/订单分市州表（必须执行）
│  ├─ sql_holiday.sql                           专项统计-重要节假日表（旧库补建时执行）
│  ├─ sql_holiday_decimal_migration.sql         节假日数值列精度迁移（旧库升级）
│  ├─ sql_holiday_comparison_base_migration.sql 节假日环比基期字段迁移（旧库升级）
│  └─ sql_holiday_previous_day_migration.sql    节假日前一日配置迁移（旧库升级）
└─ README-部署说明.txt
```

## 五、目标机器部署步骤

### 5.1 准备数据库（两条路线二选一，**不要混着做**）

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

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

```bash
cd db
mysql --default-character-set=utf8mb4 -u root -p            < init.sql          # 建库 + 28 张基础表 + 预置账号
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 张表，执行 `sql_holiday.sql`；若已有节假日表但缺精度、环比基期字段或前一日配置，按需执行 `sql_holiday_decimal_migration.sql`、`sql_holiday_comparison_base_migration.sql`、`sql_holiday_previous_day_migration.sql`。
> 4 个脚本共覆盖 33 张表（init.sql 28 张，其中含节假日 4 张 + 城市客运 3 张 + 网约车 2 张）。

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

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

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

```bash
"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
```

在目标机器：

```bash
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`（以实际备份为准，最新为 33 张）：**目标库要是已有数据，会被直接覆盖**。请还原到空库，或先自己备份目标库。
- 本次已生成并**验证过**备份：`traffic_audit_full_20260913.sql`（45.5 MB，8.0.29 客户端导出）。
  验证方式：把备份库名改成临时库导入，逐表比对 `SHOW CREATE TABLE`（表结构）与 `COUNT(*)`（行数）——**29 张表结构与行数均 0 差异（新增节假日模块后为 33 张）**，抽查 `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 的，不要用）。

在目标机器：

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

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

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

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

### 5.4 Windows 开机自启（推荐：注册成 Windows 服务）

在 `backend` 目录里**右键 `install-service.cmd` →「以管理员身份运行」**即可（直接双击也行，它会自己弹 UAC）。它实际调用的就是同目录的 `install-service.ps1`，等价命令：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File install-service.ps1
```

脚本会自动定位 java、注册服务、启动，然后探测端口打印结果；起不来时直接打印 `logs\*.log` 的最后 15 行。

| 项 | 值 |
|----|----|
| 服务名 | `TrafficAuditBackend`（services.msc 里显示为 TrafficAudit Backend） |
| 启动类型 | 自动 + 延迟启动（先等 MySQL 就绪），不需要任何用户登录 |
| 运行身份 | LocalSystem |
| 失败重启 | 10s / 30s / 60s 递增，1 小时后计数清零（由服务控制管理器执行） |
| 日志 | `backend\logs\trafficAudit.out.log`、`trafficAudit.err.log`（10MB × 10 滚动） |

常用参数：`-Status`（无需管理员）、`-Restart`、`-Remove`、`-NoStart`、`-JavaPath "D:\jdk8\bin\java.exe"`。
脚本会自动定位 `java.exe`（JAVA_HOME → PATH → JavaSoft 注册表 → Program Files）并把**绝对路径**写进 `trafficAudit.xml`（SYSTEM 服务的 PATH 与登录用户不同，写绝对路径更稳）。重复执行是幂等的：先停服务再重新注册并启动。

> 同一台机**不要**同时启用计划任务方式（`install-autostart.ps1`），两个宿主会抢 8090 端口。

#### 操作系统兼容性

服务本身（自动启动 / 延迟启动 / 失败重启）从 Win7 SP1 到 Win11、Server 2008 R2 到 Server 2022/2025 机制一致，差别只在包装器依赖的运行时：

| 目标系统 | 用哪个包装器 | 额外依赖 |
|----------|--------------|----------|
| Win10 / Win11 / Server 2016 及以上（推荐） | 包内 `trafficAudit.exe`（WinSW 2.12.0 x64 自包含） | 无（自带 .NET 6 运行时） |
| Win7 SP1 / Server 2008 R2 / Server 2012(R2) | 先试包内自包含版（Win7 需 KB2533623）；报 `api-ms-win-*.dll` 缺失时换 `WinSW.NET461.exe` 改名成 `trafficAudit.exe` | .NET Framework 4.6.1+ |
| 32 位系统 | `WinSW-x86.exe` 改名成 `trafficAudit.exe` | 无（自带 .NET 6 运行时） |

下载页：<https://github.com/winsw/winsw/releases/tag/v2.12.0> —— 任何构建都用同一份 `trafficAudit.xml`，改的只是包装器文件名。
`install-service.ps1` 在 Windows PowerShell 2.0+ 可用；`install-autostart.ps1` 用到 `New-ScheduledTask*`，需 Win8 / Server 2012 及以上。

### 5.5 访问

浏览器打开 `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`；确认 5 个 SQL 脚本已执行 |
| 启动报 `Access denied ... (using password: NO)` | 后端拿到的库口令是**空串**：jar 内置 `${TRAFFIC_DB_PASSWORD:}` 未被外置配置覆盖。把 `backend/application.yml` 放在 jar 同级并填 `spring.datasource.password`，或设环境变量 `TRAFFIC_DB_PASSWORD`；改完重启，无需重打包 |
| 端口占用 | 改 `server.port`；前端开发端口 8080 |
| 服务已注册但 8090 打不开 | 看 `backend\logs\trafficAudit.err.log`；服务方式读的是 `backend\application.yml`，`password` 必须是真实口令 |
| 服务报“拒绝访问”/写不了日志 | 部署目录权限不足：换到 `D:\trafficAudit` 这类简单路径，或给 LocalSystem 授写权限 |
| 不想开机自启但保留服务 | `Set-Service TrafficAuditBackend -StartupType Manual` |
| Win7/2008R2 上服务启不了（报 `api-ms-win-*.dll`） | 见 5.4「操作系统兼容性」：把 `WinSW.NET461.exe` 改名成 `trafficAudit.exe` 替换 |

## 十、开发环境日常启动

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

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

## 十一、变更记录

- **2026-10-05**：版本管理采用方案 A。`pom.xml` 为唯一版本源，jar 固定名为 `traffic-audit-server.jar`，构建自动注入 `app-version.properties` 与 `MANIFEST.MF`；发布包名带版本，新增 `/api/version` 页面显示，首次升级旧服务器需一次性修改 `trafficAudit.xml`，以后只替换 jar 并重启。
- **2026-10-03**：`pack-deploy.ps1` 补齐外置 `application.yml`/`docs`/`db`/启动脚本并同步 `backend\web`（修 `Access denied ... (using password: NO)`）；模板端口 8080→8090；新增 Windows 服务方式开机自启（WinSW 2.12.0 `trafficAudit.exe` + `trafficAudit.xml` + `install-service.ps1`，自动/延迟启动、失败重启、日志滚动），计划任务方式降为备选；补操作系统兼容性说明。
- **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` | 覆盖以上任意一项 | 否 | 否 |

### 本机开发（值放环境变量，不落文件）

```powershell
setx TRAFFIC_DB_PASSWORD "本机 MySQL 口令"     # 设一次即可，之后新开的终端自动带上
setx DEEPSEEK_API_KEY   "DeepSeek key"
# 需要时再覆盖：setx TRAFFIC_DB_URL / TRAFFIC_DB_USER / TRAFFIC_JWT_SECRET

powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1   # 会自动从注册表补齐并注入后端进程
```

- `traffic-audit-server/config/application.yml` 只留注释说明（无明文）；删掉它也不影响（值全在环境变量里）。
- 若用 IDE 直接跑主类，请在**新开的**终端/IDE 里启动（让新终端继承用户环境变量），或手动 `setx` 后重启 IDE。

### 打包前自查（30 秒）

```powershell
# 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.jar').read('BOOT-INF/classes/application.yml').decode('utf-8'))" | Select-String "password:|api-key:"
```


### 一键打包（推荐，2026-09-27 起）

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File pack-deploy.ps1
# 可选参数： -OutRoot "E:\试验"   -SkipFrontend
```

脚本做四件事：
1. 用 `deploy-templates/jar-application.yml`（全占位符）临时替换源码 `application.yml`，再 `mvn clean package -DskipTests`，构建后自动还原开发机真实配置；
2. **解压 jar 自检**：检查 `BOOT-INF/classes/application.yml` 是否全为占位符——一旦发现 `sk-` 或明文口令**直接中止打包**；
3. `npm run build` 重建前端 `dist`；
4. 按 `deploy-templates/` 组装完整部署包（backend / frontend / db / README-部署说明.txt）——`backend/` 含 jar、`application.yml`、启动脚本、`docs/`、`web/`（由 dist 自动同步，供 8090 单端口模式），以及 Windows 服务三件套 `trafficAudit.exe` + `trafficAudit.xml` + `install-service.ps1`，输出到 `<OutRoot>\traffic-audit-deploy-<yyyyMMdd>-v<version>`；
   WinSW 优先用 `deploy-templates\tools\winsw.exe` 缓存（校验 SHA-256），缓存缺失或哈希不符时自动从 GitHub 官方发布页下载 v2.12.0 x64（该产物未做 Authenticode 签名，因此以固定 SHA-256 作完整性校验）；
5. 对组装后的整包再扫一遍明文密钥。

可选参数：`-OutRoot` 指定输出目录（默认仓库 `deploy\`）、`-SkipFrontend` 复用现有 dist、`-SkipBackend` 复用现有 jar（只重组包、不重编译，用于快速补包）、`-SkipServiceWrapper` 不把 WinSW 服务包装器打进包（即不要“注册成 Windows 服务”的开机自启）。

> 记录（2026-10-03）：此前手工产出的 10-02 包只有 jar+web+dist，缺 `application.yml`/`docs`/`db`/启动脚本，部署机启动报 `Access denied ... (using password: NO)`。现已由脚本自动补齐这些文件并在打包前替换占位符配置。

模板件统一放在 **`deploy-templates/`**（已入库）：外部 `application.yml`、`start-backend.cmd/.sh`、`trafficAudit.xml`、`install-service.ps1`、`start-backend-service.cmd`、`install-autostart.ps1`、`nginx.conf.example`、`db\{init.sql,sql_city_bus,sql_city_taxi,sql_wyc}.sql`、`README-部署说明.txt`。改模板即改打包产物。

> `deploy-templates\tools\`（WinSW 二进制，17.4MB）**不入库**（已加 `.gitignore`），由打包脚本按需下载并校验 SHA-256。

### 轮换密钥后同步本机

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File set-secrets.ps1
```

交互式输入（回车跳过某一项），自动 `setx` 到用户环境变量并提示重启后端；值不会写入任何文件。

### 部署机上加/换 DeepSeek key

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

### 轮换（作废）已泄露的 key

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