socialmediaocr

只需要3步骤，实现OCR图片批量识别，并保存到本地数据库，并同步远程数据库

1. 创建一个带透明通道的mask图片（要同尺寸），放到 mask/{平台}/{标签}/ 目录下
2. 修改配置文件 config.ini，按行从上到下的顺序写每个涂抹区域对应的含义
3. 将需要ocr分析的图片放到 images/（或 OCR_IMAGES_PATH）目录下，执行即可

文档导航

文档	内容
docs/ARCHITECTURE.md	项目定位、分层架构、目录职责、技术栈、关键设计
docs/DATA_FLOW.md	采集端→SFTP→加工端全链路、两种采集模式、目录/文件/字段契约、入库
docs/DEPLOYMENT.md	容器/裸机部署、OCR 引擎接入与健壮性、环境变量表、常见问题

安装依赖

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

使用方法

手动执行模式（默认）

# 执行OCR识别和数据同步
python social_ocr.py

# 或明确指定模式
python social_ocr.py --mode manual

# 执行OCR识别但不进行数据同步
python social_ocr.py --mode manual --no-sync

定时任务模式

# 每小时执行一次OCR识别和数据同步
python social_ocr.py --mode schedule

# 每30分钟执行一次OCR识别和数据同步
python social_ocr.py --mode schedule --interval 30

# 每天10:00执行一次OCR识别和数据同步
python social_ocr.py --mode schedule --at-time "22:00"

# 每小时执行OCR识别但不进行数据同步
python social_ocr.py --mode schedule --no-sync

TZ='Asia/Shanghai' nohup python social_ocr.py --mode schedule --at-time "22:00" >> run.log 2>&1 &

在定时任务模式下，系统会按照指定的时间间隔或时间点自动执行OCR识别和数据同步任务。

项目结构

socialmediaocr/
├── core/                 # 核心功能模块
│   ├── run.py            # 加工主流程：目录扫描 + 平台 parser 分发
│   ├── mask_ocr.py       # 蒙版合成 + OCR识别 + 结果校验
│   ├── parsers/          # 各平台解析器（xhs/weibo/tiktok/coolapk）
│   ├── ocr.py            # OCR行排序工具
│   ├── ppocr_api.py      # PaddleOCR-json 引擎封装
│   └── logger.py         # 日志
├── db/                   # 数据库相关
│   ├── __init__.py       # 记录构建（内存字典）+ 平台 appid 登记表 SOURCE_TYPES
│   └── data_sync.py      # 同步远程MySQL
├── docker/               # 容器化部署（双容器：引擎 socket 服务 + 应用）
│   ├── docker-compose.yml
│   ├── Dockerfile.app
│   ├── Dockerfile.engine
│   └── download_engine.sh  # 引擎包下载 + SHA256 校验
├── images/               # 待识别图片（上游采集落盘目录，可用 OCR_IMAGES_PATH 覆盖）
├── mask/                 # 遮罩图片库（已拍平：{平台}/{标签}/）
├── docs/                 # 项目文档（架构/数据流转/部署）
├── tmp/                  # 临时文件
├── config.ini            # OCR 加工规则：tag 字段提取顺序 + 中文段名→表英文列映射
├── social_ocr.py         # 主入口文件
└── requirements.txt      # 项目依赖

上游契约

上游 sma_autoui 各平台 scraper 统一继承 BaseProfileScraper，每个采集运行目录 （{平台}/{YYYYMMDD}/{设备}#{账号}/）产出：

• user_info.json：用户信息（UserInfo 模型序列化）→ 同步到 s_xhs_user_info_ocr
• post_data.json：帖子/内容数据（PostInfo 模型序列化列表）→ 同步到内容大表
• {标签}#{标识}.png：截图（仅xhs/tiktok）→ 蒙版OCR后同步到内容大表

两条通道最终入库同一张表 s_xhs_data_overview_traffic_analysis，缺失字段为空。

配置说明

1. OCR引擎配置

OCR 引擎统一为 PaddleOCR（PaddleOCR-json v1.4.1），已移除历史上的 surya 分支。通过环境变量配置：

• OCR_ENGINE: OCR引擎类型，仅支持 PaddleOCR（设为其他值记 error 并跳过 OCR）
• OCR_ENGINE_PATH: 两种形态
  • 本地引擎二进制路径（如 /opt/paddleocr-json/PaddleOCR-json）：pipe 子进程模式，按需拉起
  • remote://ip:port（如 remote://ocr-engine:9985）：socket 模式，连接独立部署的引擎服务（容器化部署使用）
• OCR_IMAGES_PATH: 采集落盘根目录（默认项目内 images/）
• OCR_RECENT_DAYS: 处理最近N天的目录（默认2）
• OCR_ENGINE_RETRY_INTERVAL: 引擎初始化失败后的退避间隔秒数（默认 30），窗口内不重复拉起
• OCR_ENGINE_HEALTH_CHECK: 复用缓存引擎前是否先跑健康探针（默认 1 开；0/false/no 关闭）

引擎为单例懒加载，命中缓存先跑健康探针（local 查子进程存活 / remote 发空指令测连通）， 探针失败自动关闭旧实例并重连/重启，实现断线自愈；详见 docs/DEPLOYMENT.md。

2. 数据库配置

连接信息与库名通过环境变量（.env）配置，不同环境各自维护：

