daschswiss/knora-api

Knora-API 镜像文档

镜像概述

Knora-API 镜像为 Knora 数字人文框架（Knora Framework）的官方 API 服务组件，封装了 Knora 后端的 API 服务模块，提供标准化接口以支持数字人文研究数据的全生命周期管理。该镜像简化了 Knora API 服务的部署流程，可快速集成至现有数字人文平台或作为独立服务提供数据访问能力。

核心功能与特性

• 标准化 REST API：遵循 OpenAPI 规范，提供一致的资源访问接口，支持数据查询、创建、更新及删除操作。
• 数字人文数据模型支持：兼容 Knora 自定义数据模型（Ontologies），支持复杂人文数据结构（如文本、图像、时空数据）的建模与查询。
• 元数据管理：内置元数据处理机制，支持 Dublin Core、MODS 等人文领域常用元数据标准，实现数据描述的规范化。
• 权限与访问控制：集成认证授权功能，支持基于角色的访问控制（RBAC），确保敏感研究数据的安全访问。
• 跨格式数据兼容：支持常见数字人文数据格式（TEI XML、IIIF 图像、RDF 三元组等）的解析与输出，便于跨平台数据交换。
• 日志与监控：提供详细操作日志，支持集成外部监控工具，便于服务状态跟踪与问题排查。

使用场景与适用范围

• 学术机构数字人文平台：高校或研究机构搭建本地数字人文数据管理平台，通过 API 向师生提供数据集访问。
• 文化遗产机构数据共享：博物馆、档案馆等通过 API 开放数字藏品数据，支持外部应用（如数字展览、学术研究）调用。
• 跨机构协作研究：多团队联合开展人文研究时，通过统一 API 实现研究数据的实时同步与共享。
• 教学实践：数字人文课程中作为教学工具，演示研究数据的标准化管理与 API 交互流程。

使用方法与配置说明

4.1 基本部署（Docker Run）

通过 docker run 命令快速启动 Knora-API 服务：

bash
docker run -d \
  --name knora-api \
  -p 8080:8080 \
  -e DB_HOST=postgresql-host \
  -e DB_PORT=5432 \
  -e DB_NAME=knora \
  -e DB_USER=knora_user \
  -e DB_PASSWORD=secure_password \
  -e JWT_SECRET=your-jwt-secret \
  -v ./knora-data:/app/data \
  docker.xuanyuan.run/knora/knora-api:latest

4.2 Docker Compose 配置示例

创建 docker-compose.yml 实现多容器协同（含数据库）：

yaml
version: '3.8'
services:
  knora-api:
    image: docker.xuanyuan.run/knora/knora-api:latest
    container_name: knora-api
    ports:
      - "8080:8080"
    environment:
      - DB_HOST=knora-db
      - DB_PORT=5432
      - DB_NAME=knora
      - DB_USER=knora_user
      - DB_PASSWORD=secure_password
      - JWT_SECRET=your-jwt-secret
      - LOG_LEVEL=INFO
    volumes:
      - knora-data:/app/data
    depends_on:
      - knora-db
    restart: unless-stopped

  knora-db:
    image: docker.xuanyuan.run/postgres:14
    container_name: knora-db
    environment:
      - POSTGRES_DB=knora
      - POSTGRES_USER=knora_user
      - POSTGRES_PASSWORD=secure_password
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  knora-data:
  postgres-data:

4.3 环境变量配置

Knora-API 镜像支持以下关键环境变量进行配置：

4.4 数据持久化

通过挂载卷（如示例中的 -v ./knora-data:/app/data）持久化存储 Knora 配置文件、日志及临时数据，避免容器重启后数据丢失。

4.5 API 访问验证

服务启动后，可通过 http://localhost:8080/api/health 验证 API 服务状态，返回 200 OK 表示服务正常运行。完整 API 文档可访问 http://localhost:8080/api/docs（基于 OpenAPI 规范）。

注意事项

• 首次启动需确保数据库已初始化，镜像通常内置数据库迁移脚本自动完成表结构创建。
• 生产环境中需替换默认 JWT_SECRET 为高强度密钥，并限制 CORS_ALLOWED_ORIGINS 以增强安全性。
• 高并发场景下建议配置外部反向代理（如 Nginx）进行负载均衡，并调整数据库连接池参数。