简介：这份资源面向在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 是当前最稳的两个 LTS，24.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 # 确认网络能到你的 IOC，Channel Access 走的是 UDP 5064/5065 ping -c 3 <你的IOC地址>逻辑说明：lsb_release -a看发行版代号，决定后面加哪个 apt 源；uname -m确认架构，避免下错二进制包；free -h和df -h是给存储规划做参考，PV 多的时候一天写入量能到几十 GB；ping是确认采集机能到 IOC，Channel 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.url=jdbc:postgresql://localhost:5432/archiverdb db.user=archiver db.password=换成你的强密码 # 存储路径，确保这块盘够大 storage.path=/var/epics-archiver/storage # 采集线程数，PV 多时适当调大 engine.threads=4 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] Description=EPICS Archiver Engine After=network.target postgresql.service [Service] Type=simple User=archiver WorkingDirectory=/opt/epics-archiver ExecStart=/usr/bin/java -jar /opt/epics-archiver/engine.jar \ -config /opt/epics-archiver/archiver.properties Restart=on-failure RestartSec=10 [Install] WantedBy=multi-user.target逻辑说明：After保证网络和数据库先起来；Restart=on-failure让进程异常退出后自动拉起，这是长期无人值守的关键；RestartSec=10避免疯狂重启刷日志。
参数说明：User=archiver建议单独建一个系统用户，别用 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，连续量 scan，scan 周期按你关心的最小变化时间定，别盲目追求 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_LIST=NO避免广播干扰。
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才算成功。
健康检查我一般写一个定时脚本，查采集器状态接口和磁盘剩余，异常就发告警。别等用户来问「怎么没数据了」才发现服务早停了。这套东西搭一次能跑很久，但前提是你把监控和容量规划当回事。我自己吃过亏，早期图省事没做磁盘告警，结果一个长假回来数据断了三天，补都补不回来。希望帮到你。
本文还有配套的精品资源，点击获取
