万朱浩 / Venue-Ops

Go to a project
Toggle navigation Toggle navigation pinning
马一丁
69ba0f22 1 parent be1fe539

Update the Dependency Handling Scheme

Inline Side-by-side
Showing 4 changed files with 100 additions and 14 deletions
@@ -392,23 +392,41 @@ uv pip install -r requirements.txt @@ -392,23 +392,41 @@ uv pip install -r requirements.txt
392 392
393 ### 3. 安装 PDF 导出所需系统依赖（可选） 393 ### 3. 安装 PDF 导出所需系统依赖（可选）
394 394
395 -> ⚠️ **注意**：如果您需要使用 PDF 导出功能，请按照以下步骤安装系统依赖。如果不需要 PDF 导出功能，可以跳过此步骤，系统其他功能不受影响。 395 +> ⚠️ **注意**：如果您需要使用 PDF 导出功能，请按照以下步骤安装系统依赖。如果不需要 PDF 导出功能，可以跳过此步骤，系统其他功能不受影响。在此部分操作之前，建议重新运行“2. 安装依赖包”的代码。
396 396
397 <details> 397 <details>
398 <summary><b>📦 macOS 系统安装步骤</b></summary> 398 <summary><b>📦 macOS 系统安装步骤</b></summary>
399 399
  400 +> 🔴 **重要提示**：macOS 用户必须完成以下**两个步骤**，缺一不可！仅安装系统依赖而不设置环境变量会导致 `cannot load library 'libgobject-2.0-0'` 错误。
  401 +
400 ```bash 402 ```bash
401 -# 1. 安装系统依赖（在宿主机上执行） 403 +# 步骤 1: 安装系统依赖
402 brew install pango gdk-pixbuf libffi 404 brew install pango gdk-pixbuf libffi
403 405
404 -# 2. 设置环境变量（必需） 406 +# 步骤 2: 设置环境变量（⚠️ 必须执行！）
  407 +# 方法一：临时设置（仅当前终端会话有效）
405 export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH 408 export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH
406 409
407 -# 或永久添加到 ~/.zshrc 410 +# 方法二：永久设置（推荐）
408 echo 'export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH' >> ~/.zshrc 411 echo 'export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH' >> ~/.zshrc
409 source ~/.zshrc 412 source ~/.zshrc
410 ``` 413 ```
411 414
  415 +**验证安装**：
  416 +
  417 +```bash
  418 +# 测试 PDF 依赖是否正确配置
  419 +python -m ReportEngine.utils.dependency_check
  420 +# 应该显示：✓ Pango 依赖检测通过，PDF 导出功能可用
  421 +```
  422 +
  423 +**常见问题**：
  424 +
  425 +- 如果仍然提示找不到库，请确保：
  426 + 1. 已执行 `source ~/.zshrc` 重新加载配置
  427 + 2. 在新终端中运行应用（确保环境变量已生效）
  428 + 3. 使用 `echo $DYLD_LIBRARY_PATH` 验证环境变量已设置
  429 +
412 </details> 430 </details>
413 431
414 <details> 432 <details>
@@ -1047,8 +1047,9 @@ def export_pdf(task_id: str): @@ -1047,8 +1047,9 @@ def export_pdf(task_id: str):
1047 if not pango_available: 1047 if not pango_available:
1048 return jsonify({ 1048 return jsonify({
1049 'success': False, 1049 'success': False,
1050 - 'error': 'PDF 导出功能不可用：缺少 Pango 系统依赖',  
1051 - 'details': '请查看 requirements.txt 文件中的 "===== PDF生成 =====" 部分了解如何安装 Pango', 1050 + 'error': 'PDF 导出功能不可用：缺少系统依赖',
  1051 + 'details': '请查看根目录 README.md 第393行「PDF 导出依赖」部分了解如何安装依赖',
  1052 + 'help_url': 'https://github.com/666ghj/BettaFish#3-安装-pdf-导出所需系统依赖可选',
1052 'system_message': pango_message 1053 'system_message': pango_message
1053 }), 503 1054 }), 503
1054 1055
@@ -1135,8 +1136,9 @@ def export_pdf_from_ir(): @@ -1135,8 +1136,9 @@ def export_pdf_from_ir():
1135 if not pango_available: 1136 if not pango_available:
1136 return jsonify({ 1137 return jsonify({
1137 'success': False, 1138 'success': False,
1138 - 'error': 'PDF 导出功能不可用：缺少 Pango 系统依赖',  
1139 - 'details': '请查看 requirements.txt 文件中的 "===== PDF生成 =====" 部分了解如何安装 Pango', 1139 + 'error': 'PDF 导出功能不可用：缺少系统依赖',
  1140 + 'details': '请查看根目录 README.md 第393行「PDF 导出依赖」部分了解如何安装依赖',
  1141 + 'help_url': 'https://github.com/666ghj/BettaFish#3-安装-pdf-导出所需系统依赖可选',
1140 'system_message': pango_message 1142 'system_message': pango_message
1141 }), 503 1143 }), 503
1142 1144
@@ -16,9 +16,19 @@ try: @@ -16,9 +16,19 @@ try:
16 from weasyprint import HTML, CSS 16 from weasyprint import HTML, CSS
17 from weasyprint.text.fonts import FontConfiguration 17 from weasyprint.text.fonts import FontConfiguration
18 WEASYPRINT_AVAILABLE = True 18 WEASYPRINT_AVAILABLE = True
19 -except ImportError: 19 +except (ImportError, OSError) as e:
20 WEASYPRINT_AVAILABLE = False 20 WEASYPRINT_AVAILABLE = False
21 - logger.warning("WeasyPrint未安装，PDF导出功能将不可用") 21 + # 判断错误类型以提供更友好的提示
  22 + if isinstance(e, OSError):
  23 + logger.warning(
  24 + "PDF 导出依赖缺失（系统库未安装或环境变量未设置），"
  25 + "PDF 导出功能将不可用。其他功能不受影响。"
  26 + )
  27 + else:
  28 + logger.warning("WeasyPrint未安装，PDF导出功能将不可用")
  29 +except Exception as e:
  30 + WEASYPRINT_AVAILABLE = False
  31 + logger.warning(f"WeasyPrint 加载失败: {e}，PDF导出功能将不可用")
