> For the complete documentation index, see [llms.txt](https://bio-os.gitbook.io/userguide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bio-os.gitbook.io/userguide/zui-jia-shi-jian/for-bioos-kai-fa-zhe.md).

# For Bio-OS开发者

## 架构

特点：高可扩展，包括接口、存储层等；深度集成生信领域流行的开源工具，Cromwell、JupyterHub等；

下图展示了运行依赖的网络和存储，及内部各组件间的调用关系；

文件存储存放生信分析作业的输入输出和Notebook，DB存放各类实体控制信息，包括工作流脚本。

<figure><img src="/files/AkLM6jbNEv3GB7MrLpYz" alt=""><figcaption></figcaption></figure>

## 领域设计

整个项目深度实践了领域驱动设计；图中仅示意了API Server所代表的核心域设计，Cromwell、JupyterHub处于支撑域未做体现；限界上下文划分基于动静分离原则，出于轻量化的考虑，所有限界上下文被集中实现于单个服务中。

<figure><img src="/files/XpaQ92YNTsZvE6JwpHVG" alt=""><figcaption></figcaption></figure>

| 限界上下文           | 职责                                 |
| --------------- | ---------------------------------- |
| Workspace       | 用于归档和呈现生信分析过程和结果资料，同时也是划分人员权责的基本单元 |
| Notebook Server | 用于管理Notebook编辑环境，即环境设置和环境生命周期      |
| Submission      | 用于管理工作流运行及其历史                      |

## 代码

### 框架

[Hertz](https://www.cloudwego.io/zh/docs/hertz/) 字节跳动CloudWeGo团队开源的HTTP服务框架[GRPC](https://github.com/grpc/grpc-go) GRPC主要被用于CLI接入及内部各限界上下文间的接口调用[Casbin](https://casbin.org/zh/) 基于其RBAC能力支持访问控制[GORM](https://gorm.io/zh_CN/docs/index.html) Go生态中最流行的ORM框架，所有关系型数据库都借助它进行连接

### 目录

代码部分

```Shell
.
├── cmd # 各组件的main入口，以cobra command形式运行
│   ├── apiserver
│   └── bioctl
├── internal # 组件内部逻辑
│   ├── apiserver
│   ├── bioctl
│   ├── context # 各限界上下文实现
│   │   ├── notebookserver
│   │   ├── submission
│   │   └── workspace
│   │       ├── application
│   │       ├── domain
│   │       ├── infrastructure
│   │       └── interface
├── pkg # 后端公共库部分，被cmd和ineternal引用
│   ├── auth # 身份校验和权限检查配置
│   ├── client
│   ├── consts
│   ├── db # 数据库配置
│   ├── errors
│   ├── eventbus # 事件总线配置
│   ├── jupyterhub
│   ├── log
│   ├── middlewares # 处理API接入的身份校验和权限检查
│   ├── notebook # notebook配置
│   ├── schema
│   ├── server # server框架配置
│   ├── storage # 文件存储配置
│   ├── utils
│   ├── validator # API入参检查方法
│   └── version
└── web # 前端部分
    ├── public # 页面入口相关静态资源
    ├── src # TS代码
    └── swagger-gen.js # 从swagger生成API调用代码
```

其他

```Shell
.
├── build # 各组件Dockerfile
│   ├── apiserver
│   ├── bioctl
│   └── web
├── conf # apiserver和ctl启动配置示例
├── docs # API文档 swagger形式
├── hack
│   ├── boilerplate # LICENSE头
│   └── make-rules # Makefile各target实现
└── githooks # Git提交检查
```

### DDD实践

项目采用经典四层结构：

1. **Interface层** 用于借助各种server框架实现不同的种类的接口，与Hertz和GRPC的对接就在该层实现，在层内会对不同的协议类型分别定义View Object，并实现从View Object到Data Transfer Object的转换
2. **Application层** 按[CQRS原则](https://learn.microsoft.com/zh-cn/azure/architecture/patterns/cqrs)分command和query，其中query中带有Read Model抽象定义，由Infrastructure层实现，用于与Interface层传递的数据Data Transfer Object定义于此
3. **Domain层** 最核心的部分，其对外部的依赖也由其进行抽象定义，抽象的实现由外部完成，比如典型的Repository，表现为依赖倒置
4. **Infrastructure层** 负责对包括存储在内的各种外部设施的对接，表现为各种抽象的实现

<figure><img src="/files/QZYeiUETTvVRlmnNymzS" alt=""><figcaption></figcaption></figure>

### 开发环境

所需工具（未涉及前端）：

1. Git
2. GNU Make
3. Go 1.19或以上
4. Docker

其余的工具（例如swagger、womtool、protoc等）可以通过`make tools`一键安装

## 运行

对于集群部署，推荐使用官方提供的[helm charts](https://github.com/Bio-OS/helm-charts)，原文档中以Minikube为运行环境，但更推荐使用公有云kubernetes托管服务，能一键安装网络、存储组件，另外公有云也有NFS、MySQL产品

### 附：单机运行Cromwell

1. 准备一个工作目录，在目录中创建application.conf，并将以下内容进行粘贴

```Bash
include required(classpath("application"))
webservice {
  port = 8000
}
workflow-options {
  workflow-log-dir = /nfs/bioos-storage/cromwell-workflow-logs
  workflow-log-temporary = false
}
call-caching {
  enabled = true
  invalidate-bad-cache-results = true
}
database {
  profile = "slick.jdbc.MySQLProfile$"
  db {
    driver = "com.mysql.cj.jdbc.Driver"
    url = "jdbc:mysql://${db_endpoint}:3306/${db_name}?rewriteBatchedStatements=true&useSSL=false"
    port = 3306
    user = "${db_username}"
    password = "${db_password}"
    connectionTimeout = 5000
  }
}
backend {
  default = "Local"
  providers {
    Local {
      config {
        root = "/nfs/bioos-storage/cromwell-executions"
        filesystem {
          local {
           localization: [
                  "hard-link", "soft-link", "copy"
           ]

            caching {
              duplication-strategy: [
                "hard-link", "soft-link", "copy"
              ]
              hashing-strategy: "md5"
              check-sibling-md5: false
            }
          }
        }
      }
    }
  }
}
```

2. 下载程序文件cromwell.jar

从下面的链接下载cromwell-85.jar：<https://github.com/broadinstitute/cromwell/releases/tag/85>

3. 运行`bash ./run.sh`

```Bash
#!/bin/bash
set -e
echo 'starting cromwell'
nohup java -jar -Dconfig.file=${application.conf} -DLOG_LEVEL=INFO -DLOG_MODE=standard ${cromwell_path} server >log1 2>logerr &
echo 'started cromwell'
```