DataRaum

DataRaum

将组织的运营模式扎根于自身数据中的理解层。

语义层会告诉 BI 工具列叫什么。DataRaum 会了解它们意味着什么——组织的概念、关系、规则和指标——并将每一项扎根于实际数据，同时为其提供经过测量的置信度。完整介绍请参阅文档。

Monorepo 布局

packages/
├── engine/          # Python — pipeline, detectors, Temporal activity worker
├── cockpit/         # TypeScript — TanStack Start web UI
├── dataraum-config/ # YAML data — entropy config, LLM prompts, verticals (bind-mounted, never imported)
└── infra/           # docker-compose orchestration

每个包都有自己的 README。如果你正在处理某个特定包，请从这里开始。

状态

DataRaum 以多容器平台的形式运行，并按工作区隔离：

• engine（Python）——一个 Temporal 活动工作器，不提供 HTTP。负责执行持久化分析（add_source、begin_session、operating_model），并将元数据写入工作区的 Postgres 模式。
• cockpit（TanStack Start）——你使用的 Web 应用。它承载聊天 Agent、呈现结果，并通过 Temporal 触发 engine 工作流来协调整个流程。

每个工作区都会运行各自的一对容器。在它们前面的是 portal（以第二种角色运行的 cockpit 镜像——登录、成员路由、工作区预配）和 Caddy，它会在父域名上提供 portal，并在每个工作区自己的子域名上提供对应的服务。

它们共享同一套基础设施：Postgres（元数据 + cockpit 状态 + 目录）、S3 对象存储（DuckLake 数据湖 + 上传文件）以及 Temporal（持久化编排）。engine 和 cockpit 之间没有 HTTP 接口——集成面是 Postgres + Temporal。请参阅平台架构。

快速开始

# Set the LLM key
cp packages/infra/.env.example packages/infra/.env
echo "ANTHROPIC_API_KEY=sk-ant-..." >> packages/infra/.env

# Bring up the whole installation (substrate, engine worker + cockpit for the
# default workspace, portal, and the Caddy ingress)
docker compose -f packages/infra/docker-compose.yml up -d --wait

# Engine health = the Temporal worker heartbeat (no HTTP endpoint):
docker compose -f packages/infra/docker-compose.yml run --rm --no-deps \
  --entrypoint temporal temporal-admin-tools \
  worker list --namespace default --address temporal:7233   # → Status: Running

# Sign in at the portal, then open the default workspace from there
open http://dataraum.localhost              # [email protected] / dataraum-dev

Caddy 按主机名路由：父域名提供 portal（登录 + 你的工作区），每个工作区都有自己的子域名（http://ws1.dataraum.localhost）。localhost:3000 仅用于调试——会话 Cookie 的作用域限定在父域名，因此浏览器访问该地址时会被重定向到 portal，而脚本会收到 401。

首次运行时最容易遇到的问题是：**Caddy 会绑定端口 80。**如果该端口已被占用（macOS 自带 Apache），up 会在容器启动时失败，portal 也无法启动——设置 CADDY_HTTP_PORT 和对应的 DATARAUM_PORTAL_ORIGIN 即可更换端口。（*.localhost 无需在 /etc/hosts 中添加条目。）

Compose 仅定义一对工作区容器——这是引导脚手架，确保全新安装后有可登录的工作区，也有可供预配器克隆的工作区。其他所有工作区都通过 portal（New workspace）或 bun run workspace:create 创建；Compose 不会为每个工作区增加一个服务。

完整操作指南（包括故障排查）：运行整套服务。

如需迭代 UI，可在 Docker 外运行 cockpit 开发服务器以启用热重载——请参阅 packages/cockpit/README.md。

运行已发布版本（已发布镜像）

以上快速开始步骤会从源代码构建 engine 和 cockpit。若要改为运行已发布的版本镜像——例如在部署主机上运行且没有构建工具链——请叠加发布配置并指定版本：

export DATARAUM_VERSION=1.2.3          # any tag from a GitHub Release
docker compose \
  -f packages/infra/docker-compose.yml -f packages/infra/docker-compose.release.yml \
  --env-file packages/infra/.env up -d --wait --no-build

这会拉取该标签下的 ghcr.io/dataraum/{dataraum, dataraum-cockpit, dataraum-cockpit-migrate}。有关镜像、模式/迁移处理方式和按工作区划分的拓扑结构，请参阅部署。

开发

• Engine（Python）：cd packages/engine && uv sync --group dev && uv run pytest --testmon tests/unit -q。请参阅 packages/engine/README.md 和 packages/engine/CLAUDE.md。
• Cockpit（TypeScript）：cd packages/cockpit && bun install && bun --bun run dev（必须使用 --bun 标记）。请参阅 packages/cockpit/README.md 和 packages/cockpit/CLAUDE.md。
• 拉取 engine 元数据模式（cockpit）：cd packages/cockpit && DATARAUM_WORKSPACE_ID=<id> METADATA_DATABASE_URL=<url> bun run db:pull:metadata。engine 添加或更改 SQLAlchemy 模型后，请重新运行。

文档

平台文档位于 docs/（工作区根目录），并通过 Zensical 发布。请从 docs/index.md 开始，或在本地运行网站：

uv run --project packages/engine zensical serve   # run from the repo root

• 文档首页 — 快速了解 DataRaum 的功能
• 旅程 · 管线与阶段 · 可学习表面 · 测量与检测器
• 平台架构 — 了解底层实现
• 决策记录 — 架构背后的原因

许可证

Apache 2.0 — 详见 LICENSE。