简介：cgminer 3.1.1 Windows 版是一份面向比特币及衍生币挖矿软件研究者的多线程、多池矿机程序包，支持 GPU、FPGA 与 ASIC 设备，并带有 ATI 显卡监控、超频和风扇转速调节能力，适合需要了解早期挖矿客户端在 Windows 下运行机制、设备适配与算力调度方式的开发者或爱好者。压缩包共 43 个文件，约 6.83MB，以 txt 说明文档、dll 运行库、bit 与 bin 位流、cl OpenCL 内核、exe 可执行程序、php/java/c API 示例及 conf 配置样例为主，覆盖从依赖库、显卡内核到设备固件和接口调用的多个层面。已有 560 人学习，说明其在挖矿软件资料中具有一定参考热度。读者可从中获得 Windows 平台矿机程序的目录组织、OpenCL 内核适配、API 接入示例、FPGA 位流文件及构建与使用说明等线索，便于分析多池切换、设备监控和超频参数设置等实现思路；需注意该版本明确要求不要同时用于多条区块链。

1. 拆开 cgminer 3.1.1 windows 包之前，先想清楚你要的是哪一条路径

在 Windows 上折腾 cgminer 3.1.1，真正卡住人的从来不是算法，而是这个 windows 包太老：它依赖的运行库、驱动接口、编译链，在这十几年里基本都换过一轮。3.1.1 属于 3.x 末期版本，是少数还同时保留 GPU（OpenCL）路径与串口设备路径的分支，命令行参数、JSON 配置格式、4028 端口 API 协议都在这个版本上定型。翻出这个包的人一般干三件事：验证老显卡还能不能被枚举出来、把老配置文件嫁接到新工具上做对照、或者干脆从源码重建一遍确认行为差异。这三条路的前置条件和踩坑位置完全不同，混着走最容易翻车。适合手上有闲置机器、愿意看日志、能接受命令行的人；想要双击 exe 就出结果，这个包会让你失望。

2. 目录与运行前置：三分钟判断这个 windows 包能不能直接启动

拿到压缩包先别急着解压到桌面。Windows 下这类老程序的路径解析对中文和空格都不友好，放到D:\tools\这类纯英文短路径下，后面排查 DLL 缺失能少一半干扰。

2.1 发行包里真正需要动的文件只有三类

一个典型的 3.1.1 Windows 发行包，根目录下是cgminer.exe加若干个 DLL，旁边放cgminer.conf（或example.conf），再有一个doc目录装说明文档。真正需要你关心的只有三类：exe 本体、与它同目录的 DLL、以及配置文件。doc 目录里那份说明写于 2013 年，参数名大体还能对上，但里面提到的驱动版本要求早就失效了，只能当历史参考看，别照着它去装驱动。

判断依赖是否齐全，最不该用的方法就是双击。双击要么窗口一闪而过，要么弹一个「应用程序无法正常启动 (0xc000007b)」的框——这个错误码既可能是缺 DLL，也可能是位数不匹配，信息量太低，等于没告诉你任何东西。正确做法是开一个 cmd 窗口，让程序在能留住输出的环境里跑一次。

:: 进入解压目录，路径保持纯英文、无空格 cd /d D:\tools\cgminer-3.1.1-win32 :: 先看同目录到底带了哪些动态库，肉眼数一遍 dir /b *.dll :: 最轻量的探针：只加载动态库并打印版本，不进主循环 cgminer.exe --version

--version这个参数的价值在于它是整个程序里最早发生动态链接的入口。缺哪个 DLL，Windows 加载器会在这里把文件名完整报出来，而不是等到 OpenCL 初始化阶段才含糊地退出。如果这一步能打印出版本号，说明 exe 与同目录 DLL 的匹配关系没问题，可以往下走；如果报「找不到 XXX.dll」，就拿着这个名字去发行包或系统目录里找，别猜。

接下来确认 OpenCL 运行时在不在。这里有个很容易被忽略的细节：64 位 Windows 上，C:\Windows\System32放的是 64 位库，32 位库在C:\Windows\SysWOW64。名字是反的，很多人第一次查会查错地方。

:: 分别确认两个位数目录下是否存在 OpenCL 运行时 where /r C:\Windows\System32 OpenCL.dll where /r C:\Windows\SysWOW64 OpenCL.dll

