Apache Archiva 2.2.10 常用 CLI 命令与工具详解

目标：详解 Apache Archiva 2.2.10 的常用命令行工具——bin/archiva 服务生命周期管理（含线程 dump）、systemctl 托管命令、curl 调用 REST API（三重鉴权与仓库管理）、jps/netstat/日志文件诊断。所有命令与回显均为真实环境实测。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS
Java：OpenJDK 1.8.0_504
Apache Archiva：2.2.10（独立发行包，JSW wrapper 3.2.3）
安装目录：/opt/archiva
服务脚本：/opt/archiva/bin/archiva
服务端口：8080（HTTP）
管理账号：admin / q1w2e3r4
运行方式：本文演示 bin/archiva 子命令时先停 systemd 避免二者互相干扰（混用后果见 6.1），演示完恢复 systemd 托管

二、工具概览

工具	位置	用途
`archiva`	`/opt/archiva/bin/`	服务启停/状态/线程 dump（console、start、stop、restart、status、dump）
`systemctl`	系统命令	systemd 托管（推荐的生产运行方式）
`curl`	系统命令	调用 `/restServices/` REST 接口（鉴权、仓库管理、制品下载）
`jps`	JDK 自带	查看 Archiva Java 进程及 JVM 参数生效值
`netstat`	`net-tools` 包	校验 8080 端口监听
日志文件	`/opt/archiva/logs/`	archiva.log / wrapper-日期.log / request-日期.log / archiva-audit.log 排障

三、前置条件

已按《Apache Archiva 2.2.10 安装指南》完成安装：/opt/archiva 就绪，JDK 8 已装（含 jps），管理员已初始化。
若 Archiva 由 systemd 托管，演示 bin/archiva 前先停止服务：

systemctl stop archiva
systemctl is-active archiva

inactive

四、工具详解

4.1 bin/archiva 服务管理

bin/archiva 是 JSW wrapper 的管理脚本，不带参数运行查看用法：

cd /opt/archiva && ./bin/archiva

Usage: ./bin/archiva { console | start | stop | restart | status | dump }

子命令	说明
`start`	后台启动（wrapper 守护 java 进程），pid 写入 `/opt/archiva/logs/archiva.pid`
`stop`	停止服务
`restart`	先停后启
`status`	输出运行状态（括号内为 wrapper 进程号）
`dump`	向运行中的 JVM 请求线程 dump，写入 wrapper 日志
`console`	前台运行，日志直接打到当前终端（Ctrl+C 退出）

启动服务：

cd /opt/archiva && ./bin/archiva start
./bin/archiva status
jps -l | grep -v Jps

Starting Apache Archiva...
Apache Archiva is running (27953).
27955 org.tanukisoftware.wrapper.WrapperSimpleApp

💡 说明：status 括号里的 27953 是 wrapper 守护进程号，jps 里的 27955 是它拉起的 java 子进程，二者相差一位属正常。启动到端口就绪约 10-20 秒。

重启与停止（实测回显）：

./bin/archiva restart
sleep 3 && ./bin/archiva status

Stopping Apache Archiva...
Stopped Apache Archiva.
Starting Apache Archiva...
Apache Archiva is running (28161).

./bin/archiva stop
./bin/archiva status

Stopping Apache Archiva...
Stopped Apache Archiva.
Apache Archiva is not running.

线程 dump（排障利器，输出追加到当日 wrapper 日志）：

./bin/archiva dump
grep -c "Full thread dump" /opt/archiva/logs/wrapper-$(date +%Y%m%d).log
grep -m1 "Full thread dump" /opt/archiva/logs/wrapper-$(date +%Y%m%d).log

Dumping Apache Archiva...
Dumped Apache Archiva.
3
INFO   | jvm 1    | 2026/10/13 03:38:18 | Full thread dump OpenJDK 64-Bit Server VM (25.504-b01 mixed mode):

4.2 systemctl 托管命令

生产环境推荐 systemd 托管（单元文件见《安装指南》4.7），管理一律走 systemctl：

systemctl start archiva && sleep 15
systemctl is-active archiva
systemctl status archiva --no-pager -n 0 | head -6

