alexfalkowski/bezeichner Docker 镜像 - 轩辕镜像

Bezeichner 镜像文档

概述

Bezeichner 是一个专注于管理服务中标识符的工具镜像，旨在简化分布式系统和服务架构中标识符的生成、验证与维护流程。通过统一管理标识符生命周期，解决因标识符不一致或管理混乱导致的服务集成问题，确保跨服务标识符的一致性、唯一性和可靠性。

核心功能与特性

• 标识符生成：支持多种标准与自定义标识符格式（如 UUID、雪花算法 ID、业务自定义规则 ID 等），可按需生成符合规范的标识符。
• 标识符验证：提供标识符格式验证功能，支持预定义规则校验，避免非法标识符进入系统。
• 格式管理：允许通过配置定义和管理标识符格式规则，支持动态更新格式策略，适应不同业务场景需求。
• 集成能力：提供 REST API 接口，便于与微服务、API 网关等组件集成，支持 HTTP/HTTPS 通信协议。
• 轻量级设计：镜像体积小，资源占用低，可快速部署于容器化环境，兼容 Kubernetes 等编排工具。

使用场景

• 微服务架构：在微服务间数据交互中，统一管理服务实例标识符、请求 ID 等，确保追踪与溯源能力。
• 分布式系统：为分布式数据库、消息队列等组件生成全局唯一标识符，避免数据冲突。
• API 开发：为 API 请求、用户会话、资源标识等生成和验证标识符，提升接口安全性与可维护性。
• 数据同步场景：在跨系统数据同步过程中，管理实体标识符映射关系，确保数据一致性。

使用方法与配置说明

快速启动

通过以下命令启动 Bezeichner 容器：

bash
docker run -d -p 8080:8080 --name bezeichner-container bezeichner:latest

默认情况下，容器在 8080 端口提供 REST API 服务。

环境变量配置

支持通过环境变量进行基础配置，常用变量说明：

示例：使用自定义格式和文件存储启动：

bash
docker run -d \
  -p 8081:8080 \
  -e IDENTIFIER_FORMAT=CUSTOM \
  -e STORAGE_TYPE=FILE \
  -e LOG_LEVEL=DEBUG \
  -v ./data:/app/data \  # 挂载文件存储目录
  --name bezeichner-custom bezeichner:latest

配置文件使用

支持通过配置文件进行高级配置，配置文件路径为 /app/config.yaml，可通过挂载文件实现自定义配置。示例配置：

yaml
identifier:
  formats:
    custom:
      pattern: "SVC-{8}_{4}_{4}_{4}_{12}"  # 自定义格式模板
      checksum: true  # 启用校验和验证
api:
  cors:
    allowed-origins: "*"
storage:
  file:
    path: /app/data/identifiers.db  # 文件存储路径

启动时挂载配置文件：

bash
docker run -d \
  -p 8080:8080 \
  -v ./config.yaml:/app/config.yaml \
  --name bezeichner-config bezeichner:latest

API 使用示例

生成标识符

bash
curl http://localhost:8080/api/v1/identifiers/generate
# 响应示例：{"id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6", "format": "UUIDv4", "timestamp": "2024-05-20T10:30:00Z"}

验证标识符

bash
curl -X POST http://localhost:8080/api/v1/identifiers/validate \
  -H "Content-Type: application/json" \
  -d '{"id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6", "format": "UUIDv4"}'
# 响应示例：{"valid": true, "message": "Identifier is valid"}

注意事项

• 使用文件存储时，建议通过持久化卷挂载存储目录，避免容器重启导致数据丢失。
• 自定义标识符格式时，需确保规则唯一性，避免生成重复标识符。
• 生产环境建议启用 HTTPS 并配置访问控制，保护 API 接口安全。