“

系列：S12 开发者教程 · 第 1 篇 | 难度：入门 | 阅读时间：15 分钟

5 分钟本地部署 coomia-dip

#引言

在企业数字化转型的浪潮中，数据平台的重要性不言而喻。Palantir Foundry 作为行业标杆，以其强大的本体建模和数据融合能力著称，但高昂的许可费用让许多企业望而却步。coomia-dip 应运而生——一个开源的、对标 Palantir Foundry 的本体驱动智能决策平台即服务（PaaS）。

本教程将带你在 5 分钟内完成 coomia-dip 的本地部署，让你快速体验这个强大平台的核心能力。无论你是架构师想要评估技术方案，还是开发者希望快速上手，这篇教程都将为你提供最简洁的入门路径。

#前置条件

在开始之前，请确保你的开发机器满足以下要求：

#硬件要求

CPU：4 核以上（推荐 8 核）
内存：16 GB 以上（推荐 32 GB）
磁盘：至少 20 GB 可用空间（SSD 推荐）

#软件要求

操作系统：Linux（Ubuntu 20.04+）、macOS 12+、Windows 10/11（需 WSL2）
Docker：24.0+ 且 Docker Compose v2 已集成
Git：2.30+
Python：3.11+（用于 SDK 交互）
Java：JDK 21+（用于 Control Layer 开发，部署可选）

#验证环境

打开终端，运行以下命令验证你的环境：

Bash

# 验证 Docker
docker --version
# 期望输出：Docker version 24.x.x 或更高

# 验证 Docker Compose
docker compose version
# 期望输出：Docker Compose version v2.x.x

# 验证 Git
git --version
# 期望输出：git version 2.30+

# 验证 Python
python3 --version
# 期望输出：Python 3.11+

# 验证 Java（可选）
java --version
# 期望输出：openjdk 21+

如果某项未安装，请参考对应官方文档进行安装。Docker Desktop 用户在 Windows 和 macOS 上通常已包含 Docker Compose。

#第一步：克隆项目

Bash

# 克隆 coomia-dip 仓库
git clone https://github.com/coomia-dip/coomia-dip.git
cd coomia-dip

# 查看项目结构
ls -la

你将看到以下核心目录结构：

Code

coomia-dip/
├── control-Layer/          # Control Layer：控制层（Spring Boot 3.x, Java 21）
├── data-Layer/             # Data Layer：数据层（Quarkus 3.x, Iceberg）
├── intelligence-Layer/     # Reasoning & Decision Layer + Agent Runtime Layer：推理决策 + Agent 运行时
├── deployment-Layer/       # Deployment & Operations Layer：部署运维
├── sdk-Layer/              # SDK & Developer Experience Layer：SDK 和开发者体验
├── python-sdk/             # Python SDK
├── docker-compose.yml      # 一键部署编排文件
├── docs/                   # 设计文档
├── tests/                  # 测试代码
└── sprints/                # Sprint 管理

#八大 Layer 架构简介

coomia-dip 采用 8 Layer 分层架构，每个 Layer 负责独立的关注点：

Layer	名称	职责	技术栈
A	Platform Deployment & Ops	部署编排与运维	Docker Compose, Python
B	Control Layer	本体管理、元数据、权限	Spring Boot 3.x, Java 21, gRPC
C	Data Layer	数据存储、Pipeline、计算	Quarkus 3.x, Iceberg+Nessie
D	Reasoning & Decision	推理引擎、规则引擎	Python 3.x, FastAPI, gRPC
E	Agent Runtime	AI Agent 执行环境	Python 3.x, FastAPI, Temporal
F	Pipeline & Orchestration	数据管道编排	合并至 Data Layer
G	Metadata & Governance	元数据治理	合并至 Control Layer
H	SDK & Developer Experience	SDK、CLI、代码生成	Python SDK, TypeScript

#第二步：配置环境变量

coomia-dip 提供了默认的开发环境配置，你只需要复制模板文件即可：

Bash

# 复制环境变量模板
cp .env.example .env

# 查看默认配置
cat .env

默认的 .env 文件包含以下关键配置：

