现场安装

公司口径是现场必装虹元：智眸只跟虹元通信，HSE 与随手拍也都经虹元拿事件、回写处置。这一页照安装包的顺序写，现场实施人员按步骤走一遍即可。

装什么

组件	位置	说明
PostgreSQL 14 及以上，或 openGauss	本机	建议装本机，不要求容器。验证过 PostgreSQL 16、17 与 openGauss 6.0.0
业务库 uancore	数据库	UTF8，属主是应用账号
uancore 二进制	/opt/uancore/uancore	只在编译机编，现场机器不编译，架构要对上
控制台静态页	/opt/uancore/web	单页自包含，换页面不用重启
迁移文件与台账	/opt/uancore/migrations、库内表 schema_version	跑过的文件必须留在机器上
运行环境文件	/opt/uancore/env，权限 600	口令与密钥只在这里，不进仓库
证据缓存	/opt/uancore/evidence	从智眸取回的快照副本，可重取，不进备份
制度库原件	/opt/uancore/kbdocs	没配对象存储时原件存这里，备份另打一个原件包
systemd 单元	uancore.service	非特权账号运行，异常退出自动拉起
备份	/opt/backup/uancore	库加配置，本地轮转 14 天，至少留 3 份

目录与单元名都可用环境变量改，同机装第二套不冲突。

前置条件

动手前对一遍，缺一条装不起来：

• 操作系统。 x86_64 或 aarch64 的 Linux，带 systemd。国产操作系统走同一套脚本，二进制按目标架构在编译机编好。
• 命令。 psql、pg_dump（openGauss 换成 gs_dump）、python3、systemctl、curl、sha256sum、tar、gzip。
• 数据库。 PostgreSQL 14 及以上，或 openGauss。库编码 UTF8，允许应用账号从本机用 scram-sha-256 连。PostgreSQL 上应用账号是库的属主，迁移、备份、恢复都不需要超级用户；openGauss 另有三条前提，见下文。
• 端口。 默认 8100，装时可改。被占时脚本直接拦下。另有 UDP 广播 45678 用于自动发现，同网段有第二套虹元时关掉一套。
• 对外暴露。 现场内网即可，不需要公网口。云端 HSE 要看现场证据照片有两条路：现场虹元对云端开一个只读入口，经虹元取；或者不开口，HSE 在推送回执里点名要哪几张，现场虹元把图直传到 HSE 的对象存储。两条路都不要把智眸直接暴露出去。
• 磁盘。 库加证据缓存加 14 天备份，试点规模按 50GB 起备。
• 时区。 机器时区设成现场当地，海外现场另在环境文件里设时区偏移。

DBA 手工建库时：

CREATE ROLE uancore LOGIN PASSWORD '<现场设，别写进任何文件>';
CREATE DATABASE uancore OWNER uancore ENCODING 'UTF8' TEMPLATE template0;

openGauss（信创）

同一套脚本，连上库自动认方言，命令和 PostgreSQL 一样。多三个前提：

1. 给一个有 SYSADMIN 权限的管理连接 ADMIN_DB_URL。openGauss 只有 sysadmin 能建函数，建函数的迁移和整库恢复走管理连接，做完把属主交回应用账号。没给就停，一个迁移都不灌。
2. gs_dump 在 PATH 里。
3. 应用账号口令至少 8 位，大写、小写、数字、特殊字符占三类。

迁移文件以 PostgreSQL 写法为准，灌到 openGauss 时脚本在执行前改写它不认的几种写法，台账照旧记原文件指纹，两种库都不漂移。备份在 openGauss 上出 INSERT 写法的包，恢复脚本见到 COPY 写法的包直接拒绝。

现场部署都是单库形态，不需要额外配置。一租户一库是公有云用的形态，当前只支持 PostgreSQL。

安装步骤

1. 二进制在编译机编好传到现场机器。
2. 部署包传到现场：deploy/、migrations/、web/ 三样。
3. 执行安装：

sudo deploy/install.sh \
  --binary /tmp/uancore \
  --db-url 'postgres://uancore:<口令>@127.0.0.1:5432/uancore' \
  --create-db \
  --set UANCORE_INSTANCE=uancore-<现场码> \
  --set UANCORE_NAME='<单位> 虹元'

4. 需要接门户或业务系统的，编辑环境文件解开对应注释，再 systemctl restart uancore。

安装脚本幂等：重复执行不重建库、不重灌迁移、不覆盖已填好的环境文件、不刷掉二进制备份。跑一半发现少填一项，补上再跑一遍是正常用法。首次生成环境文件时管理密钥与会话密钥自动填随机值。

