# CLAUDE.md

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

## 仓库性质

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

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

mond 是 Monero 守护进程 `monerod` 的定制换名构建。换名通过 [init.sh](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](conf/params.example.conf)。

## 构建与发布流程（CI）

[.gitea/workflows/ci.yaml](.gitea/workflows/ci.yaml) 是 Gitea Actions 流水线：

1. **build-and-test**（矩阵 `arch=[amd64,arm64]`，跑在对应架构原生 runner）：用 `docker buildx` 按 [docker/Dockerfile.ubuntu](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=…`）交叉编译，产物为纯静态二进制（`ldd` 显示 "not a dynamic executable"），任意发行版可跑，Alpine 无需单独构建；且单次构建耗时 30–60 分钟，加 distro 维度会让 CI 翻倍而无收益。
- **版本号约定**：包版本硬编码在 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}"` 归一。发版改 `PACKAGE_VERSION` 并打对应 `v*` tag。
- **依赖精简**：depends 系统已将 boost/openssl/zmq/unbound/sodium/unwind 静态链入，故 [debian/control.template](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 为纯数字）。

## 本地常用命令

```bash
# 本地编译某架构的二进制（输出到 ./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` 校验纯静态。

## Debian 包布局与服务

- 二进制装到 `/opt/mond/mond`，systemd 服务文件 [debian/mond.service](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`。