ENV

# 平台基础配置
coomia-dip_ENV=development
coomia-dip_VERSION=latest

# 数据库配置（PostgreSQL）
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=coomia-dip
POSTGRES_USER=onto_admin
POSTGRES_PASSWORD=onto_dev_2024

# Doris 配置（OLAP 引擎）
DORIS_FE_HOST=doris-fe
DORIS_FE_HTTP_PORT=8030
DORIS_FE_QUERY_PORT=9030

# Kafka 配置
KAFKA_BOOTSTRAP_SERVERS=kafka:9092

# Nessie 配置（数据版本管理）
NESSIE_URI=http://nessie:19120/api/v1

# Temporal 配置（工作流引擎）
TEMPORAL_HOST=temporal
TEMPORAL_PORT=7233

# gRPC 端口配置
CONTROL_PLANE_GRPC_PORT=50051
DATA_PLANE_GRPC_PORT=50052
INTELLIGENCE_PLANE_GRPC_PORT=50053

对于本地开发，默认配置通常无需修改。如果你的本地端口有冲突，可以调整对应的端口号。

#自定义配置（可选）

如果你需要连接已有的外部数据库或消息队列，可以修改 .env 文件中的对应配置：

Bash

# 例如：使用已有的 PostgreSQL
POSTGRES_HOST=your-postgres-host
POSTGRES_PORT=5432
POSTGRES_DB=your_database
POSTGRES_USER=your_user
POSTGRES_PASSWORD=your_password

#第三步：一键启动

这是最激动人心的步骤——一条命令启动整个平台：

Bash

# 使用 Docker Compose 启动所有服务
docker compose up -d

# 查看启动进度
docker compose ps

#启动过程详解

Docker Compose 将按依赖顺序启动以下服务：

基础设施层（约 30 秒）
- PostgreSQL：关系型数据存储
- Doris FE/BE：OLAP 分析引擎
- Kafka + ZooKeeper：消息队列
- MinIO：对象存储（S3 兼容）
- Nessie：数据版本管理
平台服务层（约 60 秒）
- Control Layer（gRPC :50051）：本体管理服务
- Data Layer（gRPC :50052）：数据服务
- Intelligence Layer（gRPC :50053）：推理服务
运行时层（约 30 秒）
- Temporal Server：工作流引擎
- Temporal Worker：工作流执行器

#等待服务就绪

Bash

# 等待所有服务健康检查通过（约 2-3 分钟）
docker compose ps --format "table {{.Name}}\t{{.Status}}"

期望输出中所有服务状态应为 Up 或 Up (healthy)：

Code

NAME                    STATUS
coomia-dip-postgres      Up (healthy)
coomia-dip-doris-fe      Up (healthy)
coomia-dip-doris-be      Up (healthy)
coomia-dip-kafka         Up (healthy)
coomia-dip-nessie        Up (healthy)
coomia-dip-minio         Up (healthy)
coomia-dip-control       Up (healthy)
coomia-dip-data          Up (healthy)
coomia-dip-intelligence  Up (healthy)
coomia-dip-temporal      Up (healthy)

#常见启动问题排查

问题 1：端口冲突

Bash

# 检查端口占用
lsof -i :5432   # PostgreSQL
lsof -i :9092   # Kafka
lsof -i :50051  # Control Layer gRPC

# 解决方案：修改 .env 中对应的端口配置

问题 2：内存不足

Bash

# 检查 Docker 可用内存
docker info | grep "Total Memory"

# 如果内存低于 8 GB，可以启动最小化模式
docker compose -f docker-compose.minimal.yml up -d

问题 3：镜像拉取超时

Bash

# 使用国内镜像加速（中国用户）
# 在 /etc/docker/daemon.json 中添加镜像源
{
  "registry-mirrors": ["https://mirror.ccs.tencentyun.com"]
}

# 重启 Docker
sudo systemctl restart docker

#第四步：验证部署

#4.1 健康检查

Bash

# 检查 Control Layer 健康状态
curl http://localhost:8080/actuator/health

