架构 on 姚玉亮的网络日志

最强的模型选了主键关联：不是它不够强，是业务没人替它想清楚

Fri, 04 Sep 2026 10:00:00 +0800

先承认：模型真的很强

我是 yusanwen，一名深度使用 AI 的工程师。我承认大模型是真的强，强到逻辑推演接近无敌：让它在代码里找边界情况、做多步推理，它做得比大多数同事都快。这篇文章不是唱衰模型，恰恰相反：正因为承认它强，有个问题才值得写下来。

一个"当下完全正确"的 demo

前几天我用目前能调到的最强档 Codex 模型（5.6 sol）做一个内部小 demo。需求很小：描述几个实体、说清楚它们之间的关系，让它建一套带接口的最小系统。我没有给表结构、没有给任何存储选型约束，想看看它"自己会怎么设计"。

它交出来的东西非常干净：每个实体一张表，自增主键，实体之间全部用主键 id 互相外键关联。代码规整，测试全绿，接口能跑。一切看起来完美。

但我盯着那张 ER 图，后背有点发凉。

单看当下，主键关联没有任何问题。问题藏在一个没说出口的假设里：这套关联成立的前提，是"永远只有这一张主键表、永远只有一套存储、永远不迁移"。

只要未来有一天换库类型（比如从单库换成分库/异构存储，或者业务合并、要和另一套系统的数据对上），以主键 id 为语义的关联就全线失效：两边都有 id=1，却不是同一个东西。那时怎么办？洗数据：把几十万行关联按业务规则重映射。能做，但那是用未来的一场大手术，偿还现在省下的十分钟。

说"后背发凉"，不是这套设计错了，主键外键在大多数单库场景就是对的。凉的是：这个"对当下完全正确、对未来埋雷"的决策，全程没有任何人做过。模型默默地替你选了，而你默认了。

为什么最强的模型，选了最"平均"的方案

第一反应当然是怪模型：不是号称最强吗，连外键策略都选不好？想了两分钟，我收回这句话。

因为大模型本质上是概率模型。它产出的不是"最优解"，而是训练数据分布里的最可能解：在它见过的几千万张表里，“自增主键 + id 外键"是最常见的写法，没有之一。我描述实体和关系时没给任何反向约束，它按概率落点，自然落在最常见、最不需要解释的答案上。

它优化的是"这段设计看起来像什么”，不是"这段设计未来扛不扛得住"。更要命的是，它没有 skin in the game：换库的迁移成本是几个月后的我的，不是现在的它的。一个不用承担后果的决策者，天然倾向于选择让自己"看起来最正常"的选项，哪怕那个选项把风险往后推。

所以，凡是你没说出口的约束，概率模型都会替你平均掉。

为什么这套设计能一路绿灯

因为链条上每个环节都在奖励"快"。demo 要得急，模型写得快，自测全绿，人扫一眼觉得"挺规范的"。管理层的关注点不在主键策略上，利益也不在那里：那里要的是交付速度、团队吞吐、demo 赶紧变成能演示的东西。没有人有动力为一个"当下完全正确"的设计踩刹车。

于是模型参与越深、任务越重，这种"概率平局"的设计被无审查放行的比例就越高。不是哪个人不负责，是速度把"想清楚"这个环节压缩没了，而模型用一个看似专业的默认值，恰好补上了这个真空。它越强，输出越像资深工程师的手笔，就越没人质疑。我在这个 demo 里看到的最危险的东西，不是主键，是流畅的平庸。

解法：把约束说出口，而不是靠模型自觉

结论不是"关键设计别让模型碰"，那是因噎废食。要做的，是把被速度压缩掉的环节，重新变成显式的东西。

解法一：关系是业务语义，先写出来，再让模型建表。

“订单属于用户"是业务，“订单表加一列 user_id 外键"是实现。只给模型后者，它就会顺着 id 一路关联下去；给它前者，它才可能停下来想"该用哪个键表达这个关系”。所以我现在的做法是，做这类 demo 前先花十分钟写一段领域骨架：每个实体的业务唯一键是什么、实体之间靠什么语义关联（单号？编码？还是本就同库同生命周期？）。这段骨架不属于任何技术选型，换什么存储都成立。写清楚之后模型再怎么实现都安全，因为最危险的那个决策，已经被写下来的业务做完了。

