简介这份资源面向在Ubuntu环境下部署EPICS控制系统的工程师与科研人员提供EPICS Archiver Appliance的完整安装配置项目代码。Archiver Appliance是基于Java的开源数据归档系统用于长期采集、存储和检索实时数据适合科学实验设施与工业控制场景的数据管理需求。资源包共8个文件以5个sh脚本为主辅以md说明文档、inscode配置与gitignore文件压缩包约14KB涵盖安装、启动、验证等关键环节的脚本化实现。已有57人学习下载。读者可借助脚本快速完成Java 21环境校验、系统参数检查、存储路径初始化与前端服务启动并参考文档理解归档策略配置、数据检索与集群部署思路为EPICS数据归档系统的落地提供可复用的操作模板与排错参考。1. 从一台裸机 Ubuntu 到能查历史数据的 Archiver这套代码包到底装了什么手里有一台刚装好的 Ubuntu想跑 EPICS Archiver 把 IOC 的 PV 历史数据存下来结果翻官方文档翻到怀疑人生——这是我最近一次帮同事搭环境的真实开场。EPICS Archiver 本质是一套长期运行的数据归档系统负责把 Channel Access 上的 PV 采样值按时间序列落库再通过 Web 界面或 Retrieval 接口把历史曲线捞出来。它由 Archiver Appliance 本体、Tomcat 容器、MySQL 或 PostgreSQL 元数据库、以及可选的集群配置组成任何一个环节版本对不上启动就是一堆 Java 异常。这份项目代码包把安装脚本、配置模板和依赖清单打包在一起省掉了从零拼装的过程适合做控制系统、加速器、实验装置数据采集的工程师也适合刚接触 EPICS 生态、想先跑通再深挖的开发者。下面按我实际复现的顺序拆开讲。2. 装之前先把地基打平Ubuntu 环境、Java 与依赖的选型逻辑2.1 为什么 Archiver 对 Java 版本这么挑Archiver Appliance 是 Java 写的跑在 Tomcat 里不同大版本对 JDK 的要求差异很大。老版本1.x 早期用 JDK 8 编译新版本2.x 之后逐步迁到 JDK 11 甚至 17。如果你 Ubuntu 上默认装的是 JDK 21Tomcat 启动时可能直接抛UnsupportedClassVersionError因为 class 文件版本比运行环境高。常见做法是先用java -version确认当前默认 JDK再决定是装 OpenJDK 11 还是 17。我一般会保留多个 JDK 并用update-alternatives切换避免把系统默认 Java 改乱影响其他服务。# 查看当前默认 Java 版本 java -version # 安装 OpenJDK 11Archiver 常用稳定版本 sudo apt update sudo apt install -y openjdk-11-jdk # 注册到 alternatives方便切换 sudo update-alternatives --install /usr/bin/java java /usr/lib/jvm/java-11-openjdk-amd64/bin/java 1111 sudo update-alternatives --config java逻辑说明update-alternatives --install把新装的 JDK 注册进系统候选列表最后的数字是优先级越大越优先。--config会弹出交互菜单让你选当前默认。参数上路径要按实际安装位置改java-11-openjdk-amd64是 Ubuntu 上 OpenJDK 11 的常见目录名ARM 机器上可能是java-11-openjdk-arm64用ls /usr/lib/jvm/先确认。2.2 Tomcat、MySQL 与系统依赖的安装顺序Archiver 依赖 Tomcat 做 Web 容器依赖 MySQL 或 PostgreSQL 存元数据和采样数据。顺序上我建议先装数据库再装 Tomcat最后部署 Archiver 的 war 包。原因很简单Archiver 首次启动会去连数据库建表如果数据库没起来Tomcat 日志里会刷一堆连接拒绝排查起来反而绕远。Ubuntu 上装 MySQL 用apt最省事但要注意 8.0 之后默认认证插件变了老版本 Archiver 的 JDBC 驱动可能不认需要改用户认证方式或换驱动。# 安装 MySQL 服务端 sudo apt install -y mysql-server # 启动并设置开机自启 sudo systemctl enable --now mysql # 登录后创建 Archiver 专用库和用户 sudo mysql -e CREATE DATABASE archiver DEFAULT CHARACTER SET utf8mb4; sudo mysql -e CREATE USER archiverlocalhost IDENTIFIED BY yourpassword; sudo mysql -e GRANT ALL PRIVILEGES ON archiver.* TO archiverlocalhost; sudo mysql -e FLUSH PRIVILEGES;逻辑说明utf8mb4是为了兼容 PV 名里可能出现的特殊字符。创建独立用户而不是直接用 root是为了后面配 JDBC 时权限清晰也方便审计。密码换成你自己的别用示例里的。MySQL 8 如果报caching_sha2_password相关错误可以执行ALTER USER archiverlocalhost IDENTIFIED WITH mysql_native_password BY yourpassword;切回老认证方式这是血泪经验很多老 war 包就卡在这。Tomcat 的安装可以用apt install tomcat9也可以直接下二进制包解压。用 apt 的好处是 systemd 服务现成坏处是目录结构固定、权限受控。我一般下二进制包放到/opt/tomcat自己控制CATALINA_HOME和CATALINA_BASE这样多实例部署时互不干扰。# 下载 Tomcat 9 二进制包版本按需替换 wget https://archive.apache.org/dist/tomcat/tomcat-9/v9.0.85/bin/apache-tomcat-9.0.85.tar.gz sudo tar -xzf apache-tomcat-9.0.85.tar.gz -C /opt sudo mv /opt/apache-tomcat-9.0.85 /opt/tomcat # 设置环境变量写入 profile echo export CATALINA_HOME/opt/tomcat | sudo tee -a /etc/profile.d/tomcat.sh echo export PATH$CATALINA_HOME/bin:$PATH | sudo tee -a /etc/profile.d/tomcat.sh source /etc/profile.d/tomcat.sh逻辑说明CATALINA_HOME指向 Tomcat 安装根目录PATH加上 bin 是为了能直接敲startup.sh。写到/etc/profile.d/下对所有用户生效比改~/.bashrc更适合服务化部署。参数上Tomcat 版本要和 Archiver 的 war 包兼容9.x 是当前主流10.x 因为 Jakarta EE 命名空间变化很多老 war 包跑不起来别盲目追新。3. 部署 Archiver Appliancewar 包、配置模板与首次启动3.1 把 war 包放进 Tomcat 并配好 JDBC项目代码包里通常包含archiver.war或分模块的多个 warengine、retrieval、etl、mgmt。单机部署一般把 engine 和 retrieval 合在一个实例里跑集群才拆开。部署动作本身很简单把 war 丢进webappsTomcat 会自动解压。关键是解压后要改archappl.properties或archappl.properties里的数据库连接串否则启动时连不上库直接失败。# 停止 Tomcat如果已在运行 /opt/tomcat/bin/shutdown.sh # 拷贝 war 包到 webapps cp /path/to/archiver.war /opt/tomcat/webapps/ # 等待自动解压后编辑配置 sudo nano /opt/tomcat/webapps/archiver/WEB-INF/classes/archappl.properties配置文件里要改的核心项# 数据库连接 jdbc.urljdbc:mysql://localhost:3306/archiver?useSSLfalseserverTimezoneUTC jdbc.userarchiver jdbc.passwordyourpassword # 存储路径确保目录存在且 Tomcat 用户有写权限 archive.storage.path/data/archiver/storage逻辑说明useSSLfalse在本地回环连接时可以省掉证书配置的麻烦生产环境按需开启。serverTimezoneUTC避免时间戳偏移EPICS 数据对时间敏感时区错了曲线会整体平移。archive.storage.path指向实际存采样文件的目录默认可能在/tmp下重启就丢必须改成持久化路径。改完确认目录权限sudo chown -R tomcat:tomcat /data/archiver用户按你 Tomcat 运行身份调整。3.2 启动顺序与日志观察点配置改完后启动 Tomcat别急着开浏览器先盯日志。Archiver 启动时会做几件事连数据库、建表首次、加载 PV 配置、启动采样引擎。任何一步失败都会在catalina.out里留痕。我一般用tail -f跟日志看到Started Appliance或类似字样才算真正起来。# 启动 Tomcat /opt/tomcat/bin/startup.sh # 实时跟日志 tail -f /opt/tomcat/logs/catalina.out日志里重点看几类信息SQLException说明数据库连接或建表有问题FileNotFoundException或AccessDeniedException说明存储路径权限不对Address already in use说明端口被占改server.xml里的 Connector 端口。首次启动建表可能花几十秒别看到没动静就重启容易把建表过程打断留下半拉表结构后面更麻烦。3.3 验证服务是否真的可用服务起来后用浏览器访问http://服务器IP:8080/archiver能看到 Archiver 的 Web 界面。但界面出来不代表归档功能正常还要确认 engine 是否在采样。可以进Metrics页面看 PV 计数或者直接调 Retrieval 接口拉一个已知 PV 的数据。如果手头没有现成 IOC可以先用softIoc起一个模拟 PV 测试。# 安装 EPICS base如果还没装 sudo apt install -y epics-base # 起一个软 IOC创建一个测试 PV softIoc -d EOF record(ai, test:pv) { field(VAL, 1.0) } EOF逻辑说明softIoc是 EPICS 自带的软 IOC不需要硬件就能产生 PV。record(ai, ...)定义一个模拟输入记录test:pv就是 PV 名。起好后在 Archiver 界面里添加这个 PV等几分钟看是否有数据点入库。这一步能跑通说明从 CA 采集到落库的链路是通的后面接真实 IOC 只是换 PV 名的事。4. 避坑与排查那些让 Archiver 起不来的常见问题4.1 启动报数据库连接失败现象Tomcat 日志里反复出现Communications link failure或Access denied for user。原因通常是三种MySQL 没启动、JDBC URL 里的库名或端口写错、用户权限没给够。解决先systemctl status mysql确认服务在跑再用mysql -u archiver -p手动登录验证账号密码最后检查archappl.properties里的 URL 是否和实际库名一致。注意 MySQL 8 的认证插件问题必要时切mysql_native_password。4.2 war 包解压后配置不生效现象改了archappl.properties重启行为没变化。原因多半是 Tomcat 缓存了旧解压目录或者你改的是源包里的配置而不是webapps下解压后的。解决停 Tomcat删掉webapps/archiver和work/Catalina下的缓存重新放 war 让它重新解压再改配置。改完确认文件时间戳是新的。4.3 存储路径权限导致采样写入失败现象Web 界面能打开PV 也能添加但一直没数据点日志里有Permission denied。原因archive.storage.path指向的目录 Tomcat 运行用户没有写权限。解决chown -R把目录给 Tomcat 用户或者chmod放开写权限。别图省事用chmod 777生产环境按最小权限给。4.4 端口冲突导致 Tomcat 起不来现象startup.sh执行后进程秒退日志里Address already in use。原因8080 或 8005 被其他服务占了。解决ss -tlnp | grep 8080找到占用进程要么停掉它要么改 Tomcat 的server.xml里 Connector 和 Shutdown 端口。改端口后记得防火墙同步放行。4.5 PV 添加后一直显示未归档现象PV 加进去了状态是Not being archived。原因可能是 CA 连不上 IOC、PV 名拼错、或者 engine 没启动。解决先在命令行用caget test:pv确认 PV 本身可访问再检查 Archiver 的 engine 日志有没有Channel not found。如果是网络隔离确认 CA 端口 5064/5065 通不通。5. 进阶用 Retrieval 接口批量导出历史数据与自动化验证跑通单 PV 归档只是起点实际项目里往往要批量导出历史数据做分析或者定期验证归档链路是否健康。Archiver 的 Retrieval 接口支持按 PV、时间范围、采样方式拉数据返回 JSON 或 CSV。我一般写个小脚本做两件事一是批量导出指定 PV 最近一小时的数据二是检查数据点数量是否为零来告警。import requests import json from datetime import datetime, timedelta # Archiver Retrieval 接口地址 BASE http://localhost:8080/retrieval/data/getData.json def fetch_pv(pv_name, minutes60): end datetime.utcnow() start end - timedelta(minutesminutes) params { pv: pv_name, from: start.strftime(%Y-%m-%dT%H:%M:%S.000Z), to: end.strftime(%Y-%m-%dT%H:%M:%S.000Z) } resp requests.get(BASE, paramsparams, timeout30) resp.raise_for_status() data resp.json() # 返回结构里第一个元素是元信息第二个是数据点 points data[0].get(data, []) if data else [] return points if __name__ __main__: pv_list [test:pv, demo:temperature] for pv in pv_list: pts fetch_pv(pv) print(f{pv}: {len(pts)} points) if not pts: print(f [WARN] {pv} 无数据检查归档链路)逻辑说明getData.json是 Retrieval 的标准端点from和to用 ISO8601 UTC 格式时区必须带Z。返回的 JSON 是个数组第一个元素含元信息data字段才是采样点列表。参数上minutes控制回看窗口按需调整。这个脚本可以直接挂 cron 做巡检数据点为零就发告警。注意接口默认可能对单次返回点数有限制大批量导出要分页或按时间切片。验证归档健康度还有一招对比 IOC 当前值和 Archiver 最新归档值。如果两者长期偏差大说明采样频率或死区设置有问题。Archiver 的采样策略可以在 PV 配置里调默认按监控模式PV 值变化才记对高频信号可能丢点需要改成周期采样。这个参数在samplingMethod里设常见值有MONITOR和SCAN按信号特性选。从那以后我每次部署 Archiver都强制先跑一遍单 PV 的端到端验证——起软 IOC、加 PV、等数据、调接口拉数——四步全绿才接真实设备。这套习惯帮我挡掉过好几次“界面正常但实际没归档”的假成功。希望帮到你。本文还有配套的精品资源点击获取