EPICS Archiver Appliance部署教程：历史数据归档系统搭建指南

做EPICS控制系统的工程师，十有八九会被同一个问题折磨——历史数据。束流调试的时候想看看昨晚的腔压曲线，设备重启了想找回重启前的波形，写论文要拉半年以上的温度趋势，这些需求一旦出现，你总不可能天天守在IOC前面手动记录。早期我们团队自己写Python脚本轮询PV、存CSV、再用Matplotlib画图，凑合能用，但PV一多就崩，磁盘文件乱得跟垃圾桶一样，检索起来更是噩梦。后来换上了EPICS Archiver Appliance，这套由SLAC开源的历史数据归档系统，算是彻底把这个问题解决了。

严格来说，Archiver Appliance不是一个简单的数据采集程序，而是一整套“采集、存储、检索、展示”闭环方案。它内部基于Tomcat和MySQL，对外提供Web管理界面、HTTP查询API，以及多种客户端接入方式，装上之后你只需要告诉它“我要归档哪些PV”，剩下的自动完成。这篇教程就是我从零开始部署Archiver Appliance的完整记录，包括设计思路、环境选型、核心配置、常见坑点，照着做基本能一次跑通。

1. Archiver Appliance凭什么能解决归档难题

1.1 它到底做了什么

先理解Archiver Appliance在系统里的位置。EPICS里每个实时数据点叫PV（Process Variable），IOC持续更新这些PV的值。传统做法是你自己写程序去不断轮询、记录，但做出来的系统往往有两个问题：第一是轮询频率和存储格式难权衡，存太密磁盘爆掉，存太稀数据没有分析价值；第二是查询接口各自为政，数据可视化工具根本没法统一对接。Archiver Appliance则把所有PV的历史数据按照统一格式接收、压缩、存储，并对外提供标准查询API，上层不管是CSS、Phoebus Data Browser还是你自己写的Python脚本，都能用同一套协议把数据取出来。

它内部拆成几个模块：数据接收引擎负责连接EPICS Channel Access或者利用PVAccess获取数据；存储引擎负责把数据写进时序文件；MySQL数据库只保存元数据信息（比如PV别名、存储策略、数据文件索引），真正的大块时间序列数据存放在普通文件系统里；管理Web界面让你在浏览器里完成PV管理和存储策略配置。这样设计的好处非常明显——数据量大时不至于拖垮数据库，数据库挂了历史数据文件也还在，安全性高得多。

1.2 三层存储架构背后的设计思考

这是Archiver Appliance最值得说的设计之一。它把存储切成了三个区：STS（短期存储）、MTS（中期存储）、LTS（长期存储）。听起来高大上，本质就是“新数据放SSD、中期数据放大容量SATA盘、冷数据放到便宜的机械盘或NAS”。新写入的数据先进STS，便于近期频繁查询；随着时间推移，数据自动向MTS、LTS迁移。

为什么非要搞三层？用过你就明白。对实验装置来说，最近几小时的波形是调试时最常翻的，必须访问快；半年以上的数据，基本只是写报告时才拉一次，放在慢速大容量盘上完全没毛病。如果所有数据都留在SSD上，成本会让你怀疑人生；如果全部直接进慢盘，在线查看实时趋势就会卡顿到崩溃。Archiver Appliance用一套后台迁移机制自动完成数据搬迁，你在Web界面里只需要配置每个存储区对应的目录路径和迁移策略，剩下的事情它自己搞定。

1.3 四种部署模式，先搞清楚该选哪个

Archiver Appliance支持Single、Dual、Cluster、Razor四种部署模式。Single就是单机版，所有组件跑在一台机器上，适合测试环境和小装置；Dual是两台机器，一台负责接收数据写入，一台负责提供查询服务，写入机器故障时查询机器还能继续服务；Cluster是多台机器组成集群，更适合大型装置，每台机器分管一部分PV；Razor则是更极端的扩展模式，用NoSQL存储后端支撑海量数据场景。

