p2pool/CLAUDE.md

CLAUDE.md

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

仓库性质

本仓库只包含构建与打包基础设施，不含 p2pool 源码。源码在编译时从上游克隆（见 docker/Dockerfile）：

• 源码仓库：github.com/SChernykh/p2pool.git（p2pool 官方仓库，非换名）
• 发布仓库：Gitea gitea.bcde.io 下 wangdefa/p2pool 的 Generic / Debian 包仓库

p2pool 是 Monero 去中心化矿池的 sidechain 节点。本项目对上游唯一的定制是 -DWITH_MERGE_MINING_DONATION=OFF（禁用合并挖矿捐赠），不改源码。

与同目录 gitea-xxxig / gitea-xxxig-proxy / gitea-mond 的关系：四者共享同一套 CI / build-deb / debian 打包骨架，且均为 musl fully-static 构建。差异：xxxig 系是 XMRig 换名仓库源码；mond 克隆 Monero 官方靠 init.sh 现场换名；p2pool 直接构建官方源码、不换名，版本号纯数字（4.15.1，上游 git tag 带 v、构建时补回）。

整体架构：单二进制

编译产出单个可执行文件 p2pool：连接 monerod（本地，或经 --rpc-ssl 连外部 SSL 节点）、维护 P2Pool sidechain、提供 stratum 给矿工。配置模板 conf/params.conf.example。

构建与发布流程（CI）

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

1. build-and-test（矩阵 arch=[amd64,arm64]，跑在对应架构原生 runner）：用 docker buildx 按 docker/Dockerfile 原生编译 → 打成 tar.gz → 解包冒烟（p2pool --help + ldd 纯静态校验）→ 调 debian/build-deb.sh 打 .deb → 上传 artifact。
2. release（仅 tag 触发）：下载 artifact，上传 tar.gz 到 Generic Package Registry、上传 .deb 到 Debian Registry（stable/main），并用 python3 生成描述创建 Gitea Release。

关键点：

