简介面向Ubuntu环境下需要部署EPICS Archiver Appliance的系统工程师与科研人员这份代码包提供了完整的安装脚本与配置说明解决EPICS控制系统中实时数据长期归档、检索与存储的落地难题。包体体积仅14KB共8个文件其中5个shell脚本涵盖环境准备、快速启动、下载与验证等关键环节配套Markdown文档介绍配置细节另有inscode与gitignore文件辅助工程管理结构精炼可直接对照执行。已有56人学习可作为EPICS Archiver快速上手的参考模板。内含可直接运行的启动脚本并对Java 21版本约束、依赖工具更新、端口监听、数据持久化路径等做了适配说明借助这些脚本用户可跳过繁琐的环境调研在统一配置下完成归档服务初始化与前端访问适合希望在实验或生产环境快速验证Archiver Appliance能力的开发者。1. Archiver Appliance 是什么为什么值得装1.1 一句话定位给 EPICS 的 PV 数据建一座长期档案馆做实验物理控制系统EPICS的同行应该都有体会装置跑起来之后IOC 里的过程变量PV成百上千每次实验调束、分析故障、优化流程都需要回看历史数据。如果只靠手动记录或者临时抓数三两天还能凑合时间一长数据要么丢失要么散落各处。Epics Archiver官方项目名 Archiver Appliance就是为解决这个问题而生的它把 PV 的变化按时间序列归档到后端存储并提供统一的查询和管理界面让历史数据随取随用。这套系统由 SLAC 主导开发在同步辐射光源、自由电子激光和加速器控制领域用得非常多。不同于早期工具“定时轮询”的思路Archiver Appliance 的定位是“按需归档 分层存储 前后端分离”它更像一个面向控制系统的时序数据服务平台。对需要长期跑装置、做数据回溯的团队来说这不是装不装的问题而是早晚要装的问题。1.2 与 Channel Archiver 的对比存储策略和查询方式差异很大很多老团队还在用 EPICS Channel Archiver先别急着换但建议把两边差异理清楚。对比项Channel ArchiverArchiver Appliance采集方式周期性扫描按固定周期取数支持扫描和死区触发也支持事件驱动存储策略文件列表管理简单但检索麻烦分层存储RAM/SSD 暂存 长期磁盘ETL 自动合并查询接口命令行工具或专用客户端HTTP/REST API浏览器直接看图、导数据配置方式文本配置Web 管理界面可批量操作 PV扩展性单机为主可横向扩展为集群支持高可用实际体验下来最明显的差异在“存储分层”。Archiver Appliance 把数据按时间切成一个个 partition归档周期新数据先落在快速的暂存区后台 ETL 进程再按策略合并到长期存储。这样既保证了写入实时性又不需要一开始就把所有容量都配成高速盘。对于加速器这种动辄几十万个 PV 的场景这个设计非常关键。Channel Archiver 并非不能用但如果你已经受够了“查询历史数据要翻半天文件”“采样周期太粗导致信号细节丢失”这些痛点直接上 Archiver Appliance 是更省心的选择。2. 安装前的环境准备Ubuntu 22.04 一台2.1 基础系统与软件包我用的是 Ubuntu 22.04 LTS其他 20.04/24.04 同样适用。系统装好后先做常规更新sudo apt update sudo apt upgrade -y sudo apt install -y wget git curl build-essential maven如果下载速度慢先把 apt 源换成国内镜像源这个网上教程很多不再展开。需要提醒的是Archiver Appliance 的编译过程中 Maven 会拉取大量第三方依赖建议顺手把 Maven 仓库也配置成阿里云镜像否则等依赖下载就能等掉半条命。具体做法是在~/.m2/settings.xml里加 mirror 配置实测从国外源换成国内镜像后首次编译时间能缩短一半以上。2.2 JDK 与 Tomcat版本选择是成败关键这是最容易翻车的环节。Archiver Appliance 虽然是 Java 项目但官方对 JDK 版本有要求实测最稳的是 OpenJDK 8JDK 11 在某些历史版本上会出现 JAXB 相关异常JDK 17 就不要轻易尝试了。sudo apt install -y openjdk-8-jdk java -versionTomcat 选择 8.5 或 9.x 均可注意如果 Tomcat 9 配上 JDK 8 也没问题。我习惯手动解压 Tomcat 到 /opt而不是用 apt 自带的 tomcat9这样后续配置和控制更干净wget https://dlcdn.apache.org/tomcat/tomcat-9/v9.0.100/bin/apache-tomcat-9.0.100.tar.gz sudo mkdir -p /opt/tomcat sudo tar -xzf apache-tomcat-9.0.100.tar.gz -C /opt/tomcat --strip-components1解压后创建软链或直接设置环境变量并给 Tomcat 分配足够内存。Archiver 是数据密集型应用至少给 2GB生产环境建议 4GB 以上。在/opt/tomcat/bin/setenv.sh里写export JAVA_HOME/usr/lib/jvm/java-8-openjdk-amd64 export CATALINA_HOME/opt/tomcat export CATALINA_OPTS-Xms1g -Xmx4g -DARCHAPPL_CONFIG/etc/archappl这里ARCHAPPL_CONFIG是关键配置它让所有 webapp 读取同一个外部配置目录而不是各自用 war 包里的默认配置。这个后面详细说。2.3 MySQL 数据库和存储路径规划Archiver Appliance 的 PV 元数据和归档配置放在数据库里默认支持 MySQL / MariaDB。单机部署用 MariaDB 也行我这次按 MySQL 8.0 来。安装后创建专用数据库和账号sudo apt install -y mysql-server sudo mysqlCREATE DATABASE archappl CHARACTER SET utf8mb4; CREATE USER archlocalhost IDENTIFIED BY 你的密码; GRANT ALL PRIVILEGES ON archappl.* TO archlocalhost; FLUSH PRIVILEGES;注意 MySQL 8 默认的caching_sha2_password认证插件有时会让 JDBC 连接报错如果后面连不上记得把用户改成mysql_native_password认证。存储路径方面我建议在数据盘上单独划分一个目录比如/data/archiver/store用来放归档文件和系统盘分开避免日志把根分区写满。3. 源码编译与部署一步步推到 Tomcat3.1 获取源码并编译源码在 GitHub 上仓库名slacmshankar/epicsarchiverap。建议 checkout 一个 release 标签而不是直接用 master毕竟是给装置用的东西稳定性优先git clone https://github.com/slacmshankar/epicsarchiverap.git cd epicsarchiverap git checkout R1.5.1 # 具体标签以仓库实际为准 mvn -DskipTests package首次编译时间比较长大概 10 到 30 分钟不等取决于网络和机器性能。编译完成后在target目录部分版本在build目录下会生成四个 war 包archappl_mgmt.wararchappl_engine.wararchappl_etl.wararchappl_retrieval.war这四个组件分别负责管理界面、数据采集、数据转储和数据查询。单机部署时可以把四个 war 包全部丢进同一个 Tomcat 的 webapps 目录生产环境要拆开跑也没问题推荐前期先单机全上跑通流程再说。3.2 初始化数据库编译产物里带了初始化 SQL 脚本。找到src/main/install_scripts/sql/mysql/目录按顺序执行里面的脚本。不同版本文件名可能略有差异基本是先执行create_archappl_db.sql再视需要执行补丁脚本mysql -u arch -p archappl src/main/install_scripts/sql/mysql/create_archappl_db.sql这一步会创建 Archiver 运行所需的全部表结构。执行时如果提示某个表已存在多半是重复执行了确认脚本没问题就可以忽略反过来如果少了关键表后面启动一定会报错需要回头检查执行过程有没有缺漏。3.3 修改 appliance.xml 和 Tomcat 配置这是整个安装过程里最需要耐心的一步。将源码中src/main/resources/appliance.xml复制到/etc/archappl/目录sudo mkdir -p /etc/archappl sudo cp src/main/resources/appliance.xml /etc/archappl/然后编辑这个文件核心要改三处。第一是数据库连接找到jdbc_url、db_username和db_password三个属性替换成自己数据库的信息。第二是存储路径ram和staging存储的rootFolder指到前面规划的数据盘目录archive存储就是长期归档的主目录。第三是集群名单机部署保持默认即可如果以后要扩展节点需要保证同一集群的节点配置一致。提示appliance.xml 如果改错了service 可能起得来但功能异常最典型的表现是“PV 添加成功但迟迟没有数据”。修改完记得检查 XML 格式最好用xmllint --noout验证一下。最后把四个 war 包拷贝到 Tomcat 的 webapps 下启动 Tomcatsudo cp target/archappl_*.war /opt/tomcat/webapps/ sudo /opt/tomcat/bin/startup.sh启动后第一次访问会比较慢因为 webapp 要初始化连接池和检查目录。看日志可以用tail -f /opt/tomcat/logs/catalina.out等到出现Server startup字样就说明部署成功了。4. 启动服务并跑通第一个归档任务4.1 检查关键端口和进程启动完成后先别急着打开浏览器按顺序确认三件事。第一Tomcat 进程是否存活使用ps -ef | grep tomcat或jps查看。第二8080 端口是否监听用ss -tlnp | grep 8080确认。第三数据库连接是否正常看 catalina.out 里有没有 JDBC 相关异常。如果前面配置没问题此时应该能通过浏览器访问管理页面http://服务器IP:8080/archappl_mgmt/index.html登录默认是匿名访问或者使用配置的管理员账号。界面打开后能看到 PV 管理、归档策略、存储状态等模块就说明管理组件已经正常工作了。此时 engine 和 etl 组件会在后台自动运行。4.2 在管理界面添加 PV 并验证归档接下来用一个真实的 PV 做端到端验证。假设你的 IOC 已经启动PV 名是Test:AI1。在 mgmt 界面点击“Add PV”输入 PV 名称选择归档策略。这里要注意一个核心概念归档策略决定数据怎么被采集。常用的有两种Scan是指定周期轮询采集适合需要固定采样率的信号Monitor是死区触发PV 变化超过某个阈值才记录适合变化频繁但冗余大的信号。我建议先用Monitor配合 0.1 或 1.0 的死区做测试这样数据量小能快速看到效果。添加成功后engine 组件会通过 CA 协议连接 IOC。在命令行里用caget验证 IOC 可见性caget Test:AI1caget来自 EPICS base如果你机器上没装也没关系任何能通过 CA 协议访问 PV 的客户端工具都可以用来做这个验证。等几分钟回到 mgmt 界面应该能看到该 PV 的状态变成“正在归档”。然后打开 retrieval 查询界面选择这个 PV 和时间范围如果能查到数据并画出波形整个链路就是通的。这一步跑通了后面批量加 PV 就是体力活了。5. 踩坑记录与生产环境建议5.1 编译和启动阶段常见问题先说编译期。Maven 首次构建慢是通病建议在~/.m2/settings.xml里配置阿里云镜像如果报某个依赖找不到优先确认 JDK 版本和 Maven 版本是否匹配Maven 3.6 以上比较稳。启动阶段最高频的问题是端口冲突。有些机器上 8080 已经被 Nginx 或其他服务占用表现为 Tomcat 能起来但访问不到页面。处理方法是ss -tlnp找到占用进程或者直接把 Tomcat 的 port 改掉改conf/server.xml。另一个常见问题是内存不足。-Xmx4g在 2GB 内存的小机器上直接启动失败错误信息是Could not reserve enough space for object heap。这种情况下要么加大物理内存要么把堆内存降到合理范围但不要低于 1GB否则后期归档大 PV 容易频繁 GC。5.2 数据库与连接问题数据库问题往往是“最后一个报错才暴露”。如果你看到Access denied for user大概率是账号密码不对或者 MySQL 8 的认证插件不兼容。后者的解决办法很直接ALTER USER archlocalhost IDENTIFIED WITH mysql_native_password BY 你的密码; FLUSH PRIVILEGES;还有一种情况是数据库建好了、脚本也执行了但启动时报找不到表。这通常是执行 SQL 脚本时没指定数据库名导致建在别的库里。检查执行命令是否带了archappl参数以及脚本开头有没有USE语句。最后提醒一句如果机器时间不同步Archiver 的时间戳会乱甚至在检索时出现数据错位。务必装好 NTP 或 chronysudo apt install -y chrony sudo systemctl enable --now chrony5.3 数据质量与生产部署建议数据顺利归档只是开始生产环境还有几件事值得提前规划。第一是容量规划根据 PV 数量和变化频率估算每天的数据量留出至少双倍余量长期存储尽量用大容量机械盘暂存区用 NVMe 或 SSD。第二是备份策略数据库要定期备份归档文件建议配合快照或 rsync。第三是监控Archiver Appliance 本身有存储状态页面建议接入日常值班监控存储写满或 ETL 停滞时能第一时间发现。实用小技巧批量添加 PV 时mgmt 界面支持 CSV 导入不用一个个点。把 PV 列表整理成 CSV字段按官方模板填好一次能导入上千个。这个小功能非常省事。最后一个建议如果你是多节点机房部署把四个组件拆开每个节点承担单一职责配合负载均衡用起来更顺。单机方案适合开发环境和小型装置规模上来之后再考虑集群化不迟。我在实际维护中发现最先出现问题的往往不是软件本身而是磁盘容量和时钟同步这两件事做好Archiver 能非常安静地跑很久。本文还有配套的精品资源点击获取