数据 on 姚玉亮的网络日志

OpenAlex 学术数据同步：增量拉取与去重设计

Sat, 16 Nov 2024 10:30:00 +0800

2.5 亿条 Works，全量拉不动

我们在数据治理平台里需要把 OpenAlex 的学术数据（Works、Authors、Institutions 这些）同步到本地 MySQL，再通过 StarRocks 外表做多维分析。OpenAlex 的全量 Works 超过 2.5 亿条，每次全量拉，不仅耗时巨大，还频繁触发对方的限流。

所以诉求很明确：增量拉取，而且重复运行不能留脏数据。

游标、状态表，再加一个天然主键

方案拆开就三件事。

第一，增量靠游标分页加日期过滤。OpenAlex 支持 filter=from_publication_date 和 cursor 游标分页，天然适合增量：每次从上次记下的游标继续，不用从头翻页。

第二，断点靠一张 sync_state 表。每个实体记最后游标、最后同步日期和更新时间，任务中断了能接着跑。

第三，去重靠 OpenAlex 自己的 ID。每条记录都有全局唯一 ID（W123456 这种），直接拿来当业务主键，冲突就更新，不做插入。

同步任务跑在 Temporal Worker 上，单页失败自动重试，整个流程可观测、可恢复。

请求就一个 GET

请求封装很薄，带上了 mailto，后面会讲为什么：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


type OpenAlexClient struct {
 baseURL string
 email string // 加入 polite pool
 client *http.Client
}

type WorksResponse struct {
 Meta struct {
 Count int `json:"count"`
 NextCursor string `json:"next_cursor"`
 } `json:"meta"`
 Results []Work `json:"results"`
}

func (c *OpenAlexClient) FetchWorksPage(ctx context.Context, cursor, fromDate string) (*WorksResponse, error) {
 u := fmt.Sprintf("%s/works?filter=from_publication_date:%s&per_page=200&cursor=%s&mailto=%s",
 c.baseURL, fromDate, url.QueryEscape(cursor), c.email)

 req, err := http.NewRequestWithContext(ctx, "GET", u, nil)
 if err != nil {
 return nil, err
 }
 resp, err := c.client.Do(req)
 if err != nil {
 return nil, err
 }
 defer resp.Body.Close()

 var result WorksResponse
 if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
 return nil, err
 }
 return &result, nil
}

冲突就更新，别插入

去重写入用 GORM 的 OnConflict 子句，按 openalex_id 冲突时更新所有字段：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


func (r *WorkRepo) UpsertBatch(ctx context.Context, works []Work) error {
 if len(works) == 0 {
 return nil
 }
 return r.db.WithContext(ctx).
 Clauses(clause.OnConflict{
 Columns: []clause.Column{{Name: "openalex_id"}},
 UpdateAll: true,
 }).
 CreateInBatches(&works, 200).Error
}

主循环：翻页、落库、记游标

同步主循环从状态表读游标，逐页拉取并落库，最后更新游标：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


func (s *Syncer) SyncWorks(ctx context.Context) error {
 state, _ := s.stateRepo.Get(ctx, "works")
 cursor := state.Cursor
 if cursor == "" {
 cursor = "*"
 }

 for {
 page, err := s.client.FetchWorksPage(ctx, cursor, state.LastDate)
 if err != nil {
 return err // Temporal 会重试
 }
 if err := s.workRepo.UpsertBatch(ctx, page.Results); err != nil {
 return err
 }
 if page.Meta.NextCursor == "" {
 break
 }
 cursor = page.Meta.NextCursor
 _ = s.stateRepo.UpdateCursor(ctx, "works", cursor)
 }
 return nil
}

四个坑

游标不是永久有效的。间隔过久再拿同一个游标去请求，可能直接报错。我们的做法是每次同步完成后检查：如果游标已过期，就回退到按日期重新拉最近 7 天的数据，靠 Upsert 兜底去重。

per_page 最大 200。一开始设的 100，翻页次数多了一倍；调到 200 之后整体耗时明显下降，代价是单次响应体变大，HTTP client 的超时要设置得合理一些。

