Wang DefaandClaude Opus 4.8
116023cd24
Build and Release / build-and-test (amd64, alpine) (push) Successful in 20s
Build and Release / build-and-test (arm64, alpine) (push) Successful in 42s
Build and Release / build-and-test (amd64, ubuntu) (push) Successful in 27s
Build and Release / build-and-test (arm64, ubuntu) (push) Successful in 9s
Build and Release / release (push) Has been skipped
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
58 lines
4.2 KiB
Markdown
58 lines
4.2 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-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/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），并用 `jq` 生成描述创建 Gitea Release。
|
||
|
||
关键点：
|
||
- 版本号**硬编码**在 ci.yaml 的 `PACKAGE_VERSION: "6.26.0"`（纯数字，符合 Debian 版本规范），发版改这里。**关键分界**：上游源码 git tag 带 `v`（CI 用 `XXXIG_PROXY_VERSION=v${PACKAGE_VERSION}` 检出 `v6.26.0`），而 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 三处必须一致。
|
||
- 构建用 `cmake .. -DCMAKE_BUILD_TYPE=Release`（**动态链接**，依赖 libuv/OpenSSL），与矿工的静态构建不同；Dockerfile.ubuntu 基于 `ubuntu:20.04`（glibc 2.31，与 control.template 的 `libc6 (>= 2.31)` 对齐）。
|
||
- 架构名映射：`x86_64→amd64`、`aarch64→arm64`。
|
||
- tar.gz 下载 URL 形如 `https://gitea.bcde.io/api/packages/wangdefa/generic/xxxig-proxy/{version}/xxxig-proxy-{arch}-{os}-{version}.tar.gz`。
|
||
|
||
## 本地常用命令
|
||
|
||
```bash
|
||
# 本地编译某架构/发行版的二进制（输出到 ./output/linux_<arch>/）
|
||
docker buildx build --platform linux/amd64 \
|
||
--build-arg XXXIG_PROXY_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-proxy-amd64-ubuntu-6.26.0.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`。
|
||
- **已知待办**：proxy 为动态链接（依赖 libuv/OpenSSL），但 control.template 的 `Depends` 目前仅 `libc6`。待 CI 首次构建出产物后用 `ldd` 实测，再补全 `libuv1`、`libssl`（按构建发行版包名，ubuntu 20.04 为 `libssl1.1`，22.04 为 `libssl3`，写错会导致 apt 拒装）。
|