文档 on gobrave - 生物信息学分析平台

快速开始

Wed, 12 Aug 2026 00:00:00 +0800

概述

本文帮助你在几分钟内本地启动 gobrave，使用默认 Go 服务入口。

前置条件

Go 1.25 或更高版本
可访问数据库：SQLite（默认）、MySQL 或 PostgreSQL
若需要容器化分析运行时，请准备 Docker、k8s 或 k3s

1. 克隆并进入项目

1
2


git clone https://github.com/gobravedev/gobrave.git
cd gobrave

2. 创建运行配置

1

cp config.example.yml config.yml

至少请确认：

database.*
container.runtime
storage.base_dir（可选但建议设置）

3. 启动服务

1

go run ./cmd/server

默认监听：

配置说明

Wed, 12 Aug 2026 00:00:00 +0800

概述

gobrave 配置加载遵循“默认值 -> config.yml -> CLI 覆盖”的合并顺序。

解析优先级

配置优先级如下：

程序内置默认值
config.yml
CLI 参数（如 --port、--db-driver、--runtime）

配置文件位置

启动时配置路径解析顺序：

--config CLI 参数
对 config.yml 的外部路径解析

核心配置段

`server`

1
2
3
4


server:
 host: 0.0.0.0
 port: 8082
 log_path: logs/server.log

`database`

1
2
3
4
5
6
7
8
9


database:
 driver: sqlite # sqlite | mysql | postgres
 host: 127.0.0.1
 port: "5432"
 user: postgres
 password: ""
 name: postgres
 ssl_mode: disable
 path: "" # sqlite 使用

`container`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


container:
 runtime: docker # docker | k8s | k3s
 kubernetes:
 namespace: default
 kubeconfig: ""
 in_cluster: false
 refresh_image_status_on_start: true
 recover_running_dag_on_start: true
 cleanup_dag_node_containers_before_start: true
 delete_container_on_node_success: true
 dag_node_cleanup_on_failed: stop
 dag_node_cleanup_on_dag_finished: delete
 create_queue_max_concurrency: 3
 create_queue_max_pending: 50

`route`

route.registry 用于控制路由注册策略：

系统架构

Wed, 12 Aug 2026 00:00:00 +0800

概述

gobrave 是一个模块化的 Go 后端，核心围绕项目级生信工作流、数据资产与容器化执行。

高层组件

flowchart TD
 UI[Web / API 客户端] --> API[GIN Router + Handlers]
 API --> APP[应用服务层]
 APP --> DOM[领域管理层]
 DOM --> RT[容器运行时注册表]
 DOM --> REPO[仓储层]
 REPO --> DB[(MySQL/Postgres/SQLite)]

 APP --> BUS[内存事件总线]
 BUS --> WK[Outbox 分发器 + Workers]
 WK --> RT

启动期组装

服务启动时会构建依赖注入容器并完成接线：

配置加载器
数据库连接
仓储实现
领域 manager/service
容器运行时注册表
Router 与 Handler

该模式既保证单可执行部署，又保留模块替换能力。

关键子系统

API 层

Gin Router 按领域注册路由（auth、project、data、workflow、container、store）
API 版本前缀：/api/v1

数据与领域层

基于 GORM 的仓储持久化
明确的所有权边界：project、dataset、sample、file、workflow、analysis

容器运行时层

运行时抽象支持：docker、k8s、k3s
将运行时事件统一映射为稳定的容器生命周期状态

事件与异步执行层

内存事件总线用于领域事件分发
Outbox + Worker 模式提供可恢复的异步生命周期执行

实时通信层

支持 ws 和 sse 两种传输
支持每用户连接上限与 ACK 重试控制

请求到执行路径

客户端调用 API。
Handler 校验并调用 service/manager。
Service 持久化状态变更。
异步操作写入 outbox。
Worker 执行运行时操作并回发事件。
Manager 对账状态并推送实时更新。

设计目标

单二进制部署，降低运维摩擦
运行时无关的容器生命周期管理
借助对账与持久化 outbox 保障重启安全
项目中心化数据模型，适配 DAG 工作流执行

容器管理

Wed, 12 Aug 2026 00:00:00 +0800

