新增錯誤排查與支援文件,提供常見問題解決方案;新增開發與貢獻指南,說明專案結構與開發流程;新增授權說明文件,詳述AGPL-3.0授權條款及第三方元件使用情況。

This commit is contained in:
Your Name 2026-01-25 16:09:58 +08:00
parent 11d751250b
commit caecb2e001
13 changed files with 3269 additions and 369 deletions

154
docs/00-專案總覽.md Normal file
View file

@ -0,0 +1,154 @@
# 專案總覽
ConvertX-CN 是一個**開箱即用的全功能檔案轉換服務**,基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) 衍生開發,專注於**中文使用者體驗優化**與**進階 PDF 處理能力**。
---
## 目錄
- [專案定位與目標](#專案定位與目標)
- [ConvertX-CN 與原始 ConvertX 的差異](#convertx-cn-與原始-convertx-的差異)
- [支援格式總覽](#支援格式總覽)
- [版本選擇](#版本選擇)
- [相關文件](#相關文件)
---
## 專案定位與目標
### 🎯 核心目標
1. **開箱即用**:一個 Docker 命令5 分鐘內完成部署
2. **中文優化**:內建中日韓字型與 OCR告別亂碼問題
3. **全格式支援**:文件、圖片、影音、電子書,一站式轉換
4. **PDF 進階處理**:翻譯(保留公式)、智能擷取(保留表格、圖片)
### 🌟 專案特色
| 特色 | 說明 |
|------|------|
| 📁 **1000+ 格式** | 文件、圖片、影音、電子書一次搞定 |
| 🔧 **25+ 引擎** | LibreOffice、FFmpeg、Pandoc 全到位 |
| 🈶 **中文優化** | 內建中日韓字型與 OCR告別亂碼 |
| 🌐 **65 種語言** | 跨國團隊無障礙使用 |
| 📊 **PDF 翻譯** | PDFMathTranslate + BabelDOC 雙引擎 |
| 📄 **PDF 轉 MD** | MinerU 智能擷取(保留表格、公式、圖片) |
---
## ConvertX-CN 與原始 ConvertX 的差異
| 項目 | 原始 ConvertX | ConvertX-CN |
|------|--------------|-------------|
| **語言支援** | 英文介面為主 | 65 種語言介面,中文優化 |
| **字型支援** | 基本字型 | 內建中日韓完整字型集 |
| **OCR 語言** | 需手動安裝 | 預裝 7 種常用語言Full 版 65 種) |
| **PDF 翻譯** | ❌ 不支援 | ✅ PDFMathTranslate + BabelDOC |
| **PDF 轉 MD** | ❌ 不支援 | ✅ MinerU 智能擷取 |
| **BabelDOC** | ❌ 不支援 | ✅ 進階 PDF 處理 |
| **Docker 大小** | 較小 | 較大(功能更完整) |
| **維護者** | C4illin | pi-docket |
### 新增功能清單
- ✅ **PDFMathTranslate**:翻譯 PDF 並保留數學公式與排版
- ✅ **BabelDOC**:進階 PDF 翻譯與轉換
- ✅ **MinerU**PDF 轉 Markdown智能擷取表格、公式、圖片
- ✅ **OCRmyPDF**PDF OCR 文字辨識
- ✅ **完整 CJK 字型**:思源黑體、思源宋體
- ✅ **65 種介面語言**:自動偵測或手動切換
---
## 支援格式總覽
### 按類型分類
| 類型 | 轉換器 | 支援格式數 |
|------|--------|-----------|
| 🎬 **影音** | FFmpeg | 400+ |
| 🖼️ **圖片** | ImageMagick, GraphicsMagick, Vips | 300+ |
| 📄 **文件** | LibreOffice, Pandoc | 160+ |
| 📚 **電子書** | Calibre | 50+ |
| ✏️ **向量圖** | Inkscape, Potrace, VTracer | 40+ |
| 📊 **PDF 處理** | PDFMathTranslate, BabelDOC, MinerU, OCRmyPDF | 30+ |
| 🎮 **3D 模型** | Assimp | 100+ |
| 📋 **資料檔案** | Dasel | 10+ |
### 完整轉換器列表
| 轉換器 | 用途 | 輸入格式 | 輸出格式 |
|--------|------|----------|----------|
| FFmpeg | 影音 | 472 | 199 |
| ImageMagick | 圖片 | 253 | 183 |
| GraphicsMagick | 圖片 | 167 | 130 |
| Vips | 高效圖片處理 | 45 | 23 |
| LibreOffice | 文件 | 41 | 22 |
| Pandoc | 文件 | 43 | 65 |
| Calibre | 電子書 | 31 | 21 |
| Inkscape | 向量圖形 | 7 | 17 |
| libjxl | JPEG XL | 11 | 11 |
| libheif | HEIF/HEIC | 11 | 3 |
| Assimp | 3D 模型 | 77 | 23 |
| Potrace | 點陣轉向量 | 4 | 11 |
| VTracer | 點陣轉向量 | 8 | 1 |
| resvg | SVG 渲染 | 1 | 1 |
| XeLaTeX | LaTeX | 2 | 1 |
| dvisvgm | 向量圖形 | 4 | 2 |
| Dasel | 資料檔案 | 5 | 4 |
| msgconvert | Outlook | 1 | 1 |
| VCF to CSV | 聯絡人 | 1 | 1 |
| Markitdown | 文件轉 MD | 6 | 1 |
| MinerU | PDF → MD | 7 | 2 |
| PDFMathTranslate | PDF 翻譯 | 1 | 15 |
| BabelDOC | PDF 翻譯 | 1 | 45 |
| OCRmyPDF | PDF OCR | 1 | 8 |
| deark | 解包/解析 | 100+ | 1 |
---
## 版本選擇
ConvertX-CN 提供三個版本,滿足不同需求:
| 特性 | Lite 版 | 一般版(推薦) | Full 版 |
|------|---------|---------------|---------|
| **Image 大小** | ~3 GB | ~7 GB | ~15 GB |
| **部署速度** | 最快 | 中等 | 較慢 |
| **適用對象** | 輕量使用者 | 一般使用者 | 進階/多語言 |
| **基本轉檔** | ✅ | ✅ | ✅ |
| **OCR7語言** | ❌ | ✅ | ✅ |
| **PDF 翻譯** | ❌ | ✅ | ✅ |
| **MinerU AI** | ❌ | ✅ | ✅ |
| **OCR65語言** | ❌ | ❌ | ✅ |
| **完整 TexLive** | ❌ | ❌ | ✅ |
### Docker Tag 說明
| Tag | 說明 |
|-----|------|
| `latest` | 一般版最新穩定版 |
| `latest-lite` | Lite 版最新穩定版 |
| `latest-full` | Full 版最新穩定版 |
| `0.1.16` | 一般版指定版本 |
| `0.1.16-lite` | Lite 版指定版本 |
| `0.1.16-full` | Full 版指定版本 |
---
## 相關文件
| 文件 | 說明 |
|------|------|
| [01-快速開始](01-快速開始.md) | 5 分鐘內完成部署 |
| [02-部署指南](02-部署指南.md) | 詳細部署設定 |
| [03-環境變數與設定](03-環境變數與設定.md) | 所有可用設定 |
| [04-功能總覽](04-功能總覽.md) | 轉換功能詳細說明 |
| [05-API文件](05-API文件.md) | REST & GraphQL API |
| [06-錯誤排查與支援](06-錯誤排查與支援.md) | 常見問題解決 |
| [07-開發與貢獻指南](07-開發與貢獻指南.md) | 開發者指南 |
| [08-授權說明](08-授權說明.md) | AGPL-3.0 授權 |
---
[⬆️ 回到頂部](#專案總覽)