vitepress-template

Appearance

数据库设计 ​

**本文引用的文件** - [[bi-basic/docs/base.sql]](../file/bi-basic/docs/base.sql) - [[bi-basic/docs/base_category.sql]](../file/bi-basic/docs/base-category.sql) - [[bi-analysis/docs/database/design.md]](../file/bi-analysis/docs/database/design.md) - [[bi-analysis/docs/database/schema.sql]](../file/bi-analysis/docs/database/schema.sql) - [[bi-tenant/docs/database/schema.sql]](../file/bi-tenant/docs/database/schema.sql) - [[bi-sys/docs/database/schema.sql]](../file/bi-sys/docs/database/schema.sql) - [[bi-common/database/gormx/config.go]](../file/bi-common/database/gormx/config.go) - [[bi-common/database/gormx/option.go]](../file/bi-common/database/gormx/option.go) - [[bi-common/database/gormx/setup.go]](../file/bi-common/database/gormx/setup.go) - [[mcp-server-starrocks/src/mcp_server_starrocks/server.py]](../file/mcp-server-starrocks/src/mcp-server-starrocks/server.py)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介 ​

本文件面向BI分析平台的数据库设计，系统性阐述StarRocks OLAP与MySQL关系型数据库的设计理念、表结构组织、索引与分区策略、查询优化与性能调优、数据字典与业务规则、以及数据迁移与版本管理策略。文档同时提供Schema变更指南与最佳实践，帮助开发者高效、稳定地维护与扩展数据库。

项目结构 ​

本仓库包含多套数据库设计与实现：

  • StarRocks OLAP层：面向BI分析的宽表与维度表设计，强调高并发查询与快速聚合。
  • MySQL层：面向业务系统的事务型表，配合GORM连接池与日志配置。
  • BI分析系统：定义指标、维度、模板等元数据表，支撑前端可视化与分析配置。

图表来源

章节来源

核心组件 ​

  • StarRocks基础业务表：围绕订单、商品、店铺、售后、账期等核心业务实体构建宽表，采用主键表与位图索引提升分析效率。
  • BI分析元数据表：anls_table/anls_dimension/anls_field/anls_field_meta/anls_template/anls_date等，支撑指标、维度、模板与日期维度的统一管理。
  • MySQL系统表：tenant/sys模块的用户、菜单、角色、登录日志等，结合gormx连接池与日志配置，保障事务一致性与可观测性。
  • 连接与运维：mcp-server-starrocks提供StarRocks元数据查询能力；gormx提供统一的数据库初始化与连接池优化。

章节来源

架构总览 ​

下图展示StarRocks与MySQL在BI分析平台中的协作关系：MySQL承载业务与系统数据，StarRocks承载分析宽表与元数据，前端通过分析系统配置指标与维度，最终在StarRocks上执行高性能聚合查询。

图表来源

详细组件分析 ​

