xxxig/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

仓库性质

本仓库只包含构建与打包基础设施，不含矿机源码。矿机源码在编译时从外部仓库克隆（见两个 Dockerfile）：

• 源码仓库：github.com/wangdefaa/xxxig.git（注意结尾是 wangdefaa，双 a）
• 发布仓库：Gitea gitea.bcde.io 下的 wangdefa/xxxig（结尾是 wangdefa，单 a）

这两个名字极易混淆，改动 URL 时务必区分。xxxig 是 XMRig（RandomX CPU 矿机）的定制/换名构建，带 CC（Central Control 集中管理）功能。

整体架构：三个二进制

编译产出三个可执行文件，构成 XMRig-CC 的 client/server 架构：

• xxxig —— 实际挖矿程序，由 daemon 拉起
• xxxigDaemon —— 客户端守护进程，控制 xxxig，通过 cc-client 配置连接到中心服务器。这是安装后作为主服务运行的进程
• xxxigServer —— 中心控制服务器，带 Web UI（index.html），daemon 连到它上报/受控

两份配置：config.json（daemon/矿机用）与 config_cc.json（server 用），均来自源码 src/ 目录。

构建与发布流程（CI）

Gitea Actions 拆成两条独立流水线：

1. .gitea/workflows/ci.yml 仅由分支推送触发：先检查版本号和 shell 语法，再用 amd64、arm64 原生 runner 并行编译、执行严格冒烟测试并验证 DEB 包内容；不上传 artifact。
2. .gitea/workflows/release.yml 仅由 tag 推送触发：校验 tag 与 VERSION 一致，双架构原生构建 → tar.gz → DEB → artifact 汇总 → SHA256SUMS → Generic/Debian Registry → Gitea Release。

关键点：

• 根目录 VERSION 是唯一版本来源，内容为不带 v 的纯版本号；发布 tag 可带或不带 v，但归一后必须与 VERSION 完全一致。上游源码 git tag 带 v，CI 构建时自动补回；tar.gz、DEB 和 Registry 路径使用不带 v 的版本。
• 编译选项（docker/Dockerfile，musl 全静态）：-DWITH_CC_CLIENT=ON -DWITH_CC_SERVER=ON -DBUILD_STATIC=ON -DWITH_OPENCL=OFF -DWITH_CUDA=OFF，即 CPU-only 全静态构建；arm64/arm 在对应架构原生 runner 上编译并设 -DARM_TARGET=8/7。
• 为何用 musl(alpine) 而非 glibc（勿改回 glibc 全静态）：glibc 的 getaddrinfo 依赖运行时 dlopen NSS 模块，-static 全静态后无法加载，跨 glibc 版本运行时 DNS 解析失败（errno=EBUSY → libuv UV_EBUSY → DNS error: "resource busy or locked"）。musl 的 getaddrinfo 自带实现，全静态也能正常解析。曾用的 glibc(ubuntu) 构建线已删除。
• 架构名映射：x86_64→amd64、aarch64→arm64。
• tar.gz 下载 URL 形如 https://gitea.bcde.io/api/packages/wangdefa/generic/xxxig/{version}/xxxig-{arch}-linux-static-{version}.tar.gz。

本地常用命令

# 本地编译某架构/发行版的二进制（输出到 ./output/linux_<arch>/）
docker buildx build --platform linux/amd64 \
  --build-arg XXXIG_VERSION="v$(cat VERSION)" \
  --output type=local,dest=./output \
  -f docker/Dockerfile .

# 用已有 tar.gz 打 .deb 包
./debian/build-deb.sh amd64 6.26.0 xxxig-amd64-linux-static-6.26.0.tar.gz

# 改 shell 脚本后做静态检查（仓库未配置，需自行安装 shellcheck）
shellcheck script/*.sh debian/*.sh

无单元测试；CI 中唯一的冒烟测试是解包后跑 xxxigDaemon --version。

两种分发渠道与安装布局（差异很大）

	tar.gz（script/install.sh）	.deb / APT（script/install.deb.sh）
来源	Generic Registry 直接下载解包	加 APT 源后 apt-get install
二进制	/etc/miner/xxxig/（仅 daemon+矿机）	/opt/xxxig/（含 Server）
配置	/etc/miner/xxxig/config.json	/etc/xxxig/config.json、config_cc.json
服务	单个 xxxig（systemd 或 Alpine OpenRC）	xxxig-daemon + xxxig-server（仅 systemd）
默认启用	xxxig	仅 xxxig-daemon（server 需手动 enable）

.deb 的服务文件、维护脚本在 debian/；postinst 不自动启用服务，但 install.deb.sh 会主动 enable daemon。卸载统一用 script/uninstall.sh（自动探测安装方式）。

配置改写逻辑（改动重点：代码重复）

install.sh 与 install.deb.sh 各自维护一份近乎相同的 parse_args / replace_config / configure_cpu_rx / configure_hugepages。修改任何安装参数或配置写入逻辑时，两个文件都要同步改。

• 配置全部用 jq 改写 config.json（矿池 url/user/pass/algo/tls/nicehash、cc-client、donate-level=0 等）。
• CPU 亲和性 configure_cpu_rx：线程数 ≤ 核数一半时 step=2（隔核分配，避开超线程），否则 step=1，生成 cpu.rx 数组（algo 为 panthera 时写 cpu.panthera）。
• 已知差异：install.sh 把 log-file 设为 /etc/miner/xxxig/xxxig.log；install.deb.sh 设为空串（由 systemd 服务用 --log-file 显式指定到 /var/log/xxxig/）。
• 两脚本都会先卸载旧版再装（幂等重装）；缺省 wallet/password/cc-work-id 会自动生成。