解法二：把"换库演练"写进验收条件。

给模型的验收清单里加一条：回答"如果存储换成另一种形态，这套关联要改多少、怎么改”。它答不上来，说明关联设计偷懒了。这一步几乎零成本，却把"未来的成本"拉进了当前这一回合：模型不能只优化当下，因为验收里写了未来。有意思的是，概率模型其实答得上来这种问题，只要你问。

解法三：踩过的坑沉淀成约束，注入而不是叮嘱。

主键关联这种事，踩一次就够。但"记住"不该靠人脑，该靠系统：把反模式写进团队的编码规范，再通过 AGENTS.md / Skill / 提示词模板注入每个后续任务，比如"跨实体关联必须引用业务唯一键，或用一句话说明为什么不能"。AI 时代，编码经验的载体正在从"老员工脑子里"变成"可注入的约束文件里"。谁的约束写得全，谁的模型输出就靠谱。说白了，就是把概率模型的落点，用显式经验强行掰回来。

解法四：架构决策不外包，但让模型自证最坏情况。

实现可以外包，设计决策留一道复核：交付前让模型自己列"这个设计在哪些条件下会失效"。它列得出来，列不出来才是问题。这一条的本质是把隐性决策变成显性决策：主键外键可以选，但必须是"讨论过、知道代价"之后的选，而不是概率的默认值。

结尾：两种能力

回到开头。我承认大模型很强，逻辑能力甚至接近无敌。但这次 demo 让我更确定另一句话：

大模型的强，是"把说出口的经验变成执行"的强；而"把没说出口的经验变成决策"，暂时还得靠人。

未来能编好程序的人，一定是两种能力的组合：深谙业务，知道哪些关联是语义、哪些只是巧合；善用模型，能把业务约束、验收标准、历史教训，全部显式地喂给它。会写代码正在贬值，“能把业务说清楚"正在升值。模型写出的每一行都在替你打工，但往 prompt 里放什么约束，决定了它是替你赚钱，还是替你埋雷。编码的姿势，暂时还是值钱的。

封面图：Ivan Radic / Flickr · CC BY 2.0

对话编排层重构：从 Go 业务编排迁移到 Python LangGraph

Wed, 02 Sep 2026 20:00:00 +0800

一条报数指令暴露的问题

炼丹炉（Alchemy Furnace，我的开源项目）的群聊里，我发过这样一条指令：

1

@全体成员 全体都有！报数！

预期很明确：A、B、C、D 四个道人按顺序报 1、2、3、4。实际跑起来，它被当成了闲聊：有时只让一个人接话，有时人设和记忆指令还能把硬指令覆盖掉，报数报成了自由发挥。

这不是一个偶发 bug，是一类问题的缩影：当编排逻辑长在业务代码里，“确定性指令"和"开放对话"就没有边界。群聊调度全部写在 Go 网关里，意图分类、发言人选择、轮次策略和业务逻辑缠在一起，每加一个编排能力都要改 Go、编译、发布，而编排恰恰是整个产品里变化最快的部分。

于是我做了这次架构迁移：把提示词构建、群聊调度和模型调用编排，整体从 Go 迁到 Python LangGraph，形成「Go 负责数据与 CRUD，Python 负责智能编排」的分层。

Go 在变成 Agent 框架

迁移前炼丹炉是双后端：Go 网关（Gin）+ Python 引擎（FastAPI）。这个结构本身没问题，问题在于群聊上线后，Go 里长出了第三种性质的职责。

一轮群聊对话，Go 实际在做三件事：

数据：会话、消息、道人、金丹、记忆、模型的存储与 CRUD，凭据加密，这是 Go 的本行
协议：对前端的 SSE 流、内部服务调用，是稳定的契约面
智能编排：意图分类、发言人选择、提示词拼装、模型调用、轮次与收敛策略，这部分高频变化、需要快速实验

第三类和前两类完全不是一种东西。编排层需要的是图结构、状态机、检查点、可恢复执行、结构化输出校验，这些 LangGraph 生态里全是现成的，Go 里全要手写。让一个后端语言慢慢长成一个 Agent 框架，才是最贵的路线。

