Skip to content

Installation Guide

Jump to bottom
梁兆本 edited this page Apr 14, 2026 · 2 revisions

🚀 安装与部署指南

本文档提供发票OCR管理系统的两种部署方式：Docker部署和本地部署。

🐳 使用 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️⃣ 首次访问配置

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

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

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

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

(.venv) deactivate

🏭 生产环境部署

使用Gunicorn部署

  1. 安装Gunicorn
pip install gunicorn
  1. 创建系统服务

创建文件 /etc/systemd/system/invoiceocr.service:

[Unit]
Description=InvoiceOCR Service
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/path/to/invoiceOCR
Environment="PATH=/path/to/invoiceOCR/.venv/bin"
ExecStart=/path/to/invoiceOCR/.venv/bin/gunicorn -b 127.0.0.1:5001 -w 4 "app:create_app('production')"
Restart=always

[Install]
WantedBy=multi-user.target
  1. 启动服务
sudo systemctl enable invoiceocr
sudo systemctl start invoiceocr

Nginx反向代理

  1. 安装Nginx
sudo apt update
sudo apt install nginx
  1. 创建Nginx配置

创建文件 /etc/nginx/sites-available/invoiceocr:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:5001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /static/ {
        alias /path/to/invoiceOCR/app/static/;
        expires 30d;
    }

    client_max_body_size 16M;
}
  1. 启用站点
sudo ln -s /etc/nginx/sites-available/invoiceocr /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

HTTPS配置

强烈建议在生产环境中使用HTTPS加密通信。使用Let's Encrypt：

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

❓ 常见问题解决

  • 依赖安装失败：尝试更新pip后再安装 python3 -m pip install --upgrade pip
  • 数据库初始化错误：确认是否有足够权限创建文件，或检查data目录是否存在
  • OCR识别失败：检查.env文件中的腾讯云API密钥是否正确
  • 端口被占用：检查5001端口是否被其他程序占用，或修改运行端口
  • Docker容器启动失败：检查Docker服务是否正常运行，查看容器日志排查问题

Clone this wiki locally