EPICS Archiver Appliance零基础安装避坑指南（附Tomcat 9.X配置）

如果你刚刚接触EPICS Archiver Appliance，面对一堆WAR文件和Tomcat配置，感觉无从下手，那么这篇文章就是为你准备的。我见过不少开发者，尤其是从物理实验或控制系统转过来的朋友，在初次部署这个强大的数据归档系统时，会被一些看似简单却极易踩坑的细节绊住。比如，明明按照指南操作，Tomcat却启动失败；或者浏览器能打开页面，但PV（过程变量）就是无法正常归档。这些问题往往不是系统本身复杂，而是环境配置的“暗礁”在作祟。

本文的目标，就是充当你的“扫雷器”。我们将聚焦于最常见的Tomcat 9.X环境，抛开生产部署的复杂考量，专注于让你在最短时间内，成功搭建起一个可运行、可测试的评估环境。我会结合自己多次部署的经验，把那些官方文档里一笔带过、但实际中频频出错的环节——比如JDK版本兼容性、日志级别设置的真正含义、以及“配置非持久化”带来的后续影响——都掰开揉碎了讲清楚。你不是在仿照步骤操作，而是在理解每一个动作背后的逻辑，从而真正避开那些坑。

1. 环境准备：从零开始的正确姿势

在解压任何压缩包之前，一个干净、兼容的基础环境是成功的一半。很多快速开始的失败，根源其实在第一步就埋下了。

1.1 JDK版本：不是越新越好

官方指南可能会说“确认安装了最新版的JDK”，但在实际的企业级Java应用部署中，这往往是一个过于简化的建议。EPICS Archiver Appliance作为一个相对成熟的项目，其对JDK版本的兼容性有特定的范围。盲目使用最新的JDK（例如JDK 21或22），可能会遇到不兼容的API或未被充分测试的JVM行为，导致一些难以排查的运行时错误。

注意：根据社区反馈和实际测试，对于Tomcat 9.x，推荐使用JDK 8、JDK 11或JDK 17（LTS版本）。这些是经过长期支持、生态兼容性最好的版本。

如何检查并确认你的JDK版本？打开终端，执行：

java -version

你期望看到的输出应该是类似这样的结构，明确显示了LTS版本号：

openjdk version "11.0.20" 2023-07-18
OpenJDK Runtime Environment (build 11.0.20+8-post-Ubuntu-1ubuntu122.04)
OpenJDK 64-Bit Server VM (build 11.0.20+8-post-Ubuntu-1ubuntu122.04, mixed mode, sharing)

如果你的版本不符合，需要先进行安装或切换。在Ubuntu/Debian系统上，你可以使用update-alternatives来管理多个JDK版本。在CentOS/Rocky Linux上，可能需要手动配置环境变量JAVA_HOME。确保JAVA_HOME指向正确的JDK安装路径，并且该路径被加入到系统的PATH变量中。

1.2 工作目录与权限管理

创建一个独立、整洁的工作目录至关重要。这不仅能避免文件混乱，也便于后续的问题排查和清理。我建议不要直接在/home或/tmp下操作。

# 创建一个专门的目录，名字可以自定义，这里用`epics_archiver`
sudo mkdir -p /opt/epics_archiver
# 将目录所有权改为你当前的非root用户（假设用户名为`deployer`），方便操作
sudo chown -R deployer:deployer /opt/epics_archiver
cd /opt/epics_archiver

接下来，你需要下载两个核心文件：EPICS Archiver Appliance的发布包和Apache Tomcat 9.x。务必从官方或可信镜像站下载，以确保文件的完整性。

• Archiver Appliance: 从其 GitHub Releases 页面获取最新稳定版的 tar.gz 包。
• Apache Tomcat 9.x: 从 Apache Tomcat官网 下载Core分类下的 tar.gz 包。

使用wget或curl命令下载到刚才创建的目录中。完成后，使用ls命令确认两个文件都已就位：

ls -lh

预期输出应类似于：

-rw-r--r-- 1 deployer deployer 11M Mar 15 10:30 apache-tomcat-9.0.85.tar.gz
-rw-r--r-- 1 deployer deployer 45M Mar 15 10:31 archappl_v1.1.0.tar.gz

