EPICS Archiver Appliance部署配置实战：从架构到避坑指南-代码聚汇网

EPICS Archiver Appliance部署配置实战：从架构到避坑指南

是个少女·2026-09-01·阅读 24 GEO检测（免费）

EPICSArchiver Appliance部署

|难度：普通|阅读约 29 分钟

搞过加速器或者大科学装置控制系统的人，应该都体会过数据归档这个环节的折磨。EPICS系统里的PV成千上万，波形、标量、状态量全混在一起，要稳定地存下来，还要在几个月后快速查出来，原生自带的Channel Archiver用起来实在有点原始。后来SLAC出的EPICS Archiver Appliance算是把这件事做成了“一个能用的产品”，分布式存储、自动切库、Web查询界面都齐了。不过这玩意儿部署起来也不是双击下一步的事，网上教程零散，官方文档又太啰嗦，不少同事第一次装的时候都卡在莫名其妙的配置上。

我前后在好几个现场部署过Archive Appliance，踩了不少坑，也总结了一套相对稳妥的流程。这篇就把整个部署配置过程完整梳理一遍，从架构思路到具体命令，从参数含义到问题排查，尽量做到你看完能自己复现一套能用的环境。适合要搭新归档系统的EPICS工程师，也适合被现有归档系统搞到头大的运维同学参考。

1. 为什么选Archive Appliance：架构拆解与部署思路

1.1 EPICS数据归档的痛点与Appliance的定位

先聊点背景。EPICS系统里的数据归档，本质上就是把IOC里不断变化的PV值按时间顺序记录下来。听起来简单，但实际做起来有几个绕不开的问题：一是PV数量大，一个中型装置几千个PV很正常；二是数据种类杂，有几十赫兹采样的波形，也有几小时变一次的温度；三是查询需求多样，有时候要看最近五分钟的趋势，有时候要拉半年前的历史数据做分析。

早期的Channel Archiver是单机进程，存储文件分散，查询靠脚本，PV多了以后性能和运维都是噩梦。Archive Appliance的设计思路是把“接收数据”“存储数据”“查询数据”“管理配置”这四件事拆成独立组件，每个组件可以单独部署和扩展。它不是把EPICS的数据随便找个数据库一塞，而是针对时序数据的特点做了专门优化，比如按时间段切分数据文件、自动做不同粒度的归档、支持数据的合并与回填。这套设计让它在一众方案里显得特别适合大科学装置和大型实验室用。

1.2 四种应用的职责分工

Archive Appliance的核心是四个应用，很多人第一次接触时会被这四个war包绕晕，我在这里先把它们的职责理清楚：

mgmt：管理界面和配置入口。负责PV的注册、归档策略的配置、系统的整体监控。你在浏览器里看到的那个Web界面，就是mgmt提供的。
etl：数据搬运工。负责把原始数据从临时存储搬到长期存储，同时做数据粒度的归并和整理。它就像仓库里的理货员，不停地把新到的货分门别类放到对应货架上。
retrieval：数据查询服务。用户画趋势图、拉历史数据的时候，实际是retrieval在处理请求。它需要对多种存储层做聚合查询，然后把结果返回给前端。
archiveengine：数据接入引擎。它直接和EPICS的Channel Access打交道，订阅PV值变化，把数据写入存储系统。

这四个组件可以全部跑在一台机器上（小型测试环境完全够用），也可以拆到多台机器。它们的通信通过HTTP和消息队列完成，部署的时候只要保证网络互通、配置里的URL正确就行。

1.3 两种部署形态怎么选

官方提供了两种部署方式。一种是预构建的VM镜像（他们内部叫Polo-style appliance），下载下来导入虚拟化平台就能用，适合快速验证、不想折腾环境的人。另一种是手动安装到自己的服务器上，也就是所谓“社区部署”，把war包部署到Tomcat，自备MySQL和Cassandra。

我的建议是：如果你是正式环境，或者要长期维护，最好选手动部署。VM镜像虽然省事，但升级、备份、和现有监控体系的集成都会受限制，而且你没法很方便地调整JVM参数和存储路径。手动部署的第一步虽然多点，但整个系统的可控性会高很多。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 部署前的准备工作

2.1 版本选型与依赖清单

Archive Appliance对依赖的版本有要求，装之前最好确认清楚。我实际验证过比较稳的组合是：JDK 1.8（对，别上11，会有兼容问题）、Tomcat 8.5或9.0、MySQL 5.7或8.0、Cassandra 3.11。Cassandra别用4.x，Archive Appliance默认驱动对4.x兼容性不好，容易出幺蛾子。

