基于 ASP.NET Core 和 Python 的 PDF 转 Word 工具开发与部署实践
在文档处理场景中,常遇到 PDF 无法直接编辑、内容修改导致重排耗时、表格复制错位等问题。本文介绍了一个基于 ASP.NET Core 和 Python 实现的 PDF 转 Word 工具的开发与部署经验。
一、需求背景
- PDF 文件无法直接编辑
- 修改少量内容需重新排版
- 表格和格式在转换过程中容易错乱
二、项目实施踩坑总结
(一)Python 调用与 IIS 部署
- 问题:本地能跑,部署到 IIS 服务器后 Python 无法执行或路径找不到
- 原因:
- Python.exe 路径写死在本地
- IIS 应用程序池权限不足
- 解决方案:
使用配置文件 (appsettings.json) 或环境变量指定 Python.exe 路径,确保应用池有执行权限
(二)支付系统与用户次数管理
- 问题:
- Notify 回调中将流水号误当 AccountId 存入数据库,导致查询失败
- 依赖注入生命周期冲突,服务取不到最新状态
- 解决方案:
修正 AccountId 与订单流水号的对应关系。在 Controller 内使用 IServiceScopeFactory.CreateScope() 创建服务范围,确保生命周期正确
(三)文件大小限制与 Kestrel 配置
- 问题:大文件上传时失败
- 原因:ASP.NET Core 默认上传限制较小,超出阈值后服务器无法处理
- 解决方案:
修改 Kestrel 配置:options.Limits.MaxRequestBodySize = 104857600
修改 FormOptions:options.MultipartBodyLengthLimit = 104857600
(四)异步处理与生命周期冲突
- 问题:
- 在 Controller 中调用异步服务出现'对象为空'和'生命周期冲突'
- 原因:
- 直接注入 Scoped 服务到 Singleton 或后台任务
- 解决方案:
- 使用
IServiceScopeFactory.CreateScope() 在后台任务中创建服务实例,使用 using 创建临时作用域
三、技术栈
后端核心
| 技术 | 用途 | 说明 |
|---|
| ASP.NET Core 8 | Web API 框架 | 提供控制器、路由、JWT 授权、文件上传接口 |
| Entity Framework Core | 数据访问 | 与 SQL Server 对接,实现账户、文件映射、充值记录 CRUD |
| SQL Server | 数据库 | 存储账户、文件映射、充值记录、日志 |
| IOptionsMonitor / Configuration | 配置管理 | 管理 Python 路径、支付配置、速率限制等 |
身份认证与安全
| 技术 | 用途 | 说明 |
|---|
| JWT (JSON Web Token) | 用户认证 | 保护上传/下载接口,确保每个请求有用户身份 |
| Authorization Attributes | 权限控制 | [Authorize] 控制 API 权限 |
| Rate Limiting Middleware | 频率控制 | 限制请求频率,保护接口安全 |
文件处理
| 技术 | 用途 | 说明 |
|---|
| Python 3.12及相关的库:pdf2docx | PDF → Word 转换 | 使用自定义脚本 pdf_to_word.py 处理文件转换 |
| ConcurrentQueue + SemaphoreSlim | 队列处理 | 实现后台单任务队列,避免多用户同时处理冲突 |
| IWebHostEnvironment | 文件路径管理 | 管理上传目录 /uploads 和静态文件访问 |
支付与充值系统
| 技术 | 用途 | 说明 |
|---|
| 易支付(YiPay) | 支付通道 | 接收用户支付,支持异步通知 |
| TopUpService / Strategy 模式 | 充值管理 | 控制用户使用次数、减少重复逻辑 |
| 日志文件 | 调试与监控 | logs/debug.log 记录支付和文件操作状态 |
开发工具与环境
| 技术 | 用途 | 说明 |
|---|
| Visual Studio 2022 / VS Code | 开发 | 后端开发、调试、迁移数据库 |
| IIS / 云服务器 | 部署 | 托管 ASP.NET Core + Python 环境 |
| Swagger | API 文档 | 方便测试上传、下载接口和 JWT 调用 |
扩展与中间件
| 技术 | 用途 | 说明 |
|---|
| FileCleanupService / RateLimitCleanupService | 后台服务 | 清理过期文件和过期速率限制记录 |
| RequestDurationMiddleware | 性能监控 | 记录每次请求耗时,便于优化 |
四、部署注意事项
- 需要手动创建 logs、uploads 文件夹,并在安全属性中为 IIS 用户设置控制权限;
- 同时还需要手动复制
pdf_to_word.py 文件到项目目录。
配置文件说明
YiPayConfig:对接易支付平台
Jwt:生成不低于 32 位的 key
PythonConfig:注意本地环境和服务器环境 python 解释器的位置
MailSendServiceConfig:申请 SMTP 服务
权限分配脚本
1. 给应用池用户访问 Python 权限
假设 Python 安装路径:
C:\Users\Administrator\AppData\Local\Programs\Python\Python312
在 PowerShell(以管理员身份)执行:
$pythonPath = "C:\Users\Administrator\AppData\Local\Programs\Python\Python312"
$acl = Get-Acl $pythonPath
$permission = "IIS AppPool\<应用池名称>","ReadAndExecute","ContainerInherit,ObjectInherit","None","Allow"
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule $permission
$acl.AddAccessRule($rule)
Set-Acl $pythonPath $acl
这会给 IIS 应用池身份用户读取和执行 Python 的权限。
2. 给 uploads 文件夹权限
假设 uploads 文件夹在:
C:\inetpub\PDFtoWord\uploads
同样用 PowerShell 给应用池写入权限:
$uploadsPath = "C:\inetpub\PDFtoWord\uploads"
$acl = Get-Acl $uploadsPath
$permission = "IIS AppPool\<应用池名称>","Modify","ContainerInherit,ObjectInherit","None","Allow"
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule $permission
$acl.AddAccessRule($rule)
Set-Acl $uploadsPath $acl
注意:如果 uploads 文件夹不存在,需要先手动创建。
五、开发建议
- 做刚需工具:如文档处理、图片处理、格式转换。
- 不要一开始做复杂系统:聚焦核心功能,如 PDF → Word。
- 尽快上线:能用就上线,快速迭代验证。