Am Ops Observer

am操作观察员

Archivematica操作的Go服务有两个主要模块：

1. 正在运行的传输故障排除（接近实时）
2. 面向客户的KPI月度报告

PoC状态（重要）

该存储库目前是一个概念验证（PoC）：它演示了可能的功能和工作流程，但它不是一个生产强化部署。

当前假设/限制：

• 专为一体化Archivematica服务器布局而设计。
• 未针对多管道部署进行验证。
• 未针对分离/远程存储服务服务器拓扑进行验证。
• 在这个PoC阶段，跨主机网络/身份验证强化和规模调优不在范围内。
• 无身份验证/授权（无登录、无RBAC、无租户隔离）。
• 还没有API安全控制（应用程序中没有TLS终止，没有API令牌，没有速率限制）。
• 没有用于生成报告的后台作业队列/调度程序。
• 没有警报/通知策略集成。
• 应用程序拥有的SQLite数据没有迁移/版本控制工作流。
• 测试覆盖范围有限，主要集中在核心处理器上；目前还没有完整的端到端测试套件。
• 未来的工作：Keycloke/OIDC SSO集成（登录、会话处理、受保护路由和角色映射）。

安装软件包（DEB/RPM）

1） 安装软件包

Debian/Ubuntu：

sudo dpkg -i am-ops-observer__amd64.deb

RHEL/Rocky/Alma/Fedora：

sudo rpm -Uvh am-ops-observer-.x86_64.rpm

1.1）升级包

Debian/Ubuntu：

sudo dpkg -i am-ops-observer__amd64.deb

RHEL/Rocky/Alma/Fedora：

sudo rpm -Uvh am-ops-observer-.x86_64.rpm

1.2）卸载软件包

Debian/Ubuntu：

sudo dpkg -r am-ops-observer

RHEL/Rocky/Alma/Fedora：

sudo rpm -e am-ops-observer

2） 配置文件

编辑引导文件：

sudo editor /etc/default/am-ops-observer

编辑主非机密配置：

sudo editor /etc/am-ops-observer/config.env

编辑机密：

sudo editor /etc/am-ops-observer/secrets.env
sudo chmod 600 /etc/am-ops-observer/secrets.env

3） 启动服务

sudo systemctl daemon-reload
sudo systemctl enable --now am-ops-observer
sudo systemctl status am-ops-observer

4） 验证

curl -s http://127.0.0.1:8080/health | jq
curl -s http://127.0.0.1:8080/ready | jq
curl -s http://127.0.0.1:8080/metrics | head -n 40

配置快速参考（打包）

打包部署布局：

• Bootstrap文件： /etc/default/am-ops-observer
• 主要配置： /etc/am-ops-observer/config.env
• 机密文件： /etc/am-ops-observer/secrets.env

启动时配置加载顺序：

1. Bootstrap默认值来自 ./am-ops-observer.env 和 /etc/default/am-ops-observer
2. 来自的主要非秘密配置 APP_CONFIG_FILE （如果设置），否则 /etc/am-ops-observer/config.env
3. 秘密来自 APP_SECRETS_FILE （如果已设置），否则为systemd凭据目录(%d/app-secrets)，否则 /etc/am-ops-observer/secrets.env
4. 实际过程环境变量（最高优先级）

配置（所有选项）

必需选项与可选选项

传说：

• Required：必须为预期行为明确设置。
• Conditional：仅在启用功能时才需要。
• Optional：具有安全默认值。

引导和文件路径选项

HTTP服务选项

MCP数据库选项（只读）

应用SQLite选项

存储服务数据库选项（只读）

普罗米修斯选项

Elasticsearch选项（只读）

AIP风险阈值选项

范围

该项目将AM/SS/MySQL/Elasticsearch（以及可选的Prometheus）的传输见解集中到一个API+UI中。

重要模式：

• 对Archivematica系统（MCP MySQL、存储服务数据库、Elasticsearch）只读。
• 不写入MCP MySQL。
• 不写入存储服务数据库。
• 没有对Elasticsearch的写入。
• 应用程序拥有的持久性（报告模板和客户映射）可以存储在本地SQLite中。

故障排除模块

• 运行传输列表，包括阶段、已用时间和卡住指示器
• 传输时间线和错误钻取
• 源连接健康状况（AM、SS、MySQL、ES、Prometheus）

报告模块

• 每月转账总额（成功/失败）
• 持续时间关键绩效指标（平均值/p50/p95）
• 文件总计（总计/原始/标准化）
• 可配置的临时传输报告（过滤器+列+CSV导出）
• 在SQLite应用中保存报告模板

当前状态

主要终点：