StarRocks OLAP表设计（基础业务与分析元数据） ​

  • 基础业务表（主键表）

    • base_order：主键(i_order_id, i_order_goods_id)，分布式哈希(i_order_id)，位图索引(c_sku_id)。
    • base_goods：主键(i_id)，分布式哈希(i_id)，位图索引(c_product_id, c_outer_id)。
    • base_shop：主键(id)，分布式哈希(id)，位图索引(i_user_id)。
    • base_after_sale_order：主键(c_net_billcode, i_shop_id, c_refund_id)，分布式哈希(c_net_billcode)。
    • base_order_bill_period：主键(i_order_id, i_shop_id)，分布式哈希(i_order_id)。
    • base_goods_sku：主键(outer_sku_id, goods_id, sku_id)，分布式哈希(outer_sku_id)，位图索引(b_api, sku_id)。
    • base_goods_sku_inventory：主键(id)，分布式哈希(id)。
    • base_good_category：主键(category_id)，分布式哈希(category_id)，位图索引(cid, parent_id)。
    • base_custom_category：主键(category_id)，分布式哈希(category_id)，位图索引(parent_id, shop_id, tenant_id)。
    • 成本管理相关表：erp_cost_item/erp_sku_cost/erp_order_cost/erp_delivery_fee/erp_account/erp_sku_shop_map等，均为主键表或Duplicate Key表，并建立位图索引加速过滤。
    • 复购分析表：base_repeat_shopping，主键(c_batch, c_net_billcode)，位图索引(c_vip_uid, i_shop_id)。
    • 试用分析表：base_sd_order/base_sd_import_batch/base_sd_import_detail，主键与位图索引设计满足高频过滤需求。
    • 商品链接分析模板：base_goods_link_template，主键(id)，位图索引(tenant_id)。
    • 出库单据：erp_out_order，主键(id)，位图索引(tenant_id, i_shop_id)。

  • 分析元数据表

    • anls_table：数据表配置，唯一索引(c_table_name)，位图索引(status, deleted_at)。
    • anls_dimension：维度配置，唯一索引(c_key)，位图索引(status, deleted_at)。
    • anls_field：指标字段配置，唯一索引(c_field)，位图索引(tenant_id, c_group, c_type, status, deleted_at)。
    • anls_field_group：指标分组，位图索引(status, deleted_at)。
    • anls_template：模板配置，位图索引(tenant_id, status, deleted_at)。
    • anls_field_meta：字段元数据，联合唯一索引(c_group, c_table_field)，位图索引(c_group, is_metric, is_filter, status, deleted_at)。
    • anls_user_home_layout：用户首页布局配置，位图索引(tenant_id, user_id, c_type, deleted_at)。
    • anls_field_visible_config：字段可见性配置，位图索引(tenant_id, user_id, c_template_id, deleted_at)。
    • anls_date：日期维度表，主键(t_date)，预填充2020-2050年日期序列。

  • 分区与归档

    • 登录日志表（tenant_login_log/sys_login_log）：Duplicate Key + 动态分区，按login_time范围分区，启用动态分区（月粒度，回溯12个月，前瞻1个月）。

图表来源

章节来源

MySQL关系型表设计（系统与租户） ​

  • 系统管理表（sys_*）：菜单、角色、用户角色关联、登录日志等，采用主键表与位图索引，登录日志表支持动态分区。
  • 租户系统表（tenant_*）：租户、用户、角色、权限、登录日志等，登录日志表同样采用Duplicate Key + 动态分区。

章节来源