具体版本要求可以参考官方文档的版本矩阵，但上面这套组合是我在多套环境里实测稳定的。如果你手头的服务器系统是CentOS 7或Ubuntu 18.04，装这套完全没有问题；如果是更新的系统比如Ubuntu 22.04，需要注意默认JDK版本可能偏高，手动装一个OpenJDK 8就好。

2.2 安装包获取与目录结构

Archive Appliance的安装包在GitHub的epics-extensions/archiver-appliance仓库可以下载，文件名一般是archappl_vX.Y.Z.tar.gz。解压之后，里面有几个关键目录：

lib/：所有依赖的jar包
webapps/：四个war包
install_scripts/：官方提供的辅助部署脚本
config/：示例配置文件
bin/：一些管理脚本

我刚接触的时候以为把war包丢进Tomcat就完事了，其实没那么简单。Archive Appliance的war包在启动时会找你指定目录下的配置文件，如果找不到就直接罢工。所以目录结构首先要心里有数，后面配置的时候才不慌。

2.3 基础依赖安装

我一般先把Java和Tomcat装好，这是跑Archive Appliance的基础。以CentOS为例：

bash复制# 安装OpenJDK 8
yum install -y java-1.8.0-openjdk-devel

# 设置JAVA_HOME
export JAVA_HOME=/usr/lib/jvm/java-1.8.0
export PATH=$JAVA_HOME/bin:$PATH

Tomcat可以直接用官方二进制包解压安装，记得创建专用运行用户，不要用root跑Tomcat，这是基本的安全习惯。

bash复制useradd -m -d /opt/archappl archappl
wget https://archive.apache.org/dist/tomcat/tomcat-9/v9.0.xx/bin/apache-tomcat-9.0.xx.tar.gz
tar -zxvf apache-tomcat-9.0.xx.tar.gz -C /opt/archappl/

Cassandra的安装稍微繁琐一点。下载二进制包后需要调整conf/cassandra.yaml里的data目录和listen地址。测试环境可以保持默认，但生产环境一定要把data目录放到独立磁盘，否则数据量上来之后IO会成为瓶颈。

3. 核心部署实操：一步步把Appliance跑起来

3.1 初始化MySQL数据库

Archive Appliance用MySQL存元数据，比如PV的注册信息、归档策略、用户权限等。先建库建用户，官方脚本直接会用root连MySQL执行，我建议单独建一个专用账号，权限控制更清晰：

sql复制CREATE DATABASE archappl DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'archappl'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON archappl.* TO 'archappl'@'%';
FLUSH PRIVILEGES;

注意字符集一定要用utf8mb4，因为PV描述里可能有中文或者特殊符号，用默认的latin1会乱码。这个坑我踩过，当时现场有个PV的描述是中文，归档到MySQL后全成了问号，排查了半天才发现是字符集的问题。

数据库建好后，Archive Appliance在首次启动时会自动创建所需的表结构，不需要手工执行建表SQL。这也是它做得比较省心的地方，只要JDBC配置正确，启动时就会自动初始化。

3.2 配置ETL与检索组件

配置是整个部署过程中最关键也最容易出错的一步。Archive Appliance的配置文件叫appliance.xml，一般在Tomcat的conf目录下，或者通过环境变量指定。这个文件里最核心的是四个URL配置，分别对应四个组件的地址。

我贴一份我常用的最小配置示例：

xml复制<appliance>
  <identity>archappl01</identity>
  <urls>
    <url key="mgmt_url">http://localhost:17665/mgmt</url>
    <url key="etl_url">http://localhost:17668/etl</url>
    <url key="retrieval_url">http://localhost:17666/retrieval</url>
    <url key="archiveengine_url">http://localhost:17667/archive</url>
  </urls>
  <jdbc_url>jdbc:mysql://localhost:3306/archappl?useSSL=false&amp;characterEncoding=utf8</jdbc_url>
  <jdbc_user>archappl</jdbc_user>
  <jdbc_password>your_password</jdbc_password>
  <cassandra_urls>
    <url>localhost:9042</url>
  </cassandra_urls>
</appliance>

这里有几个端口要特别说明：mgmt默认是17665，retrieval是17666，archiveengine是17667，etl是17668。这些端口不是写死的，可以在Tomcat的server.xml里调整，但默认值已经规划好了，没有特殊需求就别乱改，否则多个组件间的互相调用要改的地方很多。

四个war包的部署方式也有一点讲究。我的做法是启动两个Tomcat实例：一个实例放mgmt和retrieval，另一个实例放etl，archiveengine用独立的脚本进程跑。这样做的好处是，即使etl负载很高或者出问题崩溃了，管理界面和查询功能还活着，运维上更灵活。

3.3 启动服务与首次验证

所有配置就位后，就可以启动Cassandra、MySQL、Tomcat了。启动顺序建议是：先Cassandra和MySQL，再启动Tomcat（放mgmt/retrieval的），最后启动etl的Tomcat和archiveengine。

