# 精伦IDR210 本地服务API读取身份证信息 **Repository Path**: hnrxsd/idr210bdapi ## Basic Information - **Project Name**: 精伦IDR210 本地服务API读取身份证信息 - **Description**: 身份证读卡器本地代理服务，用于解决浏览器无法直接访问本地USB读卡器的问题。采用独立Node.js服务方案，每台客户端电脑单独运行，网页通过本地HTTP接口完成读卡操作。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-16 - **Last Updated**: 2026-06-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 身份证读卡器本地代理服务 ## 项目简介 身份证读卡器本地代理服务，用于解决浏览器无法直接访问本地USB读卡器的问题。采用独立Node.js服务方案，每台客户端电脑单独运行，网页通过本地HTTP接口完成读卡操作。 ## 技术栈 - **运行时**: Node.js 16.20.2+ TypeScript - **Web框架**: Express - **跨域处理**: cors中间件 - **日志系统**: winston + winston-daily-rotate-file - **硬件支持**: 精伦IDR210读卡器 - **DLL调用**: Python ctypes（通过子进程调用） ## 项目结构 ``` node-dqsfz/ ├── src/ # 源代码目录 │ ├── types.ts # TypeScript类型定义 │ ├── device.ts # 读卡器硬件封装 │ └── server.ts # 服务入口和路由 ├── sdk/ # SDK文件目录 │ ├── 64/ # 64位DLL文件 │ │ ├── CVR100U/ # CVR100U读卡器 │ │ │ ├── Termb.dll │ │ │ ├── sdtapi.dll │ │ │ ├── WltRS.dll │ │ │ └── DLL_File.dll │ │ └── CVR100D/ # CVR100D读卡器 │ └── 32/ # 32位DLL文件 │ ├── Termb.dll │ ├── sdtapi.dll │ ├── WltRS.dll │ └── DLL_File.dll ├── frontend/ # 前端配套代码 │ ├── idCardReaderAPI.ts # API封装 │ ├── IDCardReaderComponent.tsx # React组件 │ └── README.md # 前端集成指南 ├── docs/ # 文档目录 │ ├── 政务外网部署方案.md # 政务外网部署方案 │ ├── 开发调试操作流程.md # 开发调试文档 │ ├── 客户端部署实施文档.md # 部署实施文档 │ └── 常见故障排查手册.md # 故障排查手册 ├── dist/ # 编译输出目录 │ ├── portable-x64/ # 64位便携包 │ │ ├── node/ # Node.js运行时 │ │ ├── dist/ # 应用程序代码 │ │ ├── sdk/ # SDK文件 │ │ ├── start-service.bat # 启动脚本 │ │ └── start-service.vbs # 后台启动脚本 │ └── portable-x86/ # 32位便携包 ├── logs/ # 日志文件目录 ├── package.json # 项目配置 ├── tsconfig.json # TypeScript配置 └── README.md # 项目说明 ``` ## 核心功能 ### 1. 读卡器设备管理 - 自动检测系统位数（32位/64位） - 根据系统位数自动选择对应的DLL目录 - 设备初始化和连接 - 设备状态监控 - 设备资源释放 ### 2. 身份证读取 - 读取身份证基本信息 - 读取身份证照片 - 数据格式化和验证 ### 3. HTTP API接口 - `GET /health` - 健康检查 - `GET /api/device/init` - 初始化设备 - `GET /api/device/read` - 读取身份证 - `GET /api/device/close` - 关闭设备 ### 4. 生产级特性 - 全局异常处理 - 日志记录和轮转 - 跨域支持 - 端口冲突检测（默认端口28512） - 设备状态缓存 - 优雅关闭 ## 快速开始 ### 环境要求 - Node.js 16.20.2+ - Python 3.x（用于调用DLL） - TypeScript 5.0+ - Windows 7/10/11（32位或64位） - 精伦IDR210读卡器 ### 安装步骤 1. **克隆项目** ```bash git clone https://gitee.com/hnrxsd/idr210bdapi.git cd idr210bdapi ``` 2. **安装依赖** ```bash npm install --registry=https://registry.npmmirror.com ``` 3. **准备SDK文件** 将精伦IDR210 SDK文件复制到`sdk/`目录： - 64位系统：`sdk/64/CVR100U/` 或 `sdk/64/CVR100D/` - 32位系统：`sdk/32/` 4. **编译项目** ```bash npm run build ``` 5. **启动服务** ```bash npm start ``` 服务将在 `http://127.0.0.1:28512` 启动。 ### 开发模式 ```bash # 使用ts-node直接运行（支持热重载） npm run dev ``` ## 便携包部署 ### 64位便携包 1. 下载64位便携包：`dist/portable-x64/` 2. 解压到任意目录 3. 双击 `start-service.bat` 启动服务 4. 或双击 `start-service.vbs` 后台运行 ### 32位便携包 1. 下载32位便携包：`dist/portable-x86/` 2. 解压到任意目录 3. 双击启动脚本运行 **注意**：便携包已包含Node.js运行时，无需安装Node.js。 ## API接口说明 ### 响应格式 所有接口统一返回以下格式： ```json { "code": 0, // 状态码：0=成功 -1=设备未连接 -2=读卡失败 -3=驱动缺失 -99=服务异常 "data": {}, // 响应数据 "message": "操作成功", // 响应消息 "timestamp": 1234567890 // 时间戳 } ``` ### 接口列表 #### 1. 健康检查 ```http GET /health ``` **响应示例**: ```json { "code": 0, "data": { "status": "ok", "timestamp": 1234567890, "deviceStatus": "NOT_INITIALIZED" }, "message": "服务运行正常", "timestamp": 1234567890 } ``` #### 2. 初始化设备 ```http GET /api/device/init ``` **响应示例**: ```json { "code": 0, "data": { "status": "INITIALIZED", "model": "IDR210/CVR100U", "serialNumber": "未知", "driverVersion": "1.0.0", "lastUpdateTime": 1234567890 }, "message": "设备初始化成功", "timestamp": 1234567890 } ``` #### 3. 读取身份证 ```http GET /api/device/read ``` **响应示例**: ```json { "code": 0, "data": { "name": "张三", "gender": "男", "nation": "汉", "birthDate": "19900101", "idNumber": "110101199001011234", "address": "北京市东城区某某街道123号", "issuingAuthority": "北京市公安局东城分局", "validStartDate": "20100101", "validEndDate": "20200101", "photoBase64": "...base64数据...", "photoDataUrl": "data:image/jpeg;base64,...base64数据..." }, "message": "读卡成功", "timestamp": 1234567890 } ``` #### 4. 关闭设备 ```http GET /api/device/close ``` **响应示例**: ```json { "code": 0, "data": null, "message": "设备已关闭", "timestamp": 1234567890 } ``` ## 前端集成 ### 安装前端依赖 ```bash npm install axios ``` ### 使用API封装 ```typescript import { createIDCardReaderAPI } from './idCardReaderAPI'; // 创建API实例 const api = createIDCardReaderAPI('http://127.0.0.1:28512'); // 读取身份证 async function readIDCard() { try { const response = await api.readCard(); if (response.code === 0 && response.data) { console.log('读卡成功:', response.data); // 处理身份证信息 } } catch (error) { console.error('读卡失败:', error); } } ``` ### 使用React组件 ```typescript import IDCardReaderComponent from './IDCardReaderComponent'; function App() { return ( console.log('读卡成功:', cardInfo)} onError={(error) => console.error('读卡失败:', error)} showDebug={true} /> ); } ``` 详细的前端集成指南请参考 [frontend/README.md](frontend/README.md)。 ## 部署方案 ### 方案一：便携包部署（推荐） **优点**： - 无需安装Node.js - 无需管理员权限 - 可移动到任意目录 - 不修改系统注册表 **步骤**： 1. 下载对应系统位数的便携包 2. 解压到任意目录 3. 双击启动脚本运行 ### 方案二：标准部署 **步骤**： 1. 安装Node.js 16.20.2+ 2. 安装Python 3.x 3. 克隆项目并安装依赖 4. 编译并启动服务 详细的部署步骤请参考 [docs/政务外网部署方案.md](docs/政务外网部署方案.md)。 ## 开发调试 ### 调试模式 ```bash # 使用ts-node运行，支持TypeScript直接执行 npm run dev ``` ### 查看日志 ```bash # 查看最新日志 Get-Content logs\idcard-reader-*.log -Tail 50 # 实时监控日志 Get-Content logs\idcard-reader-*.log -Wait ``` ### 接口测试 使用浏览器或curl测试接口： ```bash # 健康检查 curl http://127.0.0.1:28512/health # 初始化设备 curl http://127.0.0.1:28512/api/device/init # 读取身份证 curl http://127.0.0.1:28512/api/device/read ``` 详细的开发调试流程请参考 [docs/开发调试操作流程.md](docs/开发调试操作流程.md)。 ## 故障排查 ### 常见问题 1. **服务无法启动** - 检查端口28512是否被占用 - 检查SDK文件是否完整 - 查看日志文件获取详细错误信息 2. **读卡失败** - 检查读卡器硬件连接 - 确认身份证放置正确 - 重新初始化设备 - 检查Python是否正确安装 3. **DLL加载失败** - 检查系统位数与DLL目录是否匹配 - 确认读卡器驱动是否正确安装 - 查看Python错误输出 4. **无法连接服务** - 确认服务正在运行 - 检查防火墙设置 - 验证服务地址和端口 详细的故障排查指南请参考 [docs/常见故障排查手册.md](docs/常见故障排查手册.md)。 ## 配置说明 ### 服务配置 服务配置位于 `src/server.ts` 中的 `config` 对象： ```typescript const config: ServiceConfig = { port: 28512, // 服务端口 host: '127.0.0.1', // 服务主机名 enableCors: true, // 启用CORS corsOrigins: [ // 允许的跨域来源 'http://localhost:5173', 'http://127.0.0.1:5173', 'http://localhost:3000', 'http://127.0.0.1:3000', '*' // 允许所有来源（生产环境建议限制） ], logLevel: LogLevel.INFO, // 日志级别 logFilePath: path.join(projectRoot, 'logs'), // 日志文件路径 sdkPath: path.join(projectRoot, 'sdk') // SDK文件路径 }; ``` ### 修改配置 如需修改配置，编辑 `src/server.ts` 文件中的 `config` 对象，然后重新编译： ```bash npm run build npm start ``` ## 系统架构 ### 自动系统位数检测 服务启动时会自动检测系统架构： - 64位系统：优先使用 `sdk/64/CVR100U/`，其次 `sdk/64/CVR100D/` - 32位系统：使用 `sdk/32/` 目录 ### 端口管理 - 默认端口：28512 - 启动前自动检测端口占用 - 服务关闭时自动释放端口 ### DLL调用机制 - 通过Python子进程调用DLL - 使用ctypes库进行DLL加载 - 支持不区分大小写的DLL文件名查找 ## 安全注意事项 1. **敏感信息保护**: 身份证信息属于敏感数据，请妥善处理 2. **访问控制**: 服务默认只监听127.0.0.1，避免外部访问 3. **数据传输**: 建议在内网环境中使用 4. **日志管理**: 定期清理日志文件，避免敏感信息泄露 5. **权限控制**: 以最小权限原则运行服务 ## 性能优化 1. **日志级别**: 生产环境建议使用`INFO`或`WARN`级别 2. **资源释放**: 确保及时释放设备资源 3. **缓存策略**: 合理使用设备状态缓存 4. **并发控制**: 避免高频调用导致硬件卡死 ## 浏览器兼容性 - Chrome 90+ - Edge 90+ - Firefox 88+ - Safari 14+ 支持现代浏览器，不支持IE浏览器。 ## 技术支持 ### 文档 - [政务外网部署方案](docs/政务外网部署方案.md) - [开发调试操作流程](docs/开发调试操作流程.md) - [客户端部署实施文档](docs/客户端部署实施文档.md) - [常见故障排查手册](docs/常见故障排查手册.md) - [前端集成指南](frontend/README.md) ### 常见问题 如遇问题，请提供以下信息： - 系统版本（Windows 7/10/11，32位/64位） - Node.js版本（`node -v`） - Python版本（`python --version`） - 错误日志（`logs/` 目录下的日志文件） - 错误截图或错误信息 ## 许可证 MIT License ## 更新日志 ### v1.0.0 (2024-06-16) - 初始版本发布 - 支持精伦IDR210读卡器 - 提供完整的HTTP API接口 - 支持前端React组件集成 - 提供生产级错误处理和日志记录 - 自动检测系统位数并选择对应DLL - 提供64位和32位便携包 - 使用Python ctypes调用DLL - 支持政务外网环境部署 ## 致谢 感谢精伦公司提供的IDR210读卡器SDK和技术支持。 --- **注意**: 本项目仅供政务内网使用，请确保在合法合规的环境下部署和使用。