2. 解压与脚本执行的深层解析

很多教程把解压和运行脚本当作一个黑盒步骤。但理解里面发生了什么，能让你在出现问题时不再茫然。

2.1 解压包结构与快速启动脚本

首先解压Archiver Appliance的发布包：

tar -xvzf archappl_v1.1.0.tar.gz

解压后，你会看到一系列文件和文件夹。对于快速评估，我们最需要关注的是以下四个WAR文件和一个Bash脚本：

engine.war    # 处理数据存储和检索的核心引擎
etl.war       # 负责数据抽取、转换和加载（Extract, Transform, Load）
mgmt.war      # 提供管理界面和配置API
retrieval.war # 处理数据查询请求
quickstart.sh # 自动化部署和启动脚本

quickstart.sh 是这个快速入门流程的灵魂。它本质上是一个自动化脚本，替你完成了以下繁琐工作：

1. 解压你指定的Tomcat压缩包。
2. 将上述四个WAR文件复制到Tomcat的webapps目录下。
3. 修改Tomcat的conf/logging.properties和conf/server.xml，调整日志级别和端口。
4. 创建一个简单的setenv.sh来设置JVM参数和日志配置。
5. 最后，以前台模式启动Tomcat。

2.2 执行脚本与常见报错处理

运行脚本的命令很简单，但这里有几个关键点：

# 确保你在包含 quickstart.sh 和 tomcat 压缩包的目录下
./quickstart.sh apache-tomcat-9.0.85.tar.gz

执行时可能遇到的“坑”及解决方案：

1. 权限不足：如果脚本没有执行权限，你会看到 Permission denied。使用 chmod +x quickstart.sh 赋予执行权。
2. Tomcat端口冲突：脚本默认会使用一个相对冷门的端口（如17665）。但如果该端口已被占用，Tomcat启动会失败。脚本通常会尝试绑定到17665（mgmt）、17666（engine）等端口。你可以通过netstat -tlnp | grep :17665检查端口占用情况。如果冲突，一个快速但不适用于生产的方法是：停止占用端口的进程，或者直接重启机器（仅限测试环境）。
3. 脚本执行中途报错：仔细阅读控制台输出的红色错误信息。常见原因包括：
   • JDK版本不兼容（回归到1.1节检查）。
   • 磁盘空间不足。
   • 系统内存不足。Tomcat和四个Web应用同时运行需要一定内存，确保虚拟机或物理机有至少2GB的可用内存。

如果脚本运行成功，你将看到Tomcat的启动日志疯狂滚动。这是正常现象，说明四个Web应用正在被Tomcat加载和初始化。

3. 启动过程监控与状态确认

启动过程大约需要2到5分钟，这段时间的控制台输出信息量很大，学会从中提取关键信息，是判断部署是否成功的关键。

3.1 读懂启动日志

启动日志看起来杂乱，但有几条是“生命线”，必须找到：

... (大量INFO日志)
[main] org.apache.catalina.startup.Catalina.start Server startup in [X] milliseconds

这条信息表明Tomcat容器本身启动成功。

紧接着，你会看到四个Web应用（mgmt, engine, etl, retrieval）各自的初始化日志。最终，最重要的成功标志是出现类似下面的日志行：

[http-nio-17665-exec-6] INFO config.org.epics.archiverappliance.mgmt.MgmtRuntimeState - All components in this appliance have started up. We should be ready to start accepting UI requests.

当你看到 All components in this appliance have started up 这条信息时，恭喜你，Archiver Appliance的所有核心组件都已就绪，可以接受用户界面的访问请求了。

3.2 日志级别：ERROR与DEBUG的切换

官方指南提到默认设置Log4j根日志级别为ERROR，这意味着在控制台你只会看到错误及以上级别的日志。这是一个非常明智的默认设置，避免了信息过载。

但在排查问题时，ERROR级别可能信息不足。这时，你可以按照指南，使用-v（verbose）参数重新启动，将日志级别调整为DEBUG。

但这里有个重要的实践细节：quickstart.sh脚本在第一次运行后，已经创建并配置好了一个Tomcat实例。再次直接运行./quickstart.sh ...会尝试创建新的实例，可能导致端口冲突。更常见的做法是：