启动之前，有几个环境变量要确认好：

bash复制export JAVA_HOME=/usr/lib/jvm/java-1.8.0
export CATALINA_HOME=/opt/archappl/tomcat9
export ARCHAPPL_APPLIANCES=/opt/archappl/config/appliances.xml

ARCHAPPL_APPLIANCES这个环境变量很关键，Archive Appliance启动时会根据这个路径去找集群配置文件，如果没设置或者路径不对，war包会一直报错找不到配置。这也是新手最容易忽略的地方。

启动Tomcat后，先看日志：

bash复制tail -f /opt/archappl/tomcat9/logs/catalina.out

正常情况下会看到Archive Appliance的初始化日志，包括数据库表创建、Cassandra连接建立等。第一次启动会比较慢，因为要建表、初始化存储目录，耐心等两分钟。

验证服务是否正常，可以直接用curl看接口状态：

bash复制curl http://localhost:17665/mgmt/mgmt

如果返回一串JSON或者HTTP 200，说明管理服务起来了。retrieval和etl也可以用类似方式验证。

3.4 在界面上注册PV并查看归档数据

服务都起来后，打开浏览器访问http://your_server_ip:17665/mgmt/ui/index.html，就能看到管理界面了。第一次进去是空白的，需要先添加PV才能开始归档。

界面上的操作路径是“PV”管理页面，输入PV名称，选好归档策略，点提交。归档策略最常用的是“Scan”模式，也就是IOC的CA协议主动推送变化值。还有“Monitor”和“Passive”等模式，区别在于触发方式不同，一般用Scan就够了。

添加成功后，等几分钟就能在“Data Viewer”页面看到趋势曲线了。如果添加后一直没数据，先确认这个PV在IOC里是不是真的存在、通道名有没有写错，再看archiveengine的日志有没有报Channel Access连接错误。

4. 关键配置项与性能调优

4.1 appliance.xml核心参数解析

前面贴的最小配置能跑起来，但生产环境要关注更多参数。我这里把appliance.xml里我经常调整的几个参数展开讲讲。

首先是存储路径相关配置。Archive Appliance会把数据先写到临时存储（默认走Cassandra的内存表），然后由etl搬运到长期存储。长期存储可以是普通文件系统，也可以是网络存储。配置里对应的参数是STORE_TYPES和ARCHAPPL_STORES，我习惯把不同时间范围的数据分到不同目录，比如：

最近15天的数据放在SSD（类型为STORE_1）
15天到1年的数据放到大容量HDD（类型为STORE_2）
超过1年的数据放到归档冷存储（类型为STORE_3）

这样做的目的是控制成本，热数据用高性能存储，冷数据用低成本大容量存储。Archive Appliance内置了这种多级存储机制，配置起来并不复杂，核心是定义好每一层的路径和对应的时间范围。

其次是ARCHAPPL_POLICIES，这个参数控制数据保留策略和归并策略。比如你可以配置“波形数据保留90天，标量数据保留3年”“10分钟前的数据归并到分钟级粒度”等。这个策略是运维的关键，如果配置不当，存储会很快被塞满。

4.2 JVM内存与存储策略

Archive Appliance的四个组件对内存的要求差异很大。archiveengine是最吃内存的，因为它在内存里批量缓存数据再批量写；retrieval次之，因为查询时要聚合并行加载数据；etl相对轻量；mgmt最轻。我一般给archiveengine的JVM堆设置8GB以上（如果机器内存足够），retrieval设置4GB，etl和mgmt设置2GB就够用。

Tomcat的JVM参数在setenv.sh里配置：

bash复制CATALINA_OPTS="-Xms8192m -Xmx8192m -XX:MaxMetaspaceSize=512m -Djava.awt.headless=true"

注意JVM堆不是设得越大越好，超过物理内存的50%之后GC反而会成为问题。一般的经验是，单台机器上四个组件加起来不要超过物理内存的70%，要给操作系统和Cassandra留出余量。

Cassandra的内存配置也同样重要，它的conf/jvm.options里默认堆大小是4GB，如果机器内存不够要调低，否则Cassandra可能直接启动失败。

4.3 数据生命周期管理

数据越来越多是归档系统必然要面对的问题。Archive Appliance的Retrieval策略支持按时间范围查询跨存储层的数据，所以你不需要把所有数据都放在高性能存储上。这里我分享一个实际运维中很有效的分层策略：

用cron定期执行etl的归并任务，让数据从临时存储流入长期存储
用策略配置自动清理超过保留期限的原始数据
MySQL里的元数据要定期备份，这是整个系统的“大脑”

