mond/CLAUDE.md

CLAUDE.md

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

仓库性质

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

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

mond 是 Monero 守护进程 monerod 的定制换名构建。换名通过 init.sh 在编译期对源码做 sed 改写完成：project(monero)→project(mond)、二进制 OUTPUT_NAME monerod→mond、MONERO_VERSION_* 宏 → MOND_VERSION_*、用户可见字符串 Monero→Mond。改动版本宏或显示字符串相关逻辑时，改 init.sh 而非源码（源码每次构建都重新克隆）。

与同目录 gitea-xxxig / gitea-xxxig-proxy 的关键差异：那两个项目源码来自 wangdefaa（双 a）换名仓库；mond 直接克隆 Monero 官方仓库，靠 init.sh 现场改名。三者共享同一套 CI / build-deb / debian 打包骨架，但 mond 的构建方式（官方 depends 系统）和版本号格式（四段 0.18.5.0）不同。

整体架构：单二进制

编译产出单个可执行文件 mond：Monero 全节点守护进程，负责 P2P 同步区块链、提供 RPC。配置来自 conf/params.example.conf。

构建与发布流程（CI）

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

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

关键点：

• 只构建 ubuntu，不做 alpine（刻意取舍）：mond 用 Monero 官方 depends 系统（make depends target=…）交叉编译，将 boost/openssl/zmq 等第三方依赖全部静态链入，运行时仅动态依赖 glibc（ldd 仍列出 libc/libm/libpthread/ld-linux —— 并非纯静态，故 Alpine/musl 系统无法直接运行）。主分发渠道是面向 Debian/Ubuntu 的 .deb（Depends: libc6 (>= 2.31)）；单次构建耗时 30–60 分钟，加 distro 维度会让 CI 翻倍。若要支持 Alpine 须改用 musl + -static-pie 真静态构建（当前未做）。
• 版本号约定：包版本硬编码在 ci.yaml 的 PACKAGE_VERSION: "0.18.5.0"（纯数字、无 v，符合 Debian 版本规范）。关键分界：上游 Monero git tag 带 v，故 build job 用 MONERO_VERSION=v${PACKAGE_VERSION} 补回 v 传给 Dockerfile git checkout；tar.gz / deb / registry 路径 / Release 标题等包版本一律直接用 ${PACKAGE_VERSION}；release job 用 VERSION="${TAG#v}" 归一（tag 带不带 v 都兼容）。CI 触发条件为 tags: ['*']，发版改 PACKAGE_VERSION 并打对应 tag（纯数字，如 0.18.5.0）。
• 依赖精简：depends 系统已将 boost/openssl/zmq/unbound/sodium/unwind 静态链入，故 debian/control.template 仅 Depends: libc6，无需列动态库。
• 架构名映射：Dockerfile 内 arm64→aarch64-linux-gnu、amd64→x86_64-linux-gnu 作为 depends target。
• tar.gz 下载 URL 形如 https://gitea.bcde.io/api/packages/wangdefa/generic/mond/{version}/mond-{arch}-ubuntu-{version}.tar.gz（version 为纯数字）。

本地常用命令

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

# 用已有 tar.gz 打 .deb 包（注意第三个参数是 tar.gz，不是目录）
./debian/build-deb.sh amd64 0.18.5.0 mond-amd64-ubuntu-0.18.5.0.tar.gz

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

无单元测试；CI 中唯一的冒烟测试是解包后跑 mond --version，并用 ldd 校验运行时仅依赖 glibc（无第三方动态库）。

Debian 包布局与服务

• 二进制装到 /opt/mond/mond，systemd 服务文件 debian/mond.service，维护脚本 debian/{postinst,prerm,postrm}。
• 配置流转（单一数据源）：conf/params.example.conf 是唯一配置源 → build-deb.sh 复制进包内 /opt/mond/params.conf → postinst 首次安装时 cp 到 /etc/mond/params.conf（升级不覆盖用户已有配置；旧版本位于 /var/lib/mond/params.conf 时 postinst 会自动迁移到 /etc/mond/）。service 的 ExecStart 用 --config-file=/etc/mond/params.conf。改默认配置改 conf/params.example.conf 一处即可（不要再在 postinst 内联）。
• 数据目录 /var/lib/mond/data、日志目录 /var/log/mond，均归 mond 系统用户。
• postinst 创建 mond 系统用户/组。服务不自动启用/启动（首次同步需用户确认配置），升级时若服务原为 enabled 则重启以加载新二进制。.deb 安装后手动 systemctl enable --now mond。