1. 首先，用Ctrl+C停止当前正在前台运行的Tomcat进程。
2. 进入脚本为你解压并配置好的Tomcat目录（通常形如apache-tomcat-9.0.85）。
3. 直接运行该目录下bin文件夹中的catalina.sh脚本，并带上run参数（前台运行）和通过JAVA_OPTS传递日志级别参数。

# 假设Tomcat目录是 apache-tomcat-9.0.85
cd apache-tomcat-9.0.85
# 设置JAVA_OPTS环境变量来调整日志级别，然后启动
export JAVA_OPTS="-Dlog4j.rootLogger=DEBUG, stdout"
./bin/catalina.sh run

这种方式让你能更灵活地控制已部署实例的运行参数。

4. 访问、测试与理解“非持久化”

系统启动成功后，真正的测试才刚刚开始。浏览器访问只是第一步，理解快速入门模式的局限性至关重要。

4.1 访问管理界面并添加PV

打开你的浏览器，输入管理界面的地址。地址的构成是： http://<你的服务器IP地址>:17665/mgmt/ui/index.html

例如，如果你的服务器IP是192.168.1.100，那么地址就是 http://192.168.1.100:17665/mgmt/ui/index.html。

成功访问后，你会看到Archiver Appliance的Web管理界面。为了测试基本功能，你可以尝试归档一个PV。

一个关键技巧：如果你还没有一个正在运行的EPICS IOC（输入输出控制器）提供真实的PV，可以使用Archiver Appliance自带的模拟PV功能进行测试。在管理界面的“Archive PV”输入框中，输入以sim://开头的模式，例如：

• sim://sine （生成一个正弦波）
• sim://noise （生成带噪声的信号）
• sim://ramp （生成一个斜坡信号）

点击“Archive”后，系统会开始归档这个模拟PV。大约5分钟后（系统需要时间测量事件速率并完成初始状态转换），该PV的状态会从“Initial sampling”变为“Being archived”。你可以在“Retrieval”标签页下尝试查询和绘图，验证数据是否被成功存储和检索。

4.2 “配置非持久化”意味着什么？

这是快速入门指南中一个必须理解透彻的限制。脚本默认使用了org.epics.archiverappliance.config.ConfigServiceDefault，它将所有配置（包括你添加的PV列表、归档参数等）保存在内存中。

这带来的直接后果是：一旦你通过Ctrl+C停止Tomcat进程，所有的配置信息都会丢失。 下次启动时，你将面对一个“崭新”的Archiver，之前归档的所有PV都需要重新提交。

为了让你更清晰地理解生产部署与快速评估在这方面的区别，请看下表：

特性	快速评估模式 (quickstart.sh)	生产部署模式
配置存储	内存 (Memory)	关系数据库 (如 MySQL, PostgreSQL) 或 SQLite 文件
持久性	非持久化，进程结束即丢失	持久化，服务器重启后配置保留
优点	无需安装配置数据库，启动最快	配置可靠，支持多节点集群，易于管理
缺点	无法保存PV列表，仅用于临时测试	需要额外的数据库安装与配置步骤
适用场景	功能验证、学习、短期演示	实际数据归档、长期运行、高可用需求

4.3 安全停止与后续步骤

当你完成测试，需要停止Archiver时，请在运行Tomcat的控制台窗口中，按下 Ctrl+C。这会向Tomcat发送一个中断信号，使其进行优雅关闭，确保正在进行的操作（如数据写入）能够安全完成。

如果你想基于这个快速入门的成果，转向一个更持久、更可靠的生产环境部署，下一步就是研究如何配置数据库（MySQL或SQLite）作为配置和数据的存储后端。你需要仔细阅读项目install_scripts目录下的single_machine_install.sh脚本或相关SQL脚本，它会引导你完成数据库初始化、连接池配置等步骤。这超出了本文“避坑”的范围，但却是将评估环境转化为可用系统的必经之路。

记住，快速入门的目的达到了：你已验证了软件能在你的环境中跑起来，并理解了其核心工作流程。这为你后续更深入的探索和部署打下了最坚实、最直观的基础。