Excel2Pic API Service

这是一个轻量级的 Excel 转图片 API 服务，专为插件化部署设计。 它使用 FastAPI 构建，底层基于 openpyxl 和 Pillow (PIL) 实现高效的表格渲染，无需依赖任何 Office 组件或浏览器环境。

特性

• 🚀 高性能：基于 FastAPI，原生异步支持。
• 📦 极轻量：Docker 镜像体积 < 200MB。
• 🎨 纯 Python 实现：无需 LibreOffice 或 Headless Chrome。
• 🔠 中文支持：内置宋体和黑体支持，解决中文乱码问题。
• 🐳 一键部署：提供 Dockerfile 和一键部署脚本。

目录结构

excel2pic/
├── app.py              # FastAPI 应用入口
├── core/               # 核心逻辑模块
│   ├── renderer.py     # 渲染引擎 (ExcelRenderer)
│   └── __init__.py
├── assets/             # 静态资源 (字体文件)
│   ├── simsun.ttc      # 宋体
│   └── simhei.ttf      # 黑体
├── tests/              # 单元测试
├── deploy.sh           # 一键部署脚本
├── Dockerfile          # Docker 构建文件
└── requirements.txt    # 项目依赖

快速开始

1. 本地运行

前置条件: Python 3.12+

# 1. 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

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

# 3. 启动服务
uvicorn app:app --reload

2. Docker 部署

# 赋予执行权限
chmod +x deploy.sh

# 一键构建并启动
./deploy.sh

API 文档

启动服务后，访问 http://localhost:8000/docs 查看交互式 Swagger 文档。

核心接口

POST /api/v1/convert

将上传的 Excel 文件转换为 PNG 图片。

• 参数:

  • file: (Required) Excel 文件 (.xlsx / .xls)
  • sheet_name: (Optional) 指定要转换的工作表名称，默认为活动工作表。

• 响应:

  • Content-Type: image/png (直接返回图片二进制流)

示例调用 (cURL):

curl -X POST "http://localhost:8000/api/v1/convert" \
  -F "file=@/path/to/data.xlsx" \
  -F "sheet_name=Sheet1" \
  --output result.png

维护指南

添加新字体

1. 将 .ttf 或 .ttc 文件放入 assets/ 目录。
2. 修改 core/renderer.py 中的 __init__ 默认参数，或在初始化 ExcelRenderer 时传入路径。
3. 重新构建 Docker 镜像。

运行测试

export PYTHONPATH=$PYTHONPATH:.
pytest tests/