EPICS Archiver Appliance在Ubuntu上的部署与配置实践

简介面向Ubuntu环境下部署EPICS Archiver Appliance的开发者与控制系统运维人员这份压缩包提供了一套完整的安装项目代码。资源聚焦于为EPICS实时数据归档系统搭建Java 21运行环境覆盖quickstart、start/stop、环境检测等关键Shell脚本并附Markdown说明文档与配置辅助文件可帮助使用者规避Java版本不匹配、依赖缺失等常见部署问题。包内共8个文件以Shell脚本为主5个辅以Markdown说明、InsCode配置及Git忽略规则整体仅14KB轻量精炼。已有56人学习。通过该代码包读者不仅能快速执行安装流程还能了解Archiver Appliance的目录结构、启动参数和自定义配置方式适合希望快速在Ubuntu上启用归档服务的EPICS用户参考。 搞EPICS控制系统的人应该都有过这种经历现场几十台IOC、几千个PV过程变量在跑运行人员突然跑过来说要查“昨天下午三点那台电源的电流曲线”你翻遍手里的工具却什么都拿不出来。EPICS Archiver Appliance就是专门解决这个问题的——把PV数据长时间、低丢失地归档起来再按时间范围快速查询这几年基本成了加速器和大科学装置控制系统的标准配置。这篇文章把我自己在Ubuntu上从零安装、配置、验证一套Archiver Appliance的完整过程写出来包括JDK、Tomcat、MySQL的版本组合、appliance.xml的关键配置、四个Web服务之间的关系以及装完之后怎么用一条真实PV把“采集→归档→查询”的链路彻底打通。适合正在搭测试环境、准备从Channel Archiver迁移或者想在实验室里做一套轻量数据归档系统的同学参考。1. 装之前必须理解四个War包不是四个普通网页应用1.1 从Channel Archiver到Archiver Appliance老一代控制系统里数据归档常用的方案是Channel Archiver它靠一个独立进程按一定周期去抓PV值再写入二进制文件。这个方案的问题在后期越来越明显数据文件分散、检索效率低、进程挂了没人知道而且扩展性很差PV数量一多就吃力。Archiver Appliance是SLAC主导开发的新一代归档系统设计目标很明确把“采集”“存储”“检索”三个环节拆开每个环节独立部署、独立扩容。拆开之后的好处是采集跟不上可以加Engine节点存储不够可以加ETL节点查询变慢可以加Retrieval节点互不拖累。这套思路和现在互联网后端常见的“读写分离”其实是一个道理。1.2 mgmt、engine、etl、retrieval各管哪一段安装包里最显眼的是四个WAR文件mgmt.war、engine.war、etl.war、retrieval.war。很多人第一次接触会以为这是四个独立软件其实它们是一套系统里的四个角色缺一个都跑不起来。mgmt管理服务负责Web管理界面、PV配置、用户权限、系统状态监控。默认端口17665。engine采集引擎根据配置的PV列表通过Channel Access或PVAccess实时订阅数据把拿到的值按时间戳打包成数据块。默认端口17666。etl抽取转换加载把Engine落盘的数据块做二次整理写入长期存储生成Lucene索引同时负责跨周期数据的合并和冷热分层。默认端口17667。retrieval检索服务对外提供数据查询接口支持JSON、CSV、PNG图表等多种返回格式是用户直接打交道的服务。默认端口17668。打个比方Engine是生产线上的传感器负责把原料采集进来ETL是质检和仓库管理员负责把原料分门别类放进货架并做好标签Retrieval是前台服务员用户要什么它去货架上取mgmt是值班经理负责监控整条线有没有出问题。1.3 单机部署的架构边界本教程采用单机部署四个War包放在同一个Tomcat里数据也存放在本机磁盘。这种部署方式适合测试环境、小型实验室或者PV数量在几百到几千的中等场景维护成本最低。但有一点要注意单机部署不等于“四个服务可以随便乱放”。哪怕在一台机器上它们的目录、端口、日志也是分开的。后续如果PV量涨到几万再考虑把Engine、ETL拆到独立节点配置层面只需要改appliance.xml里的集群参数不需要推倒重来。2. 环境准备Ubuntu下的JDK、Tomcat、MySQL组合2.1 版本组合怎么选Archiver Appliance对底层依赖的版本比较敏感不是“最新就是最好”。我自己在Ubuntu 22.04上用的组合是JDK 17、Tomcat 10.1、MariaDB 10.11跑得很稳定。官方对高版本Tomcat的兼容性更新比较积极但如果你在Ubuntu 20.04这类老系统上装JDK 11和Tomcat 9的组合也能用只是部分新功能会受限。组件推荐版本说明Ubuntu22.04 LTS / 24.04 LTSLTS版本生命周期长省心JDKOpenJDK 17新版Archiver Appliance要求JDK 17Tomcat10.1.x注意Servlet版本兼容MySQL/MariaDBMariaDB 10.11 或 MySQL 8.x存元数据和配置不存原始数据块Python3.10官方工具脚本需要不影响主服务为什么不推荐直接用系统源里的老JDK因为Tomcat 10.1强制要求Jakarta EE 9老JDK编出来的Servlet根本起不来。装之前先检查一下Ubuntu软件源里有没有openjdk-17没有就手动加源。2.2 一条命令装完基础依赖在Ubuntu 22.04上基础依赖用apt就能装齐sudo apt update sudo apt install -y openjdk-17-jdk tomcat10 mariadb-server python3 python3-pip wget unzip装完检查版本确认没有装错java -version /usr/share/tomcat10/bin/version.sh mysql --versionTomcat 10.1在Ubuntu里的包名是tomcat10默认安装后服务会自动启动端口8080。这一步结束后先不急着动Tomcat等数据库和安装包准备好再一起配置避免反复重启。2.3 数据库初始化建库、建用户、调参数MySQL/MariaDB在这里只存PV配置、用户信息、存储状态等元数据真正的数据块落在磁盘文件里。先启动MariaDB并进入命令行sudo systemctl enable --now mariadb sudo mysql然后执行建库建用户SQL密码建议设强一点后面appliance.xml里要写CREATE DATABASE archappl CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER archiverlocalhost IDENTIFIED BY 在这里换成你的密码; GRANT ALL PRIVILEGES ON archappl.* TO archiverlocalhost; FLUSH PRIVILEGES; EXIT;还有一个必须改的参数max_allowed_packet。Engine往库里写PV配置时一次请求的包如果超过默认值会直接失败。在MariaDB配置文件里加一行[mysqld] max_allowed_packet64M改完重启数据库sudo systemctl restart mariadb。3. 下载安装包与appliance.xml配置最容易返工的一步3.1 下载成品tar包别从源码硬编Archiver Appliance官方仓库在GitHub上有Releases页面每个版本都会打一个tar.gz包里面的目录结构是整理好的包含四个War、安装脚本、默认配置和文档。我见过不少人一上来就git clone整个源码然后用Maven自己build结果不是依赖拉不下来就是打包报错折腾半天。如果你不是要改源码直接用Release包最省事。cd ~ wget https://github.com/slac-epics/archiver-appliance/releases/download/版本号/archiver-appliance-版本号.tar.gz tar -xzf archiver-appliance-版本号.tar.gz cd archiver-appliance-版本号解压后重点看几个目录Tomcat目录里面有官方整理好的Tomcat运行环境、InstallScripts目录官方安装脚本、lib目录各类依赖jar包。3.2 一个单机可用的appliance.xml示例appliance.xml是整个系统最核心的配置文件指定了集群节点信息、数据库连接、存储目录。它不放在某个War包内部而是放在Tomcat的共享类加载路径下这样四个War启动时都能读到同一份配置。官方安装包里有模板文件我直接给出一个单机可用的最小版本。注意替换数据库密码、机器名和存储路径?xml version1.0 encodingUTF-8? appliance cluster hostnamelocalhost/hostname machine_id1/machine_id /cluster ports mgmt_port17665/mgmt_port engine_port17666/engine_port etl_port17667/etl_port retrieval_port17668/retrieval_port /ports database urljdbc:mariadb://localhost:3306/archappl/url userarchiver/user password在这里换成你的密码/password max_pool_size10/max_pool_size /database storage urlfile:///archappl/store/mgmt/url urlfile:///archappl/store/engine/url urlfile:///archappl/store/etl/url urlfile:///archappl/store/retrieval/url /storage lucene urlfile:///archappl/lucene/url /lucene logs urlfile:///archappl/logs/url /logs /appliance文件保存为/archappl/config/appliance.xml注意目录属主要改成tomcat用户否则Tomcat读不了。3.3 存储目录的划分建议存储路径千万别全塞在系统盘。数据块文件会持续增长系统盘满了会导致整个Ubuntu卡死。我建议把/archappl单独挂到一块大容量数据盘上比如容量2TB以上的机械盘或SSD。实测下来单机场景下Engine写最新数据、ETL做整理、Retrieval读旧数据四个目录都放在同一块盘上问题不大但如果你有条件把Lucene索引目录放到SSD上查询速度提升非常明显。目录用途建议/archappl/store/engine最新数据块给足空间写入频繁/archappl/store/etl长期数据块容量需求最大/archappl/store/retrieval检索缓存不用太大/archappl/lucene索引文件放SSD/archappl/logs日志定期清理我个人习惯把存储目录的所有者直接改成tomcat:tomcat省得后面启动时报权限错误sudo mkdir -p /archappl/{store/{mgmt,engine,etl,retrieval},lucene,logs,config} sudo chown -R tomcat:tomcat /archappl4. 部署到Tomcat手工操作一次就明白官方脚本在干什么4.1 把War包放对位置官方包里的InstallScripts/install-archiver.sh会自动拷贝War包、调整配置、设置Tomcat环境变量。但我还是建议你手工做一遍这样出问题时知道去哪里排查。操作其实很简单把四个War包复制到Tomcat的webapps目录sudo cp ~/archiver-appliance-版本号/Tomcat/webapps/*.war /var/lib/tomcat10/webapps/Tomcat启动时会自动解压War包。这里有个细节把War包复制过去之后最好手动删掉Tomcat默认的ROOT目录避免Tomcat自带首页干扰端口判断。不过这一步不是必须的。4.2 JVM内存和catalina.properties的调整Archiver Appliance对内存的需求比一般Web应用高。默认Tomcat的堆内存只有256MB跑Engine和ETL根本不够。在Ubuntu的Tomcat启动环境文件里调整sudo nano /etc/default/tomcat10找到JAVA_OPTS这一行改成JAVA_OPTS-Djava.awt.headlesstrue -Xms2g -Xmx4g -XX:UseG1GC-Xms2g的意思是启动时分配2GB堆-Xmx4g是最大可用4GB。如果服务器内存只有8GB这个配置没问题如果只有4GB建议把最大值压到2GB否则Tomcat容易OOM。还需要把刚才的appliance.xml目录加入Tomcat的共享类加载路径。编辑/etc/tomcat10/catalina.properties找到shared.loader这一行如果没有就追加shared.loader/archappl/config改完重启Tomcatsudo systemctl restart tomcat104.3 启动、看日志、验证四个服务Tomcat启动后检查这四个服务是否都正常注册curl -s http://localhost:17665/mgmt/mgmt/health curl -s http://localhost:17666/engine/bpl/health curl -s http://localhost:17667/etl/bpl/health curl -s http://localhost:17668/retrieval/bpl/health如果返回{status:ok}这类响应说明服务起来了。如果没起来先看日志sudo tail -f /archappl/logs/*.log日志是排查问题的第一入口。常见的启动失败有两类一是appliance.xml路径没配好Tomcat找不到配置文件报ClassNotFound二是数据库连接不上报Communications link failure。前者去检查catalina.properties里的shared.loader后者去检查数据库用户名密码和网络权限。5. 初始化管理与首条PV归档链路验证5.1 初始化管理员账号和数据库表首次访问管理界面http://你的UbuntuIP:17665/mgmt第一次打开会引导创建管理员账号。不同版本引导方式略有差异有些版本提供create_admin.py脚本界面也会给出提示。关键点账号创建成功后数据库里会自动建好所有元数据表不需要手工执行建表SQL。如果界面提示数据库错误就回到第2.3节检查数据库授权和max_allowed_packet。四个服务刚启动时会自动在数据库里注册自身节点信息你可以在管理界面的Cluster Status页面看到四个角色都在线状态为绿色。如果哪个角色显示离线多半是端口冲突或者该War包启动失败。5.2 建一个测试IOC让PV真实变化要验证归档链路最好有一个真实产生数据的PV。Ubuntu上如果没有真实IOC可以用softIoc搭一个最小模拟。先安装EPICS base并创建一个测试数据库文件test.dbsudo apt install -y epics-base cat test.db EOF record(ai, TEST:VOLTAGE) { field(SCAN, 1 second) field(VAL, 0) } EOF用softIoc加载softIoc -d test.db在另一个终端用caput改变PV值比如每几秒改一次电压for i in $(seq 1 20); do caput TEST:VOLTAGE $i; sleep 2; done如果没有IOC环境也可以直接使用Archiver Appliance内置的模拟数据源在添加PV时选择“Test”类型的数据源。不过我建议还是搭一个真实PV这样能测试完整的Channel Access连接逻辑。5.3 在mgmt界面配置归档并验证数据查询登录管理界面后左侧找到Archiver Management点击Add Archiver填PV名TEST:VOLTAGE选择采样策略其他选项保持默认提交。大约十几秒后这个PV的状态会变成“Being archived”。如果一直是“Not connected”说明Engine连不上IOC检查IOC是否在运行、防火墙是否放行Channel Access端口默认5064/5065UDP和TCP都需要。等一两分钟让Engine积累一些数据块然后用Retrieval接口查数据curl http://127.0.0.1:17668/retrieval/data/getData.json?pvTEST:VOLTAGEfrom2024-01-01T00:00:00.000Ztonow返回的JSON里应该能看到多个数据点每个点带时间戳和value说明这条链路已经真正走通IOC→Engine采集→ETL入库→Lucene索引→Retrieval查询整个闭环完成。6. 我实际踩过的坑端口、时区、权限和索引6.1 ufw防火墙拦住了retrieval端口装好之后我在本机curl一切正常但换一台机器用浏览器访问http://服务器IP:17665/mgmt却连不上。排查半天发现是Ubuntu的ufw防火墙没有放行这些端口。解决方式很简单sudo ufw allow 17665/tcp sudo ufw allow 17666/tcp sudo ufw allow 17667/tcp sudo ufw allow 17668/tcp sudo ufw allow 5064/tcp sudo ufw allow 5064/udp sudo ufw allow 5065/tcp sudo ufw allow 5065/udp如果你用云服务器还要在云控制台的安全组里放行这几个端口。这类问题最坑的是“本机能用、别人不能用”排查时直接用另一台机器telnet一下端口就能定位。6.2 数据库时区导致启动异常第一次启动时ETL服务总是报错日志里出现和serverTimezone相关的提示。这是因为MariaDB默认时区和JVM时区不一致导致时间转换出错。解决办法是在数据库连接串里显式指定时区urljdbc:mariadb://localhost:3306/archappl?serverTimezoneUTC/url也可以直接把系统时区统一成UTC工程上更省心。我后来把整个Ubuntu服务器时区都设置成UTC彻底避开了夏令时和各种本地时区带来的时间戳偏差sudo timedatectl set-timezone UTC6.3 存储目录权限不足有一次升级版本重新解压安装包后忘了改/archappl目录属主启动时Engine和ETL一直报Permission denied。排查日志才发现连/archappl/logs都没写进去。这个坑特别容易在“按文档一步步操作但漏了一两步”时出现。解决办法就是前面写过的sudo chown -R tomcat:tomcat /archappl建议每次升级或迁移后都执行一遍确保万无一失。6.4 数据写进去了但查不到索引缺失还遇到过一个比较隐蔽的问题Engine监控状态显示“Being archived”数据库里也能看到PV配置但Retrieval查询永远返回空数组。最后发现是Lucene索引没有建立起来。ETL正常工作时会自动生成索引但某些异常中断会导致索引目录为空。处理办法是到mgmt管理界面找到索引维护相关功能对目标PV触发一次索引重建。重建期间ETL会扫描已有数据块并重新写入索引目录数据量大的时候会很慢但索引重建完成后查询就正常了。通过这个经验我也养成了一个习惯装完后不要立刻大量灌数据先验证1到2条PV的查询正常再正式接入生产PV列表。6.5 排查问题速查表现象可能原因排查方向mgmt界面打不开端口未放行/服务没起curl本机health接口PV状态一直Not connectedChannel Access网络不通检查IOC状态和防火墙Engine报数据库连接失败库密码错误/max_allowed_packet太小检查appliance.xml和MariaDB配置查询有数据但时序图断断续续存储盘空间不足df -h看磁盘使用率日志报没有写权限/archappl属主错误chown -R tomcat:tomcat /archappl最后再分享一个我个人的使用习惯正式接入生产环境之前先用脚本批量加PV时每批不要超过500个加完留意Engine的CPU和内存曲线确认稳定后再加下一批。Archiver Appliance这套系统本身很稳但PV数量暴涨时如果内存不够采集线程会堆积表现为Engine响应迟缓。与其一上来就堆几千个PV不如分批推进让系统在负载爬坡过程中自己把状态调整到最佳。毕竟数据归档这种基础服务稳定压倒一切。本文还有配套的精品资源点击获取