From 8010a3e73e83baa91f93d6353fbc975516c345d1 Mon Sep 17 00:00:00 2001 From: Wang Defa <1+wangdefa@noreply.gitea.bcde.io> Date: Tue, 9 Jun 2026 12:01:08 +0800 Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84=20deb=20=E6=89=93=E5=8C=85?= =?UTF-8?q?=E5=81=A5=E5=A3=AE=E6=80=A7=EF=BC=8C=E8=A1=A5=E5=85=85=20README?= =?UTF-8?q?=20=E4=B8=8E=20.gitignore?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- .gitignore | 6 +++- CLAUDE.md | 74 +++++++++++++++++++++++++++++++++++++++ README.md | 77 +++++++++++++++++++++++++++++++++++++++++ debian/build-deb.sh | 2 ++ debian/control.template | 2 +- debian/postinst | 6 ++-- 6 files changed, 163 insertions(+), 4 deletions(-) create mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore index 10d13ea..c35c48a 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,8 @@ .idea .DS_Store -CLAUDE.md \ No newline at end of file +# 构建产物 +*.deb +*.tar.gz +output/ +packages/ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b0a32d9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,74 @@ +# 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_/） +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 会自动生成。 diff --git a/README.md b/README.md index e69de29..490f821 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,77 @@ +# XXXig + +XXXig 是 [XMRig](https://github.com/xmrig/xmrig) 的定制构建——带 CC（Central Control 集中管理）功能的 RandomX CPU 挖矿软件套件。 + +**本仓库只包含构建与打包基础设施**，不含矿机源码：二进制在 CI 中从上游源码仓库 `github.com/wangdefaa/xxxig` 编译，再打包分发到 [gitea.bcde.io](https://gitea.bcde.io) 的 Generic / Debian 包仓库。 + +## 产物 + +每次构建产出三个可执行文件（CPU-only，静态链接 libuv/OpenSSL/hwloc，运行时仅依赖 glibc）： + +| 二进制 | 作用 | +|---|---| +| `xxxig` | 实际挖矿程序，由 daemon 拉起 | +| `xxxigDaemon` | 守护进程，控制矿机并通过 cc-client 连接中心服务器；安装后作为主服务运行 | +| `xxxigServer` | 中心控制服务器，带 Web UI | + +支持架构 `amd64` / `arm64`，发行版 Ubuntu/Debian、Alpine。 + +## 安装 + +完整参数、服务管理、故障排查见 [script/README.md](script/README.md)。 + +```bash +# tar.gz（通用：Alpine / Ubuntu / Debian） +sudo ./script/install.sh -o pool.example.com:3333 -w YOUR_WALLET + +# APT（Debian / Ubuntu） +sudo ./script/install.deb.sh -o pool.example.com:3333 -w YOUR_WALLET + +# 卸载（自动识别安装方式） +sudo ./script/uninstall.sh +``` + +两种渠道的安装布局不同： + +| | tar.gz | .deb / APT | +|---|---|---| +| 来源 | Generic Package Registry | Debian Package Registry | +| 二进制 | `/etc/miner/xxxig/` | `/opt/xxxig/` | +| 配置 | `/etc/miner/xxxig/config.json` | `/etc/xxxig/config.json`、`config_cc.json` | +| 服务 | 单个 `xxxig` | `xxxig-daemon` + `xxxig-server` | + +## 构建与发布 + +CI 定义于 [.gitea/workflows/ci.yaml](.gitea/workflows/ci.yaml)： + +- **push 到 `main`/`develop`**：矩阵 `arch=[amd64,arm64] × distro=[ubuntu,alpine]`，在原生 runner 上用 Docker 编译为 tar.gz，ubuntu 再打 `.deb`。 +- **打 tag**：产物上传到 Generic / Debian 包仓库并创建 Release。 + +本地构建： + +```bash +# 编译某架构/发行版二进制（输出到 ./output/linux_/） +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 +``` + +## 版本号约定 + +- **上游源码 git tag** 带 `v`（如 `v6.26.0`），CI 用 `XXXIG_VERSION=v${PACKAGE_VERSION}` 检出。 +- **包版本**（tar.gz / deb / registry 路径）一律用数字（如 `6.26.0`），符合 Debian 版本规范。 + +发版只需改 ci.yaml 的 `PACKAGE_VERSION`。 + +## 目录结构 + +``` +.gitea/workflows/ CI 流水线 +docker/ 各发行版 Dockerfile（从上游源码编译） +debian/ .deb 打包：control 模板、维护脚本、systemd 服务 +script/ 安装/卸载脚本 + 详细文档 +``` diff --git a/debian/build-deb.sh b/debian/build-deb.sh index b22c0d3..d250766 100755 --- a/debian/build-deb.sh +++ b/debian/build-deb.sh @@ -14,6 +14,8 @@ TARGZ_FILE=$3 PKG_NAME="xxxig" DEB_VERSION="${VERSION#v}" # Debian 版本号必须以数字开头，去掉可能的 v 前缀 +[ -f "$TARGZ_FILE" ] || { echo "❌ 找不到产物包: $TARGZ_FILE"; exit 1; } + # 转换架构名称（Docker 使用的架构名到 Debian 架构名） case "$ARCH" in amd64) diff --git a/debian/control.template b/debian/control.template index 8697fb8..da5af7f 100644 --- a/debian/control.template +++ b/debian/control.template @@ -3,7 +3,7 @@ Version: {{VERSION}} Section: net Priority: optional Architecture: {{ARCH}} -Depends: libc6, libuv1, libssl3 | libssl1.1, libhwloc15 | libhwloc5 +Depends: libc6 (>= 2.31) Maintainer: XXXig Team Homepage: https://github.com/wangdefaa/xxxig Description: Cryptocurrency mining software suite diff --git a/debian/postinst b/debian/postinst index 773aeac..f7d86b2 100755 --- a/debian/postinst +++ b/debian/postinst @@ -33,9 +33,11 @@ if [ ! -f /etc/xxxig/config_cc.json ]; then chmod 640 /etc/xxxig/config_cc.json fi -# Set permissions +# Set permissions：目录与二进制 755，配置/页面等数据文件 644 chown -R root:root /opt/xxxig -chmod -R 755 /opt/xxxig +find /opt/xxxig -type d -exec chmod 755 {} + +find /opt/xxxig -type f -exec chmod 644 {} + +chmod 755 /opt/xxxig/xxxig /opt/xxxig/xxxigDaemon /opt/xxxig/xxxigServer # Reload systemd if [ -d /run/systemd/system ]; then