我建议的原则是：实验室内测试、调程序用Single模式足够了，省心省事；如果有正经的束流运行需求，至少上Dual模式；整个大科学装置级别再考虑Cluster。别一上来就搭集群，Archiver Appliance的集群部署复杂度跟单机完全不是一个量级，坑也更多。你完全可以从Single起步，数据和配置随时可以迁移，这个学习成本值得花。

2. 部署前的环境准备，版本选型有讲究

2.1 硬件与系统建议

部署Archiver Appliance对硬件的下限要求不高，2核4G内存的虚拟机也能起来，但这仅仅是“能跑”。生产环境我建议至少8核16G内存起步，因为Tomcat + MySQL + 数据接收线程在PV数量上千时会明显吃资源。存储方面，STS区一定要用SSD，如果你的装置PV数量大、采样频率高，这块盘的性能直接决定系统能不能跟上数据写入速度。MTS和LTS用普通SATA盘就可以，容量尽量留足，按照“每个PV占用多少字节 × PV数量 × 存储时长”粗略估算，宁可多配不要少配。

操作系统方面，CentOS 7、CentOS 8、Ubuntu 18.04及更高版本都在官方支持范围内。我自己用的是CentOS 7.9，稳定性是第一位，而且yum源里直接有JDK和MySQL的安装包，装起来顺手。Debian系的话注意包管理器命令不同，其他没差别。

2.2 JDK、Tomcat、MySQL版本怎么选

这是最容易踩坑的地方。Archiver Appliance官方编译基于Java 8，虽然Java 11理论上也能跑，但我在实测中遇到过一次类库不兼容，换回Java 8就正常了。所以老老实实用JDK 1.8，别追求新版本。Tomcat推荐8.5.x，这是官方持续测试的版本，Tomcat 9我也试过，能起来但日志里偶尔会有奇怪的告警，没有排查价值就不折腾了。MySQL建议用5.7，原因后面会在“常见问题”里专门解释，先用结论：5.7版本配合mysql_native_password认证插件，最省心。

整个部署流程本质上就是：把MySQL建好库、把Tomcat跑起来、把war包丢进去、配置appliance.xml指向你的存储路径和数据库，重启Tomcat。理解了这条主线，后面所有步骤都是在帮你把这条线走通。

2.3 下载安装包与目录结构

去Archiver Appliance官方GitHub Releases页面下载最新发布包，文件名大概是archiver_appliance-x.y.z.tar.gz。解压后你会看到几个目录：

• install：数据库初始化脚本和相关安装脚本，initdb.sql就在这里。
• lib：程序运行需要的依赖JAR包。
• src/main/conf：配置文件模板，最重要的appliance.xml就在这个目录下。
• src/main/webapp：Web前端资源，一般不用动。
• bin：脚本集，有些发布版本会包含启动辅助脚本。

不要一上来就急着改配置文件，先花20分钟把这个目录结构看一遍。特别是appliance.xml模板，每项配置的作用心里有数。我见过太多人部署失败是因为配置文件里存储路径写了个相对路径，Tomcat一启动就报错，后面排查半天才发现这种低级问题。

3. 完整的部署配置步骤，照着敲就行

3.1 数据库初始化与账号配置

先确保MySQL已经安装并启动。然后创建Archiver Appliance专用的数据库和账号：

bash复制mysql -u root -p
# 进入MySQL后执行
CREATE DATABASE archappl DEFAULT CHARACTER SET utf8mb4;
CREATE USER 'archappl'@'localhost' IDENTIFIED BY 'yourpassword';
GRANT ALL PRIVILEGES ON archappl.* TO 'archappl'@'localhost';
FLUSH PRIVILEGES;
EXIT;

接着用官方脚本初始化表结构：

bash复制mysql -u root -p archappl < install/initdb.sql

如果你用的是MySQL 8.0及以上版本，执行完这段之后大概率会遇到Tomcat连不上数据库的诡异问题，报错信息是“Unable to load authentication plugin 'caching_sha2_password'”。推荐这步就彻底一点，在MySQL 8里把默认认证插件改掉，或者直接按文章开头推荐的用MySQL 5.7，把认证机制搞成mysql_native_password，一劳永逸。

