Apache Tentacles 在 Ubuntu 22.04 集成使用指南

在 Ubuntu 22.04 上部署 Apache Tentacles 0.1 并与 Apache Rat 0.18 联动：官方发行件安装与校验、远程仓库批量下载解包、本地 file 模式离线取样与批量许可审计，全部命令实测通过。

Apache TentaclesApache TentaclesPythonUbuntuUbuntu 22.04命令行Apache2026/10/16

Apache Tentacles 在 Ubuntu 22.04 集成使用指南

目标：在一台 Ubuntu 22.04 服务器上从零部署 Apache Tentacles 0.1（Apache Creadur 的发布合规取样工具），完成远程仓库批量下载解包、本地 file 模式离线取样，并与 Apache Rat 0.18 联动对发行件与解包源码做批量许可审计。全部命令已在 Ubuntu 22.04.5 LTS + OpenJDK 17 环境实测通过。

一、环境信息

本文所有命令与回显均在一台全新 Ubuntu 22.04 服务器上实测采集，演示统一在 /root 目录下进行：

Tentacles 的定位与选型背景见《Apache Tentacles 介绍与选型指南》，命令全集逐项实测见《Apache Tentacles 常用 CLI 命令与工具详解》。

二、前置条件

2.1 安装 JDK

Tentacles 0.1 是 Java 工具，官方发行 jar 自带全部依赖，除 JDK 外无其他运行时依赖。0.1 源码按 Java 8 基线编译，master 分支（0.2-SNAPSHOT）要求 JDK 17；本文直接以 Ubuntu 22.04 仓库自带的 OpenJDK 17 运行 0.1 发行 jar，实测兼容。安装命令：

apt-get update && apt-get install -y openjdk-17-jre-headless

实测输出（节选，已装时提示为最新版）：

Reading package lists...
Building dependency tree...
Reading state information...
openjdk-17-jre-headless is already the newest version (17.0.20.1+1-1~22.04).
0 upgraded, 0 newly installed, 0 to remove and 3 not upgraded.

验证安装结果：

java -version

实测输出：

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

2.2 确认官方下载源连通

Tentacles 官方发行件托管在 downloads.apache.org，先验证可达：

wget -q --spider https://downloads.apache.org/creadur/apache-tentacles-0.1/apache-tentacles-0.1-jar-with-dependencies.jar && echo "downloads.apache.org 可达"

实测输出：

downloads.apache.org 可达

2.3 pip 方案辨析（重要：pip 装不到 Apache Tentacles）

Tentacles 不存在 Python 形态，pip 安装路径不可用。若直接执行 pip3 install tentacles，Ubuntu 22.04（Python 3.10.12、pip 22.0.2）会装到 PyPI 上一个完全无关的同名 Python ORM 库（tentacles 0.1.1，GPLv3，作者 Guillaume Bour），该包没有任何命令行入口：

pip3 install tentacles 2>&1 | tail -2

实测输出：

Installing collected packages: tentacles
Successfully installed tentacles-0.1.1

pip3 show tentacles | head -5

实测输出：

Name: tentacles
Version: 0.1.1
Summary: Object-Relational Mapping (ORM)
Home-page: http://devedge.bour.cc/wiki/Tentacles
Author: Guillaume Bour

tentacles --help

实测输出：

bash: line 1: tentacles: command not found

确认误装后立即卸载，保持环境干净：

pip3 uninstall -y tentacles

实测输出：

Successfully uninstalled tentacles-0.1.1

⚠️ 注意：Apache Tentacles 官方仓库 git 历史中从未存在 Python 代码（git log --all --name-status -- '*.py' 实测 0 命中），官方运行方式只有一种：java -jar。凡教程中出现「pip 安装 Tentacles」的说法均指向上述无关包。

三、依赖引入（安装）

3.1 方案一：官方发行目录下载（推荐）

官方发行目录 downloads.apache.org/creadur/apache-tentacles-0.1/ 提供两类核心发行件：可执行 jar（含全部依赖）与源码发行包。下载并校验：

