98 lines
2.5 KiB
Markdown
Executable File
98 lines
2.5 KiB
Markdown
Executable File
# 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+
|
||
|
||
```bash
|
||
# 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 部署
|
||
|
||
```bash
|
||
# 赋予执行权限
|
||
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)**:
|
||
|
||
```bash
|
||
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 镜像。
|
||
|
||
### 运行测试
|
||
```bash
|
||
export PYTHONPATH=$PYTHONPATH:.
|
||
pytest tests/
|
||
```
|