我们如何重建云控制台（在运行它的时候）

欢迎来到我们发布周的第二天！

上个月，我们发布了 ClickHouse Cloud 控制台的重大更新，您可以在这里了解所有信息。在这篇文章中，我们想分享我们的经验以及我们在从头开始重建我们的云控制台中获得的知识。

2022 年底，在 ClickHouse Cloud 发布之前不久，我们与一家名为 Arctype 的早期阶段创业公司联手，该公司正在构建一个 SQL 客户端。在收购之后，我们最初将 Arctype 的大多数 SQL 客户端和数据库可视化功能迁移到一个新的 ClickHouse Cloud 原生（但仍然是独立的）SQL 控制台，但我们的愿景一直是更进一步——我们相信一个真正“托管”的 DBaaS 不应该仅仅抽象化基础设施的复杂性，它还应该为每天与数据打交道的开发人员和分析师提供一流的体验。换句话说，配置 ClickHouse Cloud 服务只需要点击几下，与该服务（以及其中包含的任何数据）交互不应该要求用户离开云控制台。为了实现这一愿景，我们知道我们需要将旧的 ClickHouse Cloud 控制台和全新的 SQL 控制台合并到一个应用程序中。

云平台是一个有趣的野兽。你永远无法真正为一个用户设计它们。虽然关于各种用户角色可以写很多，但为了本文的目的，我们将保持简单。

首先，是需要对所有系统有 100 英尺的视野，并能够管理其用户的权限和安全访问权限，以及监控其使用情况和计费信息的管理员类型用户。这些用户可能每个月只在任何给定的云界面中花费 1-5 个小时，但当他们需要查找信息并完成任务时，速度和易用性是硬性要求。

其次，我们有分析师类型用户，他们可能会：查看、创建和运行查询；导入和导出大量数据；启动、停止和调整 ClickHouse 服务的大小；以及与他人共享他们的发现（查询和可视化）。与管理员用户不同，分析师每天可能在云界面中花费数小时。他们需要一个舒适、可预测的环境来帮助他们沉浸在工作中。

第三，也是最重要的，我们有开发人员。对于开发人员来说，云界面（特别是这种情况下的云数据库界面）主要是其数据的真实来源。例如，数据是否存在于表中，存储了多少数据，查询是否已正确优化等等，以及创建、修改和监控摄取/消费服务的集中式位置。

不用说，每个用户角色都代表了完全不同的使用模式，不同的关注点，以及在判断我们假设的新的云界面体验的质量时可能不同的标准集。在兼顾所有三个方面的情况下进行设计将是一件棘手的事情。

无论何时处理复杂系统和大量数据，重要的是它不要让人感觉你在处理复杂系统和大量数据。出于这个原因，我们知道在审美上，我们需要朝着干净和轻盈的方向发展。UI 框架必须是最小的，以上下文方式提供最基本的信息。我们在方法中选择了清晰度和一致性。可预测性确实是任何成功用户界面的关键——如果用户知道他们在执行操作时接下来会发生什么，他们将很快学会信任并欣赏你的应用程序。

如前所述，我们有一些用户每天在我们的云界面中花费数小时。在任何你投入大量时间的区域，都必须是舒适的。舒适性和可定制性是相辅相成的，因此我们确保 ClickHouse Cloud 的这个新版本以非常模块化的方式设计——这种方式可以让我们轻松地切换颜色以创建多个主题。

这在概念上都很好，但现在我们实际上需要构建它。

在我们达成一致的愿景的道路上，出现了一个小小的障碍；它需要我们将两个大型代码库合并成一个，但更具挑战性的是，我们的旧版云控制台是用 Angular 编写的，而 SQL 控制台使用的是 React。换句话说，这两个应用程序是用截然相反的 JS 前端框架（或者更准确地说，是框架和库）编写的。

经过一番激烈的辩论，我们一致认为，将旧的云控制台 Angular 应用程序迁移到 React 是最好的行动方案。有很多文献比较和对比这两种方法，由于我们选择其中一种与另一个无关紧要，因此我们将免除大家一场辩论。但需要说明的是，任何熟悉 React 和 Angular 的人都可能会发现我们的决定是可以理解的（至少是）。

无论如何，这意味着实现我们的愿景实际上需要对（至少是）旧的云控制台代码库进行心脏手术，除了构建一个流畅、直观且自以为是的端到端用户体验之外。尽管听起来很有挑战性，但我们坚信，由此，统一控制台项目诞生了。

我们将在本文后面详细介绍，但在我们开始之前，这里是对我们最终工作流的概览。我们希望创建一个连接的系统，其中设计工作从 Figma 开始，与我们的 React 组件库紧密同步，并直接流向我们的云体验。

