Ubuntu 22.04 安装 Apache Yetus 指南

在 Ubuntu 22.04 服务器从零安装 Apache Yetus 0.15.1 的完整指南，涵盖依赖准备、官方 tarball 下载与 SHA512 校验、解压部署、环境变量配置、releasedocmaker 最小实测与常见问题。

Apache YetusApache Yetus2026/10/12

Ubuntu 22.04 安装 Apache Yetus 指南

一、环境信息

本文所有步骤均在 Ubuntu 22.04 服务器上实际执行验证，关键软件版本如下：

项目值
操作系统Ubuntu 22.04.5 LTS（x86_64）
内核6.8.0（实际以服务器为准，无特殊内核要求）
Apache Yetus0.15.1（官方二进制包）
Python3.10.12（apt 默认版本）
Git2.34.1
curl7.81.0
ShellCheck0.8.0（apt 源）
安装目录/opt/yetus
下载目录/opt/yetus-dl
执行账号root

二、前置条件

  1. 服务器可访问公网（需访问 downloads.apache.org 与 apt 软件源）。
  2. 以 root 身份操作，或使用具备 sudo 权限的账号。

最小化安装的 Ubuntu 22.04 默认没有 python3、git、curl，先安装依赖：

apt-get update
apt-get install -y python3 python3-pip git curl shellcheck

实测安装完成后版本确认：

python3 --version
git --version
curl --version | head -1
shellcheck --version | head -2

实测回显：

Python 3.10.12
git version 2.34.1
curl 7.81.0 (x86_64-pc-linux-gnu) libcurl/7.81.0 OpenSSL/3.0.2 zlib/1.2.11 brotli/1.0.9 zstd/1.4.8 libidn2/2.3.2
ShellCheck - shell script analysis tool
version: 0.8.0

三、版本选型

Apache Yetus 官方下载页（https://yetus.apache.org/downloads/）当前提供的最新稳定版本为 0.15.1，同时提供 0.14.1 与 0.13.0。本文统一选用 0.15.1。

每个版本提供两类包：

  • Source：apache-yetus-0.15.1-src.tar.gz（源码，需自行构建）；
  • Binaries：apache-yetus-0.15.1-bin.tar.gz（官方构建的即用二进制，脚本与库齐全，推荐）。

本文使用 Binaries 包。0.15.1 的发布日期为 2025-02-16（可从生成的 CHANGELOG 中确认）。

四、部署步骤

4.1 下载与校验

创建下载目录并下载官方二进制包与官方校验文件：

mkdir -p /opt/yetus-dl
cd /opt/yetus-dl
curl -sSLO https://downloads.apache.org/yetus/0.15.1/apache-yetus-0.15.1-bin.tar.gz
curl -sSLO https://downloads.apache.org/yetus/0.15.1/apache-yetus-0.15.1-bin.tar.gz.mds

确认文件完整：

ls -la /opt/yetus-dl/apache-yetus-0.15.1-bin.tar.gz

实测回显：

-rw-r--r-- 1 root root 165232 Oct 12 14:18 apache-yetus-0.15.1-bin.tar.gz

使用官方 .mds 文件中的 SHA512 值进行校验：

cd /opt/yetus-dl
EXPECTED=$(grep 'SHA512' apache-yetus-0.15.1-bin.tar.gz.mds | tr -d ' \n' | cut -d= -f2)
LOCAL=$(sha512sum apache-yetus-0.15.1-bin.tar.gz | awk '{print toupper($1)}')
if [ "$EXPECTED" = "$LOCAL" ]; then echo "SHA512 校验通过"; else echo "SHA512 校验失败"; fi

实测回显：

SHA512 校验通过

本地计算所得 SHA512 值（小写）为：

6a26e30063f72ac407d4bc37e76a3bc036f5cb2353495218b59a67c1fddf7a8bc57250350c16ea70b3c108143e7c27e5631acb16d448db88bc3a647e6fd6d58a

4.2 解压安装

解压到 /opt/yetus（--strip-components=1 去掉包名层目录）：

mkdir -p /opt/yetus
tar -xzf /opt/yetus-dl/apache-yetus-0.15.1-bin.tar.gz -C /opt/yetus --strip-components=1
ls -la /opt/yetus/

实测回显：

total 52
drwxr-xr-x  4 root dialout  4096 Oct 12 14:19 .
drwxr-xr-x  8 root root    4096 Oct 12 14:19 ..
-rw-r--r--  1 root dialout 20994 Dec  3  2021 LICENSE
-rw-r--r--  1 root dialout   258 May 21  2023 NOTICE
-rw-r--r--  1 root dialout  4245 Feb 12  2025 README.md
drwxr-xr-x  2 root dialout  4096 Oct 12 14:19 bin
drwxr-xr-x  6 root dialout  4096 Oct 12 14:19 lib

