About InvoiceOCR

基于腾讯云OCR API的发票识别与管理系统，支持自动识别发票数据、图像处理、项目分类和数据导出功能。

Published by

chiupam

Visit View Profile

InvoiceOCR

View on GitHub

🧾 发票OCR管理系统

一个基于Flask框架开发的智能发票管理系统，支持发票图片上传与OCR识别，提供发票信息管理、数据导出及统计分析等功能。系统采用腾讯云OCR API进行发票文字识别，实现发票信息的智能提取与处理。

✨ 功能特点

📤 发票图片和PDF文件上传与预览
✏️ 支持手动创建发票，无需上传图片
🔍 基于腾讯云OCR API的发票文字识别
📄 支持直接识别PDF发票第一页
💾 发票数据结构化处理与存储
📋 发票列表展示与多维度排序
🔎 发票详情查看与编辑
📁 项目分类管理功能
👁️ 发票图片与PDF预览功能
📊 发票数据导出（CSV、Excel格式）
📈 发票统计分析与图表展示
📱 响应式网页设计，适配多种设备
⏱️ 定时任务自动清理过期文件
🔐 用户登录认证（bcrypt加密 + 仅密码登录）
🛡️ 两步验证（TOTP，兼容Google Authenticator）
🔒 账户锁定保护（5次失败锁定15分钟 + 倒计时）
🚫 CSRF全局防护 + 请求限流
📝 安全审计日志

🔄 最近更新

最新版本 v1.4 (2026.04.14)

🔐 用户认证与安全体系

✅ 新增完整的用户登录认证系统（Flask-Login + bcrypt）
✅ 新增首次启动密码设置流程，无需用户名，仅需设置密码
✅ 新增 TOTP 两步验证（MFA），兼容 Google Authenticator
✅ 新增账户锁定机制：5次密码错误锁定15分钟，锁定期间禁用表单+倒计时
✅ 新增 Flask-Limiter 请求限流（GET 60/min, POST 20/min）
✅ 新增全局 CSRF 防护（Flask-WTF CSRFProtect）
✅ 新增会话安全配置（HttpOnly + Secure + SameSite=Lax）
✅ 新增安全审计日志（data/logs/security.log）

🛡️ CLI 管理工具

✅ 新增 flask unlock-admin 应急解锁命令
✅ 新增 flask reset-account 账户初始化重置命令
✅ 加固 flask create-admin 命令，限制仅无用户时可执行

🔒 安全增强

✅ 密码存储升级为 bcrypt 算法（rounds=12），兼容旧 pbkdf2 自动迁移
✅ Settings 页面 API 密钥脱敏显示（password 类型 + 显示/隐藏切换）
✅ 所有表单和 AJAX 请求添加 CSRF Token
✅ 新增 429 限流友好中文提示页面
✅ 登录页锁定状态：禁用密码输入 + 实时倒计时 + 自动刷新解锁

📁 项目结构调整

✅ 新增 app/auth.py 认证蓝图（登录/设置/MFA/密码管理）
✅ 新增 app/templates/auth/ 认证模板目录（8个模板文件）
✅ 新增 app/templates/errors/429.html 限流错误页面
✅ 新增 data/logs/ 安全审计日志目录

查看完整的更新历史请参考 CHANGELOG.md

📅 未来计划

💺 预计将支持12306车票及航班票次的识别

🚀 快速开始

🐳 使用 Docker

1️⃣ 准备工作

确保已安装Docker和Docker Compose：

2️⃣ 部署步骤

(1) 克隆仓库并进入项目目录

git clone https://github.com/chiupam/invoiceOCR.git
cd invoiceOCR

(2) 创建环境变量文件（可选）

cp .env.example .env
# 仅需配置基本环境变量，API密钥通过Web界面配置

(3) 构建并启动容器

docker-compose up -d

(4) 访问应用

浏览器访问 http://localhost:5001 即可使用应用。首次访问时，系统会引导您设置访问密码，登录后再配置腾讯云API密钥。

3️⃣ 常用Docker命令

查看容器日志

docker-compose logs -f

停止容器

docker-compose down

重新构建（更新代码后）

docker-compose up -d --build

4️⃣ 使用预构建的Docker镜像

我们提供了多个镜像源以适应不同地区用户的需求：

🔵 Docker Hub (推荐)

# 拉取最新版本
docker pull chiupam/invoiceocr:latest

# 拉取特定版本
docker pull chiupam/invoiceocr:v1.3

# 运行容器
docker run -d -p 5001:5001 -v $(pwd)/data:/app/data --name invoice_ocr chiupam/invoiceocr:latest

🔷 GitHub Container Registry

# 拉取最新版本
docker pull ghcr.io/chiupam/invoiceocr:latest

# 拉取特定版本
docker pull ghcr.io/chiupam/invoiceocr:v1.3

# 运行容器
docker run -d -p 5001:5001 -v $(pwd)/data:/app/data --name invoice_ocr ghcr.io/chiupam/invoiceocr:latest

💾 数据持久化

上面的命令使用了卷挂载 -v $(pwd)/data:/app/data 来保证数据在容器重启后不会丢失。您可以根据需要修改本地路径。

