GreptimeDB 仓库生成文件Generated Files管理指南哪些文件不可手改、如何正确重新生成【免费下载链接】greptimedbThe open-source observability database. One columnar engine for metrics, logs, and traces, on object storage.项目地址: https://gitcode.com/GitHub_Trending/gr/greptimedb本指南面向 GreptimeDB 的贡献者与二次开发者系统梳理仓库中由工具链自动产出的生成文件Generated Filessqlness 测试期望结果、配置文档、Grafana 仪表盘、build.rs构建期代码以及 Protobuf/gRPC 类型。文中说明每一类文件为何不能手改、底层生成机制如何工作、应当通过哪些命令在源头变更后重新生成并结合仓库中的 Makefile 目标、生成脚本与实际测试结构给出可验证的依据。为什么生成文件不可手改是仓库的硬性约定仓库在 .agents/generated-files.md 中开门见山地给出了约束这些产物由工具tooling生成手工编辑它们几乎总是错误的——你的修改要么在下次重新生成时被覆盖要么直接导致 CI 失败。正确的做法是修改源头源 SQL、示例 TOML、仪表盘 JSON、build.rs或上游依赖然后用约定的命令重新生成。这条约定背后有两层工程动因可重复性生成文件是结果其原因存在于源头文件中。只有原因可被版本管理、评审与回滚结果才会稳定CI 一致性仓库的检查工作流会验证生成文件与源头是否同步任何漂移都会被当作错误拦截详见下文各小节。sqlness.result文件由.sql用例驱动、由 runner 重写生成关系与存放位置sqlness 是 GreptimeDB 使用的 SQL 集成测试框架。每个用例由一对文件组成tests/cases/**/*.sql—— 贡献者编写的 SQL 用例源头同名的.result文件 —— runner 执行后记录的期望输出生成物。仓库中实际存在大量这样的配对例如 tests/cases/standalone/local_file_access.sql 与同目录的local_file_access.result。从源码可见其工作方式.sql中连续执行CREATE TABLE、INSERT、COPY TO、CREATE EXTERNAL TABLE、SELECT等语句.result则逐条记录每个语句的Affected Rows与查询结果表格例如COPY local_file_access_source TO local_file_access/table.parquet; -- 对应 .result 输出 -- Affected Rows: 2因此文档明确要求永远不要手工编辑.result。要更新期望结果应修改.sql或修正引擎行为本身然后重新运行测试由 runner 重写.result。运行命令cargo sqlness bare # 运行全部本地用例 cargo sqlness bare -t name # 仅运行单个用例执行后务必用git diff tests审查重新生成的输出确认期望值的变化符合预期。common目录是指向同一份文件的符号链接文档特别提示tests/cases/distributed/common是指向tests/cases/standalone/common的符号链接两者是同一批文件。这一点可以在仓库文件系统中直接验证tests/cases/distributed/common - ../standalone/common。含义包括修改其中一侧就等于同时修改两侧无需分别维护两套期望也不需要单独对比 standalone 与 distributed 的结果差异分布式与单机模式共享同一组公共 SQL 期望。例如tests/cases/distributed/下的local_file_access.sql/local_file_access.result与 standalone 版是独立副本而common子目录则完全共享。配置文档config/config.md由示例 TOML 与模板渲染生成config/config.md约 770 行覆盖 Standalone 与 Distributed 全部组件配置项不是手写的而是由两类源头合成的config/*.example.toml—— 各组件的示例配置standalone、frontend、metasrv、datanode、flownode 各一份见 config/ 目录config/config-docs-template.md—— 渲染模板其内容是一份目录骨架并在各组件小节中放置{{ toml2docs ./xxx.example.toml }}占位指令见 config/config-docs-template.md。重新生成命令make config-docs该目标在 Makefile 中定义实际通过 Docker 容器执行.PHONY: config-docs config-docs: ## Generate configuration documentation from toml files. docker run --rm \ -v ${PWD}:/greptimedb \ -w /greptimedb/config \ toml2docs/toml2docs:v0.1.3 \ -p ## \ -t ./config-docs-template.md \ -o ./config.md要点不要直接编辑config/config.md。若某个配置项说明有误或缺失应修改对应的*.example.toml含注释或模板再执行make config-docs重新渲染。从生成的config.md可以看到模板中的##标题层级与 TOML 注释中的Descriptions被逐项渲染为参数表格例如http.addr、mysql.enable、grpc.bind_addr等均带类型、默认值与详细说明。Grafana 仪表盘单一 JSON 为源脚本派生其余文件生成关系对于 metrics 仪表盘唯一的手写源头是集群版 JSONgrafana/dashboards/metrics/cluster/dashboard.json—— 编辑对象源头生成器在此基础上派生五个文件standalone 版dashboard.json—— 通过删除$datanode/$frontend/$metasrv/$flownode的 instance 过滤器得到集群版与 standalone 版的dashboard.yaml、dashboard.md—— 由dac工具从对应 JSON 转换而来。实际文件列表与文档一致grafana/dashboards/metrics/cluster/与grafana/dashboards/metrics/standalone/下各含dashboard.json、dashboard.yaml、dashboard.md三个文件。这六个文件中的五个standalone JSON 两套 yaml/md都不允许手改。重新生成命令make dashboards对应脚本 grafana/scripts/gen-dashboards.sh 的核心逻辑分两步remove_instance_filters用sed把集群版 JSON 中的instance~$datanode等过滤表达式删除得到 standalone 版 JSONgenerate_intermediate_dashboards_and_docs通过dac容器镜像ghcr.io/zyy17/dac分别把两版 JSON 转为dashboard.yaml与dashboard.md。CI 校验生成结果必须零漂移grafana/scripts/check.sh 把生成一致性直接固化进检查流程check_dashboards_generation() { ./grafana/scripts/gen-dashboards.sh if [[ -n $(git diff --name-only grafana/dashboards/metrics) ]]; then echo Error: The dashboards are not generated correctly. You should execute the make dashboards command. exit 1 fi }除此之外该脚本还会校验每个面板的描述非空以及 datasource uid 必须为${metrics}Prometheus或${information_schema}MySQL超出这些约束即报错。这意味着任何绕过make dashboards的手工改动都会被git diff捕获并导致 CI 失败。不属于生成器的两个例外grafana/dashboards/events/dashboard.json与grafana/dashboards/logs/dashboard.json不是该生成器的输出不在不可手改的约束范围内。当前仓库中实际存在grafana/dashboards/events/dashboard.jsonlogs目录暂未检出。build.rs生成代码产物在 OUT_DIR仓库里没有可编辑文件部分 crate 在构建期通过build.rs向 Cargo 的OUT_DIR生成代码涉及common-version构建/ Git 信息commit、分支、版本号等common-catalogcommon-function的系统表log-storeservers。这些生成的.rs文件不会 check-in 到仓库因此不存在可手工编辑的已提交文件。如需改动必须修改对应 crate 的build.rs或其输入如Cargo.toml、proto 文件、静态数据然后由构建系统在编译时重新生成。Protobuf / gRPC 类型来自仓库外部依赖GreptimeDB 的线格式wire format类型并非在本仓库内生成而是由外部的greptime-protocrate提供。因此本仓库中不存在需要手工维护的.proto生成物要修改线格式应在greptime-proto上游完成变更再升级本仓库对该依赖的版本引用这条约束在 .agents/generated-files.md 中被明确列出与仓库内log-store/proto/logstore.proto这类本地 proto 源文件是两回事——后者是源头而非生成物。License 头由工具检查、enterprise 门控文件需双列表同步License 头由korandoru/hawkeyev5在.github/workflows/checks.yml中检查。对于 enterprise 门控enterprise-gated文件除了常规检查外还需要同时更新两个 license 列表并执行make check-enterprise-license从仓库根目录的licenses/目录含README.md、enterprise-header.txt与 scripts/check-enterprise-license.py 可见其配套工具链。核心约定与全文一致源头变化后走生成/检查流程而不是手改产物。汇总贡献者工作流速查生成文件类别源头可编辑重新生成命令CI 校验tests/cases/**/*.result同名.sqlcargo sqlness bare [-t name]由测试运行结果保证config/config.mdconfig/*.example.tomlconfig-docs-template.mdmake config-docs文档生成一致性Grafana metrics 仪表盘standalone JSON、yaml、mdgrafana/dashboards/metrics/cluster/dashboard.jsonmake dashboardsgrafana/scripts/check.sh零漂移 描述 datasourcebuild.rs生成代码各 crate 的build.rs及输入构建期自动生成产物在OUT_DIR构建系统Protobuf / gRPC 类型外部greptime-proto上游升级依赖版本依赖构建License 头源码头部 licenses/列表make check-enterprise-licensehawkeyev5checks.yml实践要点总结提交前先自问这个文件是不是某条命令的产物若是一律修改源头每次修改源头后运行对应的make目标或cargo sqlness并用git diff审查生成结果不要为绕过 CI 而手工修好生成文件——CI 里的生成一致性检查如check_dashboards_generation就是为了捕获这类改动对于依赖上游生成的类型如greptime-proto改动必须回归到上游仓库并升级依赖而非在本仓库打补丁。遵循这套源头变更 → 重新生成 → diff 审查的流程既能避免无谓的合并冲突也能确保每一次提交都是可复现、可评审、与 CI 严格一致的。【免费下载链接】greptimedbThe open-source observability database. One columnar engine for metrics, logs, and traces, on object storage.项目地址: https://gitcode.com/GitHub_Trending/gr/greptimedb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考