---
url: /zh/operate/analytics-catalog-console.md
description: 部署分析目录的控制台，让数据负责人登录，并用它审查数据源、发布数据集、审批需要审批的变更，以及对数据集的行执行操作。
---

# 数据目录控制台

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

## 它们怎样协作 {#how-it-fits-together}

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

## 部署 {#deploy-it}

[`deploy/analytics-catalog`](https://github.com/Ahoo-Wang/Wow/tree/main/deploy/analytics-catalog) 里是它用于 Wow chart 的 values，两个节点，基于 MongoDB（或用 `values-postgres.yaml` 改用 PostgreSQL），沿用与 eShop 服务相同的选择（[Kubernetes](./kubernetes)）：

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

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

## 谁能做什么 {#who-may-do-what}

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

## 审批 {#approvals}

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

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

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

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

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

## 它读取的设置 {#the-settings-it-reads}

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

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

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

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

## 使用控制台 {#work-with-the-console}

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

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

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

## 本地运行 {#run-it-locally}

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