数据字典与字段含义 ​

  • 订单表（base_order）：包含主订单编号、子订单编号、店铺ID、平台、类目、付款时间、订单状态、商品ID/SKU、付款金额、数量、成本、运费、平台扣点、买家ID、试用标记、退款标记、虚拟商品标记、成本/运费核销标记、无成本标记、礼物标记、创建/更新时间等。
  • 商品表（base_goods）：商品唯一ID、关联店铺ID、平台、平台商品ID、商家编码、标题、主图URL、价格、累计销售额、平台类目、类目名称、首次上架/创建日期、累计销量、上架状态、虚拟商品标记、自定义类目ID、商品经理/助理/负责人ID、商家状态、运营状态、创建/更新时间。
  • 店铺表（base_shop）：店铺唯一ID、操作用户ID、平台店铺唯一标识、A/B测试名称、店铺名称、平台ID、卖家昵称、来源类型、海外店铺标记、创建时间、启用状态、智图AI/云图授权状态、利润转化率、平台扣点转化率、试用费用、试用单基础运费、试用订单运费、是否更新外部商品ID、生意参谋类目、试用状态标志、无效成交标记、支付项金额、是否下载城市广告报表、默认商品经理/助理/主管操作员ID、是否开启推广/支付宝API、订单/支付宝/推广授权状态。
  • 售后订单表（base_after_sale_order）：关联主订单编号、关联店铺ID、退款唯一标识、退款申请提交时间、关联子订单编号、退款类型、退款处理完成时间、退款商品件数、退款原因、售后备注、退款金额、成本冲减金额、扣点冲减金额、买家ID、是否全额退款、是否试用订单。
  • 订单账期表（base_order_bill_period）：关联主订单编号、关联店铺ID、关联子订单编号、账期时间、付款时间、订单标记、关联商品ID、账期场景、账期金额、账期描述、账期备注、目标账户。
  • 商品SKU表（base_goods_sku）：商家编码（复合主键）、关联商品ID（复合主键）、平台SKU ID（复合主键）、SKU唯一ID、关联店铺ID、SPU编码、规格属性JSON、SKU图片URL、SKU价格、SKU状态、成本价、销售价、库存数量、淘宝库存数量、创建/更新时间、成本管理扩展字段（数据来源、ERP账号ID、运费单价、是否组合装、平台标识、商品名称、平台创建/修改时间）。
  • SKU库存表（base_goods_sku_inventory）：库存记录唯一ID、关联SKU ID、库存类型Key/名称、库存数量、创建/更新时间。
  • 商品类目表（base_good_category）：类目ID（主键）、平台、平台类目ID、类目名称、是否父类、父类类目ID、等级、类目路径ID/名称、创建/更新/删除时间。
  • 自定义类目表（base_custom_category）：类目ID（主键）、租户ID、店铺ID、平台、类目标识、类目名称、是否父类、父类类目ID、等级、类目路径ID/名称、排序、创建/更新/删除时间。
  • 成本管理表族：erp_cost_item/erp_sku_cost/erp_order_cost/erp_delivery_fee/erp_account/erp_sku_shop_map等，字段覆盖成本价、售价、运费单价、平台创建/修改时间、租户/用户/ERP账号ID、来源类型、平台ID、商品/SKU信息、导入/覆盖标记、删除标记等。
  • 复购分析表（base_repeat_shopping）：批次标识（复合主键）、订单号（复合主键）、店铺ID、平台ID、商品ID/SKU、商家编码、SKU商家编码、商品标题/图片、平台类目、上架状态、首次上架/创建日期、自定义类目ID、对接经理/助理/负责人ID、运营状态、SKU名称、买家ID、付款时间、付款金额、购买数量、店铺名称、旗帜标记、创建/修改/删除时间戳。
  • 试用分析表：base_sd_order/base_sd_import_batch/base_sd_import_detail，字段覆盖租户/店铺/订单、平台、付款时间、订单状态、旗帜标记、商品/SKU、付款金额、数量、运费、平台扣点、试用费用、成本/运费冲减、买家ID、数据来源、创建/更新/删除时间戳、批次状态等。
  • 商品链接分析模板（base_goods_link_template）：模板ID、租户ID、用户/操作人ID、模板名称、指标字段集合、类型、备注、排序、状态、创建/更新时间。
  • 出库单据（erp_out_order）：主键ID、租户ID、店铺ID、ERP类型、出库单号、主/子单号、外部商品/SKU编码、状态/类型、数量、物流名称/单号、商品成本、出库日期/时间、修改/开始/支付时间。

章节来源

索引设计原则 ​

  • 主键表：DISTRIBUTED BY HASH必须使用主键列，确保数据均匀分布与高效定位。
  • 位图索引（BITMAP）：广泛应用于高基数维度字段（如c_sku_id、c_vip_uid、tenant_id、platform等），加速过滤与Join。
  • 联合唯一索引：anls_field_meta(c_group, c_table_field)保证同一分组下字段名唯一，避免重复与歧义。
  • Duplicate Key表：sys_login_log/tenant_login_log的分区列需置于定义前列，确保分区与去重逻辑正确。

章节来源

数据分区策略 ​

  • 时间维度分区：登录日志表采用PARTITION BY RANGE(login_time)，动态分区（月粒度），回溯12个月，前瞻1个月，分区前缀“p”，桶数8。
  • 日期维度表：anls_date预填充2020-2050年日期序列，包含周、月、季度、年、周几、月中第几天、年中第几周、周起止日期、周显示名称等派生字段，支撑时间维度分析。

章节来源

