PDF 黑白转换服务

基于 Python 3.12 + FastAPI 的 Web 服务，支持上传 PDF 文件并将其转换为黑白/灰度版本，提供多档灰度级别选择和实时预览功能。

功能特性

• 🎯 PDF 转换: 将彩色 PDF 转换为黑白/灰度版本
• 📊 多档灰度: 支持 1-4 档灰度级别选择
• 👀 实时预览: 支持转换前后对比预览
• 📄 分页浏览: 支持多页 PDF 的翻页查看
• 🔍 缩放控制: 预览图片缩放功能
• 📱 响应式设计: 支持桌面和移动设备
• 🐳 Docker 支持: 提供 Docker 容器化部署

灰度档位说明

档位	色阶数	灰度值	描述
1 档	2	0, 255	纯黑白（二值化）
2 档	3	0, 127, 255	黑白 + 50% 灰
3 档	4	0, 85, 170, 255	黑白 + 33%/66% 灰
4 档	5	0, 64, 127, 191, 255	黑白 + 25%/50%/75% 灰

技术栈

• 后端: Python 3.12 + FastAPI
• 前端: HTML + CSS + JavaScript (原生)
• PDF 处理: PyMuPDF (fitz) + Pillow
• 容器化: Docker + Docker Compose
• 开发环境: Conda (fta-xrun-chat-bot)

快速开始

使用 Docker (推荐)

# 克隆项目
git clone <repository-url>
cd pdf-convert

# 启动服务
./start.sh

# 访问服务
open http://localhost:8000

本地开发

# 激活 Conda 环境
conda activate fta-xrun-chat-bot

# 启动开发服务器
./dev.sh

# 或者手动启动
pip install -r requirements.txt
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

API 接口

PDF 转换

POST /api/convert
Content-Type: multipart/form-data

参数:
- file: PDF 文件 (最大 50MB)
- gray_levels: 灰度档位 (1-4, 默认: 2)

响应:
{
  "task_id": "uuid",
  "status": "processing",
  "message": "PDF 转换已开始"
}

查询状态

GET /api/status/{task_id}

响应:
{
  "task_id": "uuid",
  "status": "completed",  // processing, converting, completed, error
  "progress": 100,        // 0-100
  "page_count": 10,
  "error": null
}

下载结果

GET /api/download/{task_id}

响应: 转换后的 PDF 文件

页面预览

GET /api/preview/{task_id}/{page}?preview_type=original|converted

响应: 页面图片 (PNG)

项目结构

pdf-convert/
├── SPEC.md                 # 项目规格说明
├── README.md               # 项目说明文档
├── requirements.txt        # Python 依赖
├── Dockerfile              # Docker 镜像构建文件
├── docker-compose.yml      # Docker Compose 配置
├── start.sh                # Docker 启动脚本
├── dev.sh                  # 本地开发启动脚本
├── app/
│   ├── __init__.py
│   ├── main.py             # FastAPI 应用入口
│   ├── api/
│   │   └── __init__.py
│   ├── services/
│   │   ├── __init__.py
│   │   └── pdf_converter.py # PDF 转换核心逻辑
│   ├── static/
│   │   ├── css/
│   │   │   └── style.css   # 样式文件
│   │   └── js/
│   │       └── app.js      # 前端交互逻辑
│   └── templates/
│       └── index.html      # Web 页面模板
├── uploads/                # 上传文件临时存储
└── outputs/                # 转换结果临时存储

性能要求

• ✅ 单页 PDF 转换时间: < 2 秒
• ✅ 支持最大 PDF 页数: 100 页
• ✅ 支持最大文件大小: 50 MB
• ✅ 并发处理能力: 10 个同时转换任务

安全特性

• 🔒 文件类型验证（仅接受 PDF）
• 📏 文件大小限制
• 🧹 临时文件定期清理（1小时后自动删除）
• 🛡️ 防止路径遍历攻击

开发说明

环境要求

• Python 3.12+
• Node.js (可选，用于前端开发工具)
• Docker (用于容器化部署)

本地开发

# 安装依赖
pip install -r requirements.txt

# 启动开发服务器
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# API 文档
open http://localhost:8000/docs

测试

# 运行测试 (如果存在)
python -m pytest

# 代码格式检查
black app/
flake8 app/

部署说明

Docker 部署

# 构建镜像
docker build -t pdf-convert .

# 运行容器
docker run -p 8000:8000 -v $(pwd)/uploads:/app/uploads -v $(pwd)/outputs:/app/outputs pdf-convert

# 使用 docker-compose
docker-compose up -d

生产环境

建议使用以下配置：

• 反向代理: Nginx
• 进程管理: Gunicorn + Uvicorn
• 任务队列: Celery + Redis (用于大规模并发)

常见问题

1. PDF 转换失败

• 检查文件是否为有效的 PDF 格式
• 确认文件大小不超过 50MB
• 确认页数不超过 100 页

2. 预览图片显示异常

• 检查网络连接
• 确认转换任务已完成
• 尝试刷新页面

3. Docker 启动失败

• 确认 Docker 服务已启动
• 检查端口 8000 是否被占用
• 查看容器日志: docker-compose logs

版本信息

• 版本: 1.0.0
• 创建日期: 2024-12-17
• Python 版本: 3.12
• 许可证: MIT

贡献指南

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

联系方式

如有问题或建议，请通过以下方式联系：

• 项目 Issues: GitHub Issues
• 邮箱: your-email@example.com

---

🎉 感谢使用 PDF 黑白转换服务！