# wcocr-server

**Repository Path**: zhReimu/wcocr-server

## Basic Information

- **Project Name**: wcocr-server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-10
- **Last Updated**: 2026-07-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wcocr-server

基于微信 OCR 的 HTTP 服务器，使用 Go 语言实现。

本项目是 [wechat-ocr](https://github.com/swigger/wechat-ocr) C++ 库的 Go HTTP 服务封装，通过 [purego](https://github.com/ebitengine/purego) 实现纯 Go 的 FFI 调用（无 CGO 依赖），支持 Windows / Linux / macOS 三大平台。

## 目录

- [快速开始](#快速开始)
- [前置要求](#前置要求)
- [构建 OCR 动态库（wechat-ocr）](#构建-ocr-动态库wechat-ocr)
  - [Windows 平台](#windows-平台)
  - [Linux 平台](#linux-平台)
  - [macOS 平台](#macos-平台)
- [准备 OCR 运行时文件](#准备-ocr-运行时文件)
- [编译服务器](#编译服务器)
- [运行服务器](#运行服务器)
- [项目结构](#项目结构)
- [功能特性](#功能特性)
- [Task 任务一览](#task-任务一览)
- [命令行使用](#命令行使用)
- [API 使用](#api-使用)
- [技术说明](#技术说明)
- [许可证与相关项目](#许可证与相关项目)

## 快速开始

```bash
# 1. 安装 Go 1.26+ 和 Task（https://taskfile.dev）
# 2. 编译服务器（会自动拷贝对应平台的 OCR 动态库）
task build

# 3. 准备微信 OCR 运行时文件到 dist/shared 目录（见下文）
# 4. 运行
cd dist
./wcocr-server
```

## 前置要求

| 依赖 | 版本 | 说明 |
|------|------|------|
| Go | 1.26+ | Go 语言工具链 |
| Task | 3.x | 任务运行器，[安装指南](https://taskfile.dev/installation/) |
| 微信 OCR 运行时 | - | 需自行获取（见[下文](#准备-ocr-运行时文件)） |
| OCR 动态库 | - | 本仓库 `lib/` 目录已提供 Windows 和 Linux 版本；如需自行构建见[下文](#构建-ocr-动态库wechat-ocr) |

## 构建 OCR 动态库（wechat-ocr）

本仓库的 `lib/` 目录已包含预编译的 OCR 动态库：

| 文件 | 平台 | 说明 |
|------|------|------|
| `lib/wcocr.dll` | Windows x64 | 微信 OCR 封装库 |
| `lib/wcocr.so` | Linux x86_64 | 微信 OCR 封装库 |

如需自行构建（例如更新版本或适配其他架构），请参考以下各平台说明。源码位于上游仓库 [swigger/wechat-ocr](https://github.com/swigger/wechat-ocr)。

> **命名约定**：本项目统一使用 `wcocr` 作为库名（不带平台前缀），即 Windows 为 `wcocr.dll`、Linux 为 `wcocr.so`、macOS 为 `libwcocr.dylib`。注意 CMake 在 Linux/macOS 上默认会添加 `lib` 前缀（产出 `libwcocr.so`），构建后需重命名或拷贝为 `wcocr.so`。

### Windows 平台

Windows 上有三种构建方式，均使用仓库自带的预编译 protobuf 库（`spt/x64/libprotobuf-lite.lib`），无需额外安装 protobuf。

**前置要求：**
- Visual Studio 2022（含 C++ 桌面开发工具集，平台工具集 v143）
- 或仅安装 [Build Tools for Visual Studio 2022](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
- CMake 3.20+（可选，方式三需要）

**方式一：Visual Studio 图形界面**

1. 用 Visual Studio 2022 打开 `vs.proj/wcocr.sln`
2. 选择配置 `Release | x64`
3. 生成解决方案（Ctrl+Shift+B）
4. 产物路径：`vs.proj/x64/Release/wcocr.dll`

**方式二：MSBuild 命令行**

```bat
:: 在 "x64 Native Tools Command Prompt for VS 2022" 中执行
msbuild vs.proj\wcocr.sln /p:Configuration=Release /p:Platform=x64
```

产物路径：`vs.proj\x64\Release\wcocr.dll`

**方式三：CMake + MSVC**

```bat
:: 在 "x64 Native Tools Command Prompt for VS 2022" 中执行
cmake -B build -A x64
cmake --build build --config Release --target wcocr
```

产物路径：`build\Release\wcocr.dll`

**拷贝到本项目：**

```bat
copy vs.proj\x64\Release\wcocr.dll ..\wcocr-server\lib\wcocr.dll
:: 或 CMake 方式
copy build\Release\wcocr.dll ..\wcocr-server\lib\wcocr.dll
```

### Linux 平台

Linux 上使用 CMake + GCC 构建，protobuf 通过 CMake FetchContent 自动下载并静态编译（首次构建需要联网，后续会缓存）。

**前置要求：**
- GCC 10+ 或 Clang 12+（需支持 C++20）
- CMake 3.20+
- Python 3.8+（含开发头文件 `Python.h`，用于构建 Python 绑定目标）
- Make 或 Ninja

**构建步骤：**

```bash
# 1. 克隆 wechat-ocr 源码
git clone https://github.com/swigger/wechat-ocr.git
cd wechat-ocr

# 2. CMake 配置（会自动下载 protobuf v3.21.2）
cmake -B build -DCMAKE_BUILD_TYPE=Release

# 3. 编译 wcocr 目标（-j 指定并行数）
cmake --build build --target wcocr -j$(nproc)

# 4. 拷贝产物（CMake 产出 libwcocr.so，重命名为 wcocr.so）
cp build/libwcocr.so ../wcocr-server/lib/wcocr.so
```

**验证导出符号：**

```bash
# 确认 wechat_ocr 和 stop_ocr 两个符号已导出
nm -D --defined-only lib/wcocr.so | grep -E 'wechat_ocr|stop_ocr'
```

预期输出包含：
```
000000000000a8b0 T stop_ocr
000000000000b6d0 T wechat_ocr
```

**验证动态库依赖：**

```bash
ldd lib/wcocr.so
# protobuf 已静态链接，仅依赖 libstdc++、libgcc_s、libc、libm 等系统库
```

> **提示**：也可使用本项目 Taskfile 提供的任务一键构建：
> ```bash
> # 在 wcocr-server 目录下，WEOCR_SRC 指向 wechat-ocr 源码目录
> WEOCR_SRC=../wechat-ocr task build-lib:linux
> ```

### macOS 平台

macOS 上使用 CMake + Apple Clang 构建，与 Linux 类似。

**前置要求：**
- Xcode Command Line Tools（`xcode-select --install`）
- CMake 3.20+
- Python 3.8+（含开发头文件）

**构建步骤：**

```bash
git clone https://github.com/swigger/wechat-ocr.git
cd wechat-ocr

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --target wcocr -j$(sysctl -n hw.ncpu)

# CMake 产出 libwcocr.dylib
cp build/libwcocr.dylib ../wcocr-server/lib/libwcocr.dylib
```

> **注意**：上游 `export_names.cmake` 中 macOS 平台的符号导出尚未实现（标注为 TODO），因此 macOS 版本会导出所有符号，但 `wechat_ocr` 和 `stop_ocr` 仍可正常调用。

## 准备 OCR 运行时文件

本项目需要微信 OCR 的运行时文件，这些文件**不包含在仓库中**，需要用户自行获取并放置到正确位置。

### Windows

在编译后的 `dist` 目录下创建以下结构：

```
dist/
├── wcocr-server.exe        # 编译生成的可执行文件
├── weixin.exe              # 微信可执行文件
└── shared/                  # OCR 依赖文件（需自行获取）
    ├── wcocr.dll           # OCR 封装库（本仓库 lib/ 已提供，编译时自动拷贝）
    ├── mmmojo_64.dll       # Mojo 运行时
    └── 8020/               # 微信 OCR 组件目录
        ├── wxocr.dll       # 微信 OCR 主库
        ├── mmmojo_64.dll   # Mojo 运行时副本
        ├── *.xnet          # 神经网络模型文件
        ├── *.txt           # 字符集和配置文件
        └── x64.config      # 配置文件
```

**文件来源（微信 4.x）：**
- OCR 组件：`%AppData%\Tencent\xwechat\XPlugin\plugins\WeChatOcr\8020\extracted\wxocr.dll`
- 微信目录：`C:\Program Files\Tencent\Weixin\4.0.0.26`

### Linux

在 Linux 上，微信 OCR 运行时通常安装在 `/opt/wechat/` 目录：

```
/opt/wechat/
├── wxocr                   # 微信 OCR 可执行文件（对应 Windows 的 wxocr.dll）
├── libmmmojo_64.so         # Mojo 运行时
└── ...                     # 模型文件、配置文件等
```

将构建好的 `wcocr.so` 拷贝到 `dist/shared/` 目录，或将 `-ocr-dll` 参数指向 `lib/wcocr.so` 的绝对路径。

### macOS

macOS 的文件结构与 Linux 类似，微信 OCR 运行时路径视安装位置而定，通过 `-ocr-dll`、`-ocr-exe`、`-wechat-dir` 参数指定。

## 编译服务器

```bash
task build
```

编译后的可执行文件会输出到 `dist/wcocr-server`（Linux/macOS）或 `dist/wcocr-server.exe`（Windows），同时自动拷贝对应平台的 OCR 动态库到 `dist/shared/`。

如需构建其他平台的交叉编译版本：

```bash
task build-all    # 构建所有平台
task build-linux  # 仅 Linux amd64
task build-darwin # 仅 macOS amd64
task build-windows # 仅 Windows amd64
```

## 运行服务器

确保 `shared` 目录已正确配置后运行：

```bash
# Linux / macOS
cd dist
./wcocr-server

# Windows
cd dist
wcocr-server.exe
```

服务器将在 `http://127.0.0.1:8080` 启动。

## 项目结构

```
wcocr-server/
├── cmd/
│   ├── server/          # 主程序入口
│   ├── diagnose/        # 诊断工具
│   └── test-ocr/        # OCR 测试工具
├── internal/            # 内部包
│   ├── config/         # 跨平台默认配置
│   │   └── defaults.go
│   ├── ocr/            # OCR 核心模块
│   │   ├── types.go          # 数据结构
│   │   ├── ocr.go            # OCR 引擎
│   │   ├── ocr_windows.go    # Windows 平台特定代码
│   │   ├── ocr_unix.go       # Unix 平台特定代码
│   │   ├── ffi_windows.go    # Windows FFI 实现
│   │   └── ffi_unix.go       # Unix FFI 实现
│   ├── handler/        # HTTP 处理器
│   │   └── handler.go
│   └── server/         # HTTP 服务器
│       └── server.go
├── lib/                # 预编译的 OCR 动态库
│   ├── wcocr.dll       # Windows x64
│   └── wcocr.so        # Linux x86_64
├── dist/               # 编译输出目录（.gitignore 忽略）
│   ├── wcocr-server         # 编译后的可执行文件
│   └── shared/              # OCR 依赖文件（需用户自行准备）
│       ├── wcocr.so / wcocr.dll
│       └── ...
├── .gitignore
├── .gitattributes
├── Taskfile.yml        # Task 构建配置
├── go.mod
├── go.sum
└── README.md
```

**重要说明**：`dist/shared/` 目录及其内容不包含在版本控制中（已添加到 .gitignore），需要用户自行准备。

## 功能特性

- 使用微信 OCR 引擎进行高质量文字识别
- RESTful HTTP API 接口
- 并发处理支持
- 跨平台支持（Windows / Linux / macOS）
- 使用 purego 实现纯 Go CGO-free 调用
- 符合 Go 最佳实践的项目结构
- 通过构建标签实现平台特定代码隔离

## 依赖

- Go 1.26+
- [Task](https://taskfile.dev/) - 任务运行器
- [ebitengine/purego](https://github.com/ebitengine/purego) - 纯 Go FFI 库
- 微信 OCR 运行时文件（需自行获取）
- OCR 封装库（本仓库 `lib/` 已提供 Windows 和 Linux 版本，或参考[上文](#构建-ocr-动态库wechat-ocr)自行构建）

## Task 任务一览

查看所有可用任务：

```bash
task
```

常用任务：

| 任务 | 说明 |
|------|------|
| `task build` | 编译服务器到 dist 目录（自动拷贝动态库） |
| `task build-lib:linux` | 从 wechat-ocr 源码构建 wcocr.so |
| `task build-lib:windows` | 从 wechat-ocr 源码构建 wcocr.dll |
| `task diagnose` | 编译诊断工具 |
| `task test-ocr` | 编译 OCR 测试工具 |
| `task clean` | 清理编译产物 |
| `task fmt` | 格式化代码（go fmt） |
| `task lint` | 代码检查（go vet） |
| `task modernize` | 代码现代化检查 |
| `task test` | 运行测试 |
| `task check` | 完整检查（格式化 + 检查 + 测试） |
| `task build-all` | 交叉编译全平台版本 |

## 命令行使用

### 服务器

```bash
# Linux / macOS
./wcocr-server [选项]

# Windows
wcocr-server.exe [选项]
```

选项（各平台默认值不同，以下为 Linux 默认值）：

```
  -host string
        监听地址 (默认 "127.0.0.1")
  -port int
        监听端口 (默认 8080)
  -ocr-dll string
        OCR 动态库路径 (Linux 默认 "shared/wcocr.so"，Windows 默认 "shared/wcocr.dll")
  -ocr-exe string
        OCR 可执行文件路径 (Linux 默认 "/opt/wechat/wxocr"，Windows 默认 "shared/8020/wxocr.dll")
  -wechat-dir string
        微信目录路径 (Linux 默认 "/opt/wechat/"，Windows 默认 "shared")
  -concurrent int
        最大并发数 (默认 5)
  -timeout int
        OCR 超时时间（秒） (默认 30)
```

示例：

```bash
# 默认配置运行（在 dist 目录下）
cd dist
./wcocr-server

# 指定端口
./wcocr-server -port 9090

# 指定自定义路径（使用绝对路径）
./wcocr-server -ocr-dll /path/to/wcocr.so -ocr-exe /opt/wechat/wxocr -wechat-dir /opt/wechat/

# 调整并发数
./wcocr-server -concurrent 10
```

**注意**：程序会自动将相对路径转换为基于可执行文件所在目录的绝对路径，因此建议在 `dist` 目录下运行，或使用绝对路径指定 OCR 文件位置。

### 诊断工具

用于检查 OCR 环境是否配置正确：

```bash
task diagnose
cd dist
./diagnose
```

### OCR 测试工具

测试 OCR 服务是否正常工作：

```bash
task test-ocr
cd dist
./test-ocr -image test.png
```

选项：
- `-image` - 要识别的图片路径（必需）
- `-server` - 服务器地址（默认 "http://127.0.0.1:8080"）

## API 使用

### 1. 健康检查

```bash
curl http://localhost:8080/health
```

响应：
```
OK
```

### 2. OCR 识别

```bash
curl -X POST -F "image=@test.png" http://localhost:8080/ocr
```

响应示例：

```json
{
  "errcode": 0,
  "ocr_response": [
    {
      "left": 53.354168,
      "top": 128.5,
      "right": 456.78,
      "bottom": 180.25,
      "rate": 0.95,
      "text": "识别的文字内容",
      "details": [
        {
          "chars": "识",
          "left": 53.354168,
          "top": 128.5,
          "right": 75.0,
          "bottom": 180.25
        }
      ]
    }
  ],
  "width": 800,
  "height": 600
}
```

字段说明：
- `errcode`: 错误码（0 表示成功）
- `ocr_response`: 识别结果数组，每个元素代表一个文本块
  - `left`, `top`, `right`, `bottom`: 文本块的边界框坐标（浮点数）
  - `rate`: 识别置信度（0-1 之间）
  - `text`: 识别的完整文本
  - `details`: 每个字符的详细信息（可选）
    - `chars`: 单个字符
    - `left`, `top`, `right`, `bottom`: 字符的边界框坐标
- `width`, `height`: 图片尺寸

## 技术说明

### CGO-Free 实现

本项目使用 [purego](https://github.com/ebitengine/purego) 库实现纯 Go 的 FFI（Foreign Function Interface），无需依赖 CGO。这样做的优点：

- 编译速度更快
- 交叉编译更简单
- 没有 CGO 的复杂性和依赖问题
- 更好的 Go 工具链兼容性

### 项目架构

- **cmd/server**: 程序入口，负责配置解析和启动
- **cmd/diagnose**: 环境诊断工具
- **cmd/test-ocr**: OCR 功能测试工具
- **internal/config**: 跨平台默认配置（动态库路径、OCR 路径等）
- **internal/ocr**: OCR 引擎核心逻辑，封装了与 C++ 动态库的交互
- **internal/handler**: HTTP 请求处理器
- **internal/server**: HTTP 服务器封装

### 跨平台支持

通过构建标签（build tags）实现平台特定代码隔离：

- `ocr_windows.go`: Windows 平台的宽字符串（UTF-16）处理
- `ocr_unix.go`: Unix 平台的字符串（UTF-8）处理
- `ffi_windows.go`: Windows DLL 加载（LoadLibraryExW）
- `ffi_unix.go`: Unix SO 加载（dlopen）
- `config/defaults.go`: 按平台返回默认路径

### OCR 库接口

本服务调用 `libwcocr` 导出的两个 C 函数：

```c
// 初始化并执行 OCR（imgfn 为空时仅初始化引擎）
bool wechat_ocr(const char* ocr_exe, const char* wechat_dir,
                const char* imgfn, void(*callback)(const char* result));

// 停止 OCR 引擎
void stop_ocr(void);
```

- Windows 上 `ocr_exe` 和 `wechat_dir` 参数为 UTF-16 宽字符串（`LPCTSTR`）
- Linux/macOS 上为 UTF-8 字符串（`const char*`）

## 许可证与相关项目

本项目基于原 [wechat-ocr](https://github.com/swigger/wechat-ocr) 项目封装。

相关项目：
- [wechat-ocr](https://github.com/swigger/wechat-ocr) - C++ 原始实现（提供 `wcocr.dll` / `wcocr.so` / `libwcocr.dylib`）
- [ebitengine/purego](https://github.com/ebitengine/purego) - 纯 Go FFI 库