此时，我们已同意将 React 作为我们的 JS 框架，并确定了我们的设计愿景，但我们还需要决定如何重建云控制台本身。这一次，我们着眼于更长远的未来，2-5 年后，我们知道我们将招聘更多设计师和开发人员，因此我们需要一种方法来确保新员工能够快速入职，同时仍然保持一致性并忠实于我们的视觉标识。

在设计 ClickHouse Cloud 的新版本时，我们也在 Figma 中构建我们的设计系统，正如之前提到的，可定制性是首要原则，因此我们希望每个值都能够根据主题轻松定制。不仅仅是颜色，还有字体粗细、边框圆角、阴影，所有内容。最好的方法是使用设计令牌。设计令牌本质上是变量，它们允许我们为属性分配一个值，比如 `global.background.default`，而该值可以根据主题不同而有所不同。所以在较浅的主题中，我们可能会看到以下内容

global.background.default: white

而在较深的主题中，相同的令牌可能具有不同的值

global.background.default: black

这篇文章并不是真正关于设计令牌的，所以如果你感兴趣，我们建议你观看 这个 5 分钟的快速视频，它对设计令牌做了很好的解释。

我们的目标并不是在 Figma 中管理一组设计令牌，而是想要建立一个连接的系统，在这个系统中，对 Figma 中令牌的更改可以流向下游代码并进入产品，而无需开发人员进行任何更新。

经过一番研究，我们最终确定使用一个名为 Tokens Studio 的工具，我们可以在其中通过他们的 Figma 插件存储所有令牌，然后以 JSON 格式导出它们。在最近几个月里，Tokens Studio 甚至添加了与 Figma 变量的无缝同步功能，这对于我们的设计师维护多个主题来说是一个巨大的生活质量改进。

一旦令牌以 JSON 格式导出，我们仍然需要一种方法将它们转换为 CSS，以便它们可以用于我们的组件。这就是 Amazon Style Dictionary 的用武之地。只需一点 自定义，这个灵活的构建系统就可以将我们的 JSON 文件根据主题拆分为包含变量的 CSS 文件，然后可以使用一个名为 styled-components 的 css-in-js 库将它们导入到我们的组件中。

虽然取得了很大的进展，但这又带来了一个新的难题——我们如何构建这些组件，它们应该放在哪里？在之前的角色中，我们中的一些人曾经亲自参与过从头开始构建组件库的团队。虽然这可能很有意义，但在 ClickHouse，我们既没有时间也没有胃口去构建和维护这样一个完整的库。此外，鉴于当今有大量优秀的选项，从头开始构建组件库简直是疯了。

因此，与其重新发明轮子，我们选择使用一个现有的开源（大部分）无头 React 组件库作为基础组件，然后使用我们的令牌来添加样式。在尝试了许多领先的选项之后，我们最终选择了 Radix-UI，它提供了全面的组件组合，并且还具有开箱即用的出色可访问性。

由于我们在 Figma 中的设计系统被称为 Click UI，所以我们的组件库也理所当然地叫这个名字。我们开始从 Radix 导入组件，并对它们应用我们自己的样式和自定义。在 ClickHouse，我们有开源流淌在我们的血管里，所以 Click UI 从一开始就既开源又公开构建，这从来不是一个问题。

Click UI 现在已经拥有超过 40 个组件，并且还在不断增长。你可以在 https://github.com/ClickHouse/click-ui 上关注并贡献，或者查看我们在 https://click-ui.vercel.app/ 上的公共 Storybook 游乐场。

在开发 Click UI 的过程中，我们发现了一个反复出现的问题，那就是在我们要嵌入到库中的灵活性程度和一致性程度之间进行选择。

例如，对于我们的 `Select` 组件，我们争论了是否应该公开一个通用的接口，该接口可以很好地与开发时未知的大量设计配合使用，或者应该公开一个更严格的接口，更少可定制，但这可以使 `Select` 组件更干净、更易于使用。

在 React 术语中，这将在以下两个接口之间转换

<Select>
  {children}
</Select>

以及

<Select options=[{value: ‘value1’, label: ‘label1’}] />

虽然第一种情况可以轻松地适应设计的更改（例如，为每个选项显示一个图标），但它也为更广泛的可能（误）使用打开了大门。

另一方面，第二种替代方案使得使用组件变得更加容易，并且只通过传递数据，不允许使用可能破坏设计的样式，从而使整个应用程序更加一致。

这段旅程仍在继续，因此，我们还没有找到完美的平衡。显然，如果你需要为一个非常成熟的应用程序构建一个设计系统，你可能会更倾向于一致性和易用性。

