引言

数仓成熟后，最困扰你的往往不是数据缺失，而是那些散落在各处、难以捉摸的“业务指标”。

大家好，这是我第一次从零独立做完并开源的一个小型平台——sqldm（SQL-Driven Metrics），一个轻量级的指标管理系统。经验有限，欢迎拍砖、提 Issue、给建议。

背景：数仓成熟后，指标往往「散」了

当数据仓库建设到一定程度后，团队面临的常见问题往往不再是“有没有数据”，而是：

• 业务指标散落各处：定义藏在不同的 SQL 脚本、文档甚至口头约定里。
• 新人上手成本高：需要翻找大量代码或反复询问老员工才能理解指标含义。
• 口径混乱不一致：同名指标不同口径，或同口径有不同 SQL 实现，极易混淆。
• 变更缺乏流程：指标定义谁都能改，缺乏审批与追溯，导致数据可信度下降。

为了解决这些问题，我开发了 sqldm。它的核心目标是：将指标的业务含义、SQL 模板、参数、归属主题等元数据集中化管理，并通过审批流程控制变更，最终对外提供统一的 Open API，方便下游系统（如报表、数据应用）标准化地获取指标定义。

系统概览与技术栈

核心功能

• 指标集中管理：统一维护指标的业务元数据和计算逻辑（SQL模板）。
• 权限与审批流：基于主题域的精细化权限控制，所有变更需经审批生效。
• Open API 服务：指标启用后自动生成 API 地址和调用示例，便于集成。

技术栈（简要）

• 后端：Java 21 + Spring Boot 3.2
• 数据库：PostgreSQL（表结构需手工初始化，适合对接已有数据库环境）
• 前端：原生 HTML/JS，单体应用，无需独立前端工程
• 部署：支持 Windows/Linux 脚本一键启动，也支持 Docker 容器化部署（使用外部数据库）

核心设计详解

1. 角色与权限体系

系统按“主题域”划分数据权限，共有三种系统角色：

角色	能做什么
超级管理员	用户/主题管理、全局审批、指标删除等
主题管理员	在所负责的主题内审批指标变更；可为普通用户分配主题成员身份
普通用户	在所分配的主题下创建、编辑指标（所有变更需走审批流程）

用户在主题内的身份由其系统角色自动推导：主题管理员在主题内即为“审批员”，普通用户则为“成员”。

【配图 1：用户与主题分配界面】

2. 指标元数据模型

每个指标可以配置以下核心信息：

• 基础信息：指标名称、唯一编码、业务口径说明。
• 管理信息：统计周期（如日、月）、负责人、所属数据源。
• 计算逻辑：SQL 模板，支持 ${参数名} 形式的占位符，实现动态查询。
• 参数定义：与 SQL 模板中的占位符对应的参数列表，定义其名称、类型和示例值。
• 归属主题：指定该指标所属的业务主题域。

指标一旦“启用”，系统会自动为其生成唯一的 Open API 访问地址 和 cURL 调用示例，下游系统可直接通过指标编码拉取最新的指标定义。

【配图 2：指标列表页】

【配图 3：指标编辑页】

3. 审批流程

为了保障指标定义的准确性与一致性，sqldm 设计了简单的审批流：

1. 提交变更：普通用户新增、修改或删除指标后，变更进入“待审批”状态。
2. 审批生效：由该指标所属主题的“主题管理员”或“超级管理员”进行审批。审批通过后，变更才正式生效。
3. 锁定机制：处于“待审批”状态的指标会被锁定，避免半成品定义被下游系统使用。

（注：如有待审批列表截图可补充于此；若无，配图1中的“待审批”按钮已能示意此流程。）

快速上手（3步部署）

1. 初始化数据库：由 DBA 手工执行项目中的初始化 SQL 脚本（应用本身不自动建表）。
2. 配置连接：修改 deploy/config.env 配置文件，填入外部 PostgreSQL 数据库的连接信息。
3. 构建与启动：
   • 执行 mvn package 进行项目打包。
   • 根据操作系统，运行 start.sh (Linux/Mac) 或 start.ps1 (Windows) 一键启动应用。

默认管理员账号：root / root （部署后请务必修改密码！）

开源与交流

• GitHub 仓库：https://github.com/knowcai/sqldm
• 当前版本：V1.0.1
• 仓库内容：README.md 包含架构说明、部署文档和功能截图；更详细的部署指南请查看 deploy/DEPLOY.md。

欢迎 Star、提交 Issue 或 Pull Request！如果你也在进行数仓建设或指标治理，我非常期待听到你的实际场景、遇到的坑以及宝贵的实践经验。