分层：Go 管什么，Python 管什么

迁移后的职责边界：

职责	归属
认证、请求校验、凭据加密存储	Go
会话/消息/道人/金丹/记忆/模型的存储与 CRUD	Go
正式消息落库（只在 `assistant_final` 之后，按 run_id 幂等）	Go
内部事件 → 前端 SSE 的翻译	Go
单聊/群聊路由	Python LangGraph
指令分类、确定性路由	Python
Supervisor 计划、发言人调度、收敛	Python
提示词构建、模型调用、重试	Python
记忆检索策略与记忆提案	Python 提案 → Go 校验落库

说白了：Go 不再选择发言人、不再分类对话意图、不再拼 prompt，也不再管轮次策略。前端仍然只调 Go、只消费 Go 的 SSE。对前端来说契约没变，变的是 SSE 背后的调度从 Go 挪进了图里。

边界里我最在意的一条：凭据不进图状态。API key、解密后的凭据走 LangGraph 的 context_schema（RuntimeContext：模型网关、凭据、调试开关、取消旗标），与图状态彻底分离：它们绝不进入图状态、SQLite checkpoint、对外事件和日志。图状态里只有快照：历史、道人、金丹、记忆、模型引用，都是 Go 在发起一轮 run 时传进来的不可变快照。

图架构：一张会话图，一张可复用的道人图

整个编排是四层图，顶层一张会话图：

flowchart TD
 A["ConversationGraph（一次用户轮入口）"] --> B["hydrate_context"] --> C["route_session"]
 C --> D["SingleChatGraph"] --> D1["DaoistGraph（复用子图）"]
 C --> E["GroupChatGraph"] --> F["classify_directive"]
 F --> G["deterministic_router（确定性指令）"]
 F --> H["supervisor（开放讨论出计划）"]
 G --> I["dispatch_daoists"]
 H --> I
 I --> J["DaoistGraph × N"]
 I --> K["convergence 收敛"]
 K --> L["propose_memory 记忆提案 → Go 校验落库"]

关键设计是 DaoistGraph 作为可复用子图：单聊直接调它，群聊每个发言人各自子运行一张。单聊和每个群成员走的是同一条 prompt 构建 + 模型调用管线：选定记忆、编译人设与金丹行为、调模型、校验响应、流出事件。这一条保证了"行为可解释”：单聊什么效果，群聊里同一个道人就是什么效果，不存在两套 prompt 逻辑。

群聊图里的路由是有讲究的：classify_directive 先分类这一轮用户输入，确定性指令走 deterministic_router 直接成计划，开放讨论才走 supervisor 让模型出计划，这就是下一节的内容。

混合导演：该调模型的调模型，不该调的绝不调

群聊调度我用的是混合导演策略，核心就一句：确定性的事情用代码，创造性的事情用模型。

确定性指令永不委托模型。直接 @某个成员、@全体成员、报数、停止/继续，这些必须在代码里走死路径。报数的实现是：路由器为每个成员构造一个不可变任务，里面写死序号；人设、记忆、闲聊风格规则只能影响语气，不能改数字、不能漏人、不能加戏、不能改顺序。报数这种事交给模型去"理解"，就是开头那个 bug 的根源。

开放讨论交给 Supervisor。这一轮该谁说话、按什么顺序、每人拿到什么任务、发言预算多少、要不要收束，由会话默认模型（非人设，不扮演任何道人）产出一份结构化计划。Supervisor 不可见、不写用户可见的文本，只出计划。它失败或产出无效计划时，确定性回退到被明确 @ 的成员或主成员，导演的错误不传染整轮。

这样分工还有个实际的好处：明确的群指令不花 Supervisor 的模型调用，单聊用被选中道人自己配置的模型。钱花在真正需要智能的地方。

可恢复执行：中断在发言人边界，续跑按差集

这是整个迁移里技术含量最高的部分，也是最值得抄的部分。

