koralabs/handles-api

Handles去中心化公共API

镜像概述和主要用途

Handles去中心化公共API通过Ogmios扫描节点的Handles相关交易，将信息存储在自定义内存索引中以支持快速读取。该API每日生成索引快照，容器启动时加载快照以减少加载时间，主要用于提供网络中Handles相关数据的查询服务。

核心功能和特性

• 交易扫描：使用Ogmios扫描***节点的Handles相关交易
• 快速读取：信息存储在自定义内存索引中，实现高效数据访问
• 快照机制：每日生成索引快照，容器启动时加载快照以加速初始化
• 数据持久化：支持通过卷挂载持久化存储***节点数据库和Handles扫描进度
• 灵活部署：可独立运行（包含节点）或配合外部节点（ogmios-only模式）
• 状态监控：提供健康检查端点和Swagger文档，便于API测试和状态监控

使用场景和适用范围

适用于需要访问***网络中Handles相关数据的开发者和应用，可作为Handles数据查询的后端服务，支持主网及测试网（Preview、PreProd）环境，满足Handles交易数据检索、状态查询等需求。

详细的使用方法和配置说明

前提条件

• 安装Docker（参考：Docker官方安装文档）

基本运行方法（包含***节点）

sh
docker pull koralabs/handles-api
docker run -p 3141:3141 -v db:/db -v handles:/app/handles koralabs/handles-api

• 卷挂载说明：-v db:/db 和 -v handles:/app/handles 用于持久化***节点数据库和Handles扫描进度，建议保留以避免容器停止后数据丢失。
• 节点Socket映射：可通过 -v <path_to_socket_folder>:/ipc 将节点socket文件夹映射到容器，使***节点可被容器外其他应用使用。

配合现有***节点运行（ogmios-only模式）

若已在外部运行***节点，可使用ogmios-only模式：

sh
docker pull koralabs/handles-api
docker run -p 3141:3141 -v <path_to_node.socket_folder>:/ipc -v handles:/app/handles -e MODE=ogmios koralabs/handles-api:latest

• 替换 <path_to_node.socket_folder> 为主机上包含 node.socket 文件的ipc文件夹路径。

API测试与监控

• Swagger文档：访问 http://localhost:3141/swagger 查看API接口文档
• 健康检查：访问 http://localhost:3141/health 查看服务状态
  ⚠️ 警告：健康端点返回 202 表示服务运行中但尚未同步到链尖，返回 200 后方可正常使用API结果。

环境变量配置

• MODE=ogmios：启用ogmios-only模式，配合外部***节点运行
• NETWORK=preview 或 NETWORK=preprod：指定测试网环境（默认为主网）

注意事项

• 初始化时间：首次运行时下载***节点快照和Ogmios扫描可能需要数小时。
• 内存要求：
  • 标准模式（含***节点）：最低16GB RAM，推荐20GB
  • ogmios-only模式：最低4GB RAM，推荐8GB
• 优雅关闭：容器支持***节点优雅关闭，若需手动关闭，建议执行：

  sh
  kill -SIGINT $(pidof cardano-node)
  

  （在主机或容器内执行），以优化后续启动加载速度。