开发者指南 · Zikaron

发布

发布物须能由任何人逐字节核对：校验值、签名，以及源码包与标签的一致。本页是维护者发布版本的步骤。

版本号

采用 主.次.修订 三段。每个版本的变化都列进更新记录：新增、变更与修复，文件格式与命令行输出的变化，升级时用户要做的事。账本镜像、命令行的账本目录与记录包，新版照常读；本机加密文件、机器目录与数据目录只读本版自己的形式，格式换代时，更新记录、发布说明与手册「从早先版本升级」写明怎样手工带过来。法的版本写在法的规格名中，与软件版本相互独立。

发布前

主干全部测试通过：持续集成在 macOS、Linux 与 Windows 上以发布构建构建并测试，macOS 与 Linux 两格还按发布的方式构建并核对二进制里只有中性的路径名；各平台的包再到真机上装一次、开一次。
两部法的摘要重算相符。
核与冻结核比对零分歧；链面录制全部回放一致。
合约代码哈希重算无误。
手册中英两份与界面逐句对应。
在一台干净的机器上走完首次启动六步。
在装着上一版本、有数据的机器上直接覆盖安装，机器目录与数据目录照用，账本检查答「正常」。
用 0.1.2 导出的账本镜像，照手册「从早先版本升级」走一遍收编，账本检查答「正常」。
在一个系统上导出的整机备份，到其他每个系统上各恢复一次。

构建

发布包从打了标签的那次提交构建，三个系统各用自己的工具：

git tag v0.1.5

macOS: packaging/macos/build.sh --identity Kaptonia
脚本先构建 zikaron-pack，由它给出路径映射的编译参数（zikaron-pack rustflags），再以 --locked 构建应用与命令行，用 zikaron-pack no-paths 核对二进制里只有中性的路径名，有残留即停在出包之前；然后把窗口程序 zikaron-desk、命令行 zikaron 和第三方许可装进 ZIKARON.app，逐个签名并校验，再做成 dist/ZIKARON-<版本>-macos-<架构>.dmg（带一个指向「应用程序」的链接）与 .pkg（应用进 /Applications，命令行进 /usr/local/bin），并写出 SHA256SUMS-macos-<架构>.txt。包里去掉扩展属性，dmg 里的属主、日期与分区名、pkg 里的属主与日期都中性化。
Linux: packaging/linux/build.sh
在 Linux 本机上构建，路径映射与路径核对同 macOS；在别的主机上改用 cross-build.sh，以 glibc 2.31 为目标。build.sh 用 dpkg-deb 打出 .deb，cross-build.sh 用 packaging/linux/make_deb.py 写出；AppImage 就是钉定的 AppImage 运行时接上 mksquashfs 做的镜像，只用这两样。运行时按字节钉定（x86_64 为 type2-runtime 8f39b89），下载来的不符即停，这时把钉定的文件经 APPIMAGE_RUNTIME 交给脚本；aarch64 尚待钉定运行时，只出 .deb。第三方许可放在 /usr/share/doc/zikaron-desk/，二进制的 .comment 段清空。
Windows: cargo run --release --locked -p zikaron-pack -- windows --out dist
在 Windows 上用 MSVC 排出 dist/ZIKARON-<版本>-windows-x86_64/ 文件夹，再压成发布页上的 zip。

二进制去除符号表；家目录、Cargo 与 rustup 的目录、源码目录与构建目录的路径在编译时映射掉，三个系统共用 zikaron-pack 里的同一张映射表，包里的日期一律取 SOURCE_DATE_EPOCH（默认为提交时刻），产物独立于构建机器。

校验值与 Zikaron 证明

为每个发布物（各平台的包与源码包）计算 SHA-256，合成一份发布清单 SHA256SUMS.txt；三个平台的第三方许可单独发布。发布页上共十个文件：六个包、发布清单与三份许可。
发布之前用项目的 Zikaron 账本记下十条存证，一并上链：六个包、Windows 包里的两个程序、发布清单，以及这次提交；交易、区块、记录者地址与各项指纹写在校验页。
发布页、网站下载页与清单三处的校验值一致；下载页的「Zikaron 证明」一栏填入各文件的上链交易。

用户的核对方法见校验。

系统签名

应用与 dmg 用项目自己的证书签名，证书的公用名为 Kaptonia；这张证书由项目自签，发布包在 Apple 公证之外、由项目直接发出。每个版本用同一张证书、同一个标识符 com.kaptonia.zikaron.app 签名，系统据此把各版本认作同一个应用。pkg 以 SHA-256 核对。Windows 的 zip 与 Linux 的两个包不签名，以 SHA-256 核对。

从浏览器下载的文件带着隔离标记，macOS 会拒绝打开；在较新的 macOS 上，「仍要打开」时常失灵。下载页与发布说明写明的做法是：先用 shasum -a 256 核对文件，再在终端里用 xattr 去掉隔离标记。Windows 首次打开时按「更多信息」再按「仍要运行」；Windows 11 开着「智能应用控制」时要先把它关掉。想确认文件来历的用户，可以核对签名者、证书指纹、校验值与 Zikaron 证明，见校验。

发布说明

每个版本写明：新增、变更与修复；文件格式与命令行输出的变化；升级时用户需要做的事；已知限制。仓库里的 CHANGELOG.md 与 CHANGELOG.en.md 逐版记下，发布说明链到它们与这一版的手册。

合约与网络

应用内置一张已知部署表，共四行（以太坊主网、Sepolia 测试网、Arbitrum One、OP Mainnet），每行写链号、登记合约地址、起始区块与两个预置节点。新增一行之前：

读取链上代码，核对代码哈希。
确认起始区块早于该合约上的第一条上链记录。
预置节点选两个来源相异的，均支持 TLS、返回的链号正确，实测保有起始区块以来的完整日志，两者逐条一致，查询范围太大时以明确的文字拒答；只给最近一段窗口的、要付费的、限流的节点不选。

一行发布之后，链号、登记合约与起始区块保持原样，旧账本依靠它们继续核验。预置节点的日志变得残缺时可以换：数据目录在建起时照抄一行的节点，所以换过的一对只到之后建的数据目录；已有数据目录的节点归用户自己改。

网站

网站随版本更新下载页的文件名、大小、校验值与 Zikaron 证明。页面由仓库中的脚本生成，生成结果一并提交。

发布后

从发布页下载一份，按用户的步骤核对、安装、打开。
确认网站下载页的拖放校验对每个文件都显示「与发布清单一致」。
发现发布包有误时，发布新的修订版本；已发布的文件与校验值保持原样。