限流和 politeness 直接挂钩。请求里带上 mailto 参数就能进 Polite Pool，限流明显宽松：不加的话大约 10 请求/秒就可能被 429，加了之后基本能跑到 20 以上。一行参数的事，没理由不加。

MySQL 写完还要进 StarRocks。我们用 Routine Load 订阅 Binlog 做同步，避免双写。偶尔 DDL 变更会把 Routine Load 暂停掉，这个只能靠监控告警兜着，不然数据就悄悄断流了。

后来

这套方案上线后稳定跑了几个月，没出过数据重复或丢失。回头看没有什么高深的地方：游标管"从哪继续"，ID 当主键管"重复了怎么办"，失败重试交给 Temporal。都是笨办法，拼在一起反而省心。

封面图：BinaryApe / Flickr · CC BY 2.0

MySQL + StarRocks 多数据源架构：数据仓库配置管理

Fri, 01 Nov 2024 10:30:00 +0800

一个库装不下两种负载

数据治理服务同时背两类数据访问。一类是在线交易：文件上传、元数据 CRUD、质量规则配置、任务状态流转，要低延迟、强事务，这是 MySQL 的主场。另一类是分析查询：按机构统计论文数量、按年份聚合发文趋势、质量规则的大表扫描，千万到亿级行的聚合，MySQL 跑到几十秒就受不了。

我们的解法是引入 StarRocks 做分析型数仓，MySQL 继续存权威交易数据，组成多数据源架构。要回答的是三个问题：代码里怎么清晰地路由查询，数据怎么从 MySQL 同步到 StarRocks，配置怎么统一管。

两个库，各干各的

MySQL：所有在线读写，权威库。GORM 访问，库表结构走 migration 版本化。
StarRocks：只跑 OLAP 查询，表模型按分析场景设计（主键模型做明细、聚合模型做汇总）。应用端用标准 database/sql + MySQL 驱动，StarRocks 协议兼容 MySQL。
同步：SeaTunnel 做 MySQL → StarRocks 的批量同步，按 updated_at 增量拉；实时性要求高的表（比如质量结果）走 Canal 订阅 binlog 写 StarRocks。
配置管理：各环境的数据源连接信息放配置中心，启动时构建 *gorm.DB 和 *sql.DB 两个单例，DAO 按职责显式依赖其中一个。

有一点是刻意选择的：没有用动态数据源切面（根据方法名前缀自动选库）那种魔法。每个 DAO 明确声明自己用哪个库，代码读起来啰嗦一点，但可预测。

两个数据源，显式注入

数据源初始化：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


func NewMySQL(cfg Config) (*gorm.DB, error) {
 dsn := fmt.Sprintf("%s:%s@tcp(%s)/%s?charset=utf8mb4&parseTime=true&loc=Local",
 cfg.MySQL.User, cfg.MySQL.Password, cfg.MySQL.Addr, cfg.MySQL.DB)
 db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
 if err != nil {
 return nil, err
 }
 sqlDB, _ := db.DB()
 sqlDB.SetMaxOpenConns(100)
 sqlDB.SetMaxIdleConns(20)
 return db, nil
}

func NewStarRocks(cfg Config) (*sql.DB, error) {
 dsn := fmt.Sprintf("%s:%s@tcp(%s)/%s?charset=utf8mb4&parseTime=true",
 cfg.StarRocks.User, cfg.StarRocks.Password,
 cfg.StarRocks.Addr, cfg.StarRocks.DB)
 db, err := sql.Open("mysql", dsn)
 if err != nil {
 return nil, err
 }
 db.SetMaxOpenConns(50)
 return db, nil
}

分析 DAO 直接用 *sql.DB：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


type PaperStatDAO struct {
 sr *sql.DB
}

func (d *PaperStatDAO) YearTrend(ctx context.Context, tenantID int64) ([]YearCount, error) {
 rows, err := d.sr.QueryContext(ctx, `
 SELECT publish_year, COUNT(*) AS cnt
 FROM dwd_paper
 WHERE tenant_id = ? AND publish_year IS NOT NULL
 GROUP BY publish_year
 ORDER BY publish_year`, tenantID)
 if err != nil {
 return nil, err
 }
 defer rows.Close()

 var out []YearCount
 for rows.Next() {
 var y int
 var c int64
 if err := rows.Scan(&y, &c); err != nil {
 return nil, err
 }
 out = append(out, YearCount{Year: y, Count: c})
 }
 return out, nil
}

