ghga/ucs

上传控制器服务

用于管理向S3收件箱存储桶的上传操作。

描述

该服务的详细文档将很快提供（链接待补充）。

安装

我们推荐使用提供的Docker容器。预构建版本可在Docker Hub获取：

bash
docker pull docker.xuanyuan.run/ghga/upload-controller-service:15.2.0

或从项目根目录的./Dockerfile自行构建容器：

bash
# 在项目根目录执行：
docker build -t ghga/upload-controller-service:15.2.0 .

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

bash
# 入口已预配置：
docker run -p 8080:8080 docker.xuanyuan.run/ghga/upload-controller-service:15.2.0 --help

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

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

# 运行服务：
ucs --help

配置

参数

服务需要以下配置参数：

• file_deletion_request_topic（字符串，必填）：接收文件删除请求事件的主题名称。 示例："file-deletion-requests"
• file_deletion_request_type（字符串，必填）：表示收到文件删除请求事件的类型。 示例："file_deletion_requested"
• file_internally_registered_topic（字符串，必填）：用于发布文件注册下载事件的主题名称。 示例："file-registrations"、"file-registrations-internal"
• file_internally_registered_type（字符串，必填）：表示文件已注册下载事件的类型。 示例："file_internally_registered"
• file_interrogations_topic（字符串，必填）：用于发布文件验证结果事件的主题名称。 示例："file-interrogations"
• interrogation_success_type（字符串，必填）：表示文件验证成功事件的类型。 示例："interrogation_success"
• interrogation_failure_type（字符串，必填）：表示文件验证失败事件的类型。 示例："interrogation_failed"
• enable_opentelemetry（布尔值）：是否启用OpenTelemetry追踪，默认false。
• otel_trace_sampling_rate（数字）：追踪采样率（0-1），默认1.0。
• log_level（字符串）：日志级别，可选值："CRITICAL"、"ERROR"、"WARNING"、"INFO"、"DEBUG"、"TRACE"，默认"INFO"。
• service_name（字符串）：服务名称，默认"ucs"。
• service_instance_id（字符串，必填）：服务实例唯一标识。 示例："germany-bw-instance-001"
• log_format：日志格式字符串或null，默认null。 示例："%(timestamp)s - %(service)s - %(level)s - %(message)s"
• log_traceback（布尔值）：是否在日志中包含异常堆栈，默认true。
• object_storages（对象，必填）：对象存储配置，参考S3ObjectStorageNodeConfig。
• kafka_servers（数组，必填）：Kafka bootstrap服务器列表。 示例：["localhost:9092"]
• kafka_security_protocol（字符串）：Kafka通信协议，可选"PLAINTEXT"或"SSL"，默认"PLAINTEXT"。
• mongo_dsn（字符串，必填）：MongoDB连接字符串。 示例："mongodb://localhost:27017"
• db_name（字符串，必填）：MongoDB数据库名称。 示例："my-database"
• file_upload_topic（字符串，必填）：文件上传事件主题名称。 示例："file-uploads"
• host（字符串）：服务绑定IP，默认"127.0.0.1"。
• port（整数）：服务端口，默认8080。

（注：完整参数列表请参考原始文档，此处仅列出核心参数）

定义

• AuthConfig：认证配置对象，包含auth_key（必填）、auth_algs等参数。
• S3Config：S3存储配置对象，包含s3_endpoint_url（必填）、s3_access_key_id（必填）等参数。
• S3ObjectStorageNodeConfig：对象存储节点配置，包含bucket（必填）和credentials（参考S3Config）。

使用

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

• 服务执行目录（Linux：./.ucs.yaml）
• 用户主目录（Linux：~/.ucs.yaml）

容器化部署时，路径指容器内部路径。所有参数也可通过环境变量（前缀ucs_）或文件密钥设置。

HTTP接口

该服务的OpenAPI规范可在此处找到。

架构与设计

这是一个基于Python的服务，遵循三重六边形架构模式，使用hexkit库提供的协议/提供者对和依赖注入机制。

开发

开发环境依赖VS Code的DevContainer功能和Docker Compose。具体步骤：

1. 安装Docker Compose和VS Code的"Remote - Containers"扩展。
2. 在VS Code中打开仓库，执行"Remote-Containers: Reopen in Container"命令。
3. 开发容器内提供预配置的依赖、扩展和调试工具。

许可证

本仓库遵循Apache 2.0许可证。

README生成

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