3.2 Tomcat部署与war包安装

把发布包里编译好的war包复制到Tomcat的webapps目录下。正常情况下war包会自动解压，但为了明确控制部署过程，我喜欢先停掉Tomcat、清空webapps下旧目录再复制，避免半残状态。

bash复制cp archiver_appliance.war $TOMCAT_HOME/webapps/

接下来是Tomcat的重点配置：JVM内存参数、配置文件路径参数。在Tomcat的bin目录下新建setenv.sh（如果已存在则编辑），添加如下内容：

bash复制export JAVA_HOME=/usr/lib/jvm/java-1.8.0
export CATALINA_HOME=/opt/tomcat
export CATALINA_OPTS="-Xms2g -Xmx8g -Darchappl.configFile=/opt/archappl/conf/appliance.xml"

-Darchappl.configFile这个参数特别重要，它告诉Archiver Appliance去哪里加载核心配置文件。很多部署教程没提这个，结果系统起来之后找不到配置，全部用了默认值，IP、端口、存储路径全不对。Xms和Xmx按机器实际内存调整，我给的2g/8g是16G内存机器下的合适值。

3.3 核心配置文件appliance.xml解析

这是整个部署的核心，我的做法是先把模板复制到固定目录：

bash复制mkdir -p /opt/archappl/conf
cp src/main/conf/appliance.xml /opt/archappl/conf/

然后编辑appliance.xml，核心配置项如下：

xml复制<appliance>
  <cluster_id>archappl_cluster</cluster_id>
  <identity>appliance0</identity>

  <storage>
    <sts>/data/archappl/sts</sts>
    <mts>/data/archappl/mts</mts>
    <lts>/data/archappl/lts</lts>
  </storage>

  <databases>
    <database url="jdbc:mysql://localhost:3306/archappl?useSSL=false" username="archappl" password="yourpassword" />
  </databases>
</appliance>

cluster_id是集群标识，Single模式下任意字符串都可以，但要跟你后续客户端配置保持一致。identity是当前节点名称，Single模式下也无所谓。storage里的三个路径是关键，务必使用独立、容量充足、文件系统干净的目录。不要图省事放到/tmp下，系统一重启你辛辛苦苦归档的数据全没了。数据库连接串里的数据库名要和3.1步创建的库名保持一致，useSSL=false建议加上，否则JDBC与MySQL做SSL握手会拖慢首次连接。

三个存储目录必须提前创建并赋予Tomcat运行用户写权限：

bash复制mkdir -p /data/archappl/sts /data/archappl/mts /data/archappl/lts
chown -R tomcat:tomcat /data/archappl

3.4 安全证书与HTTPS配置

Archiver Appliance的管理界面和查询接口默认走HTTPS，这就绕不开证书问题。你可以在Tomcat的server.xml里配置SSL连接器，指定Keystore；也可以让系统自带的证书生成脚本自动做这件事。我手动操作的步骤一般是：

bash复制keytool -genkey -alias tomcat -keyalg RSA -keystore /opt/tomcat/conf/keystore -validity 3650 -dname "CN=archappl.local"

然后在server.xml里取消下面这段的注释并改成你的keystore路径：

xml复制<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="150" SSLEnabled="true"
           scheme="https" secure="true"
           keystoreFile="/opt/tomcat/conf/keystore" keystorePass="changeit"
           clientAuth="false" sslProtocol="TLS" />

证书问题比较折腾人，但部署阶段值得一次搞定。还有一个关键操作：把生成的证书导入Java运行时环境的cacerts信任库，否则Archiver Appliance内部的线程之间互相访问HTTPS接口时会报SSL握手错误，你会在日志里看到一堆莫名其妙的异常。

bash复制keytool -import -alias archappl -keystore $JAVA_HOME/jre/lib/security/cacerts -file /tmp/cert.cer

3.5 启动、验证与初始化

完成上述配置后，启动Tomcat：

bash复制/opt/tomcat/bin/startup.sh
tail -f /opt/tomcat/logs/catalina.out

