63 lines
7.8 KiB
Markdown
63 lines
7.8 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 仓库性质
|
||
|
||
本仓库**只包含构建与打包基础设施**，不含 p2pool 源码。源码在编译时从上游克隆（见 [docker/Dockerfile](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.17`，上游 git tag 带 v、构建时补回）。
|
||
|
||
## 整体架构：单二进制
|
||
|
||
编译产出单个可执行文件 `p2pool`：连接 monerod（本地，或经 `--rpc-ssl` 连外部 SSL 节点）、维护 P2Pool sidechain、提供 stratum 给矿工。配置模板 [conf/params.conf.example](conf/params.conf.example)。
|
||
|
||
## 构建与发布流程（CI）
|
||
|
||
[.gitea/workflows/ci.yaml](.gitea/workflows/ci.yaml) 是 Gitea Actions 流水线：
|
||
|
||
1. **build-and-test**（矩阵 `arch=[amd64,arm64]`，跑在对应架构原生 runner）：用 `docker buildx` 按 [docker/Dockerfile](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](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.17"`（**纯数字、无 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.17`）。
|
||
- 架构映射：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 为纯数字）。
|
||
|
||
## 本地常用命令
|
||
|
||
```bash
|
||
# 本地编译某架构的二进制（输出到 ./output/linux_<arch>/p2pool）
|
||
docker buildx build --platform linux/amd64 \
|
||
--build-arg P2POOL_VERSION=v4.17 \
|
||
--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.17 p2pool-amd64-linux-static-4.17.tar.gz
|
||
```
|
||
|
||
无单元测试；CI 唯一冒烟是解包后跑 `p2pool --help`（musl 纯静态可在 glibc runner 直接运行），并用 `ldd` 校验为纯静态。
|
||
|
||
## Debian 包布局与服务
|
||
|
||
- 二进制装到 `/opt/p2pool/p2pool`，systemd 服务 [debian/p2pool.service](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 都不需要）。
|