• GET /health
• GET /ready
• GET /metrics （此应用程序的普罗米修斯展览）
• GET /api/v1/metrics/app （UI使用的轻量级应用指标摘要）
• GET /api/v1/transfers/running?limit=50
• GET /api/v1/sips/running?limit=50
• GET /api/v1/transfers/completed?limit=50
• GET /api/v1/transfers/{transfer_uuid}/summary
• GET /api/v1/transfers/{transfer_uuid}/details?limit=100
• GET /api/v1/transfers/{transfer_uuid}/timeline?limit=200
• GET /api/v1/transfers/{transfer_uuid}/errors?limit=100
• GET /api/v1/troubleshooting/stalled?limit=50
• GET /api/v1/troubleshooting/hotspots?unit=transfer|sip&hours=24&limit=20
• GET /api/v1/troubleshooting/failure-counts?hours=24
• GET /api/v1/transfers/failed?hours=24&limit=30
• GET /api/v1/troubleshooting/failure-signatures?hours=24&limit=30
• GET /api/v1/reports/monthly?customer_id=acme&month=2026-02
• GET /api/v1/charts/transfer-durations?customer_id=acme&month=2026-02
• POST /api/v1/reports/query （可配置的即席报告运行）
• GET /api/v1/reports/query/options
• GET /api/v1/reports/templates
• POST /api/v1/reports/templates
• GET /api/v1/reports/templates/{id}
• DELETE /api/v1/reports/templates/{id}
• GET /api/v1/reports/customers?limit=100
• GET /api/v1/reports/customer-mappings/{customer_id}
• GET /api/v1/metrics/prometheus/live?match=archivematica_
• GET /api/v1/charts/prometheus?target=&metric=&minutes=60
• GET /api/v1/status/services
• GET /api/v1/status/customer-mapping
• GET /api/v1/aips?limit=60&cursor=
• GET /api/v1/aips/{aip_uuid}/stats
• GET /api/v1/aips/{aip_uuid}/storage-service

当前行为：

• 在以下情况下，MySQL支持故障排除端点 APP_DB_ENABLED=true.
• 月度报告端点由MySQL支持，返回真实的KPI+每日时间序列。
• 客户映射端点是只读的。SQLite映射后端在以下情况下使用 APP_CUSTOMER_MAP_SQLITE_PATH 已设置。
• 当以下情况发生时，报告模板将持久化在应用程序SQLite中 APP_CUSTOMER_MAP_SQLITE_PATH 已设置。
• UI包括概述、失败传输、服务状态、AIP和可配置报告选项卡。
• 如果禁用DB，则返回DB支持的端点 503 带有明确的信息。

月报过滤注意事项

• month 格式： YYYY-MM
• 特殊值 all/default/空禁用客户筛选
• 首选过滤模式：SQLite客户映射(APP_CUSTOMER_MAP_SQLITE_PATH)
• 回退模式（如果未配置映射后端）： Transfers.sourceOfAcquisition = customer_id
• API在中返回活动模式 meta.customer_filter_mode

指标

• /metrics 导出Prometheus格式的应用程序指标。
• 包括HTTP请求计数和持续时间、正在进行的请求、数据库查询持续时间和连接器/操作的错误计数器、外部探测持续时间和错误计数器、报告运行计数/持续时间和运行时指标（正常运行时间、goroutines、内存、GC、CPU、进程IO）。
• /api/v1/metrics/app 提供了一个紧凑的JSON摘要，供“服务”选项卡使用（最慢的HTTP端点、最慢的DB操作、聚合错误计数器）。

在本地运行（开发）

需求

• 转到1.21+

开始

go run ./cmd/api

测试

go test ./...

尝试端点

curl -s http://localhost:8080/health | jq
curl -s http://localhost:8080/metrics | head -n 40
curl -s http://localhost:8080/api/v1/metrics/app | jq

架构（v1）

• cmd/api：应用程序入口点
• internal/config：运行时配置（环境驱动）
• internal/http：HTTP服务器和处理程序
• internal/connectors/mysql：用于故障排除/报告查询的MySQL连接器
• internal/realtime （下一篇）：业务逻辑层故障排查
• internal/reporting （下一篇）：专用报表聚合层

包装和发布

此项目包括与以下内容相同的发布结构 csp-web-checker-golang:

• .github/workflows/tests.yml CI测试
• .github/workflows/release.yml 对于经过semver验证的版本
• .github/actions/validate-semver/action.yml 共享semver验证操作
• .goreleaser.yml 用于二进制+tar.gz+DEB/RPM构建
• packaging/nfpm/*.sh 包生命周期脚本
• packaging/default/am-ops-observer 最小 /etc/default 独自创立
• packaging/default/am-ops-observer-config.env 主非秘密配置文件
• packaging/default/am-ops-observer-secrets.env 机密模板文件
• systemd/am-ops-observer.service 系统单位

许可证

• LICENSE：GNU Affero通用公共许可证v3（AGPL-3.0）

下一个里程碑

1. 添加auth/RBAC和用户范围的报告视图。
2. 添加导出端点（CSV/PDF），包括SS包/位置快照。
3. 为繁重的月度报告聚合添加缓存。