另外，Cassandra本身也有数据过期机制，如果配置了TTL，数据会在指定时间后被自动清理。但Archive Appliance官方其实不推荐依赖Cassandra的TTL，而是建议通过etl策略来做深度清理，因为TTL清理在Cassandra里会产生大量墓碑，影响查询性能。

5. 常见问题与排查技巧

5.1 启动失败与端口占用

这里我把常遇问题整理一下，方便你到时快速定位。下面这个表格是常见启动问题的排查清单：

问题现象	可能原因	排查方法
Tomcat启动后war包没解压	缺少配置文件或环境变量	检查ARCHAPPL_APPLIANCES是否设置正确
访问17665端口无响应	mgmt组件未成功启动	看catalina.out日志，确认MySQL连接是否成功
端口被占用	其他服务占用了默认端口	`netstat -tlnp \| grep 176` 查看端口占用
Cassandra启动失败	堆内存配置过大	调整jvm.options里的Xms和Xmx

端口占用的坑我遇到过一次。当时现场服务器上有个遗留的监控进程占用了17665端口，mgmt的war包一直解压失败，日志里报的是Address already in use，但第一反应根本想不到是端口问题，因为报错信息不够直观。所以端口检查要放在最前面。

5.2 数据不归档的排查思路

PV注册成功却没数据，这是问得最多的问题。我排查的顺序一般是：先看PV通道名对不对，再看网络通不通，最后看archiveengine的状态。

一些典型的坑包括：

PV名称大小写错误：CA协议对大小写敏感，myPV和mypv是完全不同的通道。
IOC的CA端口被防火墙拦截：默认CA使用端口5064/5065，UDP协议，如果防火墙只放行了TCP端口，归档系统根本发现不了IOC。
archiveengine没有权限：如果IOC配置了CA访问控制列表，需要把archiveengine所在机器的IP加进去。
时区配置不一致：Archive Appliance默认使用UTC，如果你的IOC和服务器配置的是本地时间，归档数据的时间戳会偏移8小时。这个问题很隐蔽，我建议干脆所有组件全部用UTC，展示的时候再在前端转本地时间。

5.3 存储与性能问题

数据量大了以后，性能问题会逐渐暴露。最能直观感受到的瓶颈通常是retrieval的查询变慢，特别是跨长时间范围查波形数据的时候。我的经验是：

确认etl是否正常运行，如果etl积压严重，数据会一直堆在临时存储里，查询时被迫扫描大量临时数据。
检查Cassandra的磁盘空间和IO情况，nodetool status可以快速看各节点状态。
如果查询经常要拉好几个月的数据，考虑在策略里增加“分钟级”或“小时级”的归并粒度，这样粗粒度查询就不用加载原始数据了。

Archive Appliance本身提供了管理界面的监控页面，可以看到各组件的数据流量、队列深度等指标。这些数据对定位瓶颈很有用，建议你在界面里翻一翻，关键指标包括ETL的Lag时长、archiveengine的队列长度等。

我在实际运维中发现一个经常被忽略的点：Cassandra的nodetool compactionstats和nodetool repair要定期关注。Cassandra的compaction如果一直赶不上写入速度，查询延迟会飙升。这种情况不是Archive Appliance配置能解决的，需要调整Cassandra的compaction策略，实话说这个要单独研究一下。

实操建议与个人经验

部署做多了，我总结了几条自己的心得，对你会有帮助：

一定要用systemd统一管理所有组件。Cassandra、MySQL、Tomcat（可能还有archiveengine），每个都要配成systemd服务，设置好开机自启和crash后的自动重启。没有这个，哪天半夜机器重启了你第二天早上才知道归档断了，数据就丢了一段。我的systemd服务文件里都给Tomcat设置了Restart=on-failure，这个选项很关键。

配置文件要纳入版本管理。appliance.xml、Tomcat的server.xml、Cassandra的yaml文件，都放到git仓库里，每次变更留痕。这套系统部署一次之后很少动，一旦出了问题没人说得清当时改了什么，git历史能帮你省下很多排查时间。

运维脚本要提前准备好。比如一键备份MySQL元数据、定时检查Cassandra存储空间、监控Archive Appliance各组件HTTP接口存活状态。这些脚本平时看不出价值，等出了状况就知道有多救命。

在正式接入大量真实PV之前，一定要先做压测。不要等到上线当天发现archiveengine扛不住几十个高频波形PV。你可以用EPICS自带的caget/caput配合脚本模拟大量数据写入，提前看看系统的吞吐量极限在哪。

部署EPICS Archiver Appliance这件事，说难不难，说简单也不简单，关键在于对架构的理解和对细节的把控。只要把四个组件的职责和配置逻辑搞清楚，按部就班地装，大概率能一次跑通。真遇到问题也别慌，按照日志一层层剥，大多数坑都是配置不对或者端口不通导致的，没有玄学。希望这篇笔记能帮你少走点弯路。