SeaTunnel 同步任务片段（HOCON 配置）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


source {
 MySQL-CDC {
 base-url = "jdbc:mysql://mysql:3306/dataservice"
 table-names = ["dataservice.file_objects", "dataservice.paper_meta"]
 username = "seatunnel"
 password = "${mysql_password}"
 }
}
sink {
 StarRocks {
 node-urls = ["starrocks-fe:8030"]
 base-url = "jdbc:mysql://starrocks-fe:9030"
 database = "dwh"
 table = "dwd_paper"
 username = "root"
 password = "${sr_password}"
 }
}

容易出的几类事故

别在 StarRocks 上做高频点查和单行更新。它是批量向量化引擎，高并发小查询性能反而不如 MySQL，主键模型的 Update 也是异步合并的，不适合交易场景，两类负载要严格分开。
同步有延迟，秒级到分钟级不等，产品和运营必须知道「StarRocks 的数据不是实时的」。我们在分析页面上显示「数据更新于 X 分钟前」，把话说在前面。
StarRocks 兼容 MySQL 协议，但 SQL 方言有差异：不支持外键、部分函数不同、DDL 语法也不一样。GORM 的 AutoMigrate 不能直接用在 StarRocks 上，建表语句单独维护。
多数据源最容易出的事故，就是「在事务里查了 StarRocks」或者「把分析 SQL 打到 MySQL」。代码评审时我们重点看 DAO 注入的是哪个 db，另外把 StarRocks 账号设成只读，误写也写不进去。
SeaTunnel 的 MySQL-CDC 依赖 binlog 格式为 ROW，账号还要有 REPLICATION 权限，这些得提前和 DBA 沟通好。

后来

MySQL + StarRocks 的组合，说白了就是让专业的引擎干专业的事：MySQL 扛交易，StarRocks 扛分析。这套架构里管用的就几件事：职责划分清楚，依赖显式注入，同步链路可靠，数据延迟也不藏着掖着。配置收口之后，新增一个分析查询就是写一个走 StarRocks DAO 的方法，和在线业务互不干扰。

封面图：U.S. Army Corps of Engineers Savannah District / Flickr · CC BY 2.0

基于 Temporal Worker 的数据质量规则引擎与自动检查

Wed, 16 Oct 2024 10:30:00 +0800

规则越加越多，if-else 写不动了

入库的论文元数据要跑一串质量检查：DOI 格式合不合法、作者机构是不是空的、摘要长度够不够、引用关系完不完整、字段间有没有矛盾（比如发表年份晚于当前年份）。麻烦在于规则会不断增加，不同数据源的严格程度还不一样，硬编码 if-else 显然撑不了多久。

我们把规则抽成配置，用 Temporal 编排执行。选 Temporal 而不是普通异步任务框架，是因为质量检查可能一跑几分钟到几十分钟（涉及 StarRocks 大表聚合），需要可靠的重试、超时、状态持久化和人工介入。Temporal 天生擅长这种长事务工作流。

规则进配置，检查进 Workflow

规则定义存在 quality_rules 表：规则编码、名称、类型（not_null/regex/sql/custom）、参数（正则、阈值、SQL 模板）、严重级别（error/warning/info）、适用数据源。

每个数据集入库后启动一个 Temporal Workflow，流程是这样的：

加载该数据集启用的规则列表；
用 Activity 并行执行各类检查：SQL 类规则下发到 StarRocks，正则类在 Worker 内存跑；
收集结果。error 级别阻断发布，warning 记录但放行；
生成质量报告，通知数据负责人；
如果有 error，Workflow 挂起等待人工修复或豁免信号，收到信号再继续。

Activity 是幂等的：以 dataset_id + rule_code 作为幂等键，结果写 quality_results 表，重跑时已通过的规则直接跳过。

Workflow 与 Activity

Workflow：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