SQL查询优化与性能调优 ​

  • 选择合适的分布式键：主键表DISTRIBUTED BY HASH使用主键列，避免热点；Duplicate Key表的分区键需在定义前列。
  • 位图索引优化：对高选择性维度（如c_sku_id、c_vip_uid、tenant_id、platform）建立位图索引，减少扫描。
  • 聚合与过滤前置：尽量在上游或ETL阶段完成维度派生与过滤，降低查询期计算量。
  • 动态分区裁剪：利用时间分区键进行范围裁剪，避免全表扫描。
  • 连接池优化：StarRocks驱动建议MaxIdleConns=MaxOpenConns，禁用空闲连接回收，保持稳定连接池大小。
  • 慢查询日志：设置合理的慢查询阈值，结合位图索引与分区裁剪定位瓶颈。

章节来源

数据迁移策略与版本管理 ​

  • 元数据表版本演进：anls_field_meta字段类型从字符串升级为JSON，支持c_date_type/c_operators/c_enum_values等复杂元数据，新增联合唯一索引与c_related_filters字段，增强指标级筛选能力。
  • 物理列名一致性：指标字段物理列名与c_field保持一致，便于跨表关联与查询。
  • 租户隔离：anls_field引入tenant_id字段，支持租户级指标配置与模板。
  • 初始化数据：anls_dimension提供18条维度配置初始化数据，便于快速上线。

章节来源

Schema变更指南与最佳实践 ​

  • 变更前评估：确认影响范围（表/索引/分区/元数据），评估查询路径与索引命中率。
  • 兼容性设计：优先采用向后兼容的字段扩展与索引新增，避免破坏现有查询。
  • 分批发布：先灰度到部分租户/分区，验证性能与稳定性后再全量发布。
  • 元数据同步：变更后同步anls_field_meta与anls_field配置，确保前端渲染与校验一致。
  • 回滚预案：保留历史DDL与快照，确保可回滚至最近稳定版本。

章节来源

依赖分析 ​

  • StarRocks与MySQL的耦合点：MySQL系统表与租户表为StarRocks基础业务表提供上下文（如租户ID、店铺ID、平台ID），分析元数据表为查询提供维度与指标配置。
  • 连接与运维：mcp-server-starrocks通过SHOW DATABASES/SHOW TABLES/SHOW CREATE TABLE等资源接口，暴露StarRocks元数据，便于自动化运维与Schema管理。
  • ORM与连接池：gormx提供统一的DSN生成、TLS配置、连接池优化（尤其针对StarRocks）与日志配置，简化开发与部署。

图表来源

章节来源

性能考虑 ​

  • 分布式键选择：主键表与Duplicate Key表的分布式键直接影响数据分布与查询性能，应与查询模式匹配。
  • 位图索引：对高基数维度建立位图索引，显著提升过滤与Join效率。
  • 动态分区：按时间维度分区并启用动态分区，减少冷数据扫描，提升查询响应。
  • 连接池优化：StarRocks场景下建议MaxIdleConns=MaxOpenConns，禁用空闲连接回收，降低连接抖动。
  • 慢查询治理：通过慢查询阈值与日志级别，定位热点查询并优化索引与分区策略。

故障排查指南 ​

  • 元数据查询：通过mcp-server-starrocks的资源接口查看数据库、表与Schema，快速定位DDL问题。
  • 连接问题：检查DSN参数（字符集、TLS、参数插值）、连接池配置（MaxOpenConns/MaxIdleConns/ConnMaxLifetime/ConnMaxIdleTime）与日志级别。
  • 分区异常：检查动态分区配置（time_unit/start/end/prefix/buckets）与分区键类型，确保login_time为DATETIME且分区键在定义前列。
  • 索引失效：确认位图索引建立在高选择性维度上，且查询谓词能命中索引。

章节来源

结论 ​

本设计以StarRocks为核心，结合MySQL系统表与分析元数据表，形成“业务+分析”的双引擎架构。通过主键表、位图索引、动态分区与连接池优化，实现高并发、低延迟的BI分析能力。配套的元数据表与版本管理机制，确保指标与维度的灵活扩展与稳定演进。遵循Schema变更指南与最佳实践，可进一步提升系统的可维护性与可扩展性。

附录 ​