ghga/ifrs

内部文件注册服务

本服务作为内部文件位置和表示的注册中心。

描述

该服务提供管理存储在S3兼容对象存储中的文件的功能。所有文件相关元数据存储在由本服务拥有和控制的内部MongoDB数据库中。它不暴露REST API端点，而是通过事件与其他服务通信。

消费的事件：

files_to_register

此事件表示需要在数据库中注册文件。事件中的文件元数据将被保存到数据库，文件从传入暂存桶移动到永久存储。

files_to_stage

此事件表示需要暂存文件以供下载。文件将从永久存储复制到出站箱以进行实际下载。

发布的事件：

file_internally_registered

文件在数据库中注册后发布此事件，包含files_to_register事件提供的所有文件元数据。

file_staged_for_download

文件成功暂存到出站箱后发布此事件。

安装

我们建议使用提供的Docker容器。

预构建版本可在Docker Hub获取：

bash
docker pull docker.xuanyuan.run/ghga/internal-file-registry-service:7.4.0

或从./Dockerfile自行构建容器：

bash
# 在仓库根目录执行：
docker build -t ghga/internal-file-registry-service:7.4.0 .

对于生产级部署，建议使用Kubernetes；对于简单场景，可在单台服务器上通过Docker运行服务：

bash
# 入口点已预配置：
docker run -p 8080:8080 docker.xuanyuan.run/ghga/internal-file-registry-service:7.4.0 --help

若不使用容器，可从源码安装服务：

bash
# 在仓库根目录执行：
pip install .

# 运行服务：
ifrs --help

配置

参数

服务需要以下配置参数：

• enable_opentelemetry（布尔值）：若为true，运行必要的设置代码；若为false，不运行设置代码（跟踪功能禁用）。默认值：false。
• otel_trace_sampling_rate（数字）：确定应采样的跨度比例。1.0表示全部，0表示无采样。范围：0~1。默认值：1.0。
• log_level（字符串）：捕获的最低日志级别，可选值："CRITICAL"、"ERROR"、"WARNING"、"INFO"、"DEBUG"、"TRACE"。默认值："INFO"。
• service_name（字符串）：默认值："ifrs"。
• service_instance_id（字符串，必填）：唯一标识本服务实例的字符串，用于生成全局唯一的Kafka客户端ID。示例："germany-bw-instance-001"。
• log_format：替换JSON格式的日志字符串，可选参数。示例："%(timestamp)s - %(service)s - %(level)s - %(message)s"。
• log_traceback（布尔值）：日志消息是否包含异常回溯。默认值：true。
• object_storages（对象，必填）：包含S3对象存储节点配置的对象。
• file_upload_topic（字符串，必填）：包含FileUpload出站事件的主题。示例："file-uploads"。
• file_internally_registered_topic（字符串，必填）：用于表示文件已注册的事件主题。示例："file-registrations"。
• file_internally_registered_type（字符串，必填）：文件注册事件的类型。示例："file_internally_registered"。
• file_deleted_topic（字符串，必填）：用于表示文件已删除的事件主题。示例："file-deletions"。
• file_deleted_type（字符串，必填）：文件删除事件的类型。示例："file_deleted"。
• file_staged_topic（字符串，必填）：用于表示文件已暂存的事件主题。示例："file-stagings"。
• file_staged_type（字符串，必填）：文件暂存事件的类型。示例："file_staged_for_download"。
• file_deletion_request_topic（字符串，必填）：接收文件删除请求事件的主题。示例："file-deletion-requests"。
• file_deletion_request_type（字符串，必填）：文件删除请求事件的类型。示例："file_deletion_requested"。
• files_to_stage_topic（字符串，必填）：接收文件暂存请求事件的主题。示例："file-staging-requests"。
• files_to_stage_type（字符串，必填）：文件暂存请求事件的类型。示例："file_staging_requested"。
• kafka_servers（数组，必填）：Kafka引导服务器的连接字符串列表。示例：["localhost:9092"]。
• kafka_security_protocol（字符串）：与 broker 通信的协议，可选值：PLAINTEXT、SSL。默认值："PLAINTEXT"。
• kafka_ssl_cafile（字符串）：CA证书文件路径。默认值：""。
• kafka_ssl_certfile（字符串）：客户端证书文件路径。默认值：""。
• kafka_ssl_keyfile（字符串）：客户端私钥文件路径。默认值：""。
• kafka_ssl_password（字符串，密码格式）：客户端私钥密码。默认值：""。
• generate_correlation_id（布尔值）：是否自动生成关联ID。默认值：true。
• kafka_max_message_size（整数）：压缩前可传输的最大消息大小（字节）。默认值：1048576。
• kafka_compression_type：消息压缩类型，可选值：gzip、snappy、lz4、zstd或null。默认值：null。
• kafka_max_retries（整数）：事件消费失败后的最大重试次数。默认值：0。
• kafka_enable_dlq（布尔值）：是否启用死信队列。默认值：false。
• kafka_dlq_topic（字符串）：死信队列主题名称。默认值："dlq"。
• kafka_retry_backoff（整数）：重试前等待的秒数。默认值：0。
• mongo_dsn（字符串，必填）：MongoDB连接字符串。示例："mongodb://localhost:27017"。
• db_name（字符串，必填）：MongoDB服务器上的数据库名称。示例："my-database"。
• mongo_timeout：MongoDB API调用超时（秒），可选值为整数或null。默认值：null。
• db_version_collection（字符串，必填）：存储服务DB版本信息的集合名称。示例："ifrsDbVersions"。
• migration_wait_sec（整数，必填）：再次检查DB版本前的等待秒数。示例：5。
• migration_max_wait_sec：迁移完成前的最大等待秒数，可选值为整数或null。默认值：null。

定义

• S3Config：S3服务配置参数，包含s3_endpoint_url、s3_access_key_id、s3_secret_access_key等必填项。
• S3ObjectStorageNodeConfig：对象存储节点配置，包含bucket和credentials（S3Config类型）。

使用

配置服务的模板YAML可在./example-config.yaml找到。请适配后重命名为.ifrs.yaml，并放置在以下位置之一：

• 执行服务的当前工作目录（Linux：./.ifrs.yaml）
• 主目录（Linux：~/.ifrs.yaml）

服务将自动解析该配置文件。注意：若使用容器，路径指容器内的路径。

所有参数也可通过环境变量或文件密钥设置。环境变量命名规则为ifrs_前缀（如ifrs_host），大小写均可。

架构与设计

这是一个基于Python的服务，遵循Triple Hexagonal Architecture模式，使用hexkit库提供的协议/提供者对和依赖注入机制。

开发

开发环境依赖VS Code的devcontainer功能和Docker Compose。需安装Docker Compose及VS Code的"Remote - Containers"扩展，打开仓库后运行Remote-Containers: Reopen in Container命令即可获得预配置的开发环境。

许可证

本仓库根据Apache 2.0 License免费使用和修改。

README生成

本README文件为自动生成，详情见readme_generation.md。