22 32
23 from .html_renderer import HTMLRenderer 33 from .html_renderer import HTMLRenderer
24 from .pdf_layout_optimizer import PDFLayoutOptimizer, PDFLayoutConfig 34 from .pdf_layout_optimizer import PDFLayoutOptimizer, PDFLayoutConfig
@@ -3,9 +3,57 @@ @@ -3,9 +3,57 @@
3 用于检测 PDF 生成所需的系统依赖 3 用于检测 PDF 生成所需的系统依赖
4 """ 4 """
5 import sys 5 import sys
  6 +import platform
6 from loguru import logger 7 from loguru import logger
7 8
8 9
  10 +def _get_platform_specific_instructions():
  11 + """
  12 + 获取针对当前平台的安装说明
  13 +
  14 + Returns:
  15 + str: 平台特定的安装说明
  16 + """
  17 + system = platform.system()
  18 +
  19 + if system == "Darwin": # macOS
  20 + return (
  21 + "║ 🍎 macOS 系统解决方案： ║\n"
  22 + "║ ║\n"
  23 + "║ 1. 安装系统依赖： ║\n"
  24 + "║ brew install pango gdk-pixbuf libffi ║\n"
  25 + "║ ║\n"
  26 + "║ 2. 设置环境变量（重要！）： ║\n"
  27 + "║ export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH ║\n"
  28 + "║ ║\n"
  29 + "║ 3. 永久生效（推荐）： ║\n"
  30 + "║ echo 'export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH' >> ~/.zshrc ║\n"
  31 + "║ source ~/.zshrc ║\n"
  32 + )
  33 + elif system == "Linux":
  34 + return (
  35 + "║ 🐧 Linux 系统解决方案： ║\n"
  36 + "║ ║\n"
  37 + "║ Ubuntu/Debian: ║\n"
  38 + "║ sudo apt-get install libpango-1.0-0 libpangoft2-1.0-0 \\ ║\n"
  39 + "║ libgdk-pixbuf2.0-0 libffi-dev libcairo2 ║\n"
  40 + "║ ║\n"
  41 + "║ CentOS/RHEL: ║\n"
  42 + "║ sudo yum install pango gdk-pixbuf2 libffi-devel cairo ║\n"
  43 + )
  44 + elif system == "Windows":
  45 + return (
  46 + "║ 🪟 Windows 系统解决方案： ║\n"
  47 + "║ ║\n"
  48 + "║ 下载并安装 GTK3 Runtime： ║\n"
  49 + "║ https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases ║\n"
  50 + )
  51 + else:
  52 + return (
  53 + "║ 请查看 README.md 了解您系统的安装方法 ║\n"
  54 + )
  55 +
  56 +
9 def check_pango_available(): 57 def check_pango_available():
10 """ 58 """
11 检测 Pango 库是否可用 59 检测 Pango 库是否可用
@@ -25,19 +73,27 @@ def check_pango_available(): @@ -25,19 +73,27 @@ def check_pango_available():
25 except OSError as e: 73 except OSError as e:
26 # Pango 库未安装或无法加载 74 # Pango 库未安装或无法加载
27 error_msg = str(e) 75 error_msg = str(e)
28 - if 'pango' in error_msg.lower(): 76 + platform_instructions = _get_platform_specific_instructions()
  77 +
  78 + if 'gobject' in error_msg.lower() or 'pango' in error_msg.lower() or 'gdk' in error_msg.lower():
29 return False, ( 79 return False, (
30 "╔════════════════════════════════════════════════════════════════╗\n" 80 "╔════════════════════════════════════════════════════════════════╗\n"
31 - "║ ⚠️ Pango 依赖未安装或无法加载 ║\n" 81 + "║ ⚠️ PDF 导出依赖缺失 ║\n"
32 "║ ║\n" 82 "║ ║\n"
33 "║ 📄 PDF 导出功能将不可用（其他功能不受影响） ║\n" 83 "║ 📄 PDF 导出功能将不可用（其他功能不受影响） ║\n"
34 - "║ 📖 详细安装说明请查看：根目录下的 README.md ║\n" 84 + "║ ║\n"
  85 + f"{platform_instructions}"
  86 + "║ ║\n"
  87 + "║ 📖 完整文档：根目录 README.md 第393行「PDF 导出依赖」 ║\n"
35 "╚════════════════════════════════════════════════════════════════╝" 88 "╚════════════════════════════════════════════════════════════════╝"
36 ) 89 )
37 return False, f"⚠ PDF 依赖加载失败: {error_msg}" 90 return False, f"⚠ PDF 依赖加载失败: {error_msg}"
38 except ImportError as e: 91 except ImportError as e:
39 # weasyprint 未安装 92 # weasyprint 未安装
40 - return False, f"⚠ WeasyPrint 未安装: {e}" 93 + return False, (
  94 + "⚠ WeasyPrint 未安装\n"
  95 + "解决方法: pip install weasyprint"
  96 + )
41 except Exception as e: 97 except Exception as e:
42 # 其他未知错误 98 # 其他未知错误
43 return False, f"⚠ PDF 依赖检测失败: {e}" 99 return False, f"⚠ PDF 依赖检测失败: {e}"