每个用户轮有全局唯一的 run_id，每条终稿回复有唯一 reply_id，Go 按这两个 ID 做落库幂等。LangGraph 侧用本地异步 SQLite checkpointer 做检查点。用户点停止、前端断连、进程重启，都要能恢复，而且恢复时不能重复已完成发言人的发言。

做法是把恢复粒度设计在发言人边界：dispatch 节点按计划逐个发言人在子图里跑，每个发言人之前先 await asyncio.sleep(0) 让出事件循环再查取消旗标：取消请求只能落在 await 点，这样中断恰好落在发言人之间的缝隙里，不会截断一条发到一半的回复。

续跑靠差集裁决。顶层检查点只携带「计划 + 已完成回复」，恢复重放时：

计划已存在 → 不重新规划、不重发 plan_created 事件
已完成的发言人 → 跳过，只在剩余差集上继续

其中藏着一个容易踩的坑，代码里的路由顺序：

1
2
3
4
5
6
7


def _route_after_router(state) -> Literal["dispatch", "supervisor", "end"]:
 if state.get("speaking_plan"):
 return "dispatch" # 续跑重放：计划已在，按差集续，不重规划
 kind = state["directive"]["kind"]
 if kind == "open":
 return "supervisor" # 首轮开放讨论：默认模型出计划
 return "end" # 停止/继续：控制指令，不产计划

这个判断顺序不能反。如果先看 kind，开放讨论在续跑重放时会误入 supervisor 再调一次模型；先看计划有无，重放才直接走 dispatch 按差集续跑。可恢复执行的全部难度就在这种毫厘之间：状态里每多带一个通道、路由里每换一个判断顺序，恢复语义就完全不同。

失败语义同样是发言人粒度：单个道人失败只跳过该发言人，不阻塞剩余计划成员；道人图内部对模型错误做最多 2 次机械重试；Supervisor 失败走确定性回退。三层兜底，任何一层的失败都不会把整轮炸掉。

迁移不是重写：feature flag + 一条真实的提交序列

迁移策略是增量推进，但结局只有一种实现：feature flag orchestration_engine=legacy|langgraph 是临时迁移控制，不是长期双引擎产品设置。验证通过后默认 LangGraph，短回滚窗口过后删掉 legacy。

真实提交序列（节选自仓库主干）：

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


docs: design LangGraph conversation orchestration ← 321 行设计文档
docs: plan LangGraph orchestration migration ← 873 行实施计划
build(python): add LangGraph runtime dependencies
feat(orchestration): define state and event contracts ← 状态/事件契约先行
feat(orchestration): add provider-aware model gateway
feat(orchestration): evolve speaking plan to ordered task items
feat(orchestration): route explicit group directives
feat(orchestration): add reusable Daoist graph
feat(orchestration): add hybrid group director
feat(orchestration): add resumable conversation graph
feat(orchestration): expose internal streaming API
feat(chat): persist orchestration runs idempotently

节奏是契约先行：状态、事件、模型网关先于任何图节点落地；图是一层一层长出来的（道人图 → 确定性路由 → 混合导演 → 可恢复）。整个编排包最终约 1900 行 Python，14 个文件。

验收有一条硬场景，就是开头那条报数：四个成员各回自己的序号，人设只能加语气，不能改数、不能漏人、不能加戏。这条过不了，迁移就不算完。

复盘

分层不是按语言划的，是按职责性质划的。数据是稳定的，编排是高频变化的。把变化最快的职责放进迭代最快的生态：LangGraph 的图结构、checkpointer、子图、结构化输出校验都是现成的，Go 里全要手写。
图的节点边界就是恢复边界。LangGraph 的检查点落在节点边界，所以节点怎么切，决定能从哪里恢复。想要发言人粒度的恢复，就得把调度切成发言人粒度的节点。
确定性与概率性分离，是 Agent 系统的地基。能写成代码的绝不调模型；需要模型的环节（Supervisor）只出可校验的结构化计划，失败可回退。开头那个报数 bug，本质就是没有这层分离。
契约先行让两端各自演进。11 个类型化事件 + run_id 幂等 + 快照式输入，Go 和 Python 之间只有契约没有纠缠；Go 仍然是数据的事实源，Python 在快照上做编排，记忆用提案-校验的方式回流。