mkdir -p /root/tentacles && cd /root/tentacles
wget -q https://downloads.apache.org/creadur/apache-tentacles-0.1/apache-tentacles-0.1-jar-with-dependencies.jar
wget -q https://downloads.apache.org/creadur/apache-tentacles-0.1/apache-tentacles-0.1-source-release.zip
ls -la

实测输出：

total 9576
drwxr-xr-x 2 root root    4096 Oct 16 02:40 .
drwx------ 1 root root    4096 Oct 16 02:40 ..
-rw-r--r-- 1 root root 9715403 Jan 23  2023 apache-tentacles-0.1-jar-with-dependencies.jar
-rw-r--r-- 1 root root   78101 Jan 23  2023 apache-tentacles-0.1-source-release.zip

用官方 sha512 校验和验证完整性（官方同目录提供 .sha512 文件）：

wget -q -O official.sha512 https://downloads.apache.org/creadur/apache-tentacles-0.1/apache-tentacles-0.1-jar-with-dependencies.jar.sha512
cat official.sha512 && sha512sum apache-tentacles-0.1-jar-with-dependencies.jar

实测输出（两行完全一致，校验通过）：

ae6e8d8d9e55517c0d2efc8bb5a63ad1514013d57f2d90552025321cfa246bc351b5a2a72a92882e4efca324f39391b01df2caa9aaf395f1c2099031c868d301
ae6e8d8d9e55517c0d2efc8bb5a63ad1514013d57f2d90552025321cfa246bc351b5a2a72a92882e4efca324f39391b01df2caa9aaf395f1c2099031c868d301  apache-tentacles-0.1-jar-with-dependencies.jar

💡 技术拓展：发行件完整性校验除了 sha512 还有 GPG 签名（官方同目录提供 .asc 文件）。流程为：gpg --import KEYS 导入官方 KEYS（https://downloads.apache.org/creadur/KEYS）后执行 gpg --verify <文件>.asc <文件>。签名校验能同时验证完整性与来源，比哈希更强；本文以哈希校验为最低要求。

3.2 方案二：Maven Central 下载（备选）

同一构件同步发布在 Maven Central（组 org.apache.creadur.tentacles），适合从内网 Maven 代理分发的场景：

wget -q https://repo1.maven.org/maven2/org/apache/creadur/tentacles/apache-tentacles/0.1/apache-tentacles-0.1-jar-with-dependencies.jar && echo "maven central 下载成功" && sha512sum apache-tentacles-0.1-jar-with-dependencies.jar

实测输出（哈希与官方发行目录一致）：

maven central 下载成功
ae6e8d8d9e55517c0d2efc8bb5a63ad1514013d57f2d90552025321cfa246bc351b5a2a72a92882e4efca324f39391b01df2caa9aaf395f1c2099031c868d301  apache-tentacles-0.1-jar-with-dependencies.jar

两方案对比：官方发行目录是 Apache 发布流程的正源（附 KEYS/asc 签名链），Maven Central 便于已有 Maven/Gradle 基础设施的团队复用代理与依赖管理。二选一即可，内容一致。

3.3 源码形态说明（何时需要源码包）

apache-tentacles-0.1-source-release.zip（76KB）是 Apache 发布流程要求的源码发行件，含完整 Java 源码与 Maven 构建。运行 Tentacles 不需要源码包；只有审计源码或自行改造时才解包查看：

cd /root/tentacles && mkdir -p src && cd src && unzip -q ../apache-tentacles-0.1-source-release.zip && find apache-tentacles-0.1 -maxdepth 3 -type d | sort | head -8

实测输出：

apache-tentacles-0.1
apache-tentacles-0.1/src
apache-tentacles-0.1/src/main
apache-tentacles-0.1/src/main/java
apache-tentacles-0.1/src/main/java/org
apache-tentacles-0.1/src/main/java/org/apache
apache-tentacles-0.1/src/main/java/org/apache/creadur
apache-tentacles-0.1/src/main/java/org/apache/creadur/tentacles