func QualityCheckWorkflow(ctx workflow.Context, datasetID int64) error {
 var rules []QualityRule
 if err := workflow.ExecuteActivity(ctx, LoadRulesActivity, datasetID).Get(ctx, &rules); err != nil {
 return err
 }

 // 并行执行所有规则
 futures := make(map[string]workflow.Future)
 for _, r := range rules {
 r := r
 ao := workflow.ActivityOptions{
 StartToCloseTimeout: 10 * time.Minute,
 RetryPolicy: &temporal.RetryPolicy{
 InitialInterval: 5 * time.Second,
 BackoffCoefficient: 2.0,
 MaximumAttempts: 3,
 },
 }
 ctx1 := workflow.WithActivityOptions(ctx, ao)
 futures[r.Code] = workflow.ExecuteActivity(ctx1, RunRuleActivity, datasetID, r)
 }

 var hasError bool
 for code, f := range futures {
 var result RuleResult
 if err := f.Get(ctx, &result); err != nil {
 workflow.GetLogger(ctx).Error("rule failed", "code", code, "err", err)
 hasError = true
 continue
 }
 if result.Severity == "error" && !result.Passed {
 hasError = true
 }
 }

 _ = workflow.ExecuteActivity(ctx, SaveReportActivity, datasetID).Get(ctx, nil)

 if hasError {
 // 等待人工修复或豁免信号
 var signal SignalData
 ch := workflow.GetSignalChannel(ctx, "quality-resolve")
 ch.Receive(ctx, &signal)
 if signal.Action != "exempt" {
 // 非豁免，重新跑检查
 return workflow.NewContinueAsNewError(ctx, QualityCheckWorkflow, datasetID)
 }
 }
 return workflow.ExecuteActivity(ctx, PublishDatasetActivity, datasetID).Get(ctx, nil)
}

Activity 中 SQL 类规则执行：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


func RunRuleActivity(ctx context.Context, datasetID int64, r QualityRule) (RuleResult, error) {
 result := RuleResult{RuleCode: r.Code, Severity: r.Severity}
 switch r.Type {
 case "sql":
 var cnt int64
 query := renderSQL(r.Params.SQL, datasetID)
 // starrocksDB 是独立的 *sql.DB
 if err := starrocksDB.QueryRowContext(ctx, query).Scan(&cnt); err != nil {
 return result, err
 }
 result.Passed = cnt == 0
 result.Message = fmt.Sprintf("violation rows: %d", cnt)
 case "regex":
 // 在内存拉取样本校验，略
 }
 saveResult(datasetID, result)
 return result, nil
}

五个坑

第一个是 Temporal 的默认重试。Activity 默认会无限重试，一定要自己配 RetryPolicy。我们的 SQL 检查可能因为 StarRocks 短暂不可用而失败，3 次指数退避足够；超过就标记失败让人工看，不能无限重试堆积。

第二个坑我印象很深：Workflow 里不能直接调 time.Sleep，也不能用 goroutine，必须用 workflow.Sleep 和 workflow.Go。我第一次写的时候在 Workflow 里用普通 for 循环查状态，重放时直接确定性错误，排查了很久。

规则配置还要支持灰度。我们加了规则的 enabled 开关和适用数据源范围，新规则先在 info 级别跑一周观察误报，再提升为 warning 或 error。不然一条误报多的新规则上线，一上来就阻断所有数据。

人工信号是 Temporal 的强项。数据负责人在内部页面点「豁免」，后端发 Signal 给 Workflow，流程继续往下走。比自己在 Redis 里轮询状态优雅多了。

最后一条很朴素：大表 SQL 检查不要在主 MySQL 上跑，全部路由到 StarRocks，别碰线上交易库。

后来

规则做成配置、检查交给 Temporal 编排之后，新增一条规则就是加一行配置和一个 Activity 分支，不用发版。持久化、重试、信号这些机制，让长耗时、要人工介入的检查流程变得可靠。数据治理这件事，也从「事后救火」挪到了「事前卡口」。

封面图：jitze / Flickr · CC BY 2.0

数据治理服务架构：原始文件、PDF 解析与论文元数据管理

Sun, 15 Sep 2024 10:30:00 +0800

文件杂、体积大、质量参差

某科技公司的数据平台要处理的东西很杂：客户上传的论文 PDF、期刊数据包，还有从 OpenAlex 同步来的学术数据。目标只有一个，把它们统一治理成可检索、可分析的结构化资产。