这次重构真正的收益在后面：工具调用、人工审批中断（permission_required 事件已在契约里预留）、长任务规划、更复杂的多 Agent 协作，这些以后都是"在图里加节点"，不再需要动 Go。架构分层的意义不是当下的优雅，是把未来的变化留在了便宜的地方。

封面图：Creativity103 / Flickr · CC BY 2.0

数据集管理服务架构设计

Sun, 08 Jun 2025 10:30:00 +0800

为什么不做成单体

某科技公司的 AI 数据平台需要一个统一的数据集管理服务：往上支撑学术文档上传、解析、向量化、知识图谱构建，往下给知识库问答服务供检索能力。数据形态从 PDF、Word 到图片、结构化表格都有，存储量大，处理链路又长又耗资源。

之所以不做成单体，是因为上传、解析、检索混在一个进程里会互相影响，任何一边都没法独立扩缩容。数据集管理服务就是照着这个约束设计的，后端架构由我主导。

整体怎么拆

服务基于 Hertz（字节开源的 HTTP 框架）搭，按职责拆成几块。API 层管数据集 CRUD、文档上传、检索接口，用 Hertz 的路由分组和中间件做鉴权、日志、限流。存储层分三份：原始文件放 S3 兼容对象存储（MinIO），元数据存 GaussDB，向量和图谱实体存 MongoDB，向量一个集合，图遍历也靠它。处理层用 eino 编排解析流水线，并发交给 pond，前两篇已经讲过。检索层做向量加关键词的混合召回，支持按数据集、文档、元数据过滤。

模块间的依赖注入用 Wire，Service/DAO/Client 各归各层：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// wire.go
func NewDatasetService(
 cfg *Config,
 db *gorm.DB,
 mongo *mongo.Client,
 s3 *s3.Client,
 temporalClient client.Client,
 chain *eino.Chain,
) *DatasetService {
 // ...
}

上传直传，解析异步

上传走 S3 预签名，前端直传对象存储，不占用服务带宽：

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


func (h *DatasetHandler) PresignUpload(c context.Context, ctx *app.RequestContext) {
 var req UploadReq
 if err := ctx.BindAndValidate(&req); err != nil {
 ctx.JSON(400, errResp(err))
 return
 }
 key := fmt.Sprintf("datasets/%s/%s%s", req.DatasetID, snowflake.NextID(), extOf(req.Filename))
 url, err := h.s3.PresignPutObject(c, key, 15*time.Minute)
 if err != nil {
 ctx.JSON(500, errResp(err))
 return
 }
 ctx.JSON(200, map[string]any{"url": url, "object_key": key})
}

前端拿到预签名 URL 直传 S3，传完回调服务，服务创建文档记录、投递解析任务。

处理链路交给 Temporal 编排（和数据治理服务共用一个 Temporal 集群），每个文档一个 workflow，内部调 eino Chain 走完解析、分块、embedding、写图谱。重试、超时、状态持久化都是 Temporal 的活，服务重启任务也不丢。

检索是多路召回

检索接口对知识库问答服务只暴露一个统一的 Search：

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


type SearchService struct {
 vecStore VectorStore
 kwStore KeywordStore
 graph GraphStore
}

func (s *SearchService) Search(ctx context.Context, req *SearchReq) (*SearchResp, error) {
 // 1. 向量召回
 vecHits, err := s.vecStore.Search(ctx, req.DatasetID, req.QueryEmbedding, req.TopK)
 if err != nil {
 return nil, err
 }
 // 2. 关键词召回（BM25）
 kwHits, _ := s.kwStore.Search(ctx, req.DatasetID, req.Query, req.TopK)
 // 3. 融合排序（RRF）
 fused := rrfFuse(vecHits, kwHits)
 // 4. 图谱扩展：对 top 结果关联实体补充邻接信息
 enriched := s.graph.Expand(ctx, fused, req.DatasetID)
 return &SearchResp{Hits: enriched}, nil
}

五个关键取舍

上传和处理必须拆开。最初想在上传接口里同步解析，大文件一进来接口就超时。改成预签名直传加 Temporal 异步任务之后，接口只管元数据和任务投递，处理能力想扩就单独扩。文档状态用状态机管理（uploaded → parsing → parsed / failed），前端轮询或订阅进度。

