wangdefaandClaude Opus 4.8
8010a3e73e
Build and Release / build-and-test (arm64, ubuntu) (push) Successful in 24s
Build and Release / build-and-test (amd64, alpine) (push) Successful in 13s
Build and Release / build-and-test (arm64, alpine) (push) Successful in 6s
Build and Release / build-and-test (amd64, ubuntu) (push) Successful in 0s
Build and Release / release (push) Successful in 28s
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
75 lines
4.9 KiB
Markdown
75 lines
4.9 KiB
Markdown
# 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/workflows/ci.yaml](.gitea/workflows/ci.yaml) 是 Gitea Actions 流水线：
|
||
|
||
1. **build-and-test**（矩阵 `arch=[amd64,arm64] × distro=[ubuntu,alpine]`，跑在对应架构的原生 runner 上）：用 `docker buildx` 按 `docker/Dockerfile.{distro}` 原生编译 → 打成 tar.gz → 仅 ubuntu distro 再调 `debian/build-deb.sh` 打 .deb → 上传 artifact。
|
||
2. **release**（仅 tag 触发）：下载 artifact，上传 tar.gz 到 Generic Package Registry、上传 .deb 到 Debian Registry（stable/main），并创建 Gitea Release。
|
||
|
||
关键点：
|
||
- 版本号**硬编码**在 ci.yaml 的 `PACKAGE_VERSION: "6.26.0"`（纯数字，符合 Debian 版本规范），发版改这里。**关键分界**：上游源码 git tag 带 `v`（CI 用 `XXXIG_VERSION=v${PACKAGE_VERSION}` 检出 `v6.26.0`），而 tar.gz/deb/registry 路径等包版本一律用数字；release job 用 `VERSION="${TAG#v}"` 归一，install 脚本下载时同样 `${version#v}`。
|
||
- 编译选项（两个 Dockerfile 一致）：`-DWITH_CC_CLIENT=ON -DWITH_CC_SERVER=ON -DBUILD_STATIC=ON -DWITH_OPENCL=OFF -DWITH_CUDA=OFF`，即 CPU-only 静态构建。arm64/arm 走交叉编译并设 `-DARM_TARGET=8/7`。
|
||
- 架构名映射：`x86_64→amd64`、`aarch64→arm64`。
|
||
- tar.gz 下载 URL 形如 `https://gitea.bcde.io/api/packages/wangdefa/generic/xxxig/{version}/xxxig-{arch}-{os}-{version}.tar.gz`。
|
||
|
||
## 本地常用命令
|
||
|
||
```bash
|
||
# 本地编译某架构/发行版的二进制（输出到 ./output/linux_<arch>/）
|
||
docker buildx build --platform linux/amd64 \
|
||
--build-arg XXXIG_VERSION=v6.26.0 \
|
||
--output type=local,dest=./output \
|
||
-f docker/Dockerfile.ubuntu .
|
||
|
||
# 用已有 tar.gz 打 .deb 包
|
||
./debian/build-deb.sh amd64 6.26.0 xxxig-amd64-ubuntu-6.26.0.tar.gz
|
||
|
||
# 改 shell 脚本后做静态检查（仓库未配置，需自行安装 shellcheck）
|
||
shellcheck script/*.sh debian/*.sh
|
||
```
|
||
|
||
无单元测试；CI 中唯一的冒烟测试是解包后跑 `xxxigDaemon --version`。
|
||
|
||
## 两种分发渠道与安装布局（差异很大）
|
||
|
||
| | tar.gz（[script/install.sh](script/install.sh)） | .deb / APT（[script/install.deb.sh](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](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 会自动生成。
|