💻 本地部署

1️⃣ 克隆项目

git clone https://github.com/chiupam/invoiceOCR.git
cd invoiceOCR

2️⃣ 创建并激活虚拟环境

# 创建虚拟环境
python3 -m venv .venv

# 激活虚拟环境 (Linux/Mac)
source .venv/bin/activate

# 激活虚拟环境 (Windows)
# .venv\Scripts\activate

激活后，命令行前面会出现(.venv)前缀，表示当前处于虚拟环境中。后续所有命令都应在此环境中执行。

3️⃣ 安装依赖

# 确保在虚拟环境中执行
(.venv) pip3 install -r requirements.txt

4️⃣ 基本环境配置

创建 .env 文件（可以复制 .env.example 并根据需要修改）：

# 复制示例配置
(.venv) cp .env.example .env

注意：与旧版本不同，API密钥现在不需要在环境变量中配置，而是在Web界面中设置。

5️⃣ 运行应用

(.venv) python3 run.py

应用将在 http://127.0.0.1:5001/ 运行。首次运行时，系统会自动初始化数据库并引导您完成必要的设置。

6️⃣ 首次访问配置

首次访问系统时，会自动跳转到密码设置页面：

设置访问密码（至少8位，需包含字母和数字）
设置成功后自动登录，进入系统首页
前往「系统设置」配置腾讯云OCR API密钥（SecretId和SecretKey）
- 可在腾讯云控制台获取
- 需要开通腾讯云OCR服务（增值税发票识别）

配置完成后，即可开始使用系统的所有功能。

7️⃣ 退出虚拟环境（完成使用后）

(.venv) deactivate

❓ 常见问题解决

依赖安装失败：尝试更新pip后再安装 python3 -m pip install --upgrade pip
数据库初始化错误：确认是否有足够权限创建文件，或检查data目录是否存在
OCR识别失败：检查.env文件中的腾讯云API密钥是否正确

📂 项目结构

InvoiceOCR/
├── app/                              # Web应用主目录
│   ├── static/                       # 静态资源
│   │   ├── css/                      # CSS样式
│   │   │   └── style.css             # 全局样式表
│   │   ├── js/                       # JavaScript文件
│   │   │   ├── edit_invoice.js       # 发票编辑页面脚本
│   │   │   ├── index.js              # 首页脚本
│   │   │   ├── main.js               # 主要公共脚本
│   │   │   └── upload.js             # 上传页面脚本
│   │   └── uploads/                  # 上传的发票图片存储目录
│   ├── templates/                    # HTML模板
│   │   ├── auth/                     # 认证模板
│   │   │   ├── base.html             # 认证页基础布局
│   │   │   ├── login.html            # 登录页
│   │   │   ├── setup.html            # 首次密码设置
│   │   │   ├── change_password.html  # 修改密码
│   │   │   ├── mfa_setup.html        # MFA绑定
│   │   │   ├── mfa_verify.html       # MFA验证
│   │   │   ├── mfa_manage.html       # MFA管理
│   │   │   └── profile.html          # 账户信息
│   │   ├── errors/                   # 错误页面模板
│   │   │   ├── 404.html              # 404错误页面
│   │   │   ├── 429.html              # 429限流提示
│   │   │   └── 500.html              # 500错误页面
│   │   ├── base.html                 # 基础布局模板
│   │   ├── index.html                # 首页模板
│   │   ├── invoice_create.html       # 发票创建页面
│   │   ├── invoice_detail.html       # 发票详情页面
│   │   ├── invoice_edit.html         # 发票编辑页面
│   │   ├── edit_invoice.html         # 发票编辑页面（旧版兼容）
│   │   ├── confirm_delete.html       # 删除确认页面
│   │   ├── project_detail.html       # 项目详情页面
│   │   ├── project_form.html         # 项目编辑表单
│   │   ├── project_list.html         # 项目列表页面
│   │   ├── settings.html             # 设置页面
│   │   └── upload.html               # 上传页面
│   ├── __init__.py                   # 应用工厂
│   ├── auth.py                       # 认证蓝图 
│   ├── config.py                     # 应用配置
│   ├── models.py                     # 数据模型
│   ├── routes.py                     # 主路由蓝图
│   └── utils.py                      # 辅助函数
├── core/                             # 核心功能模块
│   ├── __init__.py                   # 模块初始化
│   ├── invoice_export.py             # 发票数据导出功能
│   ├── invoice_formatter.py          # 发票数据格式化
│   ├── ocr_api.py                    # OCR API调用功能
│   ├── ocr_process.py                # OCR结果处理
│   └── README.md                     # 核心模块说明文档
├── data/                             # 数据存储目录
│   ├── invoices.db                   # SQLite数据库文件
│   ├── logs/                         # 安全审计日志 
│   │   └── security.log              # 安全操作审计记录
│   ├── output/                       # 导出文件存储目录
│   └── README.md                     # 数据目录说明文档
├── tools/                            # 工具脚本目录
│   ├── clean_temp_files.py           # 临时文件清理工具
│   ├── db_backup.py                  # 数据库备份工具
│   ├── db_init.py                    # 数据库初始化脚本
│   ├── db_query.py                   # 数据库查询工具
│   ├── generate_test_data.py         # 测试数据生成工具
│   └── README.md                     # 工具脚本说明文档
├── test/                             # 测试目录
│   ├── fixtures/                     # 测试数据目录
│   │   └── invoices/                 # 测试发票图片
│   └── README.md                     # 测试说明文档
├── .env                              # 环境变量文件（不入库）
├── .env.example                      # 环境变量示例文件
├── .gitignore                        # Git忽略文件
├── docker-compose.yml                # Docker Compose配置
├── Dockerfile                        # Docker构建文件
├── LICENSE                           # 许可证文件
├── README.md                         # 项目说明文档
├── requirements.txt                  # 项目依赖
└── run.py                            # 应用入口 + CLI命令 + 定时任务

