简介这份资源面向在Ubuntu环境下部署EPICS控制系统的运维与开发人员提供Archiver Appliance归档服务的完整安装配置代码包。Archiver Appliance基于Java构建用于长期采集、存储与检索EPICS实时数据适合科学实验设施与工业控制场景的数据管理需求。压缩包共8个文件约14KB以5个sh脚本为主涵盖setup、start、run、download、verify等安装与校验环节另含md说明文档、inscode配置与gitignore文件结构精简、开箱即用。目前已有57人学习下载。读者可借助脚本快速完成Java 21环境检测、系统参数校验、存储路径初始化与Jetty端口绑定并参考配置模板理解采集代理、存储引擎、检索服务与Web前端的模块划分为后续通道订阅、归档策略配置与集群扩展打下基础同时获得一份可复用的排错与部署参考。1. 从一台裸机 Ubuntu 到能查历史波形的 EPICS Archiver这条路值不值得走实验室里最让人头疼的场景之一是设备昨天半夜三点报了一次超温现场没人盯着等第二天上班只看到报警灯灭了具体那段时间 PV 到底怎么抖的、抖了多久、峰值多少全凭运气猜。EPICS 这套控制系统本身只管实时值它不负责把每秒的采样存下来给你回放真正干这件事的是 Archiver——把 Channel Access 上的 PV 按策略采集、落盘、再通过 Web 界面按时间段检索出来。标题里的「Ubuntu 安装 Epics Archiver 教程」说的就是在一台干净的 Ubuntu 机器上把采集引擎、存储后端和查询界面这一整套搭起来让它能长期稳定地记录你关心的 PV。适合谁做加速器、光束线、大型实验装置控制的老手以及刚接手 EPICS 环境、需要自己补一套历史数据服务的新人。这套东西装完不是玩具是能直接进生产、连续跑几个月的服务所以下面每一步我都按「装完能长期活着」的标准来写而不是「能跑起来看一眼」。2. 装之前先把架构和依赖想清楚Archiver 到底由哪几块拼起来很多人一上来就apt install结果装到一半发现数据库连不上、Java 版本不对、采集器起不来回头重装三遍。血泪经验是先把组件边界和依赖关系画在脑子里再动手。2.1 三个进程各管什么别混在一起EPICS Archiver 的经典部署是三个独立部分。第一块是采集引擎通常叫 Engine它通过 Channel Access 连到 IOC按你配置的采样策略monitor 还是 scan把 PV 的值和时标抓下来。第二块是存储后端早期用关系库现在主流是把数据写进一套带时间序列优化的存储里同时用关系库存元数据PV 名、采样策略、保留周期。第三块是检索界面一个跑在 Tomcat 里的 Web 应用用户在上面选 PV、选时间段、出图、导出。这三块可以装在同一台机器也可以拆开。单机部署适合中小规模、几百到几千个 PV一旦 PV 上万、采样率又高采集和存储分机器是迟早的事。我一般建议第一次搭就单机把链路跑通再考虑拆分。提示单机部署时磁盘 IO 是第一个瓶颈。机械盘在 PV 数量上去后写入延迟会明显拖垮采集SSD 是底线。2.2 Ubuntu 版本、Java 和数据库的选型理由Ubuntu 这边20.04 和 22.04 是当前最稳的两个 LTS24.04 也能用但部分老版本的 EPICS 基础库在 24.04 上编译时会有依赖告警需要手动补包。如果你是从零开始我倾向 22.04 LTS社区资料最全踩坑最少。Java 是硬依赖检索界面和部分采集组件跑在 JVM 上。别用系统自带的默认 JDK版本经常偏新或偏旧。装一个长期支持的 LTS 版本比如 OpenJDK 11 或 17装完用java -version确认再设好JAVA_HOME。环境变量配错是新手翻车重灾区JAVA_HOME指向的是 JDK 根目录不是bin目录这一点后面避坑章还会提。数据库方面元数据用 PostgreSQL 是常见做法稳定、生态好、和 Archiver 的 schema 兼容性经过大量验证。时间序列数据如果走关系库写入压力大时性能会掉所以现在更推荐把原始采样写进专门的时序存储关系库只留配置和索引。2.3 装之前必须确认的四件事动手前先跑几条命令确认基础环境能省掉后面一半的排查时间。# 确认系统版本和架构x86_64 是主流arm 需要额外注意预编译包 lsb_release -a uname -m # 确认内存和磁盘采集服务吃内存不凶但存储吃磁盘 free -h df -h /opt /var # 确认网络能到你的 IOCChannel Access 走的是 UDP 5064/5065 ping -c 3 你的IOC地址逻辑说明lsb_release -a看发行版代号决定后面加哪个 apt 源uname -m确认架构避免下错二进制包free -h和df -h是给存储规划做参考PV 多的时候一天写入量能到几十 GBping是确认采集机能到 IOCChannel Access 的广播和单播都依赖网络可达。参数说明/opt通常放应用/var放数据如果你打算把数据单独挂一块盘提前把挂载点规划好别等数据写满了再迁移迁移时序库比迁移普通文件麻烦得多。3. 在 Ubuntu 上把 Archiver 跑起来从装包到第一个 PV 入库这一章是核心操作按顺序走每一步都有它的道理。我按「先装依赖 → 再装采集和存储 → 最后配检索界面」的顺序来因为检索界面依赖前面两个的数据结构。3.1 装 JDK、PostgreSQL 和基础工具先更新源再装依赖。更新源如果遇到 404多半是镜像地址过期换成官方或国内可用镜像即可这是 Ubuntu 老问题不算 Archiver 的坑。sudo apt update sudo apt install -y openjdk-17-jdk postgresql postgresql-contrib \ curl wget unzip net-tools # 确认 Java 装好 java -version # 确认 PostgreSQL 服务在跑 sudo systemctl status postgresql逻辑说明openjdk-17-jdk提供 JVM 和编译工具postgresql和postgresql-contrib是元数据库curl wget unzip后面下载和解压要用net-tools里的netstat用来确认端口监听。参数说明如果你机器上已经有别的 JDK注意update-alternatives的优先级别让 Archiver 用到错误的版本。PostgreSQL 装完默认监听 5432本机访问没问题跨机访问要改postgresql.conf的listen_addresses和pg_hba.conf。3.2 建库建用户把元数据存储准备好Archiver 不会帮你自动建库这一步手动做权限给清楚。# 切到 postgres 用户操作 sudo -u postgres psql -- 建一个专用用户和数据库别用 postgres 超级用户跑应用 CREATE USER archiver WITH PASSWORD 换成你的强密码; CREATE DATABASE archiverdb OWNER archiver; \q逻辑说明应用连库用独立账号是最基本的隔离出问题时权限边界清晰。OWNER archiver让这个用户对自己库有完整权限省去后面一堆 grant。参数说明密码别用弱口令这台库以后存的是全装置的 PV 配置。如果检索界面和采集器分机器记得在pg_hba.conf里给采集机 IP 放行用md5或scram-sha-256认证。3.3 部署采集引擎和存储配置第一个采样策略采集引擎的部署方式取决于你拿到的发行包。常见做法是解压到/opt/epics-archiver改配置文件再用 systemd 托管。下面是一个典型的目录和启动配置。# 假设发行包已解压到 /opt/epics-archiver sudo mkdir -p /opt/epics-archiver sudo chown -R $USER:$USER /opt/epics-archiver # 配置数据库连接写进应用的属性文件 cat /opt/epics-archiver/archiver.properties EOF # 元数据库连接 db.urljdbc:postgresql://localhost:5432/archiverdb db.userarchiver db.password换成你的强密码 # 存储路径确保这块盘够大 storage.path/var/epics-archiver/storage # 采集线程数PV 多时适当调大 engine.threads4 EOF逻辑说明属性文件是采集器和检索界面共享的配置入口数据库和存储路径必须一致否则界面查不到采集器写的数据。engine.threads控制并发采集能力PV 少时 2 到 4 够用上千 PV 要往上调但别超过 CPU 核数太多否则上下文切换反而拖慢。参数说明storage.path指向的目录要提前建好并给写权限磁盘剩余空间至少留出按保留周期估算的容量。db.password和建库时一致改完记得重启服务。3.4 用 systemd 托管让它开机自启、崩了能拉起来手工nohup跑服务是临时方案生产必须用 systemd。下面是一个采集服务的 unit 示例。# /etc/systemd/system/epics-archiver-engine.service [Unit] DescriptionEPICS Archiver Engine Afternetwork.target postgresql.service [Service] Typesimple Userarchiver WorkingDirectory/opt/epics-archiver ExecStart/usr/bin/java -jar /opt/epics-archiver/engine.jar \ -config /opt/epics-archiver/archiver.properties Restarton-failure RestartSec10 [Install] WantedBymulti-user.target逻辑说明After保证网络和数据库先起来Restarton-failure让进程异常退出后自动拉起这是长期无人值守的关键RestartSec10避免疯狂重启刷日志。参数说明Userarchiver建议单独建一个系统用户别用 root 跑应用。ExecStart里的 jar 路径和配置路径按你实际解压位置改。写完执行sudo systemctl daemon-reload再enable --now。3.5 加第一个 PV验证数据真的落盘了服务起来后通过管理接口或配置文件加一个 PV。常见做法是用管理界面的「添加 PV」功能或者直接往配置表插一条。-- 往元数据库里加一个 PV采样策略用 monitor INSERT INTO pv_config (pv_name, sampling_mode, sampling_period, retention_days) VALUES (TEST:PV:01, monitor, 1, 30);逻辑说明monitor模式是值变化才记适合状态量scan模式按固定周期记适合连续量。retention_days控制保留天数到期自动清理别设太大把盘写满。参数说明sampling_period单位通常是秒monitor 模式下这个值影响不大scan 模式下就是采样间隔。加完 PV 后去检索界面按时间段查这个 PV能出图就说明采集、存储、查询整条链路通了。4. 检索界面和采集策略调优让 Archiver 真正好用装通只是及格线能用得顺手是另一回事。这一章讲界面部署和几个影响体验的关键参数。4.1 部署 Web 检索界面并接上后端检索界面一般是个 war 包丢进 Tomcat 就能跑。装 Tomcat 和部署的步骤不复杂关键是配置要指向同一个数据库。sudo apt install -y tomcat10 # 把 war 包放到 webapps 目录Tomcat 会自动解压部署 sudo cp archiver-webapp.war /var/lib/tomcat10/webapps/ # 确认部署成功看日志有没有报数据库连接错误 sudo tail -f /var/log/tomcat10/catalina.out逻辑说明Tomcat 自动部署 war 包访问路径通常是 war 包名。日志里如果出现数据库连接异常八成是属性文件路径不对或密码错。参数说明Tomcat 默认 8080 端口和别的服务冲突就改server.xml。检索界面本身不吃资源但并发查询多时 JVM 堆要调大改setenv.sh里的-Xmx。4.2 采样策略怎么定monitor 和 scan 的取舍这是最影响存储量和查询体验的决策。monitor 适合开关量、状态字、报警位值不变就不写省空间scan 适合温度、电流、位置这类连续量按固定周期记曲线才连续。一个常见误区是所有 PV 都用 monitor结果连续量在值稳定时几乎没有点出图断断续续。反过来全用 scan高频 PV 会把存储写爆。我的做法是状态量 monitor连续量 scanscan 周期按你关心的最小变化时间定别盲目追求 1 秒。注意scan 周期设得比 IOC 实际更新还快只会记到重复值白白占空间。4.3 保留周期和磁盘容量的估算方法保留周期直接决定磁盘需求。粗算公式单 PV 日写入量 ≈ 采样频率 × 单条记录字节数 × 86400。假设 scan 周期 1 秒、单条 50 字节一个 PV 一天约 4.3 MB一千个 PV 一天约 4.3 GB保留 90 天就是近 400 GB。这还没算索引和元数据开销。所以规划时先算总量再定保留周期最后选盘。别等盘满了才想起来清理时序库清理和扩容都比普通文件麻烦。可以按 PV 重要程度分级关键的留长调试用的留短。5. 避坑与排查装 Archiver 最容易翻车的五个地方这一章全是实际踩过的坑按「现象 → 原因 → 解决」写遇到问题直接对号入座。5.1 服务起来了但检索界面查不到任何数据现象采集器日志显示在采检索界面选 PV 出图空白。原因采集器和检索界面连的不是同一个数据库或者存储路径不一致采集器写到了另一个目录。解决核对两边的属性文件db.url和storage.path必须完全一致改完重启两个服务。5.2 Channel Access 连不上 IOC日志刷连接超时现象采集器启动后大量connection timeout。原因网络不通或者EPICS_CA_ADDR_LIST没配采集器不知道去哪找 IOC。解决先ping确认网络再设环境变量EPICS_CA_ADDR_LIST指向 IOC 所在网段必要时设EPICS_CA_AUTO_ADDR_LISTNO避免广播干扰。5.3 Java 版本不对导致检索界面启动即崩现象Tomcat 日志报UnsupportedClassVersionError。原因war 包编译用的 JDK 版本比运行环境高。解决java -version确认版本装对应或更高的 LTS JDK用update-alternatives切过去重启 Tomcat。5.4 磁盘写满后采集器静默停止现象某天开始数据断档服务进程还在但没新数据。原因存储盘写满写入失败但进程没退出。解决加磁盘监控告警保留周期别设太大systemd 里可以配Restart但写满这种问题重启也没用根本还是容量规划。5.5 环境变量配错服务读不到配置现象手工跑正常systemd 托管就报找不到配置或连不上库。原因systemd 不继承你 shell 里的环境变量JAVA_HOME、EPICS_CA_ADDR_LIST这些都没带进去。解决在 unit 文件里用Environment显式声明或者写进EnvironmentFile别指望它读你的.bashrc。6. 进阶用管理接口批量加 PV 和做健康检查手工一个个加 PV 在几十个的时候还行上千个就是折磨。Archiver 一般提供管理接口可以用脚本批量导入。下面是一个用 curl 批量提交 PV 配置的例子。#!/bin/bash # 从文件读 PV 列表逐个提交到管理接口 while read -r pv; do curl -s -X POST http://localhost:8080/mgmt/bpl/archivePV \ -H Content-Type: application/json \ -d {\pv\:\$pv\,\samplingperiod\:\1\,\policy\:\Monitor\} echo submitted: $pv done pv_list.txt逻辑说明archivePV是常见的批量归档接口policy对应 monitor 或 scan。脚本逐行读 PV 名提交适合初始化时一次性导入。参数说明samplingperiod单位秒policy大小写按接口要求来。提交后去检索界面确认 PV 状态变成Being archived才算成功。健康检查我一般写一个定时脚本查采集器状态接口和磁盘剩余异常就发告警。别等用户来问「怎么没数据了」才发现服务早停了。这套东西搭一次能跑很久但前提是你把监控和容量规划当回事。我自己吃过亏早期图省事没做磁盘告警结果一个长假回来数据断了三天补都补不回来。希望帮到你。本文还有配套的精品资源点击获取