目录说明：

  • bin/：可执行命令入口，含 releasedocmaker、test-patch、shelldocs、smart-apply-patch、qbt 等；
  • lib/：脚本库与插件，lib/VERSION 文件记录版本号（实测内容为 0.15.1）；
  • lib/precommit/plugins.d/：预提交审计插件（实测共 50 个插件脚本）。

4.3 配置环境变量

写入 profile 片段，对所有登录会话生效：

echo 'export YETUS_HOME=/opt/yetus' > /etc/profile.d/yetus.sh
echo 'export PATH=$YETUS_HOME/bin:$PATH' >> /etc/profile.d/yetus.sh

使当前会话生效：

source /etc/profile.d/yetus.sh

4.4 验证安装

确认命令可用并输出版本：

which releasedocmaker
releasedocmaker -V
test-patch --version
shelldocs -V

实测回显：

/opt/yetus/bin/releasedocmaker
0.15.1
0.15.1
0.15.1

4.5 releasedocmaker 最小实测

releasedocmaker 的数据来源是 JIRA 问题跟踪系统，首次运行会暴露缺少 Python 依赖的问题，正好用于验证安装完整性。

第一次直接运行：

releasedocmaker -V

若缺少依赖，实测报错：

ERROR:root:This script requires python-dateutil module to be installed. You can install it using:
         pip install python-dateutil

安装缺失的 Python 模块：

python3 -m pip install python-dateutil

实测回显（版本号以实际安装为准）：

Successfully installed python-dateutil-2.9.0.post0 six-1.17.0

再次运行，对 Apache JIRA 上真实存在的 YETUS 项目生成 0.15.1 的发布说明（需要外网访问 issues.apache.org）：

releasedocmaker --project YETUS --version 0.15.1 --outputdir /tmp/rdm-yetus --projecttitle 'Apache Yetus' --index
echo "exit=$?"

实测回显：

exit=0

查看生成结果：

ls -la /tmp/rdm-yetus/

实测回显：

total 16
-rw-r--r-- 1 root root 1424 Oct 12 14:20 CHANGELOG.md
-rw-r--r-- 1 root root    0 Oct 12 14:20 README.md
-rw-r--r-- 1 root root 1227 Oct 12 14:20 RELEASENOTES.md
-rw-r--r-- 1 root root    0 Oct 12 14:20 index.md

CHANGELOG.md 开头内容：

# Apache Yetus Changelog

  ## Release 0.15.1 - 2025-02-16



### BUG FIXES:

| JIRA | Summary | Priority | Component | Reporter | Contributor |
|:---- |:---- | :--- |:---- |:---- |:---- |
| [YETUS-1249](https://issues.apache.org/jira/browse/YETUS-1249) | fix macos tests in yetus-homebrew |  Major | homebrew | Allen Wittenauer | Allen Wittenauer |

以上即安装验证完成：releasedocmaker 已能从 JIRA 拉取数据并生成发布文档。

五、配置说明

  1. 环境变量：YETUS_HOME 指向安装目录，PATH 中加入 $YETUS_HOME/bin。官方二进制内部通过相对路径定位 lib 目录，无需其他强制环境变量。
  2. Python 依赖：releasedocmaker 依赖 python-dateutil，通过 python3 -m pip install python-dateutil 安装。若以 root 执行 pip，会提示 "WARNING: Running pip as the 'root' user..."，属正常提醒可忽略。
  3. 可选外部工具：test-patch 的插件按需调用外部工具。Ubuntu 22.04 常用插件工具均可直接从 apt 安装，例如 shellcheck、pylint3、yamllint、codespell、markdownlint 等；未安装对应工具时相应插件自动跳过。
  4. ShellCheck：Ubuntu 22.04 自带源中的 0.8.0 版本实测可直接配合 test-patch 的 shellcheck 插件工作，无需额外处理。
  5. 插件与 personality：test-patch 支持在项目仓库的 .yetus/personality.sh 中做项目级定制，详见《Apache Yetus 配置参数详解》。

六、升级与多版本

  1. 升级到新版本：下载新版 tarball，解压到新目录（如 /opt/yetus-0.16.0），验证后切换软链接：
ln -sfn /opt/yetus-0.16.0 /opt/yetus
  1. 多版本共存：不同项目可各自使用不同版本，直接调用绝对路径即可，例如 /opt/yetus-0.15.1/bin/test-patch。官方提醒：不同版本间不保证兼容，建议每个项目固定使用同一版本。
  2. 版本确认：cat /opt/yetus/lib/VERSION 可查看当前解压目录的版本号。

七、注意事项

  1. releasedocmaker 只支持 JIRA 作为数据源，不能直接从 git 提交记录生成 CHANGELOG；本地 git 仓库仅作为输出目录使用。若 JIRA 中的项目名不存在，会报 HTTP 400 错误（详见常见问题）。
  2. test-patch 默认不启用任何审计插件，必须通过 --plugins 显式启用（或 --plugins=all），否则只执行环境检查、不产出任何测试投票。
  3. test-patch 对工作区有洁癖：仓库存在未提交修改或未跟踪文件时会拒绝运行，报错并提示 --dirty-workspace 选项；运行结束后补丁默认仍应用在工作区（nobuild 构建工具的清理动作为空操作），需要手动还原或使用 --resetrepo。
  4. test-patch 运行过程会在 /tmp 下创建工作目录（--patch-dir 指定），CI 环境注意磁盘清理。
  5. 防火墙如启用（ufw），需放行到 issues.apache.org（releasedocmaker）及各类代码托管平台的出站访问。

八、常见问题

Q1： 执行 releasedocmaker 报 "This script requires python-dateutil module"？

现象：任何 releasedocmaker 命令均报 ERROR:root:This script requires python-dateutil module to be installed。定位：系统缺少 Python 模块 python-dateutil。解决：python3 -m pip install python-dateutil，安装后重试即可。

Q2： releasedocmaker 报 "JIRA returns HTTP error 400"？

现象实测回显：

JIRA returns HTTP error 400: . Aborting.
- Please ensure that specified authentication, projects, fixVersions etc. are correct.
- The value 'DEMOSHELL' does not exist for the field 'project'.

定位：--project 指定的项目在目标 JIRA 上不存在（或无权限访问），末行引号内为具体项目名。解决：改用 JIRA 上真实存在的项目名（如 YETUS），并确认版本号（--version）在该项目的 fixVersions 中存在。

Q3： releasedocmaker 多版本执行报 "Multiple versions require either --fileversions or --dirversions"？

现象：--version 传两个及以上版本时直接报错退出。定位：多版本输出必须指定文件命名方式。解决：追加 --fileversions（文件名嵌版本，如 CHANGELOG.0.15.1.md）或 --dirversions（按版本建子目录）。

Q4： apt 安装 shellcheck 提示找不到包？

定位：未执行 apt-get update 或 apt 源不可达。解决：先执行 apt-get update 刷新索引再安装；内网环境配置可用的内部软件源。

Q5： test-patch 报 "can't run in a workspace that contains the following modifications"？

现象实测回显：

ERROR: --dirty-workspace option not provided.
ERROR: can't run in a workspace that contains the following modifications
 M build.sh

定位：仓库工作区存在未提交修改（含未跟踪文件）。解决：先还原或提交修改，确认 git status 干净后重跑；CI 场景可追加 --dirty-workspace 跳过该检查。

Q6： test-patch 跑完没有任何测试投票、Optional Tests 为空？

定位：0.15.1 默认不启用任何插件，仅传 --build-tool 不传 --plugins 时不会执行任何测试。解决：显式指定 --plugins，例如 --plugins=shellcheck,shelldocs,blanks。

九、卸载方式

  1. 删除安装与下载目录：
rm -rf /opt/yetus /opt/yetus-dl
  1. 删除环境变量配置：
rm -f /etc/profile.d/yetus.sh
  1. 清理输出与工作目录（如不再需要）：
rm -rf /tmp/rdm-yetus /tmp/tp-out
  1. 可选：卸载随装的依赖（不影响系统其他组件可跳过）：
apt-get remove -y shellcheck
  1. 重新登录使 PATH 变更生效，确认 which releasedocmaker 无输出即卸载完成。

十、参考链接

  1. Apache Yetus 官方下载页：https://yetus.apache.org/downloads/
  2. Apache Yetus 官方文档首页：https://yetus.apache.org/
  3. releasedocmaker 官方文档：https://yetus.apache.org/documentation/in-progress/releasedocmaker
  4. test-patch（precommit）官方文档：https://yetus.apache.org/documentation/in-progress/precommit/
  5. GitHub 仓库：https://github.com/apache/yetus
  6. ASF 校验流程说明：https://www.apache.org/info/verification.html