docs: 新增打包与部署说明（md + word 版，共享同事）

xyc

5 天以前 d25bfde3f5ebc9fd8402cc60a3e798f627d3f587

docs: 新增打包与部署说明（md + word 版，共享同事）

 docs/´ò°ü²¿Êð˵Ã÷.docx

Binary files differ

 docs/´ò°ü²¿Êð˵Ã÷.md

New file
@@ -0,0 +1,157 @@
# äº¤é€šç»Ÿè®¡æŠ¥è¡¨å®¡æ ¸ç³»ç»Ÿ â€” æ‰“包与部署说明

> é€‚用：合并后 main åˆ†æ”¯ï¼ˆ2026-08-27 èµ·ï¼‰ã€‚后端 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` | è¿è¡Œæ•°æ®ç›®å½•ï¼ˆæŠ¥è¡¨ Word/Excel æ¨¡æ¿ + ç›®å½•å¯¼å…¥æ•°æ®ï¼‰ï¼Œ**发布必须带上** |
| `docs/init.sql` | æ•°æ®åº“初始化脚本（建库建表 + åˆå§‹è´¦å·ï¼‰ |

## äºŒã€çŽ¯å¢ƒè¦æ±‚

| ç»„件 | ç‰ˆæœ¬ | ç”¨é€” |
|------|------|------|
| JDK | 1.8 | åŽç«¯ç¼–译与运行 |
| Maven | 3.x | åŽç«¯æ‰“包 |
| Node.js | 14+ | å‰ç«¯æ‰“包（vue-cli 4.5） |
| MySQL | 8.0 | æ•°æ®åº“（库名 `traffic_audit`） |

## ä¸‰ã€æ•°æ®åº“初始化

先执行建库建表脚本，再按需导入城市客运数据：

```bash
mysql --default-character-set=utf8mb4 -h <主机> -P 3306 -u root -p < docs/init.sql
mysql --default-character-set=utf8mb4 -h <主机> -P 3306 -u root -p traffic_audit < docs/sql_city_bus.sql
mysql --default-character-set=utf8mb4 -h <主机> -P 3306 -u root -p traffic_audit < docs/sql_city_taxi.sql
```

- `init.sql` ä¼šé‡å»º `traffic_audit` åº“并预置初始账号：`admin / admin123`（生产环境请登录后改密码）
- `sql_city_bus.sql`、`sql_city_taxi.sql` ä¸ºåŸŽå¸‚客运（公交/出租）示例数据，按需导入

## å››ã€æ‰“包

### 4.1 åŽç«¯ï¼ˆé¡¹ç›®æ ¹ç›®å½•æ‰§è¡Œï¼‰

```powershell
cmd /c "mvn -q clean package -DskipTests -f traffic-audit-server\pom.xml"
```

产物：`traffic-audit-server\target\traffic-audit-server-1.0.0-SNAPSHOT.jar`（可执行 fat jar，约 57MB）。

### 4.2 å‰ç«¯ï¼ˆ`traffic-audit-web` ç›®å½•æ‰§è¡Œï¼‰

```powershell
cd traffic-audit-web
npm run build
```

产物：`traffic-audit-web\dist\`（`index.html` + `css/js/fonts`，纯静态文件）。

## äº”、部署目录结构（推荐）

```
deploy\
├─ app.jar                    # åŽç«¯ jar（可改名）
├─ docs\                      # å¿…须：模板与目录导入数据目录
│  â”œâ”€ åŸŽå¸‚客运\
│  â”œâ”€ å…¬è·¯æ—…客\
│  â”œâ”€ è´§è¿\
│  â”œâ”€ èƒ½è€—\
│  â”œâ”€ æŠ•èµ„\
│  â”‚  â””─ æ¨¡æ¿\
│  â””─ (6月\ 7月\ ç­‰å¯¼å…¥æ•°æ®ç›®å½•ï¼ŒæŒ‰éœ€)
└─ web\                       # å‰ç«¯ dist çš„内容
   â”œâ”€ index.html
   â”œâ”€ css\  js\  fonts\
