feat(core):优化中文字体支持和证书生成功能
- 在BszxBmServiceImpl和BszxPayServiceImpl中增强字体检测逻辑，确保正确显示中文 - 调整macOS字体优先级，优先使用PingFang SC等系统字体- 添加多层字体回退机制，包括预定义字体、逻辑字体和错误提示 - 更新Dockerfile，安装文泉驿微米黑字体以支持中文显示- 添加中文乱码修复指南文档，提供三种修复方案和故障排查方法 - 创建fix-chinese-font.sh脚本，用于在运行中的容器内安装中文字体 - 删除不再使用的SQL脚本和证书检查脚本- 改进日志输出，提供更详细的字体加载信息和错误提示
This commit is contained in:
222
docs/chinese-font-fix-guide.md
Normal file
222
docs/chinese-font-fix-guide.md
Normal file
@@ -0,0 +1,222 @@
|
||||
# 捐款证书中文乱码修复指南
|
||||
|
||||
## 问题描述
|
||||
生成的捐款证书图片中，中文字符显示为乱码或方块，影响证书的正常使用。
|
||||
|
||||
问题示例：https://file-s209.shoplnk.cn/poster/10547/pay/2536.jpg?v=0409
|
||||
|
||||
## 根本原因
|
||||
1. **系统缺少中文字体**：Docker容器（Alpine Linux）默认不包含中文字体
|
||||
2. **字体回退机制不完善**：当找不到中文字体时，回退到的默认字体不支持中文
|
||||
3. **字体检测不够严格**：原代码只检测单个汉字，可能导致误判
|
||||
|
||||
## 修复方案
|
||||
|
||||
### 方案一：重新构建Docker镜像（推荐）
|
||||
|
||||
#### 1. 使用更新后的Dockerfile
|
||||
项目的 `Dockerfile` 已经更新，新增了中文字体支持：
|
||||
|
||||
```dockerfile
|
||||
# 安装必要工具和中文字体支持
|
||||
RUN apk add --no-cache wget fontconfig ttf-dejavu && \
|
||||
# 下载并安装文泉驿微米黑字体（更好的中文支持）
|
||||
wget -O /tmp/wqy-microhei.ttc https://github.com/anthonyfok/fonts-wqy-microhei/raw/master/wqy-microhei.ttc && \
|
||||
mkdir -p /usr/share/fonts/truetype/wqy && \
|
||||
mv /tmp/wqy-microhei.ttc /usr/share/fonts/truetype/wqy/ && \
|
||||
# 刷新字体缓存
|
||||
fc-cache -fv
|
||||
```
|
||||
|
||||
#### 2. 重新构建镜像
|
||||
```bash
|
||||
# 打包项目
|
||||
mvn clean package -DskipTests
|
||||
|
||||
# 构建Docker镜像
|
||||
docker build -t websoft-api:latest .
|
||||
|
||||
# 停止旧容器
|
||||
docker stop websoft-api-container
|
||||
|
||||
# 删除旧容器
|
||||
docker rm websoft-api-container
|
||||
|
||||
# 启动新容器
|
||||
docker run -d \
|
||||
--name websoft-api-container \
|
||||
-p 9200:9200 \
|
||||
-v /path/to/uploads:/app/uploads \
|
||||
-v /path/to/logs:/app/logs \
|
||||
-e SPRING_PROFILES_ACTIVE=prod \
|
||||
websoft-api:latest
|
||||
```
|
||||
|
||||
### 方案二：在运行中的容器内安装字体
|
||||
|
||||
如果不方便重新构建镜像，可以在运行中的容器内安装字体：
|
||||
|
||||
```bash
|
||||
# 进入容器
|
||||
docker exec -it -u root websoft-api-container sh
|
||||
|
||||
# 安装字体工具
|
||||
apk add --no-cache fontconfig ttf-dejavu
|
||||
|
||||
# 下载中文字体
|
||||
wget -O /tmp/wqy-microhei.ttc https://github.com/anthonyfok/fonts-wqy-microhei/raw/master/wqy-microhei.ttc
|
||||
|
||||
# 创建字体目录
|
||||
mkdir -p /usr/share/fonts/truetype/wqy
|
||||
|
||||
# 移动字体文件
|
||||
mv /tmp/wqy-microhei.ttc /usr/share/fonts/truetype/wqy/
|
||||
|
||||
# 刷新字体缓存
|
||||
fc-cache -fv
|
||||
|
||||
# 验证字体安装
|
||||
fc-list :lang=zh
|
||||
|
||||
# 退出容器
|
||||
exit
|
||||
|
||||
# 重启应用（不重启容器）
|
||||
docker exec websoft-api-container pkill -f "java.*app.jar"
|
||||
```
|
||||
|
||||
### 方案三：使用其他基础镜像
|
||||
|
||||
如果Alpine Linux的字体支持仍有问题，可以考虑切换到Debian基础镜像：
|
||||
|
||||
```dockerfile
|
||||
FROM eclipse-temurin:17-jdk
|
||||
|
||||
# 安装中文字体
|
||||
RUN apt-get update && \
|
||||
apt-get install -y --no-install-recommends \
|
||||
fonts-wqy-microhei \
|
||||
fonts-wqy-zenhei \
|
||||
fontconfig && \
|
||||
fc-cache -fv && \
|
||||
rm -rf /var/lib/apt/lists/*
|
||||
```
|
||||
|
||||
## 代码改进说明
|
||||
|
||||
### 1. 增强的字体检测逻辑
|
||||
```java
|
||||
// 检查多个中文字符，确保字体真正支持中文
|
||||
if (font.canDisplay('中') && font.canDisplay('文')) {
|
||||
return font;
|
||||
}
|
||||
```
|
||||
|
||||
### 2. macOS字体优先级调整
|
||||
```java
|
||||
String[] chineseFonts = {
|
||||
"PingFang SC", // 苹方 (macOS) - 优先使用
|
||||
"STHeiti", // 华文黑体 (macOS)
|
||||
"Hiragino Sans GB", // 冬青黑体 (macOS)
|
||||
"Microsoft YaHei", // 微软雅黑 (Windows)
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
### 3. 多层字体回退机制
|
||||
```java
|
||||
// 第一层：预定义字体列表
|
||||
// 第二层：Java逻辑字体（SansSerif, Serif等）
|
||||
// 第三层：明确的错误提示
|
||||
```
|
||||
|
||||
### 4. 详细的日志输出
|
||||
```java
|
||||
System.out.println("✓ 成功使用字体: " + fontName + " (字号: " + fontSize + ")");
|
||||
System.err.println("✗ 严重警告：系统中没有找到任何支持中文的字体！");
|
||||
```
|
||||
|
||||
## 验证修复
|
||||
|
||||
### 1. 查看容器日志
|
||||
```bash
|
||||
docker logs -f websoft-api-container
|
||||
```
|
||||
|
||||
成功加载字体时会看到：
|
||||
```
|
||||
✓ 成功使用字体: PingFang SC (字号: 26)
|
||||
✓ 成功使用字体: PingFang SC (字号: 22)
|
||||
```
|
||||
|
||||
### 2. 测试证书生成
|
||||
调用API生成新的证书，检查中文是否正常显示。
|
||||
|
||||
### 3. 验证字体列表
|
||||
在容器内执行：
|
||||
```bash
|
||||
fc-list :lang=zh
|
||||
```
|
||||
|
||||
应该能看到已安装的中文字体列表。
|
||||
|
||||
## macOS开发环境说明
|
||||
|
||||
如果在macOS上开发，系统已经包含以下中文字体：
|
||||
- PingFang SC（苹方，推荐）
|
||||
- STHeiti（华文黑体）
|
||||
- Hiragino Sans GB（冬青黑体）
|
||||
|
||||
代码已优化为优先使用这些字体。
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 问题1：Docker镜像构建失败
|
||||
**原因**：网络问题导致字体下载失败
|
||||
**解决**：
|
||||
```bash
|
||||
# 使用国内镜像或手动下载字体
|
||||
wget https://ghproxy.com/https://github.com/anthonyfok/fonts-wqy-microhei/raw/master/wqy-microhei.ttc
|
||||
```
|
||||
|
||||
### 问题2：容器重启后字体丢失
|
||||
**原因**：使用方案二安装的字体未持久化
|
||||
**解决**：使用方案一重新构建镜像
|
||||
|
||||
### 问题3：日志显示找不到字体
|
||||
**原因**：字体安装未生效或路径错误
|
||||
**解决**：
|
||||
```bash
|
||||
# 检查字体文件是否存在
|
||||
docker exec websoft-api-container ls -la /usr/share/fonts/truetype/wqy/
|
||||
|
||||
# 重建字体缓存
|
||||
docker exec -u root websoft-api-container fc-cache -fv
|
||||
```
|
||||
|
||||
### 问题4：仍然显示乱码
|
||||
**原因**：可能是图片已缓存
|
||||
**解决**：
|
||||
1. 清除浏览器缓存
|
||||
2. 删除旧的证书图片文件
|
||||
3. 重新生成证书（URL参数v会自动更新）
|
||||
|
||||
## 性能优化建议
|
||||
|
||||
1. **字体缓存**：首次加载后，字体会被JVM缓存，后续生成速度更快
|
||||
2. **字体大小**：文泉驿微米黑字体文件约10MB，不会显著增加镜像大小
|
||||
3. **镜像层优化**：字体安装合并到一个RUN命令中，减少镜像层数
|
||||
|
||||
## 相关文件
|
||||
|
||||
- `/src/main/java/com/gxwebsoft/bszx/service/impl/BszxPayServiceImpl.java` - 捐款证书生成逻辑
|
||||
- `/src/main/java/com/gxwebsoft/bszx/service/impl/BszxBmServiceImpl.java` - 报名证书生成逻辑
|
||||
- `/Dockerfile` - Docker镜像构建配置
|
||||
|
||||
## 技术支持
|
||||
|
||||
如果问题仍未解决，请提供以下信息：
|
||||
1. Docker镜像构建日志
|
||||
2. 容器启动日志（包含字体加载信息）
|
||||
3. 生成的证书图片链接
|
||||
4. 系统环境信息（`docker version`, `docker info`）
|
||||
Reference in New Issue
Block a user