highlight.io 后端开发指南：PostgreSQL 迁移、数据库检查与 GraphQL 代码生成

• 可观测性
• 后端

本篇技术指南面向 highlight.io 开源仓库的贡献者与二次开发者，聚焦于 GraphQL 后端（backend/）日常开发中最常遇到的三个问题：如何安全地变更 PostgreSQL 表结构（schema 迁移）、如何直接进入本地数据库检查数据，以及如何基于 GraphQL Schema 重新生成服务端代码。读完本文，你将掌握 highlight.io 后端的迁移机制与自动化流程，能够独立完成"改模型 → 跑迁移 → 检查数据 → 改 GraphQL Schema → 重新生成代码"的完整开发闭环。

一文读懂 highlight.io 的后端架构

highlight.io 的后端采用 Go 语言编写，核心入口位于 backend/main.go。它对外暴露两套 GraphQL API：

• Private Graph（私有图）：面向 highlight.io 前端控制台，提供会话、错误、日志、告警等管理类查询与变更，Schema 定义在 backend/private-graph/graph/schema.graphqls；
• Public Graph（公有图）：面向被监控应用的前端 SDK，接收客户端上报的数据，Schema 定义在 backend/public-graph/graph/schema.graphqls。

两套 API 均由 gqlgen（Go 的 GraphQL 代码生成框架）驱动。数据层则主要依赖 GORM（Go ORM）操作 PostgreSQL，因此后端开发中的"加字段、建表"通常不是手写 SQL 迁移脚本，而是修改 Go 模型结构后交由 GORM 自动迁移完成——这正是本文要展开的第一条核心工作流。

FAQ 一：如何将 Schema 变更迁移到 PostgreSQL？

迁移机制：一切围绕 model.go 展开

highlight.io 的 PostgreSQL 表结构全部以 GORM 模型定义在 backend/model/model.go 中。当你修改或新增模型后，不需要手写CREATE TABLE/ALTER TABLE语句，迁移由 GORM 的AutoMigrate自动完成。

AutoMigrate的触发入口是MigrateDB函数（backend/model/model.go#L1503-L1535），其执行流程为：

1. 创建pgcrypto、vector、uuid-ossp等 PostgreSQL 扩展；
2. 创建用于生成不可猜测短链接 ID 的secure_id_generatorPL/pgSQL 函数；
3. 对 Models 列表 中注册的所有模型执行DB.AutoMigrate(Models...)；
4. 执行少量需要手动干预的 SQL（例如为error_fingerprints.error_group_id去除 NOT NULL 约束、创建物化视图等）。

从源码结构看，MigrateDB采取"AutoMigrate 为主 + 少量手工 SQL 为辅"的策略：常规的字段增删改都交给 GORM 推断，个别 GORM 处理不了的约束或视图则显式补充，这正是该项目多年迭代后仍然稳定的原因。

新表必须注册进 Models 列表

新增一张表时，只定义结构体是不够的，必须把新模型追加到 Models 切片 中，例如：

