timoreymann/schemanest-cli

SchemaNest

镜像概述和主要用途

SchemaNest是一个轻量级JSON模式管理解决方案，旨在简化团队对JSON模式的管理流程。它包含两个核心组件：CLI工具（用于从命令行上传模式）和Registry服务（提供中央存储库和Web界面），支持模式的上传、版本控制、浏览与搜索，适用于需要集中管理JSON模式的开发团队。

核心功能和特性

• 模式管理：支持JSON模式的上传和版本控制，确保模式变更可追踪
• Web界面：提供直观的Web界面，方便浏览和搜索已存储的模式
• CLI工具：通过命令行工具快速上传模式，集成到CI/CD流程
• 无障碍支持：默认支持屏幕阅读器，确保视觉障碍用户可访问
• 灵活配置：支持数据库配置、上传认证控制和API密钥管理

使用场景和适用范围

• 团队协作管理JSON模式，确保开发一致性
• API开发中集中管理请求/响应数据结构定义
• 前端表单验证规则的版本化管理
• 需要追踪模式变更历史的场景
• 小型到中型团队的模式管理需求（SQLite适用于评估，Postgres适合生产环境）

安装与使用方法

CLI组件

Docker方式

sh
docker run --rm -it -v $PWD:/workspace:ro -w /workspace \
  timoreymann/schemanest-cli schema-nest-cli \
  --help

基本使用

查看帮助信息：

sh
docker run --rm timoreymann/schemanest-cli schema-nest-cli --help

Registry组件

使用docker-compose部署

1. 创建配置文件config.toml：

   toml
   # 数据库连接字符串（生产环境推荐Postgres）
   database_dsn = "postgres://schema-nest:schema-nest@db/schema-nest"
   
   # 启用上传认证
   enable_upload_authentication = true
   
   # API密钥配置
   [[api_keys]]
   identifier = "frontend"
   # 请设置为安全的密钥（UUID、哈希等）
   key = "my-super-secret-api-key"
   patterns = [
     # 允许所有以@frontend/为前缀的模式
     "@frontend/*",
     # 允许特定模式mjml-config
     "mjml-config"
   ]
   

2. 创建docker-compose.yaml：

   yaml
   services:
     registry:
       image: timoreymann/schemanest-registry
       command:
         - schema-nest-registry
         - serve-http
         - -C
         - /etc/SchemaNest/config.toml
       volumes:
         - ./config.toml:/etc/SchemaNest/config.toml
       ports:
         - 8080:8080
     db:
       image: postgres:15-alpine
       environment:
         POSTGRES_DB: schema-nest
         POSTGRES_USER: schema-nest
         POSTGRES_PASSWORD: schema-nest
       volumes:
         - schema-nest-db-data:/var/lib/postgresql/data
       restart: always
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
         interval: 5s
         timeout: 5s
         retries: 5
   volumes:
     schema-nest-db-data:
   

3. 启动服务：

   sh
   docker compose up
   

4. 访问Web界面：http://localhost:8080

基本使用

启动Registry服务（默认端口8080）：

sh
docker run --rm -v ./config.toml:/etc/SchemaNest/config.toml timoreymann/schemanest-registry \
  schema-nest-registry serve-http -C /etc/SchemaNest/config.toml --port "8080"

配置说明

核心配置参数（config.toml）

• database_dsn：数据库连接字符串（Postgres用于生产，SQLite用于评估）
• enable_upload_authentication：是否启用上传认证（true/false）
• api_keys：API密钥列表，包含：
  • identifier：密钥标识符
  • key：实际密钥值（需保密）
  • patterns：允许访问的模式匹配规则列表

API文档

API定义基于OpenAPI 3.0，最新规范可在项目仓库的https://github.com/timo-reymann/SchemaNest/blob/main/openapi.yml%E4%B8%AD%E8%8E%B7%E5%8F%96%E3%80%82%E5%9C%A8%E7%BA%BFRedocly UI文档可访问https://timo-reymann.github.io/SchemaNest/apidocs.html%EF%BC%88%E5%BC%80%E5%8F%91%E7%89%88%E6%9C%AC%EF%BC%89%E3%80%82

API变更保持向后兼容，建议客户端代码能处理额外字段。