麻烦在于文件来源杂、体积大（单文件几十到几百 MB），质量还参差不齐。有的 PDF 是扫描件，得走 OCR；有的元数据干脆缺失；作者机构的写法五花八门。

我在数据治理服务里设计了一条从原始文件入库到结构化元数据落地的链路。思路不复杂：把「文件存储」「解析」「元数据管理」三件事拆开，每一步都能独立重试和替换。

四层流水线

整体分四层：

原始文件层：文件通过 S3 预签名直传到 MinIO，路径按 raw/{tenant}/{yyyy}/{mm}/{id}.pdf 组织，元信息写 file_objects 表。
解析层：异步 Worker 消费解析任务，按文件类型路由到不同 parser。文本型 PDF 用 pdfplumber 提取文本和章节结构，扫描件走 OCR；论文元数据通过 GROBID 或正则从首页抽取标题、作者、摘要、DOI、参考文献。
清洗层：作者名标准化、机构归一化、DOI 校验去重，用 Temporal 工作流编排（下一篇会展开规则引擎）。
元数据层：结构化结果落 MySQL 作为权威库，同时同步到 StarRocks 做分析查询，全文索引进 Elasticsearch。

各层之间通过任务表和消息队列解耦。原始文件永远不修改，所有解析结果挂在 file_id 下，出了问题随时能追溯。

文件对象与解析路由

文件在系统里的身份，是这么记录的：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


type FileObject struct {
 ID int64 `gorm:"primaryKey"`
 TenantID int64
 FileKey string // S3 object key
 FileName string
 Size int64
 MIMEType string
 Hash string // sha256，用于秒传和去重
 Status string // uploaded/parsing/done/failed
 ParsedMeta *string // JSON，解析出的标题作者等
 CreatedAt time.Time
}

解析任务的分发在 Python Worker 端，按 MIME 类型路由：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


PARSERS = {
 "application/pdf": "pdf",
 "application/epub+xml": "jats",
}

async def dispatch_parse(file_obj: dict):
 parser_type = PARSERS.get(file_obj["mime_type"])
 if parser_type == "pdf":
 meta = await parse_pdf(file_obj["file_key"])
 elif parser_type == "jats":
 meta = parse_jats(file_obj["file_key"])
 else:
 meta = {}
 await update_metadata(file_obj["id"], meta)

async def parse_pdf(key: str) -> dict:
 local = await s3_download_to_tmp(key)
 with pdfplumber.open(local) as pdf:
 first_page = pdf.pages[0].extract_text() or ""
 return {
 "title": extract_title(first_page),
 "authors": extract_authors(first_page),
 "doi": extract_doi(first_page),
 "abstract": extract_abstract(pdf),
 "page_count": len(pdf.pages),
 }

解析是最脆的一环

pdfplumber 对双栏排版、数学公式、上下标经常串行；GROBID 基于 CRF 模型，效果好但部署重，单篇解析要 5 到 10 秒。我们的做法是默认走 pdfplumber 粗解析，关键客户的高价值文件再回灌 GROBID 精修，两边各取所长。

扫描件必须 OCR，但 OCR 错误率高、成本也大。好在可以省着用：看首页有没有可选文本层，有就直接解析，没有才进 OCR 队列，不把算力浪费在本来就有文本层的 PDF 上。

去重也有一层妥协。元数据去重以 DOI 为主键，可 DOI 会缺失、会写错。没有 DOI 的论文，就用标题加首作者加年份做 SimHash 近似去重，阈值得跟着数据调。

还有两条底线。一是原始文件不可变：所有清洗都基于副本生成新版本，解析出问题随时重跑，不会污染原始数据。二是 OpenAlex 数据量太大，全量同步不现实，我们用 SeaTunnel 做增量同步，按 update_date 分批拉，避免一次性打满源库带宽。

后来

数据治理没有银弹。这套架构管用的地方，是把脏活拆成了能单独观测、重试、替换的阶段：原始文件不变，解析和清洗各管一段，元数据按用途分开存。面对来源各异的学术数据，加规则是渐进的事，不用推倒重来。

封面图：Barta IV / Flickr · CC BY 2.0