启动过程中观察日志，出现“Archiver Appliance initialization successful”或者类似的成功信息就说明已经正常起来了。首次启动会自动建表、初始化存储区，耗时看机器性能，一般一两分钟内完成。启动完成后浏览器访问：

text复制https://你的服务器IP:8443/archive/

正常情况下你应该能看到Archiver Appliance的登录界面。系统默认账号admin，默认密码admin。登录之后先别急着添加PV，去“Storage”页面确认三个存储路径都显示正常，再用“Cluster”页面确认本机节点状态为UP。状态不是UP的话，多半是存储路径权限或者数据库连接有问题，回头检查这一节前面的步骤。

4. 配置验证、数据接入与日常运维

4.1 从Web界面添加PV开始归档

登录管理界面后，导航到“PV Management”或者“Archived PVs”页面。先把你的IOC启动起来，确保PV在网络上可见。然后在界面里点击添加按钮，填PV名字，比如“TEST:CAV:VOLT”，选择采样方式。Archiver Appliance支持三种采样方式：Scan（定时轮询，类似你在IOC里指定的扫描周期）、Monitor（值变化即记录）、Passive（被动等待数据进来）。

实验装置里大部分PV适合用Monitor方式，因为它只在值变化时写一条记录，能顺带保留变化发生的精确时间戳；如果你需要固定频率的均匀采样，比如每秒一个点画趋势线，那就选Scan并指定周期。我个人的习惯是：状态量、温度等缓变量用Monitor，高频波动量如腔压、束流位置用Scan，扫描周期通常设1秒。这个选择直接决定数据量和查询效果，值得多花点心思设计。

4.2 验证数据是否真正写入

添加PV之后，等个几分钟，切到“Data Browser”或者“Plot”页面，输入PV名，拉取最近一段时间的数据，能看到曲线就说明全链路已经打通。如果查不到数据，先回Web界面看这个PV的状态，是否显示“Archiving”状态。还有一种情况是PV在界面上显示正常但查询结果为空，这时去存储目录里看看有没有生成数据文件：

bash复制ls -lht /data/archappl/sts

如果有近期生成的文件，说明数据肯定进系统了，问题大概率出在查询接口或者时间范围选择上，跟采集链路无关。这个排查思路能帮你快速定位到底问题在“采”还是“存”还是“查”。

4.3 通过命令行和API读取数据

Web界面的Data Browser适合人眼看，但自动化场景下你肯定要用API或者客户端工具。Archiver Appliance提供基于HTTP的JSON查询接口，例如：

bash复制curl -G "https://你的服务器IP:8443/archive/retrieval/data/getData.json" \
  --data-urlencode "pv=TEST:CAV:VOLT" \
  --data-urlencode "from=2025-01-01T00:00:00.000Z" \
  --data-urlencode "to=2025-01-01T01:00:00.000Z" \
  --data-urlencode "donotchunk=true"

返回的JSON里就包括时间戳和值列表。更省事的方案是直接用Python的epics archiver客户端库，或者用CSS、Phoebus里的Data Browser插件，在界面上输入Archiver Appliance地址就能直接拉数据画图，不用自己写任何代码。这也是Archiver Appliance最受欢迎的原因——生态成熟，对接成本低。

4.4 备份策略与升级注意事项

很多团队部署完Archiver Appliance就把它晾在那不管了，直到某天磁盘满了或者系统挂了才想起来没有备份。备份包含两部分：MySQL里是元数据，数据文件在存储目录里。元数据用mysqldump定期导出，数据文件更简单，快照或rsync同步到另一台机器就行。

如果做的是实验装置，建议每周备份一次;如果数据价值高，每天一次也不过分。升级方面，我个人经验是不用追新，除非新版修复了你正遇到的问题。Archiver Appliance的升级步骤一般是备份数据库和配置、停Tomcat、替换war包、重启，然后去Web界面看版本号是否更新成功。升级前一定在测试环境试一遍，生产环境直接升级翻车的案例我见过不止一次。

5. 常见问题与避坑实录

5.1 MySQL 8认证插件导致连接失败