存储选型上，GaussDB 存结构化元数据（数据集、文档、权限），MongoDB 存向量和非结构化 chunk，主要看中它的向量索引和文档模型，跟 chunk 加 metadata 的形态正合适。图谱没有引入独立图数据库，实体和关系就用 MongoDB 集合存，当前规模够用，还省掉一个中间件的运维成本；等图遍历深度真上去了，再换专门的图库不迟。

大文件和小文件分开对待。几百页的 PDF 解析起来很吃内存，我们在 Temporal workflow 里按页拆 activity，每页独立处理、独立落盘，避免整个文档一口气读进内存。小文件反过来，批量合并处理，省 workflow 调度开销。

幂等和重试要提前想好。解析任务可能因为 OOM 或节点重启被 Temporal 重试，所有写入都以文档 ID 加 chunk 序号做幂等键，重试不会产生重复向量。S3 上的中间结果（解析出的文本、表格）也缓存着，重试时已完成的阶段直接跳过。

多租户隔离贯穿全链路。数据集属于某个 AppRole 团队，所有查询强制带租户过滤条件，S3 的 key 前缀也按租户隔离，预签名 URL 带时效，防越权下载。

三条链路各走各的

整个服务拆开看就三件事：上传走对象存储直传，处理走异步工作流，检索做多路召回。Hertz 顶在 API 层，S3 承载原始文件，eino 加 pond 解决解析并发，Temporal 保证任务可靠，GaussDB 和 MongoDB 分别承接元数据和向量图谱。这套架构支撑着知识库问答服务，也给后续的知识图谱和多模态检索留了扩展空间。

封面图：motleypixel / 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

从单体到账号中台：统一认证中心的架构思考

Mon, 11 Mar 2024 10:30:00 +0800

四个系统，四套登录

2023 年底我刚到某科技公司时，内部几个业务系统各有各的登录：统一支付平台一套账号，数据治理服务一套，数据集管理服务和知识库问答服务又各搞一套。员工要记四五个密码，离职了账号还关不干净；外部客户在一个系统注册完，跳到另一个系统还得再注册一次。运维和安全团队都在催：能不能统一一下。

这就是统一认证中心的起点。但很快想明白一件事：光把用户表抽出来解决不了问题，身份怎么统一、认证方式怎么扩展、应用之间怎么建立信任，这三件事都绕不开。

核心域怎么划

我把统一认证中心划成五个域：

身份域：全局唯一的 UserID（Snowflake 生成），一个用户可以绑定多种凭证，密码、手机、邮箱、微信/企微/飞书 OAuth 都行。
应用域：每个接入方有自己的 AppID/AppSecret，配置回调地址、授权方式、可用的登录 Provider。
组织域：用 AppRole 做团队/租户隔离，用户在不同应用里可以有不同角色。RBAC 权限模型落在认证中心，资源权限还是业务系统自己持有。
会话域：认证中心统一颁发 JWT（RSA 私钥签），业务系统拿 JWKS 公钥在本地验签，不回源。
Provider 域：短信、邮件、验证码、社交登录全做成可插拔接口，默认实现腾讯云 SMS/SES/Captcha，以后要换阿里或自建，加个实现就行。

技术栈上用 go-zero 拆 RPC 服务，Wire 做依赖注入，Service/DAO 分层。

分层与关键代码

整体分层这样组织：

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


passport/
├── api/ # HTTP 网关 (go-zero rest)
│ ├── handler/
│ └── middleware/
├── rpc/ # gRPC 服务
│ ├── user/
│ ├── app/
│ ├── auth/
│ └── org/
├── internal/
│ ├── service/ # 业务编排
│ ├── dao/ # 数据访问
│ ├── provider/ # 可插拔 Provider
│ └── token/ # JWT 签发/JWKS
└── wire/

Provider 接口是可插拔的关键：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


type SMSProvider interface {
 Send(ctx context.Context, phone, tmplID string, params map[string]string) error
}

type EmailProvider interface {
 Send(ctx context.Context, to, subject, body string) error
}