🔧 配置说明

上传发票

点击左侧导航栏中的"上传发票"
选择一个项目分类（可选）
拖拽发票图片或PDF文件到上传区域，或点击选择文件
系统会自动识别并处理发票内容（对于PDF文件，会识别第一页）
上传后自动跳转到发票详情页进行查看和编辑

项目管理

点击左侧导航栏中的"项目管理"
可以创建、编辑、删除项目
点击项目卡片查看该项目下的所有发票
未分类发票会显示在"未分类"区域

查看发票列表

在首页可以看到所有上传的发票列表
可以通过点击表头排序发票
控制台上方显示统计数据和图表
可以根据项目筛选发票列表

发票详情与编辑

点击发票列表中的发票行即可查看详情
点击发票图片可以在弹窗中查看大图，支持放大缩小功能
对于PDF文件，会显示PDF阅读器方便查看
点击"编辑"按钮修改发票信息，所有金额字段会自动处理货币符号
点击"删除"按钮删除发票

导出功能

在发票详情页，可以选择导出格式（CSV或Excel）导出发票数据。在项目详情页，可以导出整个项目的发票数据为Excel。

清理导出文件

首页提供"清理导出文件"按钮，可以手动清理已导出的临时文件。系统还会自动定期（每天凌晨3点）清理过期的导出文件。

🛠️ 开发者指南

GitHub Actions 配置

本项目使用GitHub Actions自动构建和发布Docker镜像。如果您fork了本项目并希望启用自动构建，需要配置以下GitHub Secrets:

1. 访问GitHub仓库设置

前往您的GitHub仓库
点击顶部的"Settings"选项卡
在左侧菜单中找到"Security"部分下的"Secrets and variables"
选择"Actions"

2. 添加必要的Secrets

需要添加以下Secret以启用Docker Hub发布:

Secret名称	说明	获取方式
`DOCKERHUB_USERNAME`	Docker Hub用户名	您的Docker Hub账号用户名
`DOCKERHUB_TOKEN`	Docker Hub访问令牌	在Docker Hub → Account Settings → Security中创建

3. 获取Docker Hub访问令牌

登录Docker Hub
点击右上角头像 → Account Settings → Security
点击"New Access Token"按钮
输入描述（如"GitHub Actions"）
选择适当的权限（至少需要"Read & Write"权限）
点击"Generate"生成令牌
重要: 立即复制生成的令牌，它只会显示一次

4. 验证配置

配置完成后，每次发布新Release或手动触发工作流时，将自动构建并推送Docker镜像到您的Docker Hub账号。

📝 许可证

MIT License

👤 作者

chiupam
✈️ Telegram: @Chiupam
📧 Email: [email protected]

🙏 致谢

感谢您的使用和反馈！如果您有任何问题或建议，请随时联系我们。

InvoiceOCR

About InvoiceOCR

Platforms

Languages

Links

Need Help Installing InvoiceOCR?

InvoiceOCR

🧾 发票OCR管理系统

✨ 功能特点

🔄 最近更新

📅 未来计划

🚀 快速开始

🐳 使用 Docker

1️⃣ 准备工作

2️⃣ 部署步骤

(1) 克隆仓库并进入项目目录

(2) 创建环境变量文件（可选）

(3) 构建并启动容器

(4) 访问应用

3️⃣ 常用Docker命令

4️⃣ 使用预构建的Docker镜像

🔵 Docker Hub (推荐)

🔷 GitHub Container Registry

💾 数据持久化

💻 本地部署

1️⃣ 克隆项目

2️⃣ 创建并激活虚拟环境

3️⃣ 安装依赖

4️⃣ 基本环境配置

5️⃣ 运行应用

6️⃣ 首次访问配置

7️⃣ 退出虚拟环境（完成使用后）

❓ 常见问题解决

📂 项目结构

🔧 配置说明

上传发票

项目管理

查看发票列表

发票详情与编辑

导出功能

清理导出文件

🛠️ 开发者指南

GitHub Actions 配置

1. 访问GitHub仓库设置

2. 添加必要的Secrets

3. 获取Docker Hub访问令牌

4. 验证配置

📝 许可证

👤 作者

🙏 致谢