自行从源码构建仅适用于开发分支 0.2-SNAPSHOT（需 Maven 与 JDK 17，见官方仓库 README「Running with at least JDK 17」）；0.1 已提供含依赖的成品 jar，日常使用无需构建。

3.4 验证安装

安装是否成功以「能运行并输出版本行为准」。无参运行会给出官方引导提示（Tentacles 无 --help 选项，这是唯一帮助形态）：

cd /root/tentacles && java -ea -jar apache-tentacles-0.1-jar-with-dependencies.jar

实测输出：

0 [main] INFO org.apache.creadur.tentacles.Main  - Launching Apache Tentacles ...
0 [main] ERROR org.apache.creadur.tentacles.Main  - Error: Input parameter missing - you did not specify any component to run Apache Tentacles on.
0 [main] ERROR org.apache.creadur.tentacles.Main  - Please launch Apache Tentacles with an URI to work on such as 'https://repository.apache.org/content/repositories/orgapachecreadur-1000/'.

出现上述两行 ERROR 引导即说明 jar 可正常运行，只差一个目标 URI 参数。

四、核心 CLI 与参数

Tentacles 的命令行极简，没有选项体系，全部配置集中在「两个位置参数 + 一个系统属性」：

位置参数说明默认行为
第 1 参数（必填）URIhttps://（或 http://）远程仓库地址，或 file: 本地目录缺失时输出引导提示并退出
第 2 参数（可选）本地输出目录名输出根目录名（内含 repo/、content/、报告 HTML）取 URI 路径的末段目录名（如目标为 releases 仓库的 org/apache/creadur/tentacles/ 目录，则输出到 tentacles/）
JVM 系统属性-Dfilter=<正则>仅本地 file: 模式生效：按绝对路径正则筛选归档文件org/apache/openejb（默认值几乎必然不匹配你的目录，必须覆盖）
JVM 开关-ea启用 Java 断言，官方 README 要求携带不带 -ea 也能运行（实测），但按官方建议保留

💡 技术拓展：file: 模式的 -Dfilter 匹配的是文件绝对路径的正则全匹配（源码 IsArchiveInPathFilter 中 path.matches(pathNameFilter)），因此传子串（如 creadur）不会命中，需写成 .*creadur.* 形式；这解释了大量「本地模式空跑」的困惑，实测见第六章。

标准调用语法：

java -ea -jar apache-tentacles-0.1-jar-with-dependencies.jar <URI> [输出目录]

五、集成示例一：从 Apache releases 仓库批量下载并解包

本示例从 Apache 官方 releases 仓库的 org/apache/creadur/tentacles/ 目录批量取回全部发行件（5 个，体量小、适合首次演练），并生成审计报告。

mkdir -p /root/tentacles-demo && cd /root/tentacles-demo
java -ea -jar /root/tentacles/apache-tentacles-0.1-jar-with-dependencies.jar \
  https://repository.apache.org/content/repositories/releases/org/apache/creadur/tentacles/

实测输出（全程日志）：

