blame | 历史 | 原始文档

部署检查清单

📋 部署前检查

1. 环境检查

[ ] Java版本
bash java -version # 需要：Java 17 或更高版本
[ ] Maven版本
bash mvn -version # 需要：Maven 3.6 或更高版本
[ ] 磁盘空间
```bash
# Windows
dir F:\file\estate

# Linux
df -h /data/uploads
# 建议：至少10GB可用空间
```

[ ] 内存
bash # 建议：至少2GB可用内存 free -h # Linux

2. 字体检查

[ ] Windows字体
检查 C:\Windows\Fonts 目录确保有中文字体（如：微软雅黑、宋体）
[ ] Linux字体
```bash
# 安装中文字体
sudo apt-get update
sudo apt-get install fonts-wqy-zenhei fonts-wqy-microhei

# 验证字体
fc-list :lang=zh
```

3. 依赖检查

[ ] PDFBox依赖
bash # 检查pom.xml中是否包含 grep -A 5 "pdfbox" admin-server/pom.xml
[ ] 编译项目
bash mvn clean compile -DskipTests # 应该成功编译，无错误

4. 配置检查

[ ] 文件上传路径配置
yaml # application.yml file: upload: dir: F:\file\estate # Windows # dir: /data/uploads # Linux
[ ] 创建目录
```bash
# Windows
mkdir F:\file\estate\reports
mkdir F:\file\estate\reports\images

# Linux
sudo mkdir -p /data/uploads/reports/images
sudo chown -R tomcat:tomcat /data/uploads
sudo chmod -R 755 /data/uploads
```

5. 代码检查

[ ] ReportController.java
检查是否包含 convertWordToImagesAndSave() 方法
检查是否包含 getReportImages() 接口
检查是否包含 checkConversionStatus() 接口
[ ] WebMvcConfig.java
检查是否包含静态资源映射配置
检查路径配置是否正确

🚀 部署步骤

步骤1：编译打包

cd F:\code\estate_expert

# 清理并打包
mvn clean package -DskipTests

# 检查打包结果
ls -lh admin-server/target/admin-server-*.jar

步骤2：启动应用

# 方式1：直接启动
java -jar admin-server/target/admin-server-1.0-SNAPSHOT.jar

# 方式2：后台启动（Linux）
nohup java -jar admin-server/target/admin-server-1.0-SNAPSHOT.jar > app.log 2>&1 &

# 方式3：使用systemd（Linux）
sudo systemctl start estate-expert

步骤3：验证启动

# 检查端口
netstat -ano | findstr 8080  # Windows
netstat -tlnp | grep 8080    # Linux

# 检查日志
tail -f logs/spring.log

# 查找关键日志
grep "静态资源映射配置完成" logs/spring.log

✅ 功能测试

测试1：仅下载功能

curl -o test_download.docx "http://localhost:8080/admin/stat/report/fuzzyReport?checkTaskId=1&templateId=1"

# 验证
ls -lh test_download.docx
# 应该生成Word文件

预期结果：
- ✅ 成功下载Word文件
- ✅ 文件大小正常（>0字节）
- ✅ 可以用Word打开

测试2：下载并转图片

# 生成UUID
UUID=$(uuidgen | tr -d '-' | cut -c1-16)
echo "UUID: $UUID"

# 下载并转换
curl -o "test_convert_${UUID}.docx" "http://localhost:8080/admin/stat/report/fuzzyReport?checkTaskId=1&templateId=1&uuid=${UUID}"

# 等待5秒
sleep 5

# 检查转换状态
curl "http://localhost:8080/admin/stat/report/checkConversionStatus?uuid=${UUID}"

预期结果：
json { "code": 0, "message": "success", "data": { "uuid": "...", "wordFileExists": true, "imageCount": 3, "conversionCompleted": true } }

测试3：获取图片列表

curl "http://localhost:8080/admin/stat/report/getReportImages?uuid=${UUID}"

预期结果：
json { "code": 0, "message": "success", "data": [ "xxx_page_1.png", "xxx_page_2.png", "xxx_page_3.png" ] }

测试4：访问图片

# 获取第一张图片
curl -o test_image.png "http://localhost:8080/files/reports/images/${UUID}_page_1.png"

# 验证
ls -lh test_image.png
file test_image.png
# 应该显示：PNG image data

预期结果：
- ✅ 成功下载图片
- ✅ 文件类型为PNG
- ✅ 可以用图片查看器打开

测试5：检查服务器文件

# Windows
dir F:\file\estate\reports\%UUID%.docx
dir F:\file\estate\reports\images\%UUID%_*.png

# Linux
ls -lh /data/uploads/reports/${UUID}.docx
ls -lh /data/uploads/reports/images/${UUID}_*.png

预期结果：
- ✅ Word文件已保存
- ✅ 图片文件已生成
- ✅ 图片数量正确

🔍 日志检查

关键日志

