数据目录控制台

分析目录（控制台中名为「Wow 数据目录」）是分析平台的控制面：它把仓库中的表当作数据源，把数据集定义为基于它们的宽表，并把数据集的每个版本发布为一个 ClickHouse 视图，由每个服务节点提供（平台服务）。它的控制台是数据负责人做这些工作的地方：审查数据源、起草与发布数据集、审批需要审批的变更，以及读取每个已提供数据集的数据行。本页说明控制台怎样协作、怎样部署、谁能做什么，以及怎样使用它。分析目录还在孵化中：每次发布都带上它服务端的镜像，但它的模块不作为 Maven 制品发布。

它们怎样协作

• 由目录提供控制台。 控制台是一个单页应用，由目录服务从其发行包的 ui/ 文件夹以静态文件提供。浏览器只与目录通信：目录自己的路由（/analytics-catalog/…），以及每个 Wow 节点都提供的数据集路由（/wow/dataset/…）。
• 目录决定，控制台只是提供。 每个变更都是目录的一条命令，由目录授权并检查。控制台先读取目录的设置（见下文），只提供这个目录支持的操作，并说明某个操作为什么不可用；它从不决定目录不会决定的事。
• 数据集的行属于数据面。 控制台像任何读取者一样，经节点的查询策略读取它们：每个调用者读取自己租户、所有者与空间的行，每个值按其数据源的说明脱敏。读取数据行不需要任何目录角色。
• 对某一行的操作发往拥有该聚合的服务。 行的引用字段存放着一个聚合的 ID；控制台提供该聚合的命令，目录以数据负责人的名义把选中的命令转发给它的所属服务，由那个服务而不是目录来授权。目录只经由其 Manifest 描述的对端客户端到达一个上下文（wow.peers.<context>，带 contract: manifest，并用 mode: user 发送数据负责人自己的凭证）；没有这样客户端的上下文不提供操作。

部署

deploy/analytics-catalog 里是它用于 Wow chart 的 values，两个节点，基于 MongoDB（或用 values-postgres.yaml 改用 PostgreSQL），沿用与 eShop 服务相同的选择（Kubernetes）：

1. 先构建控制台，再构建服务端的发行包（它会把控制台的构建复制进 ui/ 文件夹），然后构建镜像。
2. 提供 MongoDB，以及各服务的 Sink 写入的 ClickHouse 仓库。目录不在 ClickHouse 中建表；它的账户需要在数据集的库 wow_datasets 上拥有 CREATE DATABASE、CREATE VIEW 与 DROP VIEW 权限，以及对视图读取的源表的 SELECT 权限。
3. 以 cosec profile 运行节点，放在 CoSec 网关之后：网关验证每个数据负责人的访问令牌，并转发它验证过的身份（CoSec-Identity），服务读取这个身份，自己不持有任何密钥。服务信任这个请求头，所以只有网关能到达它的 HTTP 端口；清单中的网络策略就是这样设置的（保护部署）。

控制台使用 hash 路由（/#/sources、/#/datasets），所以服务端不需要为它的页面设置回退。

谁能做什么

数据负责人粘贴一个 CoSec 访问令牌登录控制台，控制台在每个请求中带上它（Authorization: Bearer，以及控制台的应用 CoSec-App-Id: analytics-catalog-console）。被网关或服务拒绝的令牌（401）会让控制台退出登录，登录页说明原因：已过期，或被拒绝。目录的调用者属于平台租户，没有所有者；目录从身份中读取它们的角色：

角色	可以
analytics.catalog.viewer	查看数据源与数据集
analytics.catalog.editor	分析师的工作：起草、修订数据源并审查它们的保护；起草、修订、发布、回滚与下线数据集
analytics.catalog.approver	把数据源标记为已审查；审批降低的保护；审批数据源供数据集使用；批准或拒绝发布
analytics.catalog.admin	编辑者能做的一切，以及把数据源标记为已审查

• 查看目录需要这四个角色之一。四个都没有的调用者什么也读不到：它对数据源与数据集的查询以 403 wow.auth.forbidden 拒绝，控制台会说明。这保护的是控制面，即定义、列、保护与血缘，而不是数据集的行。
• 目录自己的命令是内部命令（只在内部受理的命令）：同步数据源（SyncSource）、重新编译数据集（RecompileDataset）、删除已下线数据集的视图（DropDatasetViews）。它们由目录的监视器、数据源变化后的重新编译和下线时安排的定时发送，公开端口对它们的路由答 404，对管理员也一样。监视器每隔 wow.analytics.catalog.refresh-interval（30 秒）同步清单有变化的每张表，节点启动时同步每张表，也同步目录持有数据源、而仓库已不再列出的每张表（目录停机期间被删除的表此时标记为缺失），所以要手动同步整个目录，就重启一个节点。
• 审批只属于审批者。 管理员不能审批降低的保护、数据源或发布：这些是特权审查，与管理目录的人分开。
• 由 CoSec 决定时（wow.cosec.authorizer.enabled: true），它的策略决定每条命令，目录的角色什么也不决定。控制台无法预先读取策略，所以这时它提供每个操作，拒绝以服务的回答 wow.auth.forbidden 返回。

