Nextstrain.org

Nextstrain 是一个开源项目，旨在发挥病原体基因组数据的科学和公共卫生潜力。我们提供持续更新的公开数据视图，以及供社区使用的强大分析和可视化工具。我们的目标是帮助理解流行病学并改善疫情应对。如果您有任何问题，或者只是想打个招呼，请通过 hello@nextstrain.org 联系我们，或在 discussion.nextstrain.org 上介绍自己。我们欢迎对 Nextstrain 的贡献；请参阅我们的贡献文档以了解更多信息。

此仓库包含：

一个服务器（./server.js），用于提供 nextstrain.org 上的所有内容，处理身份验证并响应 API 请求。
前端页面，位于 ./static-site 目录中。
用于构建 Auspice 客户端定制版本的代码，位于 ./auspice-client 目录中。

此仓库提供了您在本地构建 nextstrain.org 和部署 nextstrain.org 所需的工具。

在本地构建 nextstrain.org

1. 设置具有正确版本 Node.js/NPM 的环境

检查 package.json 以查看支持的版本，例如

"engines": {
  "node": "^20",
  "npm": "^10"
}

虽然其他版本可能成功构建此项目，但我们建议使用受支持的版本以与 Heroku 环境保持一致。

如果你在其他项目中使用其他版本，可以使用 nvm 或 conda 等工具在不同版本之间切换；存在一个指向受支持 Node 版本的 .nvmrc 文件，因此 nvm install 将确保你使用的是正确的版本。

2. 安装前置依赖

通过运行

npm ci

从该目录（"nextstrain.org" 目录）安装 node 依赖项。

使用 npm ci 而不是 npm install 可确保你的依赖树与 package-lock.json 中的依赖树匹配。

3. 构建站点

npm run build 运行 ./build.sh 以构建静态站点和带有自定义配置的 Auspice 客户端。以下部分详细介绍了在构建站点后，在本地服务器上提供这些页面的不同方式。

4. 运行服务器

运行镜像已部署（线上）网站的服务器

npm run server 将启动一个本地服务器，默认可在 localhost:5000 访问。这应该完全镜像你访问 nextstrain.org 时看到的内容。为了复制线上行为，你需要设置适当的环境变量（见下文）。

以开发模式运行服务器

如果你正在开发 nextstrain.org，根据你的目标，有几种推荐的路径：

在大多数情况下，运行 npm run dev 即可满足你的需求。它既会监视服务器代码（./src）的任何更改并在你更新代码时重启服务器，也会监视 next.js 前端代码（./static-site）的任何更改，并使用热重载在你进行更改时更新站点。

如果你仅对服务器代码进行更改，或者想要测试编译后的前端站点，可以运行 npm run dev:ssg。如果你修改了服务器代码，它仍然会重启服务器，但如果你更改了 ./static-site 中的任何代码，它不会进行更新。这还允许测试 next.js 前端代码在实时站点中的呈现效果。

环境变量

参见 docs/infrastructure.md 了解服务器使用的环境变量说明。对于本地运行，你应该确保

NODE_ENV 未设置为 "production"，因为身份验证在 localhost 上无法工作。
AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 是有效的 AWS IAM 用户，以便服务器能够访问 S3 存储桶。或者，可以使用 ~/.aws/credentials 来配置这些。如果你向 ~/.aws/credentials 添加了一个新配置文件，则可以通过设置 AWS_PROFILE=... 来告诉服务器使用它。

如果你已经构建了站点的 next.js 部分（./static-site），通过 npx next build static-site 或类似方式，那么设置 USE_PREBUILT_STATIC_SITE=1 将使用这些已构建的资源，而不是进行服务器端编译。

使用 DEBUG 来控制调试级别的日志输出。特别是，设置 DEBUG=nextstrain:* 对于查看我们自身代码库的所有输出非常有用。

除 Auspice 之外的前端页面

nextstrain.org 中所有使用 Auspice 可视化数据集之外的前端（客户端）页面均使用 Next.JS 构建，并位于 ./static-site/。

请参阅 static-site/README.md 了解如何添加内容的说明。请参阅上文了解如何以开发模式运行服务器，这将允许您开发这些页面。

在生产环境中，这些页面会被编译（npm run build）并通过 nextstrain.org 服务器（npm run server）提供服务。

文档

Nextstrain 文档由 Read The Docs 托管，位于 docs.nextstrain.org。请参阅此 GitHub 仓库获取更多详细信息。

请注意，文档曾通过本仓库中的服务器在诸如 nextstrain.org/docs/... 等 URL 下提供服务，直到 2020 年 11 月。已添加多个重定向以保留旧 URL。

Auspice 客户端

我们使用 Auspice 来可视化并交互系统基因组数据。

Auspice 客户端的定制版本

我们为 nextstrain.org 构建了一个定制版本的 auspice 客户端（例如您在浏览器中看到的部分）。 nextstrain.org 特有的 auspice 定制内容位于 ./auspice-client/customisations/。请参阅 auspice 文档获取更多关于定制 auspice 的信息。

本地测试

请确保首先使用 npm ci 安装依赖项（如果使用 conda 环境，请激活该环境）。