口令里有 @ : / ? # 等字符时必须百分号编码。

存量库（已跑过迁移但没有台账）先执行 install.sh --baseline --no-start 只登记不执行，确认表结构确实与迁移文件一致再用。

装完的顺序：先虹元，再智眸，再 HSE

顺序是死的，反过来配不上。

1. 装虹元。 巡检脚本退出码 0。浏览器打开控制台，用环境文件里的管理密钥登录。填实例身份（PUT /api/uancore/identity）：单位名、租户码、场站，接入方看到的是这个，不填就是实例名。
2. 智眸配对。 控制台生成一次性配对码（10 分钟有效），智眸配置页填虹元地址与配对码，双方交换密钥，之后事件加密上报。同网段智眸靠广播自动发现虹元，不用填地址。配对成功后节点列表里能看到它。
3. HSE 连接虹元。 HSE 的系统设置里填虹元地址与管理密钥，HSE 自己去虹元登记订阅与推送通道。虹元侧环境文件要有那把推送签名密钥，加完重启。随手拍经虹元进 HSE 同理，环境文件里放拉取令牌，控制台登记事件源。
4. 跑一条真告警。 走完通知、研判、派单、处理、验收、关闭、回写虹元八步，这才算通。

验证

检查	怎么看
服务	systemctl status uancore；日志里不应有 ERROR
接口	curl 127.0.0.1:8100/api/uancore/version 出版本号、提交号、编译时间、实例身份与库形态；/api/uancore/health 回 ok
闸门	带管理密钥访问 /api/uancore/auth/me 应 200，不带必须 401
迁移台账	schema_version 条数与迁移目录文件数相等。这条是重点，看表不看人
一键巡检	deploy/healthcheck.sh，退出码 0

巡检脚本查六件事：服务状态、接口与闸门、数据库、迁移台账、磁盘与日志、备份新鲜度。最近备份超过 36 小时判失败。建议挂两条定时任务：每 10 分钟巡检，每天凌晨备份。

日常运维

动作	命令	要点
启停	systemctl restart uancore	只用 systemctl，不用 kill 进程
备份	deploy/backup.sh	纯 SQL 加 gzip，双重校验，留最新 3 份不受保留天数影响；原件存本地时另打原件包
恢复	deploy/restore.sh --file <包>	破坏性；先验包、先留底、显式确认；建议先恢复到核对库
升级	deploy/upgrade.sh --binary <新包> --backup	换前留底，换后自检，失败给回滚命令

两条写进脚本的规矩：换二进制先复制到临时目录再移动，直接覆盖正在运行的文件会失败；升级带迁移时先迁移后二进制。

制度库的可选配置

用不到制度库可以不配。要用时在环境文件里加，改完重启：

配置	说明
UANCORE_DOC_S3_ENDPOINT、_BUCKET、_ACCESS_KEY、_SECRET_KEY	S3 兼容对象存储，四项配全才用；不配原件存本地目录
UANCORE_DOC_S3_PUBLIC_ENDPOINT	签短时下载地址用的对外地址，不配就不签
UANCORE_DOC_DIR	原件本地目录，缺省 /opt/uancore/kbdocs
UANCORE_EMBED_URL、UANCORE_EMBED_API_KEY	嵌入服务，配了由虹元把检索问句算成向量；不配只用关键字检索
UANCORE_EMBED_TIMEOUT_MS	等嵌入服务的时限，缺省 5000 毫秒

原件存本地目录时，安装与升级脚本会建好目录并放开服务的写权限。详见知识与制度库。

迁移台账

每个迁移文件在库里一行：文件名、指纹、时间、谁、耗时。安装与升级都先核对再执行：

情况	动作
文件在、台账无记录	执行，每个文件单事务，失败整份回滚
台账有记录、指纹一致	跳过
台账有记录、指纹不一致	停下报警，人工判断，不静默重灌
台账有记录、文件不在	警告部署包不完整

交付清单

缺一样都算没交完：安装脚本跑通且巡检退出码 0；台账条数等于迁移文件数；备份手跑一次成功且定时任务已挂；恢复到核对库演练一次；升级脚本空跑一次；环境文件权限 600 且没有未填项，管理密钥已交接给现场管理员；实例身份已填；智眸已配对且一条真告警进了事件表；HSE 已连接且八步闭环走通；同网段只有一套虹元在广播；日志保留量已限；机器时区正确。

相关文档

• 事件与遥测接入
• 控制台
• 常见问题