• musl fully-static（Alpine 构建，勿改回 glibc）：上游 p2pool 官方 release 二进制即用此法（见上游 .github/workflows/c-cpp.yml 的 Alpine static job）。docker/Dockerfile 在 alpine:3.21 下自编 external 静态库（curl/libuv/libzmq）+ 静态 grpc 栈（含 boringssl，WITH_GRPC=ON 支持 Tari 合并挖矿），再 -DSTATIC_BINARY=ON 全静态。产物 ldd = not a dynamic executable、零外部依赖，glibc/musl 任意发行版直接运行（实测 musl 产物在 Debian 13 上正常 --help）。
• 为何用 musl 而非 glibc：musl 的 getaddrinfo 自带实现，全静态也能解析 DNS；glibc 静态会因 NSS 运行时 dlopen 失败。与 gitea-xxxig/gitea-xxxig-proxy/gitea-mond 一致。曾用的 Dockerfile.ubuntu（glibc 动态）与 Dockerfile.alpine（动态链 system 库）均已删除。
• 依赖处理（关键，勿乱改）：
  • external 依赖子模块自带源码，逐个编静态（BUILD_SHARED_LIBS=OFF 等）。拉 8 个常规子模块 + grpc 及其 6 个必需 third_party（abseil-cpp/boringssl-with-bazel/cares/protobuf/re2/zlib）；其余 9 个 grpc 子模块（benchmark/googletest/envoy/googleapis/xds 等测试或 xDS 依赖，已 GRPC_NO_XDS）跳过省体积/时间。
  • WITH_GRPC=ON（支持 Tari 合并挖矿，勿改回 OFF）：上游 CMake 默认即 ON（官方 alpine static job 为省体积改 OFF，本项目恢复 ON）。ON 时 cmake/grpc.cmake 用 add_subdirectory(external/src/grpc) 自动静态编译 grpc/protobuf/abseil/re2/cares，并 add_subdirectory(external/src/Tari) 编 checked-in 的 Tari proto（.pb.cc，不需运行时 protoc），链接 Tari_gRPC grpc grpc++ libprotobuf。这样 tari:// 主机走 MergeMiningClientTari（gRPC）而非 MergeMiningClientJSON_RPC（JSON-RPC，与 Tari 不兼容、报 empty response）。代价：二进制 ~5MB→~15MB（-Wl,-s --gc-sections 剔除未用 grpc/xDS 代码后远小于全量）、构建 +约 15min/arch。曾为省体积误用 WITH_GRPC=OFF 致无法与 Tari 合并挖矿，已改回 ON，勿回退。
  • boringssl 来源：WITH_GRPC=ON 时由 grpc 子模块（third_party/boringssl-with-bazel）提供，grpc.cmake 走此分支、不再 add_subdirectory(cmake/ssl)（那是 elseif (WITH_TLS) 分支）；p2pool 主体 TLS 与下方 curl 共用这一份 boringssl。
  • curl 用 boringssl TLS（保留 rpc-ssl，勿改回 no-SSL）：完整照搬官方 c-cpp.yml 的 curl flags——P2POOL_BORINGSSL=ON（上游给 curl 的独立 boringssl 后端补丁，与 CURL_ENABLE_SSL=OFF 共存、不走 curl 标准 SSL 路径）+ 一整套 CURL_DISABLE_*（尤其 SRP/AWS/*_AUTH）。后者跳过会引用 OpenSSL::SSL imported target 的 curl_openssl_check_exists 符号检测（新版 cmake 在 try_compile 阶段校验该 target 必失败，少一个 disable 都会触发）。curl 与 p2pool 主体共用同一 boringssl，json_rpc_request 的 CURLOPT_SSL_CTX_FUNCTION 才能接管证书指纹校验——--rpc-ssl/--rpc-ssl-fingerprint 连外部 SSL monerod 的能力得以保留（已实测连真实 SSL 节点用 --rpc-ssl 拿到链上高度）。曾误用 no-SSL curl 会断此能力，勿回退。
• 版本号约定：包版本硬编码在 ci.yaml 的 PACKAGE_VERSION: "4.15.1"（纯数字、无 v，符合 Debian 版本规范）。关键分界：上游 p2pool git tag 带 v，故 build job 用 P2POOL_VERSION="v${PACKAGE_VERSION}" 补回 v 传给 Dockerfile git checkout；tar.gz / deb / registry 路径 / Release 标题等包版本一律直接用 ${PACKAGE_VERSION}；release job 用 VERSION="${TAG#v}" 归一（tag 带不带 v 都兼容，唯 Release 的 tag_name 用 git tag 原值）。CI 触发条件 tags: ['*']，发版改 PACKAGE_VERSION 并打对应 tag（纯数字，如 4.15.1）。
• 架构映射：Dockerfile 内 arm64→ARCH_ID=aarch64、amd64→ARCH_ID=x86_64（传给 p2pool cmake，控制 RandomX 优化）。
• tar.gz 下载 URL 形如 https://gitea.bcde.io/api/packages/wangdefa/generic/p2pool/{version}/p2pool-{arch}-linux-static-{version}.tar.gz（version 为纯数字）。

本地常用命令

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

# 校验纯静态（应输出 "not a dynamic executable"）
ldd output/linux_amd64/p2pool

# 用已有 tar.gz 打 .deb 包（第三个参数是 tar.gz）
./debian/build-deb.sh amd64 4.15.1 p2pool-amd64-linux-static-4.15.1.tar.gz

无单元测试；CI 唯一冒烟是解包后跑 p2pool --help（musl 纯静态可在 glibc runner 直接运行），并用 ldd 校验为纯静态。

Debian 包布局与服务

• 二进制装到 /opt/p2pool/p2pool，systemd 服务 debian/p2pool.service，维护脚本 debian/{postinst,prerm,postrm}。
• 配置流转（单一数据源，对齐 gitea-mond）：conf/params.conf.example 是唯一配置源 → build-deb.sh 复制进包内 /opt/p2pool/params.conf → postinst 首次安装时 cp 到 /etc/p2pool/params.conf（升级不覆盖用户已有配置；旧版本位于 /var/lib/p2pool/params.conf 时 postinst 自动迁移到 /etc/p2pool/）。service 的 ExecStart 用 --params-file /etc/p2pool/params.conf。改默认配置改 conf/params.conf.example 一处即可（不要再在 postinst 内联 heredoc）。
• 数据目录 /var/lib/p2pool/data-api、日志目录 /var/log/p2pool，均归 p2pool 系统用户。postinst 创建 p2pool 系统用户/组，服务不自动启用/启动（首次需用户配置钱包地址），升级时若服务原为 enabled 则重启加载新二进制。
• control.template 无 Depends 字段（纯静态，连 libc6/libuv1/libzmq5/libcurl4 都不需要）。