CLAUDE.md

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

仓库性质

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

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

这两个名字极易混淆，改动 URL 时务必区分。xxxig-proxy 是 XMRig-Proxy（Monero/RandomX 矿机代理）的定制/换名构建，已移除捐献功能。

整体架构：单二进制

编译产出单个可执行文件 xxxig-proxy：矿机代理服务，监听矿机接入并把算力聚合转发到上游矿池，降低矿池侧连接数。配置来自源码 src/config.json。

与矿工项目 xxxig 的关键差异：矿工是 xxxig / xxxigDaemon / xxxigServer 三件套 + CC（Central Control）+ Web 控制台；proxy 是单二进制、无 C&C、无 GPU、全静态链接。本仓库的 build-deb.sh / postinst / service 都只处理这一个二进制。

构建与发布流程（CI）

.gitea/workflows/ci.yaml 是 Gitea Actions 流水线：

build-and-test（矩阵 arch=[amd64,arm64]，跑在对应架构的原生 runner 上）：用 docker buildx 按 docker/Dockerfile 原生编译 → 打成 tar.gz → 调 debian/build-deb.sh 打 .deb → 上传 artifact。
release（仅 tag 触发）：下载 artifact，上传 tar.gz 到 Generic Package Registry、上传 .deb 到 Debian Registry（stable/main），并用 jq 生成描述创建 Gitea Release。

关键点：

版本号硬编码在 ci.yaml 的 PACKAGE_VERSION: "6.26.2"（纯数字，符合 Debian 版本规范），发版改这里。关键分界：上游源码 git tag 带 v（CI 用 XXXIG_PROXY_VERSION=v${PACKAGE_VERSION} 检出 v6.26.2），而 tar.gz/deb/registry 路径等包版本一律用数字；release job 用 VERSION="${TAG#v}" 归一，build-deb.sh 用 DEB_VERSION="${VERSION#v}" 归一。
Dockerfile build-arg 名为 XXXIG_PROXY_VERSION（注意 _PROXY_，与矿工的 XXXIG_VERSION 区分），ci.yaml 与两个 Dockerfile 三处必须一致。
静态构建（musl，对齐矿工）：Dockerfile 先 cd scripts && ./build_deps.sh 编译静态 libuv/OpenSSL 到 scripts/deps，再 cmake .. -DXMRIG_DEPS=scripts/deps -DBUILD_STATIC=ON 全静态链接（proxy 的 cmake/OpenSSL.cmake 仅在 WIN/APPLE 下设静态，Linux 靠 flags.cmake 在 BUILD_STATIC 下加 -static 强制全静态）。产物 ldd 为 "not a dynamic executable"，任意发行版可跑。docker/Dockerfile 基于 alpine:latest（musl libc）。
为何必须用 musl 而非 glibc（关键，勿改回）：glibc 的 getaddrinfo 依赖运行时 dlopen NSS 模块（libnss_*.so），-static 全静态后无法加载，跨 glibc 版本运行时 DNS 解析直接失败——表现为 DNS error: "resource busy or locked"（getaddrinfo 返回 EAI_SYSTEM + errno=EBUSY，libuv 经 uv__getaddrinfo_translate_error 转成 UV_EBUSY，见 src/base/net/dns/DnsUvBackend.cpp）。musl 的 getaddrinfo 自带实现、不依赖 NSS dlopen，全静态也能正常解析。曾用的 glibc(ubuntu:20.04) 全静态构建线因此被删除。
架构名映射：x86_64→amd64、aarch64→arm64。
tar.gz 下载 URL 形如 https://gitea.bcde.io/api/packages/wangdefa/generic/xxxig-proxy/{version}/xxxig-proxy-{arch}-linux-static-{version}.tar.gz。

本地常用命令

# 本地编译某架构/发行版的二进制（输出到 ./output/linux_<arch>/）
docker buildx build --platform linux/amd64 \
  --build-arg XXXIG_PROXY_VERSION=v6.26.2 \
  --output type=local,dest=./output \
  -f docker/Dockerfile .

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

# 改 shell 脚本后做静态检查（需自行安装 shellcheck）
shellcheck debian/*.sh

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

Debian 包布局与服务

二进制装到 /opt/xxxig-proxy/，systemd 服务文件 debian/xxxig-proxy.service，维护脚本 debian/{postinst,prerm,postrm}。
postinst 创建 xxxig-proxy 系统用户、把默认配置复制到 /etc/xxxig-proxy/config.json、/opt 归 root:root（目录/二进制 755、数据文件 644）。服务不自动启用/启动（默认上游 localhost 无效），升级时仅 try-restart 已在运行的服务。
本仓库不含 script/ 安装脚本（与矿工项目不同），.deb 安装后需用户手动 systemctl enable --now xxxig-proxy。
运行时依赖：产物 musl 全静态（含 OpenSSL/libuv），无任何外部动态库依赖（ldd 为 "not a dynamic executable"）；control.template 的 Depends: libc6 对 musl 静态并非必需，仅作保守声明（deb 安装环境必有 libc6，无害）。改用静态构建正是为修复动态链接 OpenSSL 1.1 在新发行版上 libssl.so.1.1 not found 的问题。源码 scripts/（build_deps/build.uv/build.openssl3）由矿工项目移植、去掉 hwloc。

5.2 KiB Raw Permalink Blame History Unescape Escape