0 [main] INFO org.apache.creadur.tentacles.Main  - Launching Apache Tentacles ...
36 [main] INFO org.apache.creadur.tentacles.Main  - Remote repository: https://repository.apache.org/content/repositories/releases/org/apache/creadur/tentacles/
36 [main] INFO org.apache.creadur.tentacles.Main  - Local root directory: tentacles
129 [main] INFO org.apache.creadur.tentacles.NexusClient  - Crawl https://repository.apache.org/content/repositories/releases/org/apache/creadur/tentacles/
1372 [main] INFO org.apache.creadur.tentacles.NexusClient  - Crawl https://repository.apache.org/content/repositories/releases/org/apache/creadur/tentacles/apache-tentacles/
1661 [main] INFO org.apache.creadur.tentacles.NexusClient  - Crawl https://repository.apache.org/content/repositories/releases/org/apache/creadur/tentacles/apache-tentacles/0.1/
1980 [main] INFO org.apache.creadur.tentacles.NexusClient  - Download https://repository.apache.org/content/repositories/releases/org/apache/creadur/tentacles/apache-tentacles/0.1/apache-tentacles-0.1-jar-with-dependencies.jar
4518 [main] INFO org.apache.creadur.tentacles.NexusClient  - Download https://repository.apache.org/content/repositories/releases/org/apache/creadur/tentacles/apache-tentacles/0.1/apache-tentacles-0.1-javadoc.jar
4799 [main] INFO org.apache.creadur.tentacles.NexusClient  - Download https://repository.apache.org/content/repositories/releases/org/apache/creadur/tentacles/apache-tentacles/0.1/apache-tentacles-0.1-source-release.zip
5080 [main] INFO org.apache.creadur.tentacles.NexusClient  - Download https://repository.apache.org/content/repositories/releases/org/apache/creadur/tentacles/apache-tentacles/0.1/apache-tentacles-0.1-sources.jar
5360 [main] INFO org.apache.creadur.tentacles.NexusClient  - Download https://repository.apache.org/content/repositories/releases/org/apache/creadur/tentacles/apache-tentacles/0.1/apache-tentacles-0.1.jar
5642 [main] INFO org.apache.creadur.tentacles.Main  - Unpack tentacles/repo/apache-tentacles/0.1/apache-tentacles-0.1-sources.jar
5646 [main] INFO org.apache.creadur.tentacles.Main  - Unpack tentacles/repo/apache-tentacles/0.1/apache-tentacles-0.1-jar-with-dependencies.jar
6441 [main] ERROR org.apache.creadur.tentacles.Main  - Not a zip tentacles/repo/apache-tentacles/0.1/apache-tentacles-0.1-jar-with-dependencies.jar
6442 [main] INFO org.apache.creadur.tentacles.Main  - Unpack tentacles/repo/apache-tentacles/0.1/apache-tentacles-0.1.jar
6445 [main] INFO org.apache.creadur.tentacles.Main  - Unpack tentacles/repo/apache-tentacles/0.1/apache-tentacles-0.1-source-release.zip
6449 [main] INFO org.apache.creadur.tentacles.Main  - Unpack tentacles/repo/apache-tentacles/0.1/apache-tentacles-0.1-javadoc.jar

验证执行结果——下载的发行件齐全（5 个）且解包目录生成：

find tentacles/repo -type f | sort

实测输出：

tentacles/repo/apache-tentacles/0.1/apache-tentacles-0.1-jar-with-dependencies.jar
tentacles/repo/apache-tentacles/0.1/apache-tentacles-0.1-javadoc.jar
tentacles/repo/apache-tentacles/0.1/apache-tentacles-0.1-source-release.zip
tentacles/repo/apache-tentacles/0.1/apache-tentacles-0.1-sources.jar
tentacles/repo/apache-tentacles/0.1/apache-tentacles-0.1.jar

报告文件也一并生成：