哪个目录下有，就说明系统装了哪个位数的 OpenCL 运行时。3.1.1 的 Windows 包绝大多数是 32 位的，它只能加载SysWOW64里那份。如果只有System32有，程序就会在枚举设备时报「No devices found」——这个报错看起来像显卡坏了，实际上只是位数对不上。

2.2 三条硬门槛：驱动、OpenCL 运行时、位数

第一条是显卡驱动。3.1.1 走 OpenCL，需要驱动里自带的 OpenCL 运行时，而不是单纯的显示驱动。很多精简版驱动包会把 OpenCL 组件裁掉，装完系统能正常显示，但 OpenCL 平台枚举为空。判断办法很简单：程序启动日志里会打出类似CL Platform 0: ...的行，如果一行平台信息都没有，就是运行时这一层断了，跟 cgminer 本身无关。

第二条是位数一致性。这条前面说过，但要再强调一次：exe 的位数、OpenCL 运行时的位数、驱动安装包的位数，三者必须对齐。任何一处错位，症状都是「设备数 0」，而且不会有任何提示告诉你错在哪。

第三条是设备被其他进程独占。老版本驱动对 OpenCL 设备的上下文管理比较粗糙，如果同时开着监控类工具或者另一个占用同一块设备的程序，cgminer 可能在枚举阶段就拿不到设备句柄。排查时先把这类常驻程序关掉再试。

提示：先跑--version，再跑不带任何设备参数的启动，看日志里平台和设备枚举那几行。这两步能把「依赖问题」和「设备问题」彻底分开，比对着报错乱改配置有效得多。

2.3 用最小命令行跑通一次握手

依赖确认完，先用最短的命令行参数跑一次，不要一上来就加载 conf。配置文件里任何一个字段写错，都会让启动失败得莫名其妙，而命令行能让你精确定位到是哪一步出的问题。

# 最小启动：池地址、账号、密码，加文本日志和调试输出 cgminer.exe \ -o stratum+tcp://127.0.0.1:3333 \ -u worker1 \ -p x \ -T -D \ -L cgminer.log

参数逐个说清楚：-o指定 stratum 服务端地址，127.0.0.1:3333是占位，换成你实际要连的地址；-u和-p是账号与口令，口令留x在很多服务端上是可接受的占位值；-T强制纯文本日志，避免 Windows 控制台转义序列把输出搅乱；-D打开调试级别输出，第一次跑必须开，否则握手阶段的细节全被吞掉；-L把同样的内容落一份到文件，方便事后翻。

启动后按顺序确认四件事：第一行版本号是不是 3.1.1；有没有CL Platform行；设备枚举数量对不对；最后有没有出现Stratum from pool 0 detected new block之类表示握手成功的行。这四行都对了，说明这条链路是通的，剩下的才是参数调优。任何一行不对，就停在这里解决，别急着改 intensity。

3. 从源码重建：MinGW32 工具链、四个 configure 参数和三类链接错误

二进制包能跑，不代表你理解它。不少人重建 3.1.1 的目的是为了改一处日志、加一个自定义字段，或者纯粹为了确认发行包里的 exe 有没有被改过。这条路比直接用二进制麻烦，但对排查玄学问题有决定性帮助。

3.1 为什么不用 MSVC：3.1.1 的 autotools 链路只认 POSIX

3.1.1 的构建系统是 autotools 生成的，configure脚本里塞满了 POSIX 检查：fork、pthread、sys/time.h、termios、unistd.h。MSVC 没有这些东西，想用它编译等于重写一遍移植层，工作量远超收益。MinGW 提供了一层 POSIX 兼容封装再加上 Win32 API，是这条路上最省力的选择。

工具链位数上我一般选i686（32 位）而不是x86_64。原因很实际：那个年代的 OpenCL 头文件和预编译库以 32 位最齐全，libusb的 Windows 预编译包也是 32 位版本更完整；另外 3.1.1 的Makefile.am里针对mingw32的条件分支写得比 64 位多，能少踩几个坑。这不是理论最优，是当年能跑通的组合。

