tyapi-server/docs/Ubuntu服务器PDF字体配置指南.md

Ubuntu服务器PDF字体配置指南

概述

本文档说明如何在Ubuntu 24.04 LTS服务器上配置PDF生成功能所需的中文字体。

字体文件位置

确保字体文件存在于以下任一位置：

推荐路径（按优先级）

1. 工作目录相对路径（最常用）

   {工作目录}/internal/shared/pdf/fonts/
   

   例如：如果工作目录是 /www/tyapi-server，则字体应在：

   /www/tyapi-server/internal/shared/pdf/fonts/
   

2. 可执行文件相对路径

   {可执行文件所在目录}/internal/shared/pdf/fonts/
   

3. 环境变量指定路径

   export PDF_FONT_DIR=/path/to/fonts
   

4. 硬编码路径（后备方案）

   • /www/tyapi-server/internal/shared/pdf/fonts ✅（已配置）
   • /app/internal/shared/pdf/fonts（Docker）
   • /usr/local/tyapi-server/internal/shared/pdf/fonts
   • /opt/tyapi-server/internal/shared/pdf/fonts
   • /home/ubuntu/tyapi-server/internal/shared/pdf/fonts
   • /root/tyapi-server/internal/shared/pdf/fonts
   • /var/www/tyapi-server/internal/shared/pdf/fonts

部署步骤

方法1：直接复制字体文件（推荐）

# 1. 创建字体目录
sudo mkdir -p /www/tyapi-server/internal/shared/pdf/fonts

# 2. 复制字体文件（从本地或Git仓库）
# 需要以下字体文件：
# - simhei.ttf (黑体，必需)
# - simkai.ttf (楷体，可选)
# - simfang.ttf (仿宋，可选)
# - YunFengFeiYunTi-2.ttf (水印字体，可选)

# 3. 设置权限
sudo chmod -R 644 /www/tyapi-server/internal/shared/pdf/fonts/*.ttf
sudo chmod -R 644 /www/tyapi-server/internal/shared/pdf/fonts/*.ttc

# 4. 确保运行用户有读取权限
sudo chown -R $(whoami):$(whoami) /www/tyapi-server/internal/shared/pdf/fonts

方法2：使用环境变量

# 设置字体目录环境变量
export PDF_FONT_DIR=/www/tyapi-server/internal/shared/pdf/fonts

# 或在 systemd 服务文件中添加
# Environment="PDF_FONT_DIR=/www/tyapi-server/internal/shared/pdf/fonts"

方法3：使用符号链接

如果字体文件在其他位置，可以创建符号链接：

sudo mkdir -p /www/tyapi-server/internal/shared/pdf/fonts
sudo ln -s /path/to/actual/fonts/*.ttf /www/tyapi-server/internal/shared/pdf/fonts/

验证字体文件

1. 检查文件是否存在

ls -lh /www/tyapi-server/internal/shared/pdf/fonts/

应该看到：

-rw-r--r-- 1 user user 9.5M Dec  3 18:00 simhei.ttf
-rw-r--r-- 1 user user 8.2M Dec  3 18:00 simkai.ttf
-rw-r--r-- 1 user user 7.8M Dec  3 18:00 simfang.ttf

2. 检查文件权限

stat /www/tyapi-server/internal/shared/pdf/fonts/simhei.ttf

确保有读取权限（至少 -r--r--r--）。

3. 检查文件类型

file /www/tyapi-server/internal/shared/pdf/fonts/simhei.ttf

应该显示：TrueType font data

验证PDF生成功能

1. 查看日志

启动服务后，查看日志中是否有以下信息：

{"level":"INFO","msg":"找到字体文件","count":3,"paths":["/www/tyapi-server/internal/shared/pdf/fonts/simhei.ttf",...]}
{"level":"INFO","msg":"成功加载中文字体","font_path":"/www/tyapi-server/internal/shared/pdf/fonts/simhei.ttf"}

2. 测试PDF生成

调用PDF下载接口，检查：

• PDF文件能正常生成
• 中文文字正常显示（不是乱码或空白）
• 没有字体相关的错误日志

3. 调试信息

如果字体未找到，查看日志中的调试信息：

{"level":"DEBUG","msg":"查找字体文件","total_paths":20,"paths":[...]}
{"level":"DEBUG","msg":"字体文件不存在","font_path":"...","error":"..."}

常见问题

问题1：字体文件找不到

症状：日志显示 "未找到中文字体文件"

解决方案：

1. 确认字体文件路径是否正确
2. 检查文件权限：chmod 644 *.ttf
3. 检查文件所有者：chown user:user *.ttf
4. 查看日志中的 "查找字体文件" 调试信息，确认尝试的路径

问题2：字体文件无权限读取

症状：日志显示 "字体文件无读取权限"

解决方案：

sudo chmod 644 /www/tyapi-server/internal/shared/pdf/fonts/*.ttf
sudo chown -R $(whoami):$(whoami) /www/tyapi-server/internal/shared/pdf/fonts

问题3：中文显示为乱码

症状：PDF中中文显示为乱码或空白

解决方案：

1. 确认字体文件已成功加载（查看日志）
2. 确认字体文件是有效的TTF格式
3. 检查字体文件是否损坏：file *.ttf

问题4：Docker容器中找不到字体

症状：在Docker容器中运行时找不到字体

解决方案：

1. 确保Dockerfile中已复制字体文件：

   COPY --from=builder /app/internal/shared/pdf/fonts/ ./internal/shared/pdf/fonts/
   

2. 或使用volume挂载：

   volumes:
     - /www/tyapi-server/internal/shared/pdf/fonts:/app/internal/shared/pdf/fonts:ro
   

Systemd服务配置示例

如果使用systemd管理服务，可以在服务文件中设置环境变量：

[Unit]
Description=TYAPI Server
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/www/tyapi-server
ExecStart=/www/tyapi-server/tyapi-server -env=production
Environment="PDF_FONT_DIR=/www/tyapi-server/internal/shared/pdf/fonts"
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

字体文件获取

如果本地没有字体文件，可以从以下来源获取：

1. Windows系统字体（如果服务器是Windows迁移过来的）

   • C:\Windows\Fonts\simhei.ttf → 复制到服务器

2. Linux系统字体包

   # Ubuntu/Debian
   sudo apt-get install fonts-wqy-zenhei fonts-wqy-microhei
   # 然后从系统字体目录复制或创建符号链接
   

3. 从项目仓库

   • 确保字体文件已提交到Git仓库
   • 使用 git pull 拉取最新代码

注意事项

1. 字体文件大小：每个TTF文件约8-10MB，确保有足够磁盘空间
2. 文件权限：确保运行服务的用户有读取权限
3. 路径一致性：确保字体路径与代码中的查找路径一致
4. 日志级别：生产环境建议将字体查找日志设为DEBUG级别，避免日志过多

技术支持

如果遇到问题，请提供以下信息：

1. 服务器操作系统版本：lsb_release -a
2. 字体文件位置和权限：ls -lh /www/tyapi-server/internal/shared/pdf/fonts/
3. 工作目录：pwd（服务运行时）
4. 可执行文件位置：which tyapi-server 或 readlink -f $(which tyapi-server)
5. 相关日志：包含 "查找字体文件" 和 "字体文件" 的日志条目