启动日志：
静态资源映射配置完成: - /files/reports/** -> file:F:\file\estate\reports/ - /files/reports/images/** -> file:F:\file\estate\reports/images/

转换日志：
开始转换Word为图片，共3页页面1已转换为图片: F:\file\estate\reports\images\xxx_page_1.png 页面2已转换为图片: F:\file\estate\reports\images\xxx_page_2.png 页面3已转换为图片: F:\file\estate\reports\images\xxx_page_3.png Word文档已成功转换为3张图片

查询日志：
查询报告图片列表: uuid=xxx, 共3张图片

错误日志检查

# 查找错误日志
grep -i "error" logs/spring.log
grep -i "exception" logs/spring.log
grep -i "failed" logs/spring.log

# 查找Word转图片相关错误
grep "Word转图片失败" logs/spring.log

🐛 常见问题排查

问题1：编译失败

错误信息：
Fatal error compiling: 无效的目标发行版: 17

原因： Java版本不匹配

解决方案：
```bash

检查Java版本

java -version

安装Java 17

Windows: 下载并安装JDK 17

Linux: sudo apt-get install openjdk-17-jdk


### 问题2：转换失败（字体错误）

**错误日志：**

Word转图片失败: ... FontException ...
```

原因： 缺少中文字体

解决方案：
```bash

Linux

sudo apt-get install fonts-wqy-zenhei fonts-wqy-microhei
fc-cache -fv

Windows

确保 C:\Windows\Fonts 有中文字体


### 问题3：图片无法访问（404）

**错误：** 访问图片返回404

**原因：** 静态资源映射未生效

**排查步骤：**
1. 检查 `WebMvcConfig.java` 配置
2. 检查启动日志是否有静态资源映射日志
3. 检查文件是否真实存在
4. 检查路径配置是否正确

**解决方案：**

检查文件是否存在

ls -lh F:\file\estate\reports\images\

检查配置

grep "addResourceHandlers" admin-server/src/main/java/com/estate/expert/admin/config/WebMvcConfig.java

重启应用


### 问题4：转换超时

**现象：** 转换一直不完成

**原因：** 文档太大或系统资源不足

**排查步骤：**
1. 检查CPU和内存使用率
2. 检查磁盘空间
3. 查看日志是否有错误

**解决方案：**

检查系统资源

top # Linux
任务管理器 # Windows

检查磁盘空间

df -h # Linux
dir # Windows

增加超时时间或使用异步处理


### 问题5：图片模糊

**现象：** 生成的图片不清晰

**原因：** DPI设置过低

**解决方案：**
修改 `ReportController.java` 第456行：

// 从 150 改为 300 或 600
BufferedImage image = pdfRenderer.renderImageWithDPI(i, 300, ImageType.RGB);
```

📊 性能监控

监控指标

# 1. 转换成功率
grep "Word文档已成功转换" logs/spring.log | wc -l
grep "Word转图片失败" logs/spring.log | wc -l

# 2. 平均转换时间
# 查看日志中的时间戳差异

# 3. 磁盘使用
du -sh /data/uploads/reports/
du -sh /data/uploads/reports/images/

# 4. 文件数量
find /data/uploads/reports/images/ -name "*.png" | wc -l

性能基准

指标	正常值	警告值
转换成功率	>95%	<90%
平均转换时间（5页）	<5秒	>10秒
磁盘使用率	<80%	>90%
内存使用	<1GB/任务	>2GB/任务

🔒 安全检查

1. 认证授权

[ ] 生产环境是否移除 @IgnoreAuth
[ ] 是否添加用户认证
[ ] 是否添加权限控制

2. 文件访问控制

[ ] 是否验证UUID合法性
[ ] 是否检查文件所有权
[ ] 是否记录访问日志

3. 资源限制

[ ] 是否限制文件大小
[ ] 是否限制并发转换数
[ ] 是否监控磁盘空间

4. 数据安全

[ ] 是否定期备份
[ ] 是否定期清理旧文件
[ ] 是否加密敏感数据

📝 部署完成确认

功能确认

[ ] ✅ 仅下载功能正常
[ ] ✅ 下载并转图片功能正常
[ ] ✅ 图片列表查询正常
[ ] ✅ 转换状态查询正常
[ ] ✅ 图片HTTP访问正常

性能确认

[ ] ✅ 转换速度符合预期
[ ] ✅ 图片质量符合要求
[ ] ✅ 系统资源占用正常
[ ] ✅ 并发处理正常

文档确认

[ ] ✅ 功能说明文档完整
[ ] ✅ API接口文档完整
[ ] ✅ 快速开始指南完整
[ ] ✅ 测试工具可用

监控确认

[ ] ✅ 日志记录正常
[ ] ✅ 错误告警配置
[ ] ✅ 性能监控配置
[ ] ✅ 磁盘空间监控

🎉 部署完成

恭喜！Word转图片功能已成功部署。

下一步

监控运行状态

定期查看日志
监控系统资源
关注错误告警

性能优化

考虑添加异步处理
考虑添加缓存机制
考虑使用对象存储

功能扩展

添加更多图片格式支持
添加图片水印功能
添加批量转换功能

技术支持

如遇问题，请查看：
- 📖 功能说明文档
- 📖 API接口文档
- 📖 快速开始指南
- 📖 实现总结

部署日期： ___________
部署人员： ___________
部署环境： ___________
部署状态： ✅ 成功 / ❌ 失败