需要准备的组件包括：MinGW32 基础工具链、MSYS 基础环境、pthreads-w32开发包、libcurl开发包、libusb开发包，以及 OpenCL 头文件CL/cl.h。最后这个不一定随驱动装，很多时候要手工放进 include 路径。

# 在 MSYS 环境里先确认工具链本身可用 which gcc gcc -dumpmachine # 确认几个关键头文件和静态库的落点，configure 就是靠这些路径找依赖 ls /usr/local/include/CL/cl.h ls /usr/local/include/curl/curl.h ls /usr/local/lib/libcurl.a ls /usr/local/lib/libpthread.a

gcc -dumpmachine输出mingw32或i686-w64-mingw32都算正常，前者是老的 MinGW，后者是 MinGW-w64 的 32 位目标。后面configure里的路径要按这个输出调整。上面几个ls任何一个报「No such file」，就先把它补上再继续，别指望 configure 能自己找到。

3.2 依赖清单与 configure 参数逐个过

第一次编译我的习惯是先把所有可选功能全关掉，确保能产出一个能跑的 exe，再一个一个打开。这样任何一次失败都能定位到刚打开的那个开关上。

# 第一轮：关掉所有需要外部 SDK 的路径，只验证主链路能编译 ./autogen.sh \ --disable-opencl \ --disable-adl \ --disable-libusb \ CFLAGS="-O2 -fno-strict-aliasing -I/usr/local/include" \ LDFLAGS="-L/usr/local/lib -static-libgcc"

参数含义：--disable-opencl关掉 GPU 路径，避免 OpenCL 头文件问题干扰主链路验证；--disable-adl绕开显卡厂商 SDK 的适配层，那套头文件在非官方环境下基本找不到；--disable-libusb关掉 USB 设备支持，因为libusb的头文件路径在不同发行版里差异最大；CFLAGS里的-I手工补上依赖的头文件目录；LDFLAGS里的-static-libgcc把 gcc 运行时静态链进去，避免 exe 拿到别的机器上又缺libgcc_s_dw2-1.dll。

第一轮通过之后，第二轮再把开关打开：

# 第二轮：恢复 OpenCL 与 USB 路径，验证真实功能 ./autogen.sh \ --enable-opencl \ --disable-adl \ --enable-libusb \ CFLAGS="-O2 -fno-strict-aliasing -I/usr/local/include" \ LDFLAGS="-L/usr/local/lib -static-libgcc" make -j2

-j2而不是-j8，是因为这套老 Makefile 的依赖声明不严密，并行度开太高会偶发「找不到刚生成的目标文件」。这类错误看起来像源码问题，实际是构建顺序问题，第一次遇到很容易被带偏。

3.3 三类链接错误和 Makefile 改法

编译阶段最容易撞上的就三类，且都不是源码的问题。

第一类，undefined reference to 'pthread_create'。现象是编译全部通过，链接最后一步炸掉，报一串pthread_*符号未定义。原因是-lpthread没进链接命令，或者进去了但位置不对。GNU ld 是单遍扫描的，库必须放在引用它的目标文件之后。查当前链接命令最直接：

# 打印实际的链接命令行，看 -lpthread 排在什么位置 make V=1 2>&1 | grep -E "gcc|ld .* -o cgminer"

如果-lpthread出现在.o列表前面，把它挪到最后；如果压根没有，就在Makefile的LIBS变量末尾补上。

第二类，fatal error: curl/curl.h: No such file or directory。这是预处理阶段就失败，说明头文件路径没进去。libcurl在 MSYS 下常装在/usr/local/include/curl/，而源码里写的是#include <curl/curl.h>，所以-I要指到/usr/local/include这一层，指到curl目录里反而找不到。

第三类，undefined reference to 'curl_easy_init'。头文件找到了，但静态库没链上，或者同样犯了顺序错误。老版本libcurl.a还依赖-lws2_32、-lwldap32、-lz一串东西，少一个就会在链接末期爆出一大堆符号缺失，看起来跟 curl 毫无关系。

# Makefile 里的 LIBS 行，被依赖的库放后面，顺序不能随意调 LIBS = -lws2_32 -lwldap32 -lz -lcurl -lpthread -lm

改完重新make clean && make。这里必须clean，因为链接命令变了但目标文件没变，make 会认为.o是最新的，直接跳到链接，你改的东西等于没生效。这个坑我吃过不止一次：明明改了LIBS，重编还是同样的错误，反复折腾半小时才发现是没清。