# 期望返回
{
  "status": "UP",
  "components": {
    "db": {"status": "UP"},
    "grpc": {"status": "UP"},
    "kafka": {"status": "UP"}
  }
}

#4.2 使用 Python SDK 连接

安装 coomia-dip Python SDK：

Bash

# 安装 SDK
pip install ontology-sdk

# 或从本地源码安装
cd python-sdk
pip install -e .

编写一个快速验证脚本：

Python

from ontology_sdk import OntoPlatform

# 连接到本地 coomia-dip 实例
platform = OntoPlatform(
    control_plane_url="localhost:50051",
    data_plane_url="localhost:50052",
    intelligence_plane_url="localhost:50053"
)

# 验证连接
status = platform.health_check()
print(f"平台状态: {status}")
# 输出: 平台状态: HealthStatus(control=UP, data=UP, intelligence=UP)

# 列出已有的 ObjectType
object_types = platform.ontology.list_object_types()
print(f"已注册的 ObjectType 数量: {len(object_types)}")

#4.3 使用 gRPC 客户端直接连接

如果你更偏好直接使用 gRPC，可以使用 grpcurl 进行测试：

Bash

# 安装 grpcurl
brew install grpcurl  # macOS
# 或 go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

# 列出可用的 gRPC 服务
grpcurl -plaintext localhost:50051 list

# 调用健康检查
grpcurl -plaintext localhost:50051 grpc.health.v1.Health/Check

# 列出 ObjectType
grpcurl -plaintext localhost:50051 onto.control.OntologyService/ListObjectTypes

#4.4 访问管理界面

coomia-dip 提供了多个管理界面：

界面	地址	用途
Platform Console	http://localhost:3000↗	平台管理主控台
Doris FE	http://localhost:8030↗	OLAP 查询界面
MinIO Console	http://localhost:9001↗	对象存储管理
Temporal UI	http://localhost:8233↗	工作流监控
Kafka UI	http://localhost:8082↗	消息队列监控

#第五步：运行示例项目

coomia-dip 内置了一个 "项目管理" 示例，帮助你快速理解核心概念：

Python

from ontology_sdk import OntoPlatform

platform = OntoPlatform(
    control_plane_url="localhost:50051",
    data_plane_url="localhost:50052"
)

# 1. 创建 ObjectType（本体类型定义）
project_type = platform.ontology.create_object_type(
    name="Project",
    display_name="项目",
    properties={
        "name": {"type": "string", "required": True},
        "status": {"type": "enum", "values": ["planning", "active", "completed"]},
        "budget": {"type": "decimal"},
        "start_date": {"type": "date"},
        "end_date": {"type": "date"}
    }
)
print(f"创建 ObjectType: {project_type.name} (rid={project_type.rid})")

# 2. 创建一个项目实例
project = platform.objects.create(
    object_type="Project",
    properties={
        "name": "coomia-dip v1.0",
        "status": "active",
        "budget": 500000,
        "start_date": "2024-01-01",
        "end_date": "2024-12-31"
    }
)
print(f"创建项目: {project.properties['name']} (rid={project.rid})")

# 3. 查询项目
results = platform.objects.search(
    object_type="Project",
    filter={"status": {"eq": "active"}}
)
for obj in results:
    print(f"  - {obj.properties['name']}: {obj.properties['status']}")

运行这个脚本后，你应该能看到：

Code

创建 ObjectType: Project (rid=ri.ontology.object-type.project-xxx)
创建项目: coomia-dip v1.0 (rid=ri.ontology.object.project-yyy)
  - coomia-dip v1.0: active

#部署架构图

本地部署的架构如下：

Code

┌─────────────────────────────────────────────────────────┐
│                    Developer Machine                      │
│                                                           │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────┐  │
│  │ Python SDK  │  │  gRPC Client │  │  Web Console    │  │
│  │ (pip)       │  │  (grpcurl)   │  │  (localhost:3000)│  │
│  └──────┬──────┘  └──────┬───────┘  └────────┬────────┘  │
│         │                │                    │           │
│  ═══════╪════════════════╪════════════════════╪═══════    │
│         │         Docker Network              │           │
│  ┌──────▼──────┐  ┌──────▼───────┐  ┌────────▼────────┐  │
│  │Control Layer│  │  Data Layer  │  │Intelligence     │  │
│  │ :50051 gRPC │  │ :50052 gRPC  │  │Layer :50053 gRPC│  │
│  └──────┬──────┘  └──────┬───────┘  └────────┬────────┘  │
│         │                │                    │           │
│  ┌──────▼────────────────▼────────────────────▼────────┐  │
│  │              Infrastructure Layer                    │  │
│  │  PostgreSQL │ Doris │ Kafka │ MinIO │ Nessie │Tempo  │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

#资源管理与清理

#停止服务

Bash

# 停止所有服务（保留数据卷）
docker compose stop

# 再次启动
docker compose start

#完全清理

Bash

# 停止并删除所有容器和网络
docker compose down

# 如果需要同时删除数据卷（谨慎操作！）
docker compose down -v

#查看资源占用

Bash

# 查看容器资源使用情况
docker stats --no-stream

# 查看磁盘占用
docker system df

#下一步

恭喜！你已经成功在本地部署了 coomia-dip。接下来，你可以：

第一个 Ontology — 深入了解 ObjectType 和 RelationType 的创建
第一条数据 — 学习实体的增删改查操作
第一个 Action — 定义并执行业务操作
OQL 查询指南 — 掌握强大的 Ontology 查询语言

#常见问题

#Q: coomia-dip 和 Palantir Foundry 有什么区别？

coomia-dip 是 Palantir Foundry 的开源替代方案。它实现了 Foundry 的核心概念——本体驱动（Ontology-driven）、数据融合、推理决策——但采用完全开源的技术栈。主要区别在于：

许可模式：coomia-dip 完全开源（Apache 2.0），Foundry 是商业许可
部署方式：coomia-dip 支持私有化部署和自托管，Foundry 主要以 SaaS 形式提供
技术栈：coomia-dip 使用 Spring Boot + Quarkus + FastAPI + gRPC，Foundry 使用私有技术栈
扩展性：coomia-dip 的插件和自定义函数机制更加开放

#Q: 最低配置需要多少资源？

最小化部署（使用 docker-compose.minimal.yml）需要：

4 核 CPU
8 GB 内存
10 GB 磁盘空间

最小化模式会禁用 Doris（使用 PostgreSQL 替代 OLAP 查询）和 Temporal，适合快速体验核心功能。

#Q: 支持 Kubernetes 部署吗？

是的，coomia-dip 提供了 Helm Chart 用于 Kubernetes 部署。详见生产部署检查清单。

#Q: 如何升级版本？

Bash

# 拉取最新代码
git pull origin main

# 拉取最新镜像
docker compose pull

# 重新启动（自动执行数据库迁移）
docker compose up -d

#Q: 数据持久化在哪里？

所有数据存储在 Docker 命名卷中：

coomia-dip-postgres-data：PostgreSQL 数据
coomia-dip-doris-data：Doris 数据
coomia-dip-kafka-data：Kafka 消息
coomia-dip-minio-data：MinIO 对象存储
coomia-dip-nessie-data：Nessie 版本数据

#总结

在这篇教程中，我们完成了以下步骤：

环境准备：验证 Docker、Git、Python 等工具的版本
克隆项目：获取 coomia-dip 源码并了解项目结构
配置环境：复制并检查环境变量配置
一键部署：使用 docker compose up -d 启动全部服务
验证部署：通过健康检查、SDK 连接、示例项目确认平台正常运行

整个过程不超过 5 分钟（不含镜像下载时间），你已经拥有了一个功能完整的本体驱动智能决策平台。在后续的教程中，我们将深入探索 coomia-dip 的每一个核心能力。

本文是 coomia-dip 开发者教程系列的第 1 篇。coomia-dip 是一个开源的 Palantir Foundry 替代方案，致力于让每个企业都能拥有世界级的数据智能平台。

项目地址：https://github.com/coomia-dip/coomia-dip↗ 许可证：Apache License 2.0