审批

两个开关决定什么需要审批者，默认都关闭：

设置	开启时
wow.analytics.catalog.require-source-approval	数据集只读取审批者已审批供数据集使用的数据源，而不只是已审查或已采纳的
wow.analytics.catalog.require-publication-approval	每次发布都要等审批者批准，查询才读取它

有些变更不论开关如何都需要审批者：

• 基于敏感值计算、或降低保护的发布要等审批者批准；数据集的详情会说明它为什么在等待。
• Wow 表的值降低保护（其 wow_catalog 行现在要求如此）只有在审批者接受后才生效。除此之外，Wow 表的保护只能收紧。
• 分析师的数据源变为已审查只能由审批者（或管理员）完成，前提是已声明它的租户列（或它是平台维度），并且每个字符串列的保护都已审查。

等待中的发布在「待审批」里，审批者批准它（这会编译并发布它）或拒绝它。被拒绝或等待中的发布不会改变查询读取的内容：正在提供的版本继续提供。

它读取的设置

GET /analytics-catalog/settings 回答控制台需要知道的这个目录的情况，任何调用者读到的都一样：

{
  "connection": "default",
  "requireSourceApproval": false,
  "requirePublicationApproval": false,
  "rolesDecide": true
}

• connection 是数据源 ID 开头的仓库连接（<connection>:<database>:<table>），即 wow.analytics.catalog.connection。控制台起草数据源时使用它，除非另外输入一个。
• requireSourceApproval 与 requirePublicationApproval 就是上面的两个开关。只有第一个开启时，控制台才为数据源显示「待审批」；第二个开启时，控制台在发布前就说明每次发布都要等待审批。
• rolesDecide 表示命令是否由目录的角色决定：没有 CoSec 的授权器时为 true。这时调用者的角色不允许的操作以禁用状态提供，并写明它需要的角色；记录本身不允许的操作也以禁用状态提供，并说明原因。为 false 时由 CoSec 的策略决定，控制台按记录允许的情况提供操作。

控制台在调用者确定之后读取一次这些设置。

使用控制台

• 数据源（首页）。仓库中的表与视图：「全部」、「待审查」（草稿）、「待审批」（仅当数据源需要审批时）、「Wow 表」、「分析师的表」、「表已不在」与「按状态统计」。数据源的详情显示它的连接、表、状态与作用域、Wow 表的 wow_catalog 行、待审批的降低保护，以及被拒绝的目录行。对分析师的表，它编辑作用域（租户、所有者与空间列，或平台维度）与引用（列=上下文.聚合）；对每个数据源，它编辑各列的保护。它的操作：标记已审查、审批供数据集使用、审批降低的保护。
• 数据集。 「全部」、「需要修订」（并显示每个是否仍在提供它已发布的版本）、「待审批」、「已发布」、「草稿」、「已下线」与「按状态统计」。数据集的详情说明它为什么需要修订或审批，编辑它的定义（JSON，错误按行与列指出）与标题，并列出已发布的版本，正在提供的排在最前，每个都带有它的视图、数据源、字段与 DDL。它的操作：发布、批准或拒绝发布、回滚到更早的版本（不能是正在提供的版本，也不能是从未发布的版本）、下线。
• 数据行。 一个已提供数据集的行，与它的任何读取者读到的一样。引用字段提供它所存 ID 的聚合的命令，每个都带有其请求体的表单。没有数据集查询后端的节点（例如以内存后端本地运行时）不提供数据集，页面会说明。
• 仪表盘。 由面板并排组成，每个面板是任一已提供数据集的视图。仪表盘保存在这个浏览器里：别人看不到。
• 起草。 按连接、库与表把分析师的表起草为数据源，以及从定义起草数据集；起草后各自在自己的页面打开，在那里审查与发布。

每个操作都要求确认，可以作用于一条记录或一组选中的记录，等待记录的快照（Wow-Wait: snapshot），并报告结果。拒绝以服务的原话和错误码说明：analytics.catalog.incomplete、analytics.catalog.definition-invalid、wow.auth.forbidden 等。列表每 15 秒以及每次操作之后重新读取：目录不推送它的快照变更。

控制台支持英文与中文，按浏览器语言中它支持的第一个选择，直到右上角的菜单另选一种。

本地运行

不使用 cosec profile 时，以开发 profile（dev）运行的目录节点从请求头而不是 CoSec 读取调用者：Wow-User、Wow-Tenant 与 Wow-Roles。控制台的登录页可以指定这样的调用者，并保存在这个浏览器里。部署会拒绝以这种方式给出的调用者，控制台随即退出登录并说明原因。构建控制台、让它对接本地目录运行，以及运行其端到端测试的命令，见控制台的 README。