4. cgminer.conf 逐项拆解：intensity、worksize、thread-concurrency 的联动怎么调

配置是这个包里最容易出事的部分。3.1.1 用 JSON 格式存配置，字段名和命令行参数一一对应，但不是所有参数都能靠命令行覆盖，有些只能在 conf 里改。

4.1 配置骨架与命令行覆盖的优先级

先看一份能启动的最小完整配置。

{ "pools": [ { "url": "stratum+tcp://127.0.0.1:3333", "user": "worker1", "pass": "x" } ], "api-listen": true, "api-port": "4028", "api-allow": "W:127.0.0.1", "intensity": "9", "worksize": "128", "thread-concurrency": "8192", "vectors": "1", "gpu-engine": "0", "gpu-memclock": "0", "scan-time": "60", "expiry": "120", "queue": "1", "log": "5", "verbose": true }

要特别注意api-port、intensity这些字段的值都是字符串，写"4028"而不是4028。3.1.1 的 JSON 解析器在某些代码路径上对数字类型做了假设，传数字进去会走到类型不匹配的分支，表现是配置被静默忽略、程序用默认值启动——这种「配置看起来生效了但实际没生效」的问题最难查，因为没有任何报错。

覆盖优先级需要理清：命令行参数 > conf 文件 > 编译期默认值。但pools数组是个例外——命令行上给一次-o会整体替换掉 conf 里的pools数组，而不是追加。所以调试阶段用命令行覆盖池地址时，别指望 conf 里配的三个池还能剩两个。

注意：3.1.1 在正常退出和收到保存命令时会把内存里的配置写回cgminer.conf。JSON 序列化会丢掉所有注释、打乱键顺序、把字符串引号风格统一。想保留人工排版的版本，就别让它直接写原文件。

4.2 显卡三参数：intensity / worksize / thread-concurrency 的联动

这三个参数不是独立的，动一个基本要跟着动另外两个，否则很容易出现「能跑但算力对不上」或者「跑几分钟就 Hardware Errors 暴涨」的情况。

intensity控制每轮提交给设备的工作量。值越高单次提交越重、中断越少、效率越高，但对显存和时序的要求也越苛刻。9 是个比较稳的起点，往 10、11 走之前先确认设备温度能压住。

worksize是 OpenCL kernel 的局部工作组大小，必须是 2 的幂，且不能超过设备的最大工作组尺寸。128 在多数设备上安全，256 有时能提一点效率，但一旦超过硬件上限，程序会直接初始化失败。

thread-concurrency是同时并发的线程数，设 0 表示让 cgminer 自己算。手动设的时候，经验做法是从「设备流处理器数量 ÷ 2」开始，往上每次加 512 试一组，观察MHS av和Hardware Errors的比值，找到错误率开始抬升之前的那一档就停。

单变量对照是这个环节唯一靠得住的方法。一次只改一个值，跑够十分钟再下结论。

# 用命令行临时覆盖 intensity 做对照，不污染已保存的 conf cgminer.exe -c cgminer.conf -I 8 -T -D -L test_I8.log

-I是intensity的短参数，-c显式指定配置文件。之所以用-c而不靠默认路径，是因为工作目录一变，cgminer 就找不到 conf、直接按默认值启动，你会以为参数生效了，其实什么都没改。

判读结果只看两个数的走向：MHS av是否随 intensity 上升而上升，Hardware Errors是否同步暴涨。前者涨后者也涨，说明过了拐点，回退一档；前者不涨后者也不涨，说明瓶颈在别处，通常是设备温度触发了降频。

4.3 API 段与日志段的配置

api-listen打开之后程序才监听 4028 端口，api-port指定端口号，api-allow控制谁能连。语法是「权限前缀 + 冒号 + 地址」，W:表示可读写，R:表示只读，地址可以是单个 IP，也可以是网段。

只做监控的话，用R:前缀比W:安全得多，避免误发写命令把运行中的实例搞停。本机监控就写"api-allow": "R:127.0.0.1"，不要图省事写通配。3.1.1 在api-allow缺省或为空时是拒绝所有连接的，这个默认行为是安全的，但也意味着「配了 api-listen 却连不上」时，第一嫌疑对象就是这一行。