• MYSQL_HOST: MySQL服务器地址
• MYSQL_PORT: MySQL端口
• MYSQL_USER: 用户名
• MYSQL_PASSWORD: 密码
• MYSQL_DATABASE: 数据库名

入库目标表名属远程库契约（跨环境恒定），登记在 db/__init__.py 的 TABLE_CONTENT_DATA / TABLE_USER_INFO 常量，与 db/init.sql 建表名一致。

3. 标签与字段映射配置（config.ini）

config.ini 职责是 OCR 加工规则，链路：OCR 文本行序 --[tags]--> 中文字段名 --[fields]--> MySQL 英文列名：

[tags]
note_data_overview_top = 曝光数,观看数,封面点击率

[fields]
# 英文列名 = 中文字段名，同一列多个中文别名用逗号分隔
view_count = 观看数
collection_time = 采集时间,采集日期

每次任务启动时会校验 [tags] 字段均能在 [fields] 映射，漏配会告警提醒（该列入库时会被丢弃）。

4. 平台appid登记

平台 appid（远程库 source_type 字段）是入库契约的一部分，跨环境恒定， 登记在 db/__init__.py 的 SOURCE_TYPES 常量表，新平台接入时与 parser 一并添加：

SOURCE_TYPES = {
    "xhs": "1894230222988058625",
    ...
}

工作流程

1. 程序扫描 images/（或 OCR_IMAGES_PATH）下最近N天的采集运行目录
2. JSON直采通道：user_info.json / post_data.json 按上游统一模型解析后入库
3. 截图通道：根据文件名标签应用对应遮罩图片 → OCR识别 → 按行序映射字段 → 有效性校验
4. 两通道记录入库同一张MySQL表（缺失字段为空），用户信息入 s_xhs_user_info_ocr

部署（Linux）

OCR 引擎统一使用 PaddleOCR-json v1.4.1 的 Linux 便携包（PaddleOCR-json_v1.4.1_debian_x64_glibc2.31.tar.xz，要求 glibc>=2.31， 即 Debian 11+/Ubuntu 20.04+）。支持两种部署方式，共用同一套代码，仅 OCR_ENGINE_PATH 不同。

方式一：容器部署（docker compose，推荐）

双容器：ocr-engine（引擎常驻 TCP 服务模式，监听 9985）+ app（常驻 schedule 模式， 每天 22:00 执行，通过 remote://ocr-engine:9985 连接引擎）。

# 1. 下载引擎包并校验 SHA256（仅首次；也可开发机下载后 scp 到 docker/ 目录）
bash docker/download_engine.sh

# 2. 准备 .env（MYSQL_* / SFTP_* 等，参考配置说明章节）

# 3. 构建并启动
docker compose -f docker/docker-compose.yml up -d --build

# 4. 验证
docker compose -f docker/docker-compose.yml ps        # engine 应为 healthy
docker compose -f docker/docker-compose.yml logs -f app
docker compose -f docker/docker-compose.yml exec app python social_ocr.py --mode manual  # 手动跑一轮全链路

挂载说明（在 docker/docker-compose.yml 中按需调整）：

• /home/callfans/ocr:/data/ocr：采集数据目录（rw，容器内会清理过期日期目录）
• ./logs:/app/logs：日志持久化到宿主项目目录

方式二：裸机部署（systemd）

# 1. 下载并解压引擎到 /opt
bash docker/download_engine.sh
sudo mkdir -p /opt/paddleocr-json
sudo tar -xJf docker/PaddleOCR-json_v1.4.1_debian_x64_glibc2.31.tar.xz \
    -C /opt/paddleocr-json --strip-components=1
sudo chmod +x /opt/paddleocr-json/PaddleOCR-json

# 2. .env 中指向本地二进制（注意 Linux 下无 .exe 后缀，pipe 模式按需拉起）
#    OCR_ENGINE=PaddleOCR
#    OCR_ENGINE_PATH=/opt/paddleocr-json/PaddleOCR-json

# 3. 安装服务（参考 pro/social_ocr.service，按实际路径/conda环境调整）
sudo cp pro/social_ocr.service /etc/systemd/system/social_ocr.service
sudo systemctl daemon-reload
sudo systemctl enable --now social_ocr.service

# 常用运维
sudo systemctl status social_ocr.service     # 查看状态
sudo systemctl restart social_ocr.service    # 重启
journalctl -u social_ocr.service -f          # 跟踪日志（或看 logs/run.log）

修改 service 文件后需 sudo systemctl daemon-reload 重新加载配置再 restart。

常见问题

• glibc 版本不够（裸机）：引擎包要求 glibc>=2.31，ldd --version 查看；不满足则改用容器部署
• 引擎启动报缺库：按报错内容在 Dockerfile.engine 的 apt 列表中补装对应组件
• 容器内解析不了 mysql-svr/callfans-rpa 等内网主机名：bridge 网络默认继承宿主 DNS， 通常可解析；失败时在 compose 中启用 extra_hosts 映射 IP 兜底
• 引擎内存占用：常驻约 800MB~1GB，可在 compose 中用 mem_limit 限制
• 挂载卷权限：app 容器以 uid=1000 运行（与宿主 callfans 对齐），若宿主数据目录属主不同需调整
• 本地 Windows 开发：OCR_ENGINE_PATH 指向 Windows 版 PaddleOCR_json.exe 即可，pipe 模式与 Linux 行为一致