active
● archiva.service - Apache Archiva Repository Manager (Jetty standalone)
     Loaded: loaded (/etc/systemd/system/archiva.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2026-10-13 07:11:33 UTC; 15s ago
   Main PID: 26946 (wrapper-linux-x)
     Tasks: 109
     Memory: 428.7M

systemctl restart archiva
systemctl stop archiva

⚠️ 注意：systemd 的 Main PID 是 wrapper 进程；Restart=on-failure 配合 wrapper 的自动重启逻辑，异常退出会由 systemd 再兜底拉起一次，因此排障时先 systemctl stop 再动 bin/archiva。

4.3 curl 调用 REST API

Archiva REST 前缀为 /restServices/，分 archivaServices（仓库管理）与 redbackServices（用户与鉴权）两大组。鉴权三要素实测：所有请求带 Origin 头（CSRF 校验，缺了直接 403）；受保护接口还需登录会话 Cookie（JSESSIONID）+ X-XSRF-TOKEN 头（值为登录返回的 validationToken）。

免登录接口（带 Origin 即可）：

curl -s -H 'Origin: http://localhost:8080' \
  http://localhost:8080/restServices/archivaServices/pingService/ping
curl -s -H 'Origin: http://localhost:8080' \
  http://localhost:8080/restServices/redbackServices/userService/isAdminUserExists

Yeah Baby It rocks!
true

登录拿会话（凭据走 JSON 体）：

curl -s -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -H 'Origin: http://localhost:8080' -c /tmp/archiva-cookie.txt \
  -d '{"username":"admin","password":"q1w2e3r4"}' \
  http://localhost:8080/restServices/redbackServices/loginService/logIn > /tmp/login.json
grep -o '"username":"admin"' /tmp/login.json

{"username":"admin","fullName":"Archiva Administrator","email":"admin@example.org",...,"validationToken":"hj5rr9jX6g2MEX..."}

组合三要素访问业务接口（列出本地仓库）：

TOKEN=$(grep -oP '(?<="validationToken":")[^"]+' /tmp/login.json)
curl -s -b /tmp/archiva-cookie.txt -H 'Origin: http://localhost:8080' -H "X-XSRF-TOKEN: $TOKEN" \
  http://localhost:8080/restServices/archivaServices/managedRepositoriesService/getManagedRepositories

[{"id":"internal",...,"location":"/opt/archiva/repositories/internal",...},{"id":"snapshots",...},{"id":"thirdparty",...}]

建仓 / 删仓（实测回显）：

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,"blockRedeployments":true,"scanned":true}' \
  http://localhost:8080/restServices/archivaServices/managedRepositoriesService/addManagedRepository
curl -s -b /tmp/archiva-cookie.txt -H "X-XSRF-TOKEN: $TOKEN" -H 'Origin: http://localhost:8080' \
  'http://localhost:8080/restServices/archivaServices/managedRepositoriesService/deleteManagedRepository?repositoryId=thirdparty&deleteContent=true'

{"id":"thirdparty","name":"Third Party Repository","layout":"default","indexDirectory":null,"description":null,"location":"/opt/archiva/repositories/thirdparty",...}
true

远程仓库连通性检查（checkPath 指向真实制品路径，见《配置参数详解》5.5）：

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

true

代理下载与仓库浏览（免登录的 HTTP 路径，Maven 客户端用的就是它们）：

curl -s -o /dev/null -w '%{http_code}\n' \
  http://localhost:8080/repository/internal/junit/junit/4.13.2/junit-4.13.2.pom
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/repository/internal/

200
200

常用接口速查：

接口	方法	鉴权	说明
`/restServices/archivaServices/pingService/ping`	GET	Origin	存活探针，应答 `Yeah Baby It rocks!`
`/restServices/redbackServices/userService/isAdminUserExists`	GET	Origin	管理员是否已初始化
`/restServices/redbackServices/userService/createAdminUser`	POST	Origin	首次初始化管理员
`/restServices/redbackServices/loginService/logIn`	POST	Origin	JSON 体登录，返回 validationToken
`/restServices/archivaServices/managedRepositoriesService/getManagedRepositories`	GET	会话+Token	本地仓库列表
`/restServices/archivaServices/managedRepositoriesService/addManagedRepository`	POST	会话+Token	新建本地仓库
`/restServices/archivaServices/managedRepositoriesService/deleteManagedRepository`	GET	会话+Token	删除仓库（查询参数传 id）
`/restServices/archivaServices/remoteRepositoriesService/addRemoteRepository`	POST	会话+Token	新建远程仓库
`/restServices/archivaServices/remoteRepositoriesService/checkRemoteConnectivity/{id}`	GET	会话+Token	远程仓库连通性
`/repository/{仓库id}/<maven路径>`	GET	无	制品下载（Maven 客户端入口）
`/repository/{仓库id}/`	GET	无	仓库目录浏览

4.4 Web 控制台访问

浏览器打开 http://<服务器IP>:8080/（页面标题实测 Apache Archiva），用 admin / q1w2e3r4 登录后可进行仓库管理、上传制品、搜索与权限配置。控制台登录走的就是 4.3 的 logIn 会话机制，脚本登录拿到的 Cookie 与浏览器会话等价。