type CaptchaProvider interface {
 Verify(ctx context.Context, ticket, randstr string) error
}

Wire 注入时按配置选择实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


func NewSMSProvider(cfg config.SMS) provider.SMSProvider {
 switch cfg.Provider {
 case "tencent":
 return tencent.NewSMS(cfg.Tencent)
 case "aliyun":
 return aliyun.NewSMS(cfg.Aliyun)
 default:
 return noop.NewSMS()
 }
}

登录入口用 AuthService 统一编排。不管密码、短信还是社交登录，最后都收拢到同一套"凭证换 UserID → 发 Token"的流程里：

 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


type AuthService struct {
 userDao dao.UserDAO
 credDao dao.CredentialDAO
 tokenSvc *token.Service
 providers provider.Container
}

func (s *AuthService) Login(ctx context.Context, req *LoginRequest) (*TokenPair, error) {
 var userID int64
 var err error
 switch req.GrantType {
 case "password":
 userID, err = s.loginByPassword(ctx, req.AppID, req.Account, req.Password)
 case "sms":
 userID, err = s.loginBySMS(ctx, req.AppID, req.Phone, req.Code)
 case "social":
 userID, err = s.loginBySocial(ctx, req.AppID, req.Provider, req.Code)
 default:
 return nil, ErrUnsupportedGrantType
 }
 if err != nil {
 return nil, err
 }
 return s.tokenSvc.Issue(ctx, userID, req.AppID)
}

JWT 签发用 RSA 私钥，公钥通过 JWKS 端点暴露：

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


func (s *Service) Issue(ctx context.Context, userID int64, appID string) (*TokenPair, error) {
 now := time.Now()
 claims := Claims{
 UserID: userID,
 AppID: appID,
 RegisteredClaims: jwt.RegisteredClaims{
 Issuer: "passport",
 Subject: strconv.FormatInt(userID, 10),
 Audience: jwt.ClaimStrings{appID},
 ExpiresAt: jwt.NewNumericDate(now.Add(2 * time.Hour)),
 IssuedAt: jwt.NewNumericDate(now),
 ID: snowflake.NextID(),
 },
 }
 accessToken, err := jwt.NewWithClaims(jwt.SigningMethodRS256, claims).
 SignedString(s.privKey)
 // refresh token 省略
 return &TokenPair{AccessToken: accessToken, ...}, nil
}

最难的是用户合并

五个域里真正难缠的是身份。一个用户先用微信登录、后来又用手机号注册，识别为同一个人之后要合并。我的做法是建一张 user_bindings 表，凭证和用户是多对一关系，合并时把旧凭证挂到新 UserID 下，再写一条审计日志。

麻烦在后头：业务系统的外键引用的还是旧 UserID，得发事件通知各系统做 ID 映射。这件事比当初拍板时想的工作量大得多。

吊销、组织树和供应商灰度

JWT 吊销是个老话题。我们用短 AccessToken（2 小时）加长 RefreshToken（7 天），RefreshToken 存 Redis，随时可吊销；AccessToken 不做黑名单，靠短过期自然失效。登出只吊销 RefreshToken。支付这类安全要求极高的场景，再加一个"令牌版本号"claim，改密码时版本号递增，旧 token 立刻作废。

组织这块一开始想把组织树建在认证中心，后来发现各业务系统的组织模型差异太大：统一支付平台里是商户，数据治理服务里是团队，知识库问答服务里是企业。强行统一就是削足适履。最后认证中心只存 (app_id, user_id, role_external_id)，组织名和层级由业务系统自己维护。

Provider 也有灰度需求。腾讯云短信偶尔抖动，我在 Provider 层加了个 FanoutProvider，按权重在多家供应商之间分流，失败自动降级，配置走配置中心热更新，不用重启。

后来

统一认证中心上线之后，新业务接入 SSO 只要半天，离职员工的账号在一处关掉就全端下线，安全审计也有了统一入口。回头看，做账号中台靠的是克制：只做身份、认证、应用信任这三件事，组织和资源权限坚决留给业务系统。“登录"这件每个系统都要重复做的事，总算变成了一个可复用的平台能力。

封面图：anthony arrigo / Flickr · CC BY 2.0