log字段控制日志详细程度，值越大输出越细，5 是常见的调试档位。长期运行的时候建议降到 2 或 3，否则日志文件增长速度会超出预期，一晚上几个 G 并不罕见。scan-time和expiry是缓存与超时相关的时间参数，单位是秒，默认值在单池场景下一般够用，多池切换频繁时才需要调小expiry。

5. 排错清单：五条从日志和任务管理器能直接定位的踩坑记录

这些是我自己撞过、也在别人机器上复现过的。每一条都按「看到什么 → 为什么 → 怎么处理」的顺序写，照着对症状查就行。

5.1 五条高频问题的定位路径

第一条：双击闪退，什么都看不到。

现象是双击cgminer.exe，黑窗口一闪而过，事件查看器里没有应用崩溃记录。

原因有两层：一是缺 DLL，Windows 加载器在还没进入main之前就终止了进程；二是 OpenCL 初始化失败后代码直接exit，没走异常路径。两种情况在双击场景下都无法看到输出。

解决方式是永远从 cmd 启动，用cgminer.exe -T -D跑，把最后一行完整贴出来。如果连版本号都没打印出来，就是加载器层面的问题，重点查 DLL；如果打印了版本号但后面断了，重点查 OpenCL。

第二条：No devices found，但显卡明明是好的。

现象是启动日志里有CL Platform行，但设备数是 0，或者干脆平台行为空。

原因是位数不匹配：32 位 exe 只能加载 32 位 OpenCL 运行时，而系统里只装了 64 位那份。另一种可能是精简版驱动裁掉了 OpenCL 组件。

解决办法是先按 2.1 里那两条where命令确认两个位数目录的情况，不对就补装对应位数的驱动组件。补完之后还不行，就用--disable-opencl编译一个版本，先确认非 GPU 路径能跑通，把问题范围缩小到「GPU 这一层坏了」还是「整个程序坏了」。

第三条：配置文件被程序改写了。

现象是手工排好版的 conf，加了缩进和注释，跑过一次之后注释全没了、键顺序也变了，回头看 diff 一脸懵。

原因是程序在正常退出时会重写配置文件，JSON 序列化不保留注释，键顺序由内存里的哈希表决定。

解决办法是把「可编辑版」和「运行版」分开：编辑版放 git，运行前拷贝一份到-c指向的路径，跑完再从 git 恢复。想让配置绝对不被回写，就把那份文件设成只读属性，程序写失败会打一条日志但继续运行。

第四条：4028 端口连不上。

现象是telnet 127.0.0.1 4028直接返回连接被拒绝，或者连上之后立刻断开。

原因按概率排：api-listen没开；api-allow为空导致全部拒绝；Windows 防火墙拦了这条入站规则；端口被上一个没退干净的实例占着。

解决办法是在 conf 里同时确认"api-listen": true、"api-port": "4028"、"api-allow": "R:127.0.0.1"三项，然后到防火墙的入站规则里给cgminer.exe放行专用网络。本机自测不建议直接关防火墙，加白名单更省事。

第五条：启动报端口绑定失败，或者 API 返回的还是旧数据。

现象是第二次启动时报bind failed，或者虽然启动成功，但 API 返回的设备状态和上次一模一样。

原因是上一个cgminer.exe进程没真正退出。这类程序在关闭控制台窗口时不一定会走清理逻辑，进程可能还在后台挂着，端口自然还被占着。

解决办法是先列进程再杀：

:: 列出所有 cgminer 进程，注意可能有多个 tasklist /FI "IMAGENAME eq cgminer.exe" :: 确认后强制结束，避免残留进程占着 4028 taskkill /F /IM cgminer.exe

/F是强制终止，会跳过正常的清理流程。因为是残留进程，本来也不会正常清理，强制是合理的。杀完再确认一次 4028 没人监听，然后重启。

5.2 日志里该盯的四个字段

启动成功之后，日志会周期性打印统计行。四个字段的信息量最大：Accepted表示被服务端接受的工作量，只增不减才对；Rejected表示被拒绝的，偶尔一两次正常，持续增长说明账号或者握手有问题；Hardware Errors表示设备层面的计算错误，稳定为 0 或者极慢增长是正常的，一晚上涨几百就是参数配过头了；MHS av是平均速率，单独看意义不大，要和瞬时速率对比着看。

