Loculus

Loculus 是一个用于构建微生物基因组数据库的软件包。主要功能包括：

通过简单的 Web 界面或 Web API 上传和存储共识序列及元数据
灵活的数据预处理：Loculus 内置了基于 Nextclade 的预处理功能，能够对齐和翻译序列，同时也易于实现和集成您自己的流水线。
强大的搜索功能：Loculus 提供了一个用户友好的界面来搜索和查看序列，以及一个使用 LAPIS 在后端查询数据的 API。
高度可配置：元数据字段列表完全可配置，Loculus 支持单片段和多片段基因组。

Loculus 面向任何管理测序数据的群体。它可以被拥有少数成员的小型公共卫生或研究实验室用于存储其内部数据，也可以被促进全球病原体序列共享的国际数据库使用。

📚 访问我们的文档网站

当前状态和路线图

Loculus 软件已处于稳定阶段，并用于生产系统（见下文“已知实例”），欢迎探索此仓库并试用。但请注意，在发布官方 1.0 版本之前，我们计划修订配置文件和 API。此外，目前的文档相当简略。我们计划在未来几个月内发布具有稳定 API 和全面文档的 1.0 版本。

如果您正在寻找一款用于管理测序数据的软件，并希望了解 Loculus 是否可能是适合您的工具，请随时联系我们。我们非常乐意了解您的项目，并在规划后续开发时考虑您的需求和要求。

已知实例

Pathoplexus 是一项旨在促进人类公共卫生重要性病毒基因测序数据共享的倡议。参见：https://pathoplexus.org

GenSpectrum 使用 Loculus 存储甲型流感病毒、呼吸道合胞病毒（RSV）及其他病毒测序数据，并为其用于分析和追踪病毒变异及突变的交互式仪表盘提供支持。参见：https://loculus.genspectrum.org

如果您也托管了一个 Loculus 实例并希望将其添加到本列表中，请联系我们！

开发

有关开发的更多文档可在每个文件夹的 README 中找到。此文件包含项目的高层概述以及最好集中在一处维护的共享开发信息。

如果您希望使用完整的本地 loculus 实例进行开发，您需要：

Deploy a local Kubernetes instance: Kubernetes
Deploy the backend: backend
Deploy the frontend/website: website

请注意，如果您单独开发后端或前端/网站，则不需要完整的本地 loculus 实例。有关更多信息，请参阅各自的 README。

架构

architecture_docs/ 包含 Loculus 的架构文档。

TLDR:

后端代码位于 backend，参见 backend/README.md
前端代码位于 website，参见 website/README.md
序列和元数据处理管道位于 preprocessing 文件夹，参见 preprocessing/specification.md
部署代码位于 kubernetes，参见 kubernetes/README.md。请查阅此处以获取本地开发环境设置说明。
身份验证由我们自己的 Keycloak 实例执行。配置参见 keycloak-image 和 realm-config。Keycloak 登录主题使用自定义的 keycloakify 构建。

以下图表展示了相关软件组件的大致概览：

architecture

GitHub Actions

虽然文档仍在编写中，但查看 .github/workflows 文件夹可能会有所帮助：

backend.yml 运行后端测试并构建后端 docker 镜像
website.yml 运行网站测试并构建网站 docker 镜像
e2e-k3d.yml 运行端到端测试

Authentication

User management

我们使用 Keycloak 进行身份验证。Keycloak 实例部署在 loculus 命名空间中，并通过 localhost:8083 或 authentication-[your-argo-cd-path] 对外暴露。Keycloak 实例配置了一个名为 loculus 的 realm 和一个名为 backend-client 的 client。该 realm 被配置为使用 Keycloak 的暴露 URL 作为 frontend URL。为了测试，我们向该 realm 添加了多个用户。这些用户是：

admin，密码为 admin（在 your-exposed-keycloak-url/admin/master/console/ 下登录）
testuser:testuser（读作用户名：testuser，密码 testuser）和 superuser:superuser（在 your-exposed-keycloak-url/realms/loculus/account/ 下登录）
以及更多的 testusers，针对 e2e 测试中的每个浏览器，遵循以下模式：testuser_[processId]_[browser]:testuser_[processId]_[browser]
这些 testusers 将在 e2e 测试的设置中被添加到 testGroup 中。如果你更改了 e2e 测试中的浏览器数量，你需要相应地调整 website/tests/playwrightSetup.ts。
为了验证用户是否存在，我们还为后端创建了一个技术用户，用户名为 backend，密码为 backend。该技术用户被授权查看用户、提交组，并且原则上可以管理其自己的账户。

Group management

组是由后端管理的实体，由名称唯一标识。
每个序列条目都归属于其最初提交时所属的组。修改（待批准期间的编辑、修订、撤销）只能由该提交组的成员进行。
每个用户可以是多个提交组的成员。
用户可以创建新的提交组，并自动成为初始成员。
组成员有权添加或移除其他成员。
组成员有权编辑所有组元数据（组 id 除外）
如果最后一个用户离开提交组，该组将变为“悬空”状态——它仍然存在但不再可访问，且无法创建同名的新组。
管理员用户可以直接在数据库上手动删除提交组，但在此之前必须将序列条目的所有权转移给另一个提交组，以满足外键约束。

为了测试，我们将上述声明的所有用户都添加到了组 testGroup。

为 Loculus 做贡献

非常欢迎贡献！请参阅 CONTRIBUTING.md 以获取更多信息，或者在需要帮助时联系我们。