var Models = []interface{}{ &ErrorObject{}, &ErrorGroup{}, &Organization{}, &Project{}, // ... 你的新模型 &MyNewModel{}, }

只有当模型出现在这个列表里，DB.AutoMigrate(Models...)才会为它建表或更新表结构。这是迁移能否生效的关键一步。

迁移在何时自动执行？

迁移的触发时机有两条路径，均在仓库源码中可查证：

• 本地开发环境：在 backend/main.go#L258-L264 中，当env.IsDevEnv()为真时，服务启动后立即调用model.MigrateDB(ctx, db)。也就是说，开发模式下只要重启后端服务，schema 变更就会自动应用到本地 PostgreSQL；
• 生产部署：由 GitHub Action 在部署流程中执行迁移，同时仓库提供了独立的迁移命令入口 backend/migrations/main.go，可通过 Makefile 中的migrate目标手动触发：

cd backend make migrate # 等价于: doppler run -- go run ./migrations/main.go

需要注意：迁移只保证"本地 dev 自动执行"，修改模型后请务必重启本地后端，或显式运行make migrate，让新表/新字段真正落到数据库。

生产迁移的注意事项

从 backend/main.go 的启动逻辑可见，MigrateDB仅在开发环境（env.IsDevEnv()）下自动运行，生产环境则依赖部署流水线中的迁移步骤。因此贡献者在提交涉及数据表的 PR 时，应当在 PR 描述中明确标注"需要执行迁移或回填数据"——仓库的 .github/PULL_REQUEST_TEMPLATE.md 中专门设有 "Are there any deployment considerations?" 一栏，其中明确提示后端改动要考虑 migrations 或 backfilling data。

FAQ 二：如何检查本地 PostgreSQL 数据库？

迁移完成后，你可能需要直接查看表结构或数据，最直接的方式是进入本地 Docker 容器中的 PostgreSQL CLI：

cd docker docker compose exec postgres psql -h localhost -U postgres postgres

执行后会进入一个连接到本地 postgres Docker 容器的 psql 交互终端。常用检查命令：

• \d：列出当前数据库的所有表；
• \d projects：查看projects这张表的详细 schema（列、类型、约束、索引）；
• select * from sessions limit 10;：查看sessions表中的数据（注意原文档中的show是笔误，psql 中查询数据应使用标准的SELECT语句）。

典型排查场景包括：确认AutoMigrate是否真的为你的新字段建了列（\d 表名）、检查迁移后数据是否完整（select查询）、以及验证外键/唯一索引是否符合预期。这条链路与 backend/model/model.go 中 GORM 标签（如gorm:"uniqueIndex"、gorm:"type:jsonb"）所定义的约束一一对应，是验证迁移结果最可靠的手段。

FAQ 三：如何生成 GraphQL 服务端定义？

生成命令与适用场景

highlight.io 的 GraphQL 服务端代码完全由 gqlgen 从 Schema 生成。每当你修改了.graphqls文件，都必须重新生成代码，否则运行时会出现字段不匹配。

根据 backend/Makefile 的定义，生成命令如下：

cd backend make private-gen # 修改 private-graph 的 schema.graphqls 后执行 make public-gen # 修改 public-graph 的 schema.graphqls 后执行

两条命令的底层实现（backend/Makefile#L9-L12）分别是：

public-gen: (cd ./public-graph; go run github.com/99designs/gqlgen) private-gen: (cd ./private-graph; go run github.com/99designs/gqlgen)

即在对应的 graph 目录下直接运行 gqlgen 工具。它们也可以在 Docker 容器内执行（等价于在backend目录下依次运行上述两条 make 目标）。

生成产物与配置说明

生成行为由各自的gqlgen.yml配置控制，以 backend/private-graph/gqlgen.yml 为例，其关键配置为：

• schema：graph/*.graphqls，即 Schema 源文件；
• exec：输出到graph/generated/generated.go，即生成的执行器（executor）代码；
• model：输出到graph/model/models_gen.go，即由 Schema 推断生成的 Go 模型；
• resolver：layout: follow-schema，输出到graph目录，即 Resolver 实现骨架；
• autobind：绑定backend/model等 Go 包，使 gqlgen 优先复用已存在的类型（如Timestamp、StringArray、Field）；
• models：声明 GraphQL 标量与 Go 类型之间的映射（例如Timestamp映射到model.Timestamp，ID映射到 gqlgen 的IntID）。

生成后你会看到 backend/private-graph/graph/generated/ 与 backend/public-graph/graph/generated/ 目录被刷新。其中 generated 目录是 gqlgen 自动生成的产物，通常不应手工修改；业务逻辑写在schema.resolvers.go中。

改 Schema 的完整工作流

一次典型的 GraphQL 后端改动流程如下：

1. 编辑 Schema 文件，例如在 backend/public-graph/graph/schema.graphqls 中新增一个input或查询字段；
2. 运行cd backend && make public-gen（或make private-gen）重新生成代码；
3. 在生成的schema.resolvers.go中实现 Resolver 逻辑；
4. 涉及新数据字段时，同步修改 backend/model/model.go 中的模型，并确保其注册进Models列表；
5. 重启本地服务（dev 环境自动迁移）或运行make migrate让表结构生效；
6. 用psql检查迁移结果，用测试（如 backend/private-graph/graph/resolver_test.go、backend/public-graph/graph/resolver_test.go）验证 Resolver 行为。

CI 质量门禁

仓库的 .github/workflows/backend.yml 为后端代码设置了多项 CI 检查，与本主题相关的主要有：格式检查（gofmt）、禁止在业务代码中直接调用os.Getenv（统一走环境变量抽象）、以及强制 GORM 调用必须携带 Context（防止无上下文数据库操作）。这提醒贡献者：在提交后端改动时，新写的 GORM 查询应使用WithContext风格调用，避免触发 CI 拦截。

总结：后端开发的黄金闭环

综合仓库源码与官方贡献文档，highlight.io 的后端日常开发实际上是一条非常标准化的流水线：

掌握这条闭环，你就能以最小的摩擦参与 highlight.io 的 GraphQL 后端开发：改模型、跑迁移、查数据、改 Schema、再生成、最后测试提交，每一步都有明确的命令和可验证的源码依据。

• 可观测性
• 后端