为了尝试解决这个问题，我们采用了一种混合方法，即使用灵活的接口实现内部组件，这些组件可以被重复使用来构建具有更严格（更干净）接口的外部组件。这意味着开发人员可以有效地选择自己的冒险——我们提供了灵活的原语和现成的构建块。

从一开始，我们就决定使用 storybook 作为记录和直观测试组件的工具。

Storybook 在演示单个组件并展示如何使用所有属性来使用它们方面提供了极佳的用户体验。它还通过为 github 提供易于设置的集成来提供对视觉测试的支持。每次打开新的 PR 时，都会针对现有组件运行一组检查。如果发现新的更改，你可以将新组件的外观与现有组件进行比较，并决定是否接受或拒绝新的更改。

这种方法的局限性在于，随着每个组件的变体数量增加，检查每个组件的所有可能组合所需的视觉测试数量呈指数级增长。

我们还选择使用 Vercel，因为它为 Storybook 生成的应用程序提供了非常容易的部署，并且为每个新打开的 PR 自动生成预览环境。此功能对于促进设计师和开发人员之间的互动非常有用，前者可以轻松地访问生成的链接并检查最新的修改，而无需在其本地机器上手动部署更改。

在这个阶段，我们有一套完整的设计，并且由于 Click UI 的帮助，我们已经预先构建了许多组件，所以现在所有工作都集中在将它们拼凑起来。

在我们能够打开香槟之前，还有许多关于迁移的艰难决定需要做出。我们应该以什么顺序转换页面？我们应该一次性发布新体验还是采取更迭代的方法？我们能花多长时间来推迟对新功能的工作来发布这个版本？

最初，我们计划将迁移分为两个阶段。我们当时的假设阶段 1 将解决服务级别功能——主要是因为我们新的以服务为中心的模型为这些页面的迁移制定了非常清晰的路线。我们仍然有一些关于组织级别页面如何融入此模型的开放性问题，所以我们计划在阶段 2 中处理这些问题，以及入职和身份验证。回顾过去，我们找到了最初记录此计划的笔记

我们最终遵循了这个概述，但有一个显著的例外：最初，我们计划在完成服务级别页面迁移（上面的第 7 步）后立即切换到新体验。这将意味着临时维护一个分叉的体验——类似于传统的控制面板/SQL 控制台划分，只是颠倒过来。相反，我们选择完成迁移的两个阶段，然后利用一个特性标记，在几周内逐步向用户推出完全集成的体验。

这个计划也带来了几个挑战

• 全新的功能开发——在迁移进行的同时，我们尽可能推迟了新的功能开发。然而，一些关键的功能无法推迟，因此需要在传统的 Angular 应用程序和新的 React 应用程序中实现。除了重复工作之外，这意味着完成一些页面迁移就像试图击中一个移动的目标。
• 两个体验，一个应用程序——由于新的控制台体验实际上是建立在现有的传统 SQL 控制台应用程序之上，我们必须同时维护同一个应用程序的两个版本，每个版本都有略微不同的布局、路由机制和主题。随着我们越来越接近完成迁移，越来越多的回归开始出现在发布测试期间的传统 SQL 控制台（偶尔也出现在生产环境中）。在两种体验之间保持稳定性变得越来越困难。

不出所料，向数万现有用户推出全新的体验——其中许多是付费用户——并非易事。在一个理想的世界里，我们会将两种体验保持数月，并为现有用户提供从传统控制台过渡的机会。但是，主要是因为上面描述的挑战，维护两种应用程序将不可行——尤其是考虑到我们的团队只有少数工程师。换句话说，我们需要快速地揭开创可贴，这样团队就可以恢复对其他重要功能的工作。

在私人预览期间大约一个月的时间里，我们对新的云控制台有了足够的信心，可以开始在全球范围内推出它。我们的计划是最初推出 20%，在 2-3 周内逐步向上增加，直到我们达到 100%（假设没有出现问题）。不可避免地，一些与 UX 相关的要求使这个计划变得复杂了

• 一个组织中的所有用户都应该具有相同的体验。这可以通过使用组织级别的特性标记轻松解决。

• 属于多个组织的用户应该在所有组织中拥有相同的体验。这个略微棘手一些，但幸运的是，对我们的组织/用户群的初步分析表明，大约 20% 的组织包含属于多个组织的用户。因此，我们从这一部分用户开始推出。

从那时起，几乎所有事情都按计划进行。我们于 4 月 30 日完成了 100% 的推出，截至发布本文时，错误报告的数量仍然相对较低，反馈也大多是积极的。同样，我们想借此机会感谢所有抽出时间为我们提供建设性反馈的人——我们认为这是我们不断改进云控制台体验的关键。

那么，接下来是什么？在接下来的几周内，云控制台将迎来许多令人兴奋的新功能——敬请期待！