ls -la tentacles/*.html | awk '{print $5, $9}'

实测输出：

42971 tentacles/apache-tentacles.0.1.apache-tentacles-0.1-jar-with-dependencies.jar.licenses.html
 3095 tentacles/apache-tentacles.0.1.apache-tentacles-0.1-jar-with-dependencies.jar.notices.html
 1521 tentacles/apache-tentacles.0.1.apache-tentacles-0.1-javadoc.jar.licenses.html
 1618 tentacles/apache-tentacles.0.1.apache-tentacles-0.1-javadoc.jar.notices.html
11657 tentacles/apache-tentacles.0.1.apache-tentacles-0.1-source-release.zip.licenses.html
 1663 tentacles/apache-tentacles.0.1.apache-tentacles-0.1-source-release.zip.notices.html
 1521 tentacles/apache-tentacles.0.1.apache-tentacles-0.1-sources.jar.licenses.html
 1618 tentacles/apache-tentacles.0.1.apache-tentacles-0.1-sources.jar.notices.html
 1505 tentacles/apache-tentacles.0.1.apache-tentacles-0.1.jar.licenses.html
 1602 tentacles/apache-tentacles.0.1.apache-tentacles-0.1.jar.notices.html
 5765 tentacles/archives.html
53951 tentacles/licenses.html
 4297 tentacles/notices.html

日志中那条 ERROR Not a zip 出现在解包 jar-with-dependencies.jar 时（其内部个别嵌套条目非标准 zip 结构，跳过即可），不影响整体：其余解包继续、报告齐全、退出码为 0。

六、集成示例二：本地 file 模式离线取样

对已经手工准备好的本地文件集（如从内网仓库同步下来的目录），Tentacles 可用 file: 协议直接取样，全程不访问外网。先准备一个演示目录：

mkdir -p /root/local-repo/org/apache/creadur
cp /root/tentacles/apache-tentacles-0.1-source-release.zip /root/local-repo/org/apache/creadur/

6.1 默认过滤器空跑（必看的坑）

直接以默认参数运行（不覆盖 -Dfilter），观察现象：

cd /root/local-repo && java -ea -jar /root/tentacles/apache-tentacles-0.1-jar-with-dependencies.jar file:/root/local-repo/ out-a

实测输出（仅 3 行启动信息，无任何 Copy/Unpack 动作）：

0 [main] INFO org.apache.creadur.tentacles.Main  - Launching Apache Tentacles ...
38 [main] INFO org.apache.creadur.tentacles.Main  - Remote repository: file:/root/local-repo/
38 [main] INFO org.apache.creadur.tentacles.Main  - Local root directory: out-a

find out-a | sort

实测输出（只生成空报告骨架，repo/ 为空）：

out-a
out-a/archives.html
out-a/repo
out-a/notices.html
out-a/style.css
out-a/licenses.html
out-a/content

原因：本地模式按绝对路径正则筛选归档，默认过滤器是 org/apache/openejb（历史遗留默认值），不匹配任何文件，且进程静默退出码为 0，极易误判为「成功但没文件」。

6.2 覆盖 -Dfilter 正确取样

用 -Dfilter='.*'（匹配所有绝对路径）重新运行，第二参数同时自定义输出目录：

cd /root/local-repo && java -ea -Dfilter='.*' -jar /root/tentacles/apache-tentacles-0.1-jar-with-dependencies.jar file:/root/local-repo/ out-b

实测输出：

0 [main] INFO org.apache.creadur.tentacles.Main  - Launching Apache Tentacles ...
39 [main] INFO org.apache.creadur.tentacles.Main  - Remote repository: file:/root/local-repo/
40 [main] INFO org.apache.creadur.tentacles.Main  - Local root directory: out-b
43 [main] INFO org.apache.creadur.tentacles.Main  - Copy file:/root/local-repo/org/apache/creadur/apache-tentacles-0.1-source-release.zip
43 [main] INFO org.apache.creadur.tentacles.Main  - Unpack out-b/repo/org/apache/creadur/apache-tentacles-0.1-source-release.zip

验证取样与解包结果：

find out-b/repo -type f && ls out-b/content/org/apache/creadur/ | head -4

实测输出：

out-b/repo/org/apache/creadur/apache-tentacles-0.1-source-release.zip
apache-tentacles-0.1-source-release.zip.contents

⚠️ 注意：file: 模式下 -Dfilter 必须按「正则全匹配绝对路径」书写：.* 匹配一切；.*creadur.* 只匹配路径含 creadur 的归档。若发现运行后没有 Copy 日志，先检查过滤器是否命中，再检查路径是否真实存在。

七、集成示例三：与 Apache Rat 0.18 联动批量审计

Tentacles 报告聚焦「法定文件存在性与声明对照」，逐文件的许可头识别交给 Apache Rat：Tentacles 取样摊开，Rat 深查判定，两者串联即完整的批量审计流水线。

7.1 安装 Apache Rat 0.18

cd /root/tentacles
wget -q https://downloads.apache.org/creadur/apache-rat-0.18/apache-rat-0.18-bin.zip
unzip -q apache-rat-0.18-bin.zip
ls apache-rat-0.18/

实测输出：

LICENSE
NOTICE
RELEASE_NOTES.txt
apache-rat-0.18.jar

Rat 同样是单 jar CLI，验证可运行（Rat 无 --version 选项，用 --help 的首行确认版本）：

java -jar apache-rat-0.18/apache-rat-0.18.jar --help | head -2

实测输出：

INFO: Apache Creadur RAT 0.18 (Apache Software Foundation)
usage: java -jar apache-rat/target/apache-rat-0.18.jar [options] [DIR|ARCHIVE]

7.2 审计 Tentacles 下载目录（归档级）

对 Tentacles 取样回来的 repo/ 目录整体扫描。--output-archive ABSENCE 让归档报告给出最详尽级别（默认 NOTIFICATION 仅列出归档不识别内部许可）：

cd /root/tentacles-demo && java -jar /root/tentacles/apache-rat-0.18/apache-rat-0.18.jar \
  --output-archive ABSENCE --output-file rat-report-detail.txt tentacles/repo > rat-stdout.txt 2>&1
grep -v SLF4J rat-stdout.txt

实测输出：

INFO: Apache Creadur RAT 0.18 (Apache Software Foundation)
INFO: RAT summary:
INFO:   Approved:  4
INFO:   Archives:  5
INFO:   Binaries:  0
INFO:   Document types:  1
INFO:   Ignored:  0
INFO:   License categories:  2
INFO:   License names:  2
INFO:   Notices:  0
INFO:   Standards:  0
INFO:   Unapproved:  5
INFO:   Unknown:  5
ERROR: Unexpected count for STANDARDS, limit is [1,2147483647].  Count: 0
ERROR: Unexpected count for UNAPPROVED, limit is [0,0].  Count: 5
Exception in thread "main" org.apache.rat.document.RatDocumentAnalysisException: Issues with STANDARDS, UNAPPROVED
        at org.apache.rat.Report.main(Report.java:60)

grep -A12 'Counters' rat-report-detail.txt | head -16

实测输出：

-----------------------------------------------------
Counters
-----------------------------------------------------
    (Entries starting with '!' exceed the minimum or maximum values)
  Approved:           4    A count of approved licenses.
  Archives:           5    A count of archive files.
  Binaries:           0    A count of binary files.
  Document types:     1    A count of distinct document types.
  Ignored:            0    A count of ignored files.
  License categories: 2    A count of distinct license categories.
  License names:      2    A count of distinct license names.
  Notices:            0    A count of notice files.
! Standards:          0    A count of standard files.
! Unapproved:         5    A count of unapproved licenses.
  Unknown:            5    A count of unknown file types.

结果解读：5 个发行件均为归档（Archives: 5），其中 4 个 jar 内部的 Apache License 2.0 被识别为已批准（Approved: 4），source-release.zip 归档未识别出许可头；Rat 0.18 对归档默认不做逐文件展开（Standards: 0）。报告正常生成，但进程退出码为 1——Rat 0.18 会对超出阈值区间的计数（此处 UNAPPROVED 上限为 0）抛出 RatDocumentAnalysisException 并以非零码退出，这是把 Rat 接入自动化流水线时必须处理的语义，不能简单以退出码判断「扫描失败」：

java -jar /root/tentacles/apache-rat-0.18/apache-rat-0.18.jar \
  --output-archive ABSENCE --output-file /tmp/e7.txt tentacles/repo > /dev/null 2>&1; echo "exit=$?"

实测输出：

exit=1

7.3 审计 Tentacles 解包后的源码树（文件级）

归档级扫描不展开内容，更彻底的做法是对 Tentacles 解包产物 content/ 中的源码树做文件级扫描。以 source-release 的解包源码为对象：

cd /root/tentacles-demo && java -jar /root/tentacles/apache-rat-0.18/apache-rat-0.18.jar \
  --output-file /root/rat-src-report.txt \
  tentacles/content/apache-tentacles/0.1/apache-tentacles-0.1-source-release.zip.contents/apache-tentacles-0.1/src \
  > /root/rat-src-stdout.txt 2>&1
grep -v SLF4J /root/rat-src-stdout.txt | head -14

实测输出：

INFO: Apache Creadur RAT 0.18 (Apache Software Foundation)
INFO: RAT summary:
INFO:   Approved:  39
INFO:   Archives:  0
INFO:   Binaries:  0
INFO:   Document types:  1
INFO:   Ignored:  0
INFO:   License categories:  2
INFO:   License names:  2
INFO:   Notices:  0
INFO:   Standards:  42
INFO:   Unapproved:  3
INFO:   Unknown:  3
ERROR: Unexpected count for UNAPPROVED, limit is [0,0].  Count: 3
Exception in thread "main" org.apache.rat.document.RatDocumentAnalysisException: Issues with UNAPPROVED

查看具体未批准的文件（报告中以 ! 标注）：

grep -E '^!' /root/rat-src-report.txt

实测输出：

! Unapproved:         3    A count of unapproved licenses.
! /main/resources/licenses/cddl-1.0.txt
! /main/resources/licenses/cpl-1.0.txt
! /site/site.xml

结果解读：42 个标准文件中 39 个携带 Apache License 2.0 许可头，3 个未批准项为 cddl-1.0.txt、cpl-1.0.txt（CDDL/CPL 许可全文副本，作为许可文本本身存在属正常，应加入 Rat 排除清单）与 site/site.xml（站点配置，确无许可头）。这正是流水线的最终产物——一张需要人工裁决的短清单。

八、注意事项与常见问题

8.1 Tentacles 侧

Q1：运行结束没有下载任何文件，退出码还是 0，是成功了吗？ 逐项排查三类静默空跑（均实测复现）：一是本地 file: 模式忘了覆盖 -Dfilter（默认值 org/apache/openejb 不命中任何文件）；二是 URI 协议不被识别——Tentacles 只处理 http/https 与 file: 前缀，输入 s3://example/repo 之类时静默生成空报告骨架退出；三是目标 URL 下确实没有匹配 jar|zip|war|ear|rar|tar.gz 后缀的文件。对照日志：真正取样时必有 Crawl/Copy/Download 行，空跑时只有 Launching/Remote repository/Local root directory 三行。

Q2：ERROR Not a zip <路径> 是失败了吗？ 不是致命错误。该日志出现在递归解包阶段，表示某归档（或其嵌套条目）不是标准 zip 结构，Tentacles 跳过该条目继续，其余解包与报告生成不受影响，退出码仍为 0（第五章实测）。需要人工确认被跳过条目里是否遗漏法定文件。

Q3：不带 -ea 能跑吗？ 能。官方 README 要求带 -ea（启用断言），实测不带 -ea 的完整下载解包流程同样正常完成；建议保留 -ea 以符合官方运行约定。

Q4：退出码可以用来判断成功吗？ Tentacles 恒返回 0——包括无参数（输出 ERROR 引导后）、不支持协议、默认过滤器空跑等所有实测场景。判断成功与否要看日志动作与 repo/、content/、HTML 报告的实际产出，不能依赖退出码。

8.2 Rat 联动侧

Q5：Rat 扫描报告生成了，但退出码是 1？ Rat 0.18 对计数阈值有内置校验（如 UNAPPROVED 上限 0、STANDARDS 下限 1），超阈值时打印 ERROR: Unexpected count ...、抛 RatDocumentAnalysisException 并以非零码退出；报告文件仍完整生成。自动化流水线应以「报告文件是否生成」为主要判据，退出码仅作参考。

Q6：Rat 对归档不展开怎么办？ 默认 --output-archive NOTIFICATION 仅登记归档；--output-archive ABSENCE 提供最详尽报告，但归档内部逐文件审计仍建议对 Tentacles 的 content/ 解包目录执行（7.3 节实测路径），两者配合覆盖归档级与文件级。

Q7：--help 报 Unrecognized option？ Rat 0.18 没有 --version 选项：java -jar apache-rat-0.18.jar --version 实测输出 ERROR: Unrecognized option: --version。查看版本用 --help 输出首行的 INFO: Apache Creadur RAT 0.18 (Apache Software Foundation)。

九、参考链接