赵忠林
6036869645
- 在BszxBmServiceImpl和BszxPayServiceImpl中增强字体检测逻辑，确保正确显示中文 - 调整macOS字体优先级，优先使用PingFang SC等系统字体- 添加多层字体回退机制，包括预定义字体、逻辑字体和错误提示 - 更新Dockerfile，安装文泉驿微米黑字体以支持中文显示- 添加中文乱码修复指南文档，提供三种修复方案和故障排查方法 - 创建fix-chinese-font.sh脚本，用于在运行中的容器内安装中文字体 - 删除不再使用的SQL脚本和证书检查脚本- 改进日志输出，提供更详细的字体加载信息和错误提示
223 lines
6.0 KiB
Markdown
223 lines
6.0 KiB
Markdown
# 捐款证书中文乱码修复指南
|
||
|
||
## 问题描述
|
||
生成的捐款证书图片中，中文字符显示为乱码或方块，影响证书的正常使用。
|
||
|
||
问题示例：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`）
|