判断设备是否健康，看的是MHS av与瞬时速率之间的差距。两者接近说明稳定；瞬时速率反复掉到平均值的一半以下再爬回来，基本可以断定是温度触发了降频，这时候该动的是散热，不是继续调 intensity。

6. 用 4028 端口的 API 做运行验证：summary、devs、pools 三个返回怎么读

图形界面不可靠、日志又会滚动，真正能拿来做自动化验证的只有 API。3.1.1 的 API 是明文 TCP，协议很简单：连上 4028，发一行 JSON 命令加换行符，服务端回一段 JSON。不需要任何第三方库，标准库就够。

6.1 一个不依赖第三方库的 API 探针

import json import socket def rpc(host="127.0.0.1", port=4028, command="summary", timeout=3): """向 cgminer 的 4028 端口发一条命令并解析返回的 JSON。 command 常见取值: summary / devs / pools / config / stats """ with socket.create_connection((host, port), timeout=timeout) as s: # 协议要求命令以换行结尾，缺了这个换行服务端会一直等 s.sendall((json.dumps({"command": command}) + "\n").encode("utf-8")) buf = b"" while True: chunk = s.recv(4096) if not chunk: break # 服务端发完即关连接，读到空即为结束 buf += chunk # 老版本可能吐出非 UTF-8 字节，用 ignore 兜底，避免整段解析失败 return json.loads(buf.decode("utf-8", "ignore")) if __name__ == "__main__": res = rpc(command="summary") print(json.dumps(res, indent=2, ensure_ascii=False))

几个地方值得说明。\n不能省，这是这套协议最容易出错的地方，缺了它服务端会一直阻塞等待，表现为「连上了但没响应」。recv循环一直读到连接关闭，而不是读一次就返回，因为返回体可能跨多个 TCP 分段。errors="ignore"是给老版本打的补丁，某些统计字段里混着非 UTF-8 字节，严格解码会整段抛异常。

6.2 summary 和 devs 的判读阈值

summary返回的是全局聚合，重点看MHS av、MHS 5s、Accepted、Rejected、Hardware Errors这几项。判读阈值我一般这么用：

devs返回的是逐设备明细，重点看每张卡的Temperature、Fan Speed、GPU Clock、Status。Status除了Alive之外的值都值得停下来看一眼，尤其是间歇性出现的非Alive，通常对应驱动层超时，这类问题在日志里只留一行，在devs里能看到明显的频率分布。

pools返回每个池的连接状态和延迟。多池配置下，Stratum Active标记的是当前生效的那个，如果它长期指向一个延迟很高的池，说明切换策略需要调，通常是expiry设得太大。

6.3 把验证做成定时快照

单次查询只能看到某一时刻的状态，真正有用的是时间序列。我的做法是每 30 秒拉一次summary和devs，把关键字段压成一行追加到 CSV，跑一晚上再用表格工具看曲线。

import csv import time FIELDS = ["MHS av", "MHS 5s", "Accepted", "Rejected", "Hardware Errors"] with open("cgminer_metrics.csv", "w", newline="") as f: writer = csv.writer(f) writer.writerow(["ts"] + FIELDS) while True: try: summary = rpc(command="summary")["SUMMARY"][0] row = [int(time.time())] + [summary.get(k, "") for k in FIELDS] writer.writerow(row) f.flush() # 立即落盘，进程被杀也不丢已采集的数据 except Exception as e: # 采集失败不中断循环，把原因写进行里方便事后定位 writer.writerow([int(time.time())] + [f"ERR:{e}"] + [""] * (len(FIELDS) - 1)) time.sleep(30)

这套东西的价值不在采集本身，而在于它能回答一个日志回答不了的问题：某次Hardware Errors上涨，是发生在温度爬升之后，还是发生在你刚改完 intensity 之后。有了时间对齐的序列，因果一下就能看出来。

从那以后我每次碰这类老版本程序，都强制先跑一遍「依赖检查 → 最小命令行握手 → API 快照」这三步，再动任何配置参数。跳过任何一步，后面调参就是在猜。希望帮到你。

本文还有配套的精品资源，点击获取