18278781533@163.com

2025-12-03 18:25:04 +08:00
parent b08a63fc99
commit b41d41ddf3
3 changed files with 379 additions and 9 deletions
--- a/docs/Ubuntu服务器PDF字体配置指南.md
+++ b/docs/Ubuntu服务器PDF字体配置指南.md
@@ -0,0 +1,242 @@
+# 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. **环境变量指定路径**
+   ```bash
+   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：直接复制字体文件（推荐）
+
+```bash
+# 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：使用环境变量
+
+```bash
+# 设置字体目录环境变量
+export PDF_FONT_DIR=/www/tyapi-server/internal/shared/pdf/fonts
+
+# 或在 systemd 服务文件中添加
+# Environment="PDF_FONT_DIR=/www/tyapi-server/internal/shared/pdf/fonts"
+```
+
+### 方法3：使用符号链接
+
+如果字体文件在其他位置，可以创建符号链接：
+
+```bash
+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. 检查文件是否存在
+
+```bash
+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. 检查文件权限
+
+```bash
+stat /www/tyapi-server/internal/shared/pdf/fonts/simhei.ttf
+```
+
+确保有读取权限（至少 `-r--r--r--`）。
+
+### 3. 检查文件类型
+
+```bash
+file /www/tyapi-server/internal/shared/pdf/fonts/simhei.ttf
+```
+
+应该显示：`TrueType font data`
+
+## 验证PDF生成功能
+
+### 1. 查看日志
+
+启动服务后，查看日志中是否有以下信息：
+
+```json
+{"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. 调试信息
+
+如果字体未找到，查看日志中的调试信息：
+
+```json
+{"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：字体文件无权限读取
+
+**症状**：日志显示 `"字体文件无读取权限"`
+
+**解决方案**：
+```bash
+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中已复制字体文件：
+   ```dockerfile
+   COPY --from=builder /app/internal/shared/pdf/fonts/ ./internal/shared/pdf/fonts/
+   ```
+2. 或使用volume挂载：
+   ```yaml
+   volumes:
+     - /www/tyapi-server/internal/shared/pdf/fonts:/app/internal/shared/pdf/fonts:ro
+   ```
+
+## Systemd服务配置示例
+
+如果使用systemd管理服务，可以在服务文件中设置环境变量：
+
+```ini
+[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系统字体包**
+   ```bash
+   # 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. 相关日志：包含 `"查找字体文件"` 和 `"字体文件"` 的日志条目
+