这是新部署环境里发生频率最高的问题。现象是Tomcat启动时报错，日志里能看到“Unable to load authentication plugin 'caching_sha2_password'”。因为MySQL 8默认认证插件改了，而Archiver Appliance自带的JDBC驱动版本比较老，不认这个新插件。

解决办法有三个，任选其一：一是改用MySQL 5.7，这是最推荐的方式；二是启动MySQL时加参数--default-authentication-plugin=mysql_native_password；三是把已有的MySQL用户改成mysql_native_password认证：

sql复制ALTER USER 'archappl'@'localhost' IDENTIFIED WITH mysql_native_password BY 'yourpassword';

改完记得重启Tomcat。

5.2 存储目录权限不足导致启动失败

Tomcat进程如果是以tomcat系统用户跑，而存储目录是root创建的，启动时大概率会在日志里看到Permission denied，同时Web界面里的Storage页面显示异常。解决思路很直接，检查目录所属用户和权限：

bash复制chown -R tomcat:tomcat /data/archappl
chmod -R 755 /data/archappl

这里想多说一句，很多人习惯用root启动Tomcat，这样权限问题是没了，但安全风险太大，生产环境千万别这么干。

5.3 证书和HTTPS导致各种诡异问题

浏览器只能看到“连接不安全”的警告，这其实还不影响使用，点“继续访问”就能进。真正坑的是Java到Java的HTTPS通信，因为我们生成的证书是自签名的，JVM默认不信任自己签发的证书，需要在每个相关节点的cacerts里导入证书并重启应用。如果你的Archiver Appliance机器需要跟其他服务通信，比如Phoebus客户端，可能需要在客户端机器上也导入证书或配置跳过SSL校验。

我在测试阶段就曾经被这个问题卡了一整天，现象是所有Web功能正常，但数据写入和查询都报SSL错误。当时只看Tomcat日志没用，最后发现是内部线程访问自己的接口都过不了证书验证，导入证书后整个世界清静了。

5.4 内存不足和频繁Full GC

PV数量大或者查询频繁时，Tomcat默认内存设置肯定不够，表现为系统运行一段时间后越来越卡，甚至直接OOM。解决方法就是setenv.sh里的Xmx调大，同时给JVM加上这两个参数：

bash复制-XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled

不过Java 8自带的内存管理本身很成熟，加不加这些参数看情况。我遇到的更关键问题其实是：光调大Xmx还不够，还要确保系统物理内存是真的大。如果你在云服务器上部署，建议按实际PV规模选型，内存不足带来的问题比CPU不足更隐蔽、更难查。

5.5 数据查不到但存储目录有文件

这个现象有一定迷惑性，但本质通常是时间范围问题。Archiver Appliance在查询接口里对时间格式很严格，必须是带时区的ISO格式，比如“2025-01-01T08:00:00.000+08:00”。如果你传的时间跟数据存储时的时区不一致，经常会出现明明有数据但查询结果为空的现象。

另外，如果你设置了PV别名或元数据缓存，新PV添加后可能需要等后台索引刷新完成后才能被检索。一般等几分钟再刷新页面就能看到。实在查不到，就去Web界面的“List Archived PVs”里确认这个PV确实处于归档状态，排除手动暂停或归档策略变更导致的情况。

5.6 常见问题速查表

6. 最后再分享一点部署心得

6. 最后再分享一点部署心得

Archiver Appliance部署本身不难，难的是你愿不愿意把每一步的原理搞明白。我第一次部署时图省事，跳过证书导入环节，结果被SSL坑了一天；第二次部署时老老实实按流程走，半小时全部搞定。这让我养成了一个习惯：凡是系统组件之间的通信，提前把证书、端口、权限这些基础环境彻底处理好，再进入业务配置，效率反而最高。

如果你打算在实验装置或者正式产线上用，我个人强烈建议先从Single模式验证全链路，跑通后再升级到Dual或Cluster，别一上来就追求大而全。另外，部署完一定要做一次“数据写入-查询-备份-恢复”的完整演练，别等到真的要用数据时才惊觉备份是坏的。这套系统确实能帮你省很多事，但该做的运维功夫一样都不能省。