概述

gobrave 通过统一的容器管理模型，支撑交互式应用会话与工作流运行任务。

运行时后端

通过 container.runtime 配置：

docker
k8s
k3s

运行时选择由容器运行时注册表统一解析。

主要实体

容器镜像：镜像元数据与拉取策略
容器模板：可复用启动定义
App Session：基于模板创建的用户会话环境
容器实例：运行时生命周期状态记录
Outbox 事件：可恢复的异步生命周期请求

核心 API 分组

镜像与模板

/container/image/*
/container/template/*

App Session 生命周期

/container/app-session/create
/container/app-session/start
/container/app-session/stop
/container/app-session/delete

运行时监控

/container/runtime/monitoring/list
/container/queue/status
/container/outbox/list-by-page

生命周期模型

典型流程：

从模板创建会话。
解析运行时并创建工作负载。
持久化 runtime ID 与实例状态。
监听运行时事件（started、failed、exited、deleted）。
触发状态迁移并执行清理策略。

队列与并发控制

容器创建受以下配置约束：

container.create_queue_max_concurrency
container.create_queue_max_pending

用于在突发负载下保护运行时资源。

清理策略

DAG 节点所属容器可通过以下配置调整清理行为：

container.delete_container_on_node_success
container.dag_node_cleanup_on_failed
container.dag_node_cleanup_on_dag_finished

运行建议

保持运行时监控开启并纳入可观测体系。
在共享集群中使用保守的创建并发配置。
根据调试需求与存储成本选择清理策略。
使用 Kubernetes 模式时，结合 /zh/docs/k8s-runtime-architecture 阅读。

数据管理

Wed, 12 Aug 2026 00:00:00 +0800

概述

gobrave 采用项目中心化数据模型，目标是让工作流输入组装可追溯、可复现。

核心数据对象

Dataset：生物数据资产的逻辑集合
Sample：样本元数据记录
File：文件元数据记录
关系：
project <-> dataset
dataset <-> sample
dataset <-> file
sample <-> file

API 范围

数据接口位于 /api/v1，按资源分组：

/data/dataset/*
/data/project-dataset/*
/data/file/*
/data/sample/*
/data/dataset-file/*
/data/sample-file/*
/data/dataset-sample/*

典型数据流程

创建项目。
创建数据集。
注册样本与文件。
绑定样本/文件角色（例如 FASTQ_R1、FASTQ_R2）。
建立 dataset 关联关系。
在工作流中按关系解析输入。

与工作流的集成

工作流引擎可从托管数据中解析结构化输入：

样本集合
按样本聚合的角色分组文件
独立参考文件

因此可实现模板化工作流，同时保留项目级数据追踪能力。

数据一致性说明

关系对象依赖后端生成 ID 进行关联。
删除与更新会经过 repository/service 层校验。
大型项目建议优先使用分页列表接口。

最佳实践

批量导入前先定义统一的文件角色体系。
用明确分析目标划分 dataset 边界。
优先使用 project 作用域接口避免跨项目泄漏。
保持工作流输入契约与数据角色命名一致。

容器队列监控

Tue, 11 Aug 2026 00:00:00 +0800

概述

本文档说明 gobrave 如何暴露容器创建队列健康状态、各监控字段的含义，以及队列状态在系统内部的计算方式。

该监控接口主要服务于运维与前端轮询场景，用于回答以下问题：

队列模式是否启用
当前有多少创建并发槽位被占用
还有多少创建请求在等待
当前配置的并发上限和排队上限是多少

架构

flowchart LR
 subgraph Client[客户端层]
 UI[Web UI / 运维脚本];
 end;

 subgraph API[接口层]
 H[ContainerHandler.GetQueueStatus];
 end;

 subgraph Worker[队列层]
 W[ContainerCreateWorker];
 QS[QueueStatus];
 end;

 subgraph Data[数据层]
 DB[(ContainerInstance + OutboxEvent)];
 end;

 UI -->|GET /container/queue/status| H;
 H -->|QueueStatus call| W;
 W --> QS;
 QS -->|CountContainerInstanceByStatuses| DB;
 QS -->|CountPendingOutboxEventsByType ContainerCreateRequest| DB;
 H -->|JSON response| UI;

启动期接线如何保障容错与指标准确性

队列监控能力依赖于依赖注入容器中的显式启动接线。这些接线不仅让队列状态可观测，也让状态在重启后可恢复、可校正。

通过 DI 注入监控注册表，并在全局激活。
- 注册 MonitoringRegistry provider，当前默认实现为内存版。
- 通过 SetMonitoringRegistry 注入运行时监控路径，确保全局只有一个监控真值来源。
- 因为是 DI 驱动，后续可替换为 Redis 等实现而无需改队列 API。
启动运行时对账器，形成持续修复闭环。

容器工作队列系统

Tue, 11 Aug 2026 00:00:00 +0800

概述

gobrave 使用基于 outbox 模式的工作队列来异步管理所有容器生命周期操作。所有操作 — 创建、启动、停止、删除 — 不再直接调用容器运行时（Docker/K8s），而是通过 ContainerCreateWorker 入队，由事件总线异步处理。

该设计提供：

并发控制 — 通过信号量限制同时创建的容器数量。
容错能力 — 失败的操作通过 outbox 模式自动重试。
一致的状态机 — 所有操作遵循统一的 FSM 驱动的生命周期。
解耦 — HTTP 处理函数立即返回，容器操作在后台执行。

架构

核心组件架构图

flowchart LR
 subgraph API[API 层]
 H[HTTP Handlers]
 end

 subgraph Core[控制层]
 M[ContainerManager\nCreateByTemplate / Start / Stop / Delete / OnEvent]
 D[OutboxDispatcher\n轮询 pending outbox]
 W[ContainerCreateWorker\n处理 create/start/stop/delete 请求]
 R[RunRuntimeReconciler\n定时恢复监控]
 end

 subgraph Data[数据层]
 DB[(ContainerInstance + OutboxEvent + ContainerEvent)]
 end

 subgraph Runtime[运行时层]
 RT[Docker / Kubernetes Runtime]
 end

 H -->|用户请求| M
 M -->|事务写入实例 + outbox 请求| DB

 D -->|拉取 pending 请求| DB
 D -->|发布 Outbox*RequestEvent| W

 W -->|执行 Create/Start/Stop/Delete| RT
 RT -->|ContainerStarted/Exited/Failed/...| M
 M -->|FSM 转换 + 事件落库| DB

 R -->|RecoverRuntimeMonitoring| RT
 R -->|扫描运行中实例| DB

该图展示了三个关键闭环：

重启后运行时监控恢复

Tue, 11 Aug 2026 00:00:00 +0800

概述

本文说明 gobrave 在进程重启后，如何恢复运行时生命周期监控。

当前恢复路径基于：

ContainerManager.RunRuntimeReconciler(...)
ContainerManager.RecoverRuntimeMonitoring(...)
运行时 Monitor(ctx, runtimeID) 实现
进程全局 MonitoringRegistry 幂等保护

目标是为可恢复的容器实例重新附加监控，并让运行时事件继续进入正常状态迁移管道。

为什么需要恢复

服务重启后，内存中的监控 goroutine 会丢失。如果不执行恢复，运行时状态可能已经变化，但持久化的 ContainerInstance 状态仍然陈旧。

启动与周期性恢复

系统启动时，依赖注入会触发：

ContainerManager.RunRuntimeReconciler(context.Background(), 600*time.Second)

RunRuntimeReconciler 会执行：

启动时立即恢复一次
按配置间隔进行周期恢复

若 interval <= 0，reconciler 会回退到 300s。

每次恢复都会调用 RecoverRuntimeMonitoring，其处理步骤为：

读取持久化 ContainerInstance 记录
过滤可进行监控恢复的记录
根据实例运行时信息解析运行时实现
对运行中实例按需回填运行时 inspect 信息
当运行时支持 RuntimeMonitor 时调用 Monitor(ctx, runtimeID)
按实例记录恢复成功或失败日志，并继续扫描后续实例

可恢复状态包括：

creating
paused
running
failed

runtime ID 为空的实例会被跳过。

MonitoringRegistry 的作用

MonitoringRegistry 用于监控 goroutine 成员管理并防止重复 watcher：

MarkIfNotMonitoring(runtimeID) 通过原子方式仅在未监控时标记
对同一 runtime ID 的重复恢复调用是安全且幂等的
watcher 退出或订阅完成时调用 UnmarkRuntimeMonitoring(runtimeID)
RuntimeMonitoringSnapshot() 暴露 runtime ID 到计数的映射，便于诊断

因此，reconciler 可以重复运行而不会创建重复的活跃监控器。

Kubernetes 运行时架构

Wed, 12 Aug 2026 00:00:00 +0800

概述

本文说明 gobrave 当前使用的 Kubernetes 运行时架构。

该实现基于以下代码：

internal/container_runtime/kubernetes/runtime.go
internal/container_runtime/kubernetes/monitor_v2.go

运行时支持两类工作负载：

deployment（长运行服务）
job（一次性执行任务）

架构目标

在大规模场景下保持运行时监控高效。
避免同一个 runtime ID 启动重复监控循环。
将 Kubernetes 工作负载状态转换为稳定的 gobrave 运行时事件。
让用户侧生命周期行为保持可预测（start、stop、delete、logs、inspect）。

高层流程

flowchart TD
 A[Create ContainerSpec] --> B[KubernetesRuntime.Create]
 B --> C{WorkloadKind}
 C -->|deployment| D[Create Deployment]
 C -->|job| E[Create Job]
 D --> F[Optional Service -svc]
 D --> G[Return runtimeID]
 E --> G

 H[Start or Recovery] --> I[KubernetesRuntime.Monitor]
 I --> J{MarkIfNotMonitoring}
 J -->|already monitoring| K[Return idempotently]
 J -->|new| L[Start shared informers once]
 L --> M[Register subscription kind namespace name]
 M --> N[Deployment or Job events]
 N --> O[Emit RuntimeEvent]
 O --> P[ContainerManager state transition]

Runtime ID 模型

Runtime ID 编码格式为：

Event Bus 订阅者（event_handlers）

Tue, 11 Aug 2026 00:00:00 +0800

概述

本文说明通过 event_handlers 依赖注入分组订阅到共享事件总线的所有处理器，以及它们面向用户的架构职责。

该分组中已注册的订阅者为：

NewRouteRegistryHandler
NewAppSessionEventHandler
NewDagRuntimeEventNotifier
ContainerCreateWorker

系统启动时会遍历 event_handlers 分组并调用 bus.Subscribe(handler)，将这些处理器统一订阅到总线上。

订阅架构

flowchart LR
 subgraph Startup[启动装配]
 C[BuildContainer]
 G[event_handlers 分组]
 B[event.Bus]
 end

 subgraph Subscribers[订阅者]
 R[RouteRegistryHandler\nNewRouteRegistryHandler]
 A[AppSessionEventHandler\nNewAppSessionEventHandler]
 D[DagRuntimeEventNotifier\nNewDagRuntimeEventNotifier]
 W[ContainerCreateWorker]
 end

 subgraph Producers[主要事件生产者]
 O[OutboxDispatcher]
 M[ContainerManager / Runtime Events]
 DG[DAG Runtime]
 end

 C --> G
 C --> B
 G -->|逐个 handler 注册| B

 O -->|OutboxCreateRequestEvent\nOutboxStartRequestEvent\nOutboxStopRequestEvent\nOutboxDeleteRequestEvent| B
 M -->|ContainerEvent| B
 DG -->|dag.RuntimeEvent| B

 B --> R
 B --> A
 B --> D
 B --> W

各订阅者作用

1) NewRouteRegistryHandler

核心作用：将 App Session 容器生命周期与外部路由记录保持同步。

Node Completion Bootstrap 架构

Tue, 11 Aug 2026 00:00:00 +0800

概述

NodeCompletionBootstrap 是用于启动装配的基础组件，负责保证 DAG 分析节点在其运行容器进入终态后能够被最终收敛（finalize）。

它通过以下方式把基础设施关注点与 DAG 编排业务解耦：

构建并注入 NodeCompletionCoordinator（含清理策略）
将 coordinator 订阅到容器生命周期事件总线
启动后台轮询兜底收敛循环

即使发生进程重启、事件漏投或短暂总线抖动，也能保证节点状态最终一致。

架构图

flowchart LR
 subgraph Startup[启动装配]
 C[DI Container Build]
 B[NodeCompletionBootstrap]
 BUS[event.Bus]
 end

 subgraph Coordinator[收敛引擎]
 N[NodeCompletionCoordinator]
 P[轮询循环 每2秒]
 EH[事件处理 ContainerStopped 或 ContainerFailed]
 end

 subgraph Data[数据层]
 CR[(ContainerInstance Repository)]
 AR[(AnalysisNode Repository)]
 end

 subgraph Runtime[节点最终化]
 RE[RuntimeEngine CompleteNode]
 PUB[发布 DAG RuntimeEvent]
 end

 subgraph Cleanup[容器清理]
 CM[ContainerManager Stop 或 Delete]
 CFG[container 配置策略]
 end

 C --> B
 B -->|Subscribe| BUS
 B -->|启动 goroutine| N

 BUS --> EH
 N --> EH
 N --> P

 EH --> CR
 P --> CR
 CR --> AR
 AR --> RE
 RE --> PUB

 CFG --> B
 B --> CM
 N -->|节点失败时| CM
 N -->|节点成功且开启时| CM

启动时序

服务启动时：

Outbox 分发器与 Worker 并发控制

Tue, 11 Aug 2026 00:00:00 +0800

概述

本文说明 RunOutboxDispatcher、OutboxDispatcher 与 ContainerCreateWorker 如何协同，为 ContainerInstance 实现队列背压与运行时并发控制。

核心目标：

限制同时执行的容器创建/启动操作数量（maxConcurrency）。
限制可排队等待的创建请求数量（maxPending）。
通过 OutboxEvent + 事件总线保持请求异步化。

组件与职责

`RunOutboxDispatcher`

在 goroutine 中启动分发循环。
异步调用 dispatcher.Start(context.Background())。

1
2
3


func RunOutboxDispatcher(dispatcher *OutboxDispatcher) {
 go dispatcher.Start(context.Background())
}

`OutboxDispatcher`

轮询待处理 outbox 记录（ListPendingOutboxEvent）。
发布前将每个请求标记为 processing。
向事件总线发布类型化请求事件：
- OutboxCreateRequestEvent
- OutboxStartRequestEvent
- OutboxStopRequestEvent
- OutboxDeleteRequestEvent

`ContainerCreateWorker`

订阅上述总线事件。
异步处理 create/start/stop/delete。
对 create/start 请求通过 acquireCapacityAndTransition 做容量检查。
成功后将 outbox 标记为 sent，可重试失败则回退为 pending。

事件总线流程

flowchart LR
 A[API / Manager enqueue] --> B[(go_outbox_event)]
 B --> C[OutboxDispatcher poll]
 C --> D[mark processing]
 D --> E[event.Bus publish]
 E --> F[ContainerCreateWorker Handle]
 F --> G{capacity + state valid?}
 G -- yes --> H[create or start container]
 G -- no --> I[keep request for retry]
 H --> J[mark outbox sent]
 I --> K[mark outbox pending]
 K --> C

`ContainerInstance` 状态与排队行为

创建请求路径

创建 API 在同一个 DB 事务内完成队列检查与入队。
事务会检查待处理创建请求数是否超过 maxPending。
若待处理创建请求已大于等于 maxPending，事务返回错误并回滚，因此不会创建 ContainerInstance 和 OutboxEvent。
若可接受，同一事务写入：

ContainerInstance{status: pending}
OutboxEvent{Type: ContainerCreateRequest, Status: pending}

OutboxDispatcher 发布 OutboxCreateRequestEvent。
ContainerCreateWorker 处理事件并调用 acquireCapacityAndTransition。

容量判定（`maxConcurrency`）

Worker 会统计当前占用并发槽位的活跃容器实例。
若活跃数小于 maxConcurrency，允许迁移，容器进入 creating，随后进入 running。
若活跃数大于等于 maxConcurrency，本轮拒绝容量，请求不会执行。

拒绝时结果：