如果您拥有 AWS 凭证，请确保它们已设置为环境变量（AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY）。这些并非必需，但如果不可用，某些功能将会缺失。

然后运行：

./build.sh auspice
npm run server

这将创建 auspice-client/index.html 和 auspice-client/dist/* 文件，这些文件已被 gitignore 忽略。请注意，auspice 不需要 favicon.png，因为 nextstrain.org 服务器会处理此问题。

您也可以运行 Auspice 自己的开发服务器（而非 nextstrain.org 服务器）以简化客户端定制的开发。这意味着您将看到不同的启动页面，并且文档将无法正常工作。目前无法在开发模式下运行 auspice 并同时查看 nextstrain.org 的启动页面和文档。请阅读下文关于 nextstrain.org 服务器的部分以获取更多背景信息。

cd auspice-client
npx auspice develop --verbose --extend ./customisations/config.json --handlers ../src/endpoints/charon/index.js

如果你不熟悉 npx，它是一个用于轻松运行由 npm 安装的程序的命令。运行上述的 npx auspice 等同于 node_modules/.bin/auspice。

使用不同版本的 Auspice

有时更改所使用的 Auspice 版本会很有用。也许你正在升级 nextstrain.org 使用的版本，或者你想针对 nextstrain.org 测试 Auspice 本地副本中的更改。

如果你正在升级所使用的 Auspice 版本，请使用以下命令安装新版本：

cd auspice-client
npm install auspice@...

将 ... 替换为您想要的语义化版本说明符]。这将更改 package.json 和 package-lock.json（位于 auspice-client/ 中），以反映您安装的新版本。在准备提交您的 Auspice 版本更改时，您还需要包含这些已更改的文件。运行 npx auspice --version（位于 auspice-client/ 中）以检查 (a) 它是否正确安装以及 (b) 您拥有哪个版本。

然后，如上所述，从仓库根目录构建并运行服务器，使用以下任一方式：

./build.sh auspice
npm run server

或

cd auspice-client
npx auspice develop --verbose --extend ./customisations/config.json --handlers ../src/endpoints/charon/index.js

如果您正在从 Auspice 源代码的本地开发副本进行安装，您可以使用 npm link 来使用您的本地副本，而无需在每次更改后重新安装：

npm link <path to auspice repo>
npm link <path to auspice repo>/node_modules/react

这在全局和本地 node_modules/ 目录内都使用符号链接，将本地 Auspice 依赖项指向你的本地 Auspice 源代码。

使用 npm install <path to auspice repo> 无法用于使用本地开发副本，因为在这种情况下，npm install 和 npm link 处理依赖项的方式不同。

Nextstrain.org 服务器

npm run server 运行 ./server.js，它提供 nextstrain.org 上的所有内容并处理身份验证。

该服务器根据路径决定提供：

捆绑的 auspice JavaScript 文件（即通过上述 ./build.sh auspice 构建的 auspice 客户端）或
（预构建的）静态 splash 和文档页面

附注：auspice（客户端）与服务器之间的通信是如何工作的？

Auspice 是一个用于可视化系统发育组学数据的灵活工具，这些数据不特定于任何领域。它可以向服务器发起以下 API 请求：

/charon/getAvailable
/charon/getNarrative
/charon/getDataset 只要存在服务器且响应适当，auspice 客户端就可以可视化数据。

nextstrain.org 服务器（server.js）使用从 ./src/endpoints/charon/index.js 导入的代码为这三个端点设置 GET 请求处理器。

这些处理器的代码由 ./src/endpoints/charon/index.js 暴露，其编写方式使其可以被以下对象导入：

nextstrain.org 服务器：npm run server（参见 server.js）
auspice 服务器：cd auspice-client && npx auspice view --handlers ../src/endpoints/charon/index.js --verbose（在这种情况下很少有用，请确保先运行了 npm run build -- auspice！）
auspice 开发服务器：npx auspice develop --handlers ./src/endpoints/charon/index.js --verbose --extend ./auspice-client/customisations/config.json（对 auspice 开发有用，注意这里也应用了客户端自定义！）

请注意，2 和 3 在本地运行 auspice 服务器，但通过一种功能对其进行修改，该功能允许默认的请求处理器（用于 /charon/... GET 请求）被命令行参数覆盖。在这种情况下，它们使用 nextstrain.org 服务器所用的处理器进行覆盖（参见 server.js），因此 auspice 服务器模拟了 nextstrain.org 服务器的行为（从 S3 获取数据集等）。有关更多信息，请参阅 auspice API 文档。

部署

有关详细信息，请参阅基础设施文档。

测试

Nextstrain.org 目前使用在 test/*.test.js 文件中定义的有限自动化测试。使用以下命令运行测试：

npm run test:ci

这将在测试期间运行一个本地服务器。或者，你可以在后台运行自己的服务器，然后运行：

npm run test

作为替代。

要运行单个测试或少量测试文件，请运行本地服务器并直接调用 Jest，例如：

NODE_OPTIONS='--experimental-vm-modules' npx jest --run-tests-by-path test/routing.test.js