121 lines
4.4 KiB
Markdown
121 lines
4.4 KiB
Markdown
# readcard-go
|
||
|
||
## GUI 读卡界面
|
||
|
||
双击打包后的 `readcard-go.exe` 会启动桌面读卡界面和后台 HTTP 服务。点击“读卡”后，成功时显示二维码，内容格式为：
|
||
|
||
```text
|
||
encodeURIComponent(Name)|IDNum|CardNum|CardIDCode
|
||
```
|
||
|
||
失败时错误原因显示在二维码下方。GUI 默认使用杭州免 PIN 读卡器类型，可在 `config.json` 中修改：
|
||
|
||
```json
|
||
"gui_reader_type": "ZJ_HZ_310000"
|
||
```
|
||
|
||
Windows Common Controls v6 清单已通过 `rsrc_windows_386.syso` 嵌入 EXE，用于避免 GUI 启动时出现 `TTM_ADDTOOL failed`。`readcard-go.exe.manifest` 是资源的源文件；如修改该文件，需要重新生成对应的 `.syso` 资源。
|
||
|
||
`card-read-service` 的 Go 版本，保持原有 HTTP 接口和响应格式，并增加业务失败、panic、DLL 崩溃与异常退出日志。
|
||
|
||
## 构建和运行
|
||
|
||
### 打包环境要求
|
||
|
||
执行打包操作的电脑必须已经安装 Go 开发环境，并且 `go` 命令已加入系统 `PATH`。可以在命令行中执行以下命令检查：
|
||
|
||
```powershell
|
||
go version
|
||
```
|
||
|
||
能够正常输出 Go 版本信息即可，例如：
|
||
|
||
```text
|
||
go version go1.26.5 windows/amd64
|
||
```
|
||
|
||
不需要另外安装 32 位 Go。厂商 `CardReaderDLL.dll` 是 32 位 DLL，打包脚本会自动设置 `GOOS=windows`、`GOARCH=386` 和 `CGO_ENABLED=0`，使用常规的 64 位 Go 环境即可生成 32 位程序。
|
||
|
||
最终使用 `dist/readcard-go.exe` 的电脑不需要安装 Go 环境，但必须复制完整的 `dist` 目录，不能只复制 exe 文件。
|
||
|
||
### 执行打包
|
||
|
||
在 PowerShell 中执行：
|
||
|
||
```powershell
|
||
.\build.ps1 -Version "1.0.0"
|
||
.\dist\readcard-go.exe
|
||
```
|
||
|
||
也可以直接双击项目根目录下的 `一键打包.bat`。脚本会自动调用 PowerShell 完成测试、构建和厂商依赖复制，成功后自动打开 `dist` 发布目录；打包版本可修改批处理文件顶部的 `BUILD_VERSION`。
|
||
|
||
在 macOS 中可使用 `一键打包.sh` 交叉编译 Windows 32 位产物：
|
||
|
||
```bash
|
||
chmod +x ./一键打包.sh
|
||
./一键打包.sh
|
||
```
|
||
|
||
只检查打包环境、不执行构建：
|
||
|
||
```bash
|
||
./一键打包.sh --check
|
||
```
|
||
|
||
macOS 脚本会检查 Go 版本和 `windows/386` 目标，编译 Windows 测试程序（不在 macOS 上运行），生成 `dist/readcard-go.exe`，并复制 `config.json` 和完整的厂商 DLL 目录。最终产物仍需在 Windows 真机上验证。
|
||
|
||
构建脚本会运行测试、生成 `dist/readcard-go.exe`，并把原项目的 `package/DWCardReaderDLL` 复制到发布目录。开发运行可执行：
|
||
|
||
```powershell
|
||
.\run.ps1
|
||
```
|
||
|
||
启动后：
|
||
|
||
- 健康检查：`GET http://127.0.0.1:17880/health`
|
||
- 免 PIN 读卡：`POST http://127.0.0.1:17880/api/card/read-nopin`
|
||
- 嘉兴带 PIN 读卡：`POST http://127.0.0.1:17880/api/card/read`
|
||
- HMAC-SM3：`POST http://127.0.0.1:17880/api/hmac-sm3`
|
||
|
||
免 PIN 读卡示例：
|
||
|
||
```powershell
|
||
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:17880/api/card/read-nopin `
|
||
-ContentType "application/json" `
|
||
-Body '{"reader_type":"ZJ_HZ_310000"}'
|
||
```
|
||
|
||
## 日志
|
||
|
||
日志默认写入程序目录下的 `logs`：
|
||
|
||
- `service-组件-YYYY-MM-DD.log`：启动、配置、DLL 加载、HTTP 失败、读卡失败、panic 堆栈和自动重启记录。
|
||
- `crash-YYYY-MM-DD.log`：工作进程写到标准错误的 Go runtime/native crash 信息。
|
||
|
||
日志达到 `log_max_file_mb` 后自动生成 `-001`、`-002` 分卷；日志目录超过 `log_max_total_mb` 时优先删除最旧分卷，同时仍按 `log_retention_days` 清理过期日志。默认单文件最大 20MB、目录总量最大 200MB、保留 30 天。
|
||
|
||
程序默认由守护进程启动工作进程。若 DLL 导致工作进程直接崩溃，守护进程会记录 PID、退出码、运行时长并自动重启；30 秒内连续崩溃达到 `max_rapid_restarts` 后停止，避免无限重启。日志不会记录身份证号、卡号、密钥或请求正文。
|
||
|
||
## 配置
|
||
|
||
`config.json`：
|
||
|
||
```json
|
||
{
|
||
"host": "127.0.0.1",
|
||
"port": 17880,
|
||
"dll_dir": "package/DWCardReaderDLL",
|
||
"cors_origin": "*",
|
||
"log_dir": "logs",
|
||
"log_retention_days": 30,
|
||
"log_max_file_mb": 20,
|
||
"log_max_total_mb": 200,
|
||
"restart_delay_ms": 1500,
|
||
"max_rapid_restarts": 5
|
||
}
|
||
```
|
||
|
||
支持环境变量：`CARD_HOST`、`CARD_PORT`、`CARD_DLL_DIR`、`CARD_CORS_ORIGIN`、`CARD_LOG_DIR`、`CARD_LOG_MAX_FILE_MB`、`CARD_LOG_MAX_TOTAL_MB`。调试时设置 `CARD_NO_SUPERVISOR=1` 可直接运行工作进程。
|
||
|
||
接口行为和 `reader_type` 列表请参照原项目 `card-read-service/README.md`。
|