4.4 KiB
readcard-go
GUI 读卡界面
双击打包后的 readcard-go.exe 会启动桌面读卡界面和后台 HTTP 服务。点击“读卡”后，成功时显示二维码，内容格式为：
encodeURIComponent(Name)|IDNum|CardNum|CardIDCode
失败时错误原因显示在二维码下方。GUI 默认使用杭州免 PIN 读卡器类型，可在 config.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。可以在命令行中执行以下命令检查：
go version
能够正常输出 Go 版本信息即可，例如：
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 中执行：
.\build.ps1 -Version "1.0.0"
.\dist\readcard-go.exe
也可以直接双击项目根目录下的 一键打包.bat。脚本会自动调用 PowerShell 完成测试、构建和厂商依赖复制，成功后自动打开 dist 发布目录；打包版本可修改批处理文件顶部的 BUILD_VERSION。
在 macOS 中可使用 一键打包.sh 交叉编译 Windows 32 位产物：
chmod +x ./一键打包.sh
./一键打包.sh
只检查打包环境、不执行构建：
./一键打包.sh --check
macOS 脚本会检查 Go 版本和 windows/386 目标，编译 Windows 测试程序（不在 macOS 上运行），生成 dist/readcard-go.exe，并复制 config.json 和完整的厂商 DLL 目录。最终产物仍需在 Windows 真机上验证。
构建脚本会运行测试、生成 dist/readcard-go.exe，并把原项目的 package/DWCardReaderDLL 复制到发布目录。开发运行可执行：
.\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 读卡示例：
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：
{
"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。