curl -s http://localhost:8080/ | grep -oE '<title>[^<]*</title>'

<title>Apache Archiva</title>

4.5 进程、端口与日志诊断

确认 JVM 参数实际生效（本文堆限制 256-512MB）：

jps -v | grep WrapperSimpleApp | grep -oE '\-Xms[0-9]+m \-Xmx[0-9]+m'

-Xms256m -Xmx512m

确认端口监听：

netstat -tlnp | grep 8080

tcp6       0      0 :::8080                 :::*                    LISTEN      27536/java

日志文件速查（/opt/archiva/logs/）：

文件	用途
`archiva.log`	应用主日志，启动阶段报错看这里
`wrapper-YYYYMMDD.log`	wrapper 与 JVM 启动日志，`dump` 的线程快照也落此
`request-YYYYMMDD.log`	HTTP 请求日志（含代理下载）
`archiva-audit.log`	仓库审计事件（部署/删除/下载）

服务不监听时优先看 wrapper 日志末尾：

tail -20 /opt/archiva/logs/wrapper-$(date +%Y%m%d).log
tail -20 /opt/archiva/logs/archiva.log

五、注意事项

pid 文件在 /opt/archiva/logs/archiva.pid，由 wrapper 写入；文件缺失不代表进程不在（见 6.1），以 jps 与端口检查为准。
console 前台运行时终端 Ctrl+C 直接终止服务，仅用于调试。
REST 请求缺 Origin 头一律 403；受保护接口缺会话或 X-XSRF-TOKEN 同样 403，三者缺一不可。
修改任何配置后需重启生效，重启后用 jps -v 与端口检查双重复核。
与 systemd 混用 bin/archiva 会触发自动重启风暴（见 6.1），一种环境只用一种托管方式。

六、常见问题

6.1 systemd 与 bin/archiva 混用导致状态错乱（实测案例）

现象：systemctl status archiva 显示 activating (auto-restart) (Result: exit-code)、Main PID ... (code=exited, status=254) 反复重启；而 bin/archiva stop 却输出：

Stopping Apache Archiva...
Apache Archiva was not running.

同时 8080 端口仍被一个 java 进程 LISTEN，REST 一切正常。

定位：此前曾用 bin/archiva start/restart 手工管理过进程（wrapper 把新实例 pid 写进 pid 文件，脱离了 systemd 的 Main PID 追踪）；之后 systemd 按重启策略拉起新实例，新实例绑定 8080 失败以退出码 254 结束，Restart=on-failure 再拉起，形成循环；pid 文件在停止流程中被清掉，bin/archiva stop 找不到 pid 便误报 not running，旧实例成了脱管进程。

解决（按序执行，实测有效）：

systemctl stop archiva                       # 停掉 systemd 的重启循环
/opt/archiva/bin/archiva stop                # 尝试脚本停止（可能报 not running）
jps | awk '/WrapperSimpleApp/{print $1}'     # 找到脱管 java 进程号
kill <上一步的pid>; sleep 4                   # 结束脱管实例
netstat -tlnp | grep 8080                    # 确认端口已释放
systemctl reset-failed archiva               # 清掉 systemd 的失败计数
systemctl start archiva && sleep 15
systemctl is-active archiva

active

预防：脚本管理（bin/archiva）与 systemd 托管不要混用；切换托管方式前，先用对方的方式把服务完整停掉。

6.2 调 REST 接口一律 403

定位：缺 Origin 头（CSRF 校验直接拒绝，响应体为空）；或访问受保护接口时缺会话 Cookie / X-XSRF-TOKEN。

解决：按 4.3 的三要素补齐请求头；Origin 值与访问的主机端口一致即可（实测 http://localhost:8080）。

6.3 登录接口报 incorrect.username.password

现象：curl -u admin:q1w2e3r4 调 loginService/logIn 返回 500：

{"errorMessages":[{"errorKey":"incorrect.username.password","args":[],"message":null}]}

定位：Redback 登录接口不接受 HTTP Basic，凭据必须放 JSON 体；账号密码本身没错也会报这个。

解决：改用 -H 'Content-Type: application/json' -d '{"username":"admin","password":"..."}' POST 登录。

6.4 jps 命令不存在

定位：jps 属 JDK 工具，只装 JRE 时没有。

解决：安装 openjdk-8-jdk-headless（含 jps），或用 ps -ef | grep WrapperSimpleApp 替代查看进程。

七、参考链接

官方管理指南（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/invokewrapper.html
Apache Attic 项目页：https://attic.apache.org/projects/archiva.html