```

关键点：

- **`docs` å¿…须放在 jar åŒçº§**。后端运行时按启动目录向上查找 `docs`（报表导出的 Word æ¨¡æ¿ã€å¯¼å…¥é¡µã€Œä¸‹è½½æ¨¡æ¿ã€ã€ç›®å½•å¯¼å…¥æ•°æ®éƒ½ä»Žè¿™é‡Œè¯»ï¼‰ï¼Œæ‰¾ä¸åˆ°ä¼šæŠ¥ã€Œæœªæ‰¾åˆ°æ•°æ®ç›®å½• docs」或「未找到模板文件 xxx」。
- é¦–次部署直接把项目里的整个 `docs` æ‹·è¿‡åŽ»æœ€ç¨³å¦¥ï¼›åŽç»­å¯ç²¾ç®€ï¼ˆåªç•™æ¨¡æ¿å­ç›®å½•ï¼‰ï¼Œè¯¦è§ã€Œå¸¸è§é—®é¢˜ã€ã€‚
- `application.yml` æ‰“包在 jar å†…；部署机需要改配置时，可在 jar åŒçº§æ”¾ä¸€ä¸ªå¤–ç½® `application.yml`（外置优先级高于内置），或改完再打包。

## å…­ã€å…³é”®é…ç½®ï¼ˆapplication.yml）

| é…ç½®é¡¹ | è¯´æ˜Ž |
|--------|------|
| `spring.datasource.url/username/password` | æ•°æ®åº“连接（模板默认 `localhost:3305/root/root`，部署机**必须改**；生产建议用环境变量 `MYSQL_PASSWORD` æ³¨å…¥ï¼‰ |
| `deepseek.api-key` | AI åˆ†æžæŽ¥å£å¯†é’¥ï¼ˆçŽ¯å¢ƒå˜é‡ `DEEPSEEK_API_KEY`，不使用 AI åˆ†æžå¯ç•™ç©ºï¼‰ |
| `jwt.secret` | ç™»å½•ä»¤ç‰Œå¯†é’¥ï¼ˆç”Ÿäº§å¿…须改，环境变量 `JWT_SECRET`） |
| `docs.template-root` | å¯¼å…¥æ¨¡æ¿ä¸‹è½½æ ¹ç›®å½•ï¼ˆé»˜è®¤ `docs`） |
| `city-passenger.template-dir` | åŸŽå¸‚客运报表模板目录（默认 `docs/城市客运`） |
| `passenger.template-dir` | å…¬è·¯æ—…客报表模板目录（默认 `docs/公路旅客`） |
| `freight.template-dir` | è´§è¿æŠ¥è¡¨æ¨¡æ¿ç›®å½•ï¼ˆé»˜è®¤ `docs/货运`） |
| `energy.template-dir` | èƒ½è€—报表模板目录（默认 `docs/能耗`） |
| `investment.template-dir` | æŠ•èµ„报表模板目录（默认 `docs/投资/模板`） |

> æ³¨æ„ï¼šä»“库只提交占位模板 `application.yml.example`，真实 `application.yml` ä¸å…¥åº“。

## ä¸ƒã€å¯åŠ¨åŽç«¯

```powershell
cd deploy
java -jar app.jar
```

- æˆåŠŸæ ‡å¿—：日志出现 `Started TrafficAuditApplication` å’Œ `Tomcat started on port(s): 8090`。
- åœ¨ `deploy` ç›®å½•ä¸‹å¯åŠ¨å³å¯å‘½ä¸­åŒçº§çš„ `docs`。

## å…«ã€å‰ç«¯éƒ¨ç½²ï¼ˆnginx ç¤ºä¾‹ï¼‰

`dist` æ˜¯çº¯é™æ€æ–‡ä»¶ï¼Œéœ€è¦ Web æœåŠ¡å™¨æ‰˜ç®¡ï¼›å‰ç«¯æŽ¥å£èµ°ç›¸å¯¹è·¯å¾„ `/api`，**必须反代到后端 8090**：

```nginx
server {
    listen 80;
    server_name _;
    root D:/deploy/web;            # å‰ç«¯ dist ç›®å½•
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;   # è·¯ç”±ä¸º hash æ¨¡å¼ï¼Œæ­¤è¡Œä¿ç•™ä»¥é˜²åŽç»­æ”¹ history
    }

    location /api {
        proxy_pass http://127.0.0.1:8090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    client_max_body_size 100m;     # ä¸Šä¼  Excel éœ€è¦ï¼Œä¸ŽåŽç«¯ multipart 100MB å¯¹é½
}
```

## ä¹ã€éƒ¨ç½²åŽéªŒè¯

1. æµè§ˆå™¨æ‰“å¼€ `http://<服务器>/`；
2. ç”¨ `admin / admin123` ç™»å½•ï¼ˆç”Ÿäº§æ”¹å¯†åŽä½¿ç”¨æ–°å¯†ç ï¼‰ï¼›
3. æ•°æ®å¯¼å…¥ï¼šä¸‹è½½æ¨¡æ¿ â†’ ä¸Šä¼  Excel（或目录导入）；
4. æŠ¥è¡¨ï¼šæŸ¥è¯¢ â†’ é¢„览/导出（依赖 `docs` æ¨¡æ¿æ–‡ä»¶ï¼‰ï¼›
5. AI åˆ†æžï¼šéœ€é…ç½® `deepseek.api-key` åŽå¯ç”¨ã€‚

## åã€å¸¸è§é—®é¢˜

| çŽ°è±¡ | åŽŸå›  / å¤„理 |
|------|------------|
| å¯åŠ¨æŠ¥ã€Œæœªæ‰¾åˆ°æ•°æ®ç›®å½• docs」 | å½“前运行目录不对；把 `docs` æ”¾åˆ° jar åŒçº§å†å¯åŠ¨ |
| å¯¼å‡ºæŠ¥ã€Œæœªæ‰¾åˆ°æ¨¡æ¿æ–‡ä»¶ xxx」 | `docs` å¯¹åº”子目录缺模板文件；首次部署拷整个 `docs` |
| é¡µé¢èƒ½å¼€ä½†æŽ¥å£ 502/404 | nginx æ²¡é… `/api` åä»£ï¼Œæˆ–后端没启动成功 |
| æ•°æ®åº“连接失败 | æ£€æŸ¥ `application.yml` åœ°å€/账号/密码；先执行 `init.sql` |
| ä¸Šä¼ å¤§æ–‡ä»¶å¤±è´¥ | æ£€æŸ¥ nginx `client_max_body_size` ä¸ŽåŽç«¯ multipart é™åˆ¶ |
| ç«¯å£å ç”¨ | åŽç«¯ 8090、前端 80/8080 |

## åä¸€ã€å¼€å‘环境日常启动

项目根目录运行一键脚本（自动拉起后端 8090 + å‰ç«¯ 8080）：

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