如何在 asapBI 中运行本地 BI 堆栈？

使用 docker-compose.yml 启动 PostgreSQL 和 ClickHouse。安装 Docker Desktop 后，通过 asapBI 界面或 CLI 启动。

asapBI 中的图形化视图是什么？

带有 SQL 逻辑的 JSON 文件，支持 Git 版本控制和代码审查。为仪表板提供单一真相来源。

如何用测试数据填充本地数据库？

通过带有复制规则的 *.dbcopy-json 文件，前/后 SQL。仅来自开发服务器的测试数据。

asapBI 中的离线 BI：Docker 和 ClickHouse

asapBI离线开发：本地栈与可视化视图

asapBI提供完整的离线BI开发支持。系统采用本地Docker栈，集成PostgreSQL与ClickHouse，可视化SQL视图以JSON文件形式存储，并通过Git进行版本管理。开发者可在无需依赖远程服务器的情况下构建查询、实验数据并记录逻辑，彻底避免因网络不稳定导致的中断问题。

本地环境确保数据隔离、安全实验和版本控制。开发人员可完全掌控容器的存储卷、CPU及内存分配。

本地栈的优势

本地开发有效解决团队协作中的核心痛点：

数据隔离：Docker卷受保护，不受外部变更影响。测试表不会因迁移或清理操作而丢失。
安全实验：复杂的JOIN操作或高负载视图仅影响本地容器，不影响共享集群。
Git版本控制：可视化视图以JSON格式保存，支持差异对比、代码审查与回滚。
数据库数字孪生：可在不影响生产环境的前提下，测试模式变更、数据类型调整与关系重构。

搭建离线开发环境

配置分为三步。

1. 从Git克隆项目

将项目下载至本地目录。项目结构按业务领域划分——财务、销售等。视图文件与dbcopy-json文件均存放于仓库中。

2. 通过Docker Compose启动BI栈

使用docker-compose.yml运行PostgreSQL与ClickHouse。示例配置如下：

services:
  asapbi-postgres:
    image: postgres:15-alpine
    container_name: asapbi-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: admin
      POSTGRES_DB: demo
      PGDATA: /var/lib/postgresql/data/pgdata
    ports:
      - "15432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U admin -d demo"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    networks:
      - asapbi-net

  asapbi-clickhouse:
    image: clickhouse/clickhouse-server:24.8-alpine
    container_name: asapbi-clickhouse
    restart: unless-stopped
    environment:
      CLICKHOUSE_USER: admin
      CLICKHOUSE_PASSWORD: admin
      CLICKHOUSE_DB: analytics
    ports:
      - "18123:8123"   # HTTP
      - "19000:9000"   # Native
    volumes:
      - clickhouse-data:/var/lib/clickhouse
      - clickhouse-logs:/var/log/clickhouse-server
    healthcheck:
      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    networks:
      - asapbi-net

volumes:
  postgres-data:
    driver: local
  clickhouse-data:
    driver: local
  clickhouse-logs:
    driver: local

networks:
  asapbi-net:
    driver: bridge

可通过asapBI界面或命令行启动。Docker将自动拉取所需镜像。

3. 使用测试数据填充数据库

通过*.dbcopy-json文件复制测试数据。示例：

{
  "description": "复制客户数据，含准备与清理步骤",
  "beforeSQL": [
    "BEGIN;",
    "SET session_replication_role = replica;",
    "CREATE TEMP TABLE IF NOT EXISTS _copy_log (ts timestamptz, msg text);"
  ],
  "afterSQL": [
    "SET session_replication_role = DEFAULT;",
    "INSERT INTO _copy_log VALUES (now(), '复制完成');",
    "COMMIT;"
  ],
  "tables": [
    {
      "schema": "reference",
      "table": "clients",
      "where": "is_active = true AND created_at >= '2024-01-01'",
      "beforeSQL": [
        "DROP INDEX IF EXISTS idx_clients_region_id",
        "DELETE FROM reference.clients WHERE created_at >= '2024-01-01'"
      ],
      "afterSQL": [
        "CREATE INDEX IF NOT EXISTS idx_clients_region_id ON reference.clients (region_id)",
        "ANALYZE reference.clients"
      ]
    },
    {
      "schema": "sales",
      "table": "orders",
      "where": "order_date >= '2024-01-01'",
      "beforeSQL": "ALTER TABLE sales.orders DISABLE TRIGGER ALL",
      "afterSQL": "ALTER TABLE sales.orders ENABLE TRIGGER ALL"
    },
    {
      "schema": "analytics",
      "table": "user_sessions",
      "where": "",
      "beforeSQL": null,
      "afterSQL": null
    }
  ]
}

在界面中选择源库与目标库，仅使用开发环境的测试数据。

可视化SQL视图

连接本地ClickHouse实例，创建可视化视图。这些视图以JSON文件形式存在，支持版本控制与代码审查。视图与仪表板解耦，确保计算逻辑的单一可信来源。

优势包括：

计算逻辑集中存储。
可跨多个仪表板复用。
通过Git diff追踪变更历史。

文档集成

将文档文件（MD、draw.io）直接放入视图所在文件夹。当模型更新时，文档自动同步。文本文件便于AI处理与自动化文档生成。

核心要点

基于持久化卷的本地Docker栈，保障数据隔离与可靠性。
可视化视图为JSON文件，支持Git版本控制与同行评审。
*.dbcopy-json实现安全、可重复的测试数据复制。
在项目文件夹中嵌入文档（MD、draw.io），保持内容实时更新。
提供完整沙箱环境，实验无损生产稳定性。

— Editorial Team

asapBI 中的离线 BI：Docker 和 ClickHouse