folioorg/okapi

FOLIO - okapi 镜像文档

镜像概述

本镜像包含FOLIO（图书馆开源服务平台）项目的核心组件Okapi及其基础模块。Okapi作为FOLIO生态的核心，负责FOLIO系统的模块生命周期管理、服务协调及API请求路由，是构建和运行FOLIO图书馆服务平台的基础组件。

主要用途

用于部署FOLIO平台的核心服务框架，实现对FOLIO模块的注册、部署、启用/禁用、版本控制等全生命周期管理，并作为API网关处理客户端与FOLIO模块间的请求路由和通信。

核心功能与特性

核心功能

• 模块管理：支持FOLIO模块的注册、部署、升级及版本控制，管理模块间依赖关系。
• API网关：提供统一API入口，处理请求路由、认证授权及请求转发。
• 服务编排：协调多模块服务的发现、注册与负载均衡，确保系统组件协同工作。
• 租户隔离：支持多租户模式，为不同机构提供独立的模块配置与服务实例。

关键特性

• 轻量级微服务架构，适配云原生部署环境
• 兼容FOLIO标准模块规范，支持第三方模块集成
• 内置健康检查与监控接口，便于系统运维
• 支持动态模块加载，无需重启即可更新服务

使用场景与适用范围

使用场景

• 构建FOLIO图书馆服务平台的基础架构层
• 管理FOLIO模块的部署与运行状态
• 实现图书馆业务系统（如 circulation、inventory）的服务集成
• 为客户端应用（如FOLIO UI）提供统一API访问入口

适用范围

• 图书馆、学术机构及需要部署FOLIO开源图书馆服务平台的组织
• FOLIO平台开发者用于本地开发、测试及生产环境部署
• 需要扩展或定制FOLIO功能的技术团队

使用方法与配置说明

基本部署（Docker Run）

最简启动命令

bash
docker run -d --name okapi -p 9130:9130 folioorg/okapi

• -p 9130:9130：映射Okapi默认端口9130（API通信端口）到主机
• 默认启动Okapi核心服务，可通过 http://localhost:9130 访问API

自定义配置示例

通过环境变量调整运行参数：

bash
docker run -d --name okapi \
  -p 8080:8080 \
  -e OKAPI_PORT=8080 \
  -e OKAPI_ENV=prod \
  -e OKAPI_LOG_LEVEL=DEBUG \
  -v okapi-data:/var/lib/okapi \
  folioorg/okapi

• OKAPI_PORT：自定义服务端口（默认9130）
• OKAPI_ENV：运行环境（dev/test/prod，默认dev）
• OKAPI_LOG_LEVEL：日志级别（INFO/DEBUG/WARN/ERROR，默认INFO）
• -v okapi-data:/var/lib/okapi：挂载数据卷持久化模块配置与状态

Docker Compose 部署示例

适用于多模块协同部署场景，以下为基础配置模板：

yaml
version: '3'
services:
  okapi:
    image: folioorg/okapi
    ports:
      - "9130:9130"
    environment:
      - OKAPI_ENV=prod
      - OKAPI_LOG_LEVEL=INFO
      - DB_HOST=postgres  # 若需数据库支持，配置数据库地址
    volumes:
      - okapi-data:/var/lib/okapi
    depends_on:
      - postgres  # 依赖PostgreSQL时添加
    restart: unless-stopped

  postgres:  # 可选：Okapi元数据存储（需额外配置数据库连接）
    image: postgres:13
    environment:
      - POSTGRES_DB=okapi
      - POSTGRES_USER=folio
      - POSTGRES_PASSWORD=folio123
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  okapi-data:
  postgres-data:

模块管理与API使用

Okapi通过REST API管理模块，核心操作示例：

1. 注册模块（需模块描述文件URL）：

   bash
   curl -X POST http://localhost:9130/_/proxy/modules \
     -H "Content-Type: application/json" \
     -d '{"id": "mod-users-1.0.0", "url": "https://folio-registry.dev.folio.org/modules/mod-users/1.0.0"}'
   

2. 部署模块实例：

   bash
   curl -X POST http://localhost:9130/_/discovery/modules/mod-users-1.0.0/instances \
     -H "Content-Type: application/json" \
     -d '{"instanceId": "mod-users-001", "url": "http://mod-users:8081"}'
   

3. 启用模块（租户级）：

   bash
   curl -X POST http://localhost:9130/_/proxy/tenants/demo/modules/mod-users-1.0.0
   

详细API文档及模块管理流程参见 FOLIO Okapi官方文档。

代码仓库

获取最新版本、源码及详细配置说明，请访问：
https://github.com/folio-org/okapi