Apache Archiva 2.2.10 配置参数详解
Apache Archiva 2.2.10 配置参数详解：逐项解析 conf/wrapper.conf（JSW wrapper 与 JVM 堆 256-512MB、jetty.port 覆盖）、jetty.xml 连接器、archiva.xml（仓库扫描文件类型、URL 失败缓存、仓库持久化）与本地/远程仓库参数（调度 cron、清理策略、连通性检查），附生产模板与生效验证方法，默认值均实测
Apache Archiva 2.2.10 配置参数详解
目标：详解 Apache Archiva 2.2.10 的核心配置——
conf/wrapper.conf（JSW wrapper 与 JVM 参数，含堆 256-512MB 与端口覆盖）、conf/jetty.xml（连接器）、conf/archiva.xml（应用与仓库持久化）以及仓库参数（本地/远程仓库、调度与清理策略），并给出可直接套用的生产模板。参数与默认值均基于真实环境实测（Ubuntu 22.04 / OpenJDK 1.8.0_504）。
一、环境信息
- 操作系统：Ubuntu 22.04.5 LTS（x86_64）
- Java：OpenJDK 1.8.0_504
- Apache Archiva：2.2.10（独立发行包，内嵌 Jetty 8.1.14.v20131031 + JSW wrapper 3.2.3）
- 安装目录：
/opt/archiva - 配置文件目录：
/opt/archiva/conf/ - 服务端口：8080（HTTP）
- 元数据库：内嵌 Derby，数据目录
/opt/archiva/data/databases - 仓库存储：
/opt/archiva/repositories/（internal、snapshots 内置 + 自建 thirdparty） - 管理账号：admin / q1w2e3r4
二、前置条件
- 已按《Apache Archiva 2.2.10 安装指南》完成安装并可正常启动。
- 配置修改后需重启服务生效：
systemctl restart archiva，用systemctl is-active archiva确认回到 active。
三、参数查看与修改方式
Archiva 的行为由 conf/ 下三类主配置控制，改前先看清各自的加载机制：
| 文件 | 作用 | 加载方式 |
|---|---|---|
wrapper.conf | JVM 参数与 wrapper 行为：classpath、堆、附加系统属性、日志滚动 | bin/archiva 脚本按行读入，拼装为 java/wrapper 启动参数 |
jetty.xml | 内嵌 Jetty 连接器：监听主机/端口、空闲超时等 | 作为启动参数传给 org.eclipse.jetty.start.Main |
archiva.xml | 应用配置：仓库扫描文件类型、URL 失败缓存、仓库定义持久化 | Archiva 应用启动与运行时读写（REST/控制台改动会写回此文件） |
shared.xml | 公共配置占位 | 出厂为空 <configuration /> |
archiva-cassandra.properties | Cassandra 会话工厂参数 | 仅当会话工厂切到 cassandra 时使用（默认 jcr，见 5.1） |
查看当前生效配置（去注释后的有效内容）：
grep -vE '^\s*#|^\s*$' /opt/archiva/conf/wrapper.conf | head -12
wrapper.java.command=java
wrapper.working.dir=..
wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperSimpleApp
set.default.REPO_DIR=lib
set.default.ARCHIVA_BASE=.
wrapper.java.classpath.1=lib/wrapper.jar
wrapper.java.classpath.2=%REPO_DIR%/archiva-jetty-2.2.10.pom
wrapper.java.classpath.3=%REPO_DIR%/jetty-server-8.1.14.v20131031.jar
wrapper.java.classpath.4=%REPO_DIR%/javax.servlet-3.0.0.v201112011016.jar
wrapper.java.classpath.5=%REPO_DIR%/jetty-continuation-8.1.14.v20131031.jar
wrapper.java.classpath.6=%REPO_DIR%/jetty-http-8.1.14.v20131031.jar
wrapper.java.classpath.7=%REPO_DIR%/jetty-io-8.1.14.v20131031.jar
修改流程统一为：编辑文件 → systemctl restart archiva → 用验证命令复核（每类参数的验证命令见对应小节）。示例（改端口后核对监听，见 5.1）：
systemctl restart archiva && sleep 15
netstat -tlnp | grep 9080
tcp6 0 0 :::9080 :::* LISTEN 27278/java
四、参数总览
| 参数 | 默认值（出厂） | 说明 |
|---|---|---|
wrapper.java.initmemory | 512 | JVM 初始堆，拼为 -Xms{n}m（本文 256） |
wrapper.java.maxmemory | 512 | JVM 最大堆，拼为 -Xmx{n}m |
wrapper.java.additional.8 | -XX:MaxPermSize=128m | 永久代上限（JDK 8） |
wrapper.java.additional.1 | -Dappserver.home=. | 安装根目录 |
wrapper.java.additional.6 | -Darchiva.repositorySessionFactory.id=jcr | 仓库会话工厂：jcr（默认）/ cassandra |
jetty.port（系统属性） | 未设置时默认 8080 | HTTP 监听端口 |
jetty.host（系统属性） | 未设置时绑定全部网卡 | 监听地址 |
仓库调度 cronExpression | internal/snapshots：0 0 * * * ?、0 0,30 * * * ? | 仓库扫描周期 |
仓库清理 daysOlder / retentionCount | 30 / 2 | 快照保留天数与版本数 |
远程仓库 timeout | 60 | 连接/读取超时（秒） |
远程仓库 cronExpression | 0 0 08 ? * SUN | 远程索引/代理更新周期 |
archivaRuntimeConfiguration.urlFailureCacheConfiguration | 2700/1800/1000 秒/秒/条 | 远程 URL 失败缓存（避免反复撞坏源） |
关键解读：日常运维最常改的是「JVM 堆、监听端口、仓库调度与清理策略」三类；
archiva.xml里的仓库定义建议经 REST 或控制台修改，手改易与运行时写回冲突。
五、核心参数分类详解
5.1 JVM 与 wrapper 参数（wrapper.conf）
wrapper.java.command=java
wrapper.working.dir=..
wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperSimpleApp
wrapper.java.additional.1=-Dappserver.home=.
wrapper.java.additional.2=-Dappserver.base=%ARCHIVA_BASE%
wrapper.java.additional.3=-Djetty.logs=%ARCHIVA_BASE%/logs
wrapper.java.additional.4=-Djava.io.tmpdir=%ARCHIVA_BASE%/temp
wrapper.java.additional.5=-DAsyncLoggerConfig.WaitStrategy=Block
wrapper.java.additional.6=-Darchiva.repositorySessionFactory.id=jcr
wrapper.java.additional.7=-Darchiva.cassandra.configuration.file=%ARCHIVA_BASE%/conf/archiva-cassandra.properties
wrapper.java.additional.8=-XX:MaxPermSize=128m
wrapper.java.initmemory=256
wrapper.java.maxmemory=512
wrapper.app.parameter.1=org.eclipse.jetty.start.Main
wrapper.app.parameter.2=%ARCHIVA_BASE%/conf/jetty.xml
wrapper.restart.delay=30
wrapper.on_exit.0=SHUTDOWN
wrapper.on_exit.default=RESTART
wrapper.logfile=%ARCHIVA_BASE%/logs/wrapper-YYYYMMDD.log
wrapper.logfile.rollmode=DATE
| 参数 | 默认值 | 说明 |
|---|---|---|
wrapper.java.command | java | 从 PATH 找 java；固定版本可写绝对路径（如 /usr/lib/jvm/java-8-openjdk-amd64/bin/java） |
wrapper.java.mainclass | WrapperSimpleApp | 以普通应用方式拉起 Jetty，wrapper 负责守护 |
additional.1/2 | appserver.home / appserver.base = . | 安装根，Derby、jcr、日志等都以此为基准 |
additional.6 | repositorySessionFactory.id=jcr | 内容仓储会话工厂；切 cassandra 才需要 additional.7 的配置文件 |
additional.8 | MaxPermSize=128m | JDK 8 永久代上限；类多时（大量代理索引）可上调 |
initmemory / maxmemory | 512 / 512 | 本文 256 / 512；wrapper 拼为 -Xms256m -Xmx512m |
app.parameter.1/2 | jetty.start.Main + jetty.xml | Jetty 入口与配置文件 |
restart.delay | 30 | 异常退出后 wrapper 等待 30 秒再拉起 |
on_exit.0 / on_exit.default | SHUTDOWN / RESTART | 正常退出（如 stop）不再拉起；其他退出码自动重启 |
logfile.rollmode | DATE | wrapper 日志按日期滚动（wrapper-YYYYMMDD.log） |
出厂堆为 512/512，小规格服务器将初始堆降到 256：
sed -i 's/^wrapper.java.initmemory=512/wrapper.java.initmemory=256/' /opt/archiva/conf/wrapper.conf
重启后用 jps -v 验证实际生效值（实测）：
systemctl restart archiva && sleep 15
jps -v | grep WrapperSimpleApp | grep -oE '\-Xms[0-9]+m \-Xmx[0-9]+m'
-Xms256m -Xmx512m
监听端口覆盖：Jetty 连接器从系统属性 jetty.port 读端口（见 5.2），wrapper 追加一行 JVM 参数即可覆盖（实测 8080 → 9080）：
sed -i 's/^wrapper.java.additional.8=-XX:MaxPermSize=128m/wrapper.java.additional.8=-XX:MaxPermSize=128m\nwrapper.java.additional.9=-Djetty.port=9080/' /opt/archiva/conf/wrapper.conf
grep -E 'additional\.(8|9)' /opt/archiva/conf/wrapper.conf
wrapper.java.additional.8=-XX:MaxPermSize=128m
wrapper.java.additional.9=-Djetty.port=9080
systemctl restart archiva && sleep 15
netstat -tlnp | grep 9080
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:9080/
tcp6 0 0 :::9080 :::* LISTEN 27278/java
200
改回时删除 additional.9 行并重启。
5.2 Jetty 连接器参数（jetty.xml）
<Call name="addConnector">
<Arg>
<New class="org.eclipse.jetty.server.nio.SelectChannelConnector">
<Set name="host"><SystemProperty name="jetty.host"/></Set>
<Set name="port"><SystemProperty name="jetty.port" default="8080"/></Set>
<Set name="maxIdleTime">30000</Set>
<Set name="Acceptors">2</Set>
<Set name="statsOn">false</Set>
<Set name="confidentialPort">8443</Set>
<Set name="lowResourcesConnections">5000</Set>
<Set name="lowResourcesMaxIdleTime">5000</Set>
</New>
</Arg>
</Call>
| 参数 | 默认值 | 说明 |
|---|---|---|
host | jetty.host 未设置 → 绑定全部网卡 | 只允许本机访问可加 -Djetty.host=127.0.0.1 |
port | jetty.port 未设置 → 8080 | 覆盖方式见 5.1 |
maxIdleTime | 30000 | 连接空闲 30 秒断开；大文件慢速代理客户端可上调 |
Acceptors | 2 | 接收线程数 |
confidentialPort | 8443 | 声明的机密端口（配合 TLS 才有意义，出厂未配 TLS） |
lowResourcesConnections | 5000 | 资源紧张阈值，超过后空闲时间改用 lowResourcesMaxIdleTime |
💡 要出 HTTPS 需自配 TLS 连接器（Jetty 8 语法）；仅内网使用时常见做法是前置 Nginx 做 TLS 终结，Archiva 保持 8080。
5.3 应用与仓库持久化（archiva.xml）
conf/archiva.xml 出厂包含三部分，且运行期的仓库管理操作会写回此文件：
（1）仓库扫描文件类型（repositoryScanning/fileTypes），决定扫描与索引哪些制品：
| fileType | 出厂 patterns（节选） | 用途 |
|---|---|---|
artifacts | **/*.pom、**/*.jar、**/*.war、**/*.ear、**/*.zip、**/*.tar.gz 等 13 种 | 计入制品清单与统计 |
indexable-content | **/*.txt、**/*.xml、**/*.xsd、**/*.tld 等 | 纳入全文索引 |
auto-remove | **/*.bak、**/*.sha1（临时产物类） | 扫描时自动清理 |
（2）运行时配置（archivaRuntimeConfiguration，出厂原样）：
<archivaRuntimeConfiguration>
<fileLockConfiguration>
<skipLocking>true</skipLocking>
</fileLockConfiguration>
<urlFailureCacheConfiguration>
<timeToIdleSeconds>2700</timeToIdleSeconds>
<timeToLiveSeconds>1800</timeToLiveSeconds>
<maxElementsInMemory>1000</maxElementsInMemory>
<maxElementsOnDisk>0</maxElementsOnDisk>
</urlFailureCacheConfiguration>
</archivaRuntimeConfiguration>
| 参数 | 出厂值 | 说明 |
|---|---|---|
fileLockConfiguration.skipLocking | true | 跳过仓库文件锁（单实例部署保持默认即可） |
urlFailureCacheConfiguration.* | 2700 / 1800 / 1000 | 远程源连接失败后的负面缓存：45 分钟不活跃过期、30 分钟存活、内存最多 1000 条；期间代理请求直接失败返回，避免反复等超时 |
（3）仓库定义持久化（managedRepositories / remoteRepositories / proxyConnectors 等段）：经 REST 或控制台创建的仓库、远程仓库与代理连接规则都会落到这里。实测创建阿里云远程仓库后，该文件出现对应 <url>https://maven.aliyun.com/repository/public</url> 节点。
5.4 本地仓库参数（managed repositories）
内置两个本地仓库（首启自动创建，落盘 /opt/archiva/repositories/）：
| 仓库 | 出厂 location | releases | snapshots | blockRedeployments | cronExpression |
|---|---|---|---|---|---|
internal | /opt/archiva/repositories/internal | true | false | true | 0 0 * * * ?（整点扫描） |
snapshots | /opt/archiva/repositories/snapshots | false | true | false | 0 0,30 * * * ?（半点扫描） |
自建本地仓库的完整参数（经 REST addManagedRepository 创建，实测 payload 与回显）：
curl -s -b /tmp/archiva-cookie.txt -X POST -H 'Origin: http://localhost:8080' \
-H 'Content-Type: application/json' -H "X-XSRF-TOKEN: $TOKEN" \
-d '{"id":"thirdparty","name":"Third Party Repository","layout":"default","location":"/opt/archiva/repositories/thirdparty","cronExpression":"0 0 * * * ?","daysOlder":30,"retentionCount":2,"releases":true,"snapshots":false,"indexed":true,"description":"Local third-party releases","stageRepoNeeded":false,"blockRedeployments":true,"scanned":true,"skipPackedIndexCreation":false}' \
http://localhost:8080/restServices/archivaServices/managedRepositoriesService/addManagedRepository
{"id":"thirdparty",...,"location":"/opt/archiva/repositories/thirdparty",...}
| 参数 | 本文取值 | 说明 |
|---|---|---|
location | /opt/archiva/repositories/thirdparty | 必须绝对路径；写 ./repositories/thirdparty 会落成 .../repositories/repositories/thirdparty（实测怪癖） |
releases / snapshots | true / false | 承载 release 版还是 snapshot 版 |
blockRedeployments | true | 禁止同版本重复部署（release 仓库强烈建议开） |
cronExpression | 0 0 * * * ? | Quartz 6 段式：秒 分 时 日 月 周；整点扫描一次 |
daysOlder / retentionCount | 30 / 2 | 快照清理：删 30 天前的、每版本至少留 2 个 |
scanned | true | 参与定期扫描 |
indexed | true | 建索引（搜索与依赖净化需要） |
stageRepoNeeded | false | 是否建配套 staging 仓库 |
删除仓库（GET + 查询参数，deleteContent=true 连同落盘内容）：
curl -s -b /tmp/archiva-cookie.txt -H "X-XSRF-TOKEN: $TOKEN" \
'http://localhost:8080/restServices/archivaServices/managedRepositoriesService/deleteManagedRepository?repositoryId=thirdparty&deleteContent=true'
true
5.5 远程仓库与代理参数（remote repositories）
内置远程仓库 central（出厂原样）：
| 参数 | 出厂值 | 说明 |
|---|---|---|
url | https://repo.maven.apache.org/maven2 | Maven 中央仓库 |
timeout | 60 | 连接与读取超时（秒） |
checkPath | 空 | 连通性探测的相对路径（见下） |
cronExpression | 0 0 08 ? * SUN | 每周日 08:00 更新远程索引 |
downloadRemoteIndex | false | 出厂不自动下载远程索引 |
内网代理常用的是指向国内镜像（实测新增阿里云镜像并验证连通性）：
curl -s -b /tmp/archiva-cookie.txt -X POST -H 'Origin: http://localhost:8080' \
-H 'Content-Type: application/json' -H "X-XSRF-TOKEN: $TOKEN" \
-d '{"id":"aliyun","name":"Aliyun Maven Mirror","url":"https://maven.aliyun.com/repository/public","layout":"default","timeout":60,"checkPath":"junit/junit/4.13.2/junit-4.13.2.pom","cronExpression":"0 0 08 ? * SUN"}' \
http://localhost:8080/restServices/archivaServices/remoteRepositoriesService/addRemoteRepository
true
连通性检查接口 checkRemoteConnectivity 的行为实测：checkPath 为空时探测根路径（镜像站根路径通常 404 → 返回 false）；把 checkPath 指向一个真实存在的制品路径后返回 true：
curl -s -m 15 -o /dev/null -w '%{http_code}\n' \
https://maven.aliyun.com/repository/public/junit/junit/4.13.2/junit-4.13.2.pom
curl -s -b /tmp/archiva-cookie.txt -H "X-XSRF-TOKEN: $TOKEN" -H 'Origin: http://localhost:8080' \
http://localhost:8080/restServices/archivaServices/remoteRepositoriesService/checkRemoteConnectivity/aliyun
200
true
代理关系经 proxy connectors 配置（控制台或 REST），配置后本地仓库即自动从远程仓库按需拉取：实测从 internal 代理取到的制品可直连下载：
curl -s -o /dev/null -w '%{http_code}\n' \
http://localhost:8080/repository/internal/junit/junit/4.13.2/junit-4.13.2.pom
200
5.6 数据目录与日志
| 目录/文件 | 用途 |
|---|---|
/opt/archiva/data/databases | Derby 元数据库（仓库定义、用户、审计等） |
/opt/archiva/data/jcr | 内容仓储（jcr 会话工厂的索引与元数据） |
/opt/archiva/data/remotes | 远程仓库下载缓存 |
/opt/archiva/data/users | 用户数据库 |
/opt/archiva/repositories/ | 仓库存储（制品按 Maven 布局落盘） |
/opt/archiva/derby.log | Derby 引擎日志（在安装根） |
logs/archiva.log | 应用主日志 |
logs/wrapper-YYYYMMDD.log | wrapper 与 JVM 启动日志（含 Full thread dump，bin/archiva dump 输出落此） |
logs/request-YYYYMMDD.log | HTTP 请求日志 |
logs/archiva-audit.log | 仓库审计事件（部署、删除、代理下载） |
备份要点：停服后打包 data/ 与 repositories/ 即为完整备份；logs/ 可按需归档。
5.7 systemd 部署参数
/etc/systemd/system/archiva.service（完整文件见《安装指南》4.7）：
| 配置项 | 本文取值 | 说明 |
|---|---|---|
Type | forking | wrapper start 拉起后台进程 |
PIDFile | /opt/archiva/logs/archiva.pid | 与 wrapper 脚本内 PIDDIR 一致 |
LimitNOFILE | 65536 | 仓库文件数大时防 too many open files |
TimeoutStartSec | 180 | 首次启动含 Derby 建库，放宽超时 |
Restart / RestartSec | on-failure / 30 | 与 wrapper 的 restart.delay=30 语义对应 |
六、生产配置模板
适用场景：4 核 8GB 内存、单实例、承担团队内部 Maven 代理与私有制品托管、仓库存储独立挂盘到 /data/archiva-repos。
conf/wrapper.conf 关键行（相对出厂的改动）：
wrapper.java.command=/usr/lib/jvm/java-8-openjdk-amd64/bin/java
wrapper.java.additional.8=-XX:MaxPermSize=256m
wrapper.java.additional.9=-Djetty.port=8081
wrapper.java.initmemory=512
wrapper.java.maxmemory=2048
wrapper.restart.delay=30
conf/jetty.xml 建议仅调 maxIdleTime（代理大文件的慢客户端）：
<Set name="maxIdleTime">60000</Set>
仓库策略建议（经控制台/REST 配置）：
| 项 | 建议值 | 理由 |
|---|---|---|
release 仓库 blockRedeployments | true | 防止同版本制品被覆盖 |
snapshot 仓库 daysOlder/retentionCount | 7 / 1 | 快照膨胀快，收紧保留策略 |
远程仓库 timeout | 120 | 弱网环境减少代理失败 |
远程索引 downloadRemoteIndex | false | 远程索引体积大，按需检索即可 |
systemd 单元与《安装指南》4.7 相同；堆 2048MB 时整机内存建议 4GB 起。
说明：256-512MB 小堆（
-Xms256m -Xmx512m）已实测可稳定启动并完成管理员初始化、建仓、代理拉取全流程（systemd Memory 字段实测 428.7M）；上表加大堆面向数百 G 制品库规模，上线后按archiva.log扫描耗时与 wrapper 日志 GC 表现微调。
七、常见问题
7.1 修改配置后不生效
现象：改了 wrapper.conf 或 jetty.xml，行为仍是旧值。
定位：只在启动时读配置，运行中不会热加载；systemd 场景还需确认改的是 /opt/archiva/conf/ 下的真实文件（多实例部署易改错目录）。
解决：重启并复核：
systemctl restart archiva && sleep 15
systemctl is-active archiva
jps -v | grep WrapperSimpleApp | grep -oE '\-Xms[0-9]+m \-Xmx[0-9]+m'
active
-Xms256m -Xmx512m
7.2 端口被占用启动失败
现象：wrapper 日志出现 Address already in use，服务反复重启（wrapper on_exit.default=RESTART）。
定位与解决：netstat -tlnp | grep 8080 找到占用进程停掉，或按 5.1 换端口（-Djetty.port）后重启。注意 wrapper 会自动重试拉起，先修配置再观察，不要在端口冲突时反复手动 start 制造多实例。
7.3 堆内存不足（OutOfMemoryError）
现象：logs/wrapper-YYYYMMDD.log 出现 java.lang.OutOfMemoryError；JDK 8 下有两类——堆不足（Java heap space）与永久代不足（PermGen space）。
解决：堆不足上调 maxmemory；PermGen 不足上调 additional.8 的 -XX:MaxPermSize。改完重启并用 jps -v 确认。512MB 堆 + 128MB 永久代实测可支撑中小规模仓库；大量代理索引时优先加永久代。
7.4 代理源连不上但镜像站可达
现象：checkRemoteConnectivity 返回 false，但同路径 curl 返回 200。
定位：checkPath 为空时探测的是远程仓库根路径，很多镜像站根路径返回 404，被判定为不可达（实测阿里云镜像即如此）。
解决：给远程仓库配置 checkPath 指向一个确定存在的制品（如 junit/junit/4.13.2/junit-4.13.2.pom），再检查即返回 true（见 5.5 实测）。
7.5 仓库落盘位置不对（多一层 repositories）
现象：建仓 location 写 ./repositories/thirdparty，实际生成 /opt/archiva/repositories/repositories/thirdparty。
定位与解决：相对路径按 repositories 根拼接且不归一化（实测怪癖），建仓一律写绝对路径；已建错的删仓重建即可。
7.6 REST 改的仓库定义和 archiva.xml 不一致
定位：仓库/远程仓库/代理连接的定义以 Archiva 运行时数据库（Derby）为准，archiva.xml 是启动持久化与写回文件；直接手改该文件不等于改运行时配置。
解决：一律经控制台或 REST 修改仓库定义；手改仅适用于 fileTypes、urlFailureCacheConfiguration 等静态段，改完重启。
八、参考链接
- 官方管理指南（2.2.10，含仓库与代理配置）：https://archiva.apache.org/docs/2.2.10/adminguide/
- REST API 文档（2.2.10）：https://archiva.apache.org/docs/2.2.10/rest-services/archiva-services.html
- Tanuki JSW wrapper 配置参考：https://wrapper.tanukisoftware.com/doc/english/props.html
- Apache Attic 项目页：https://attic.apache.org/projects/archiva.html