freehire 架构全解:Go 单体 + 一次性 worker、事务 Outbox 与零 Postgres 读取的搜索链路

原创2026-10-22 15:22:591,756 阅读
文章标签:后端前端搜索引擎网页爬虫数据工程AI 应用可观测性

freehire 架构全解:Go 单体 + 一次性 worker、事务 Outbox 与零 Postgres 读取的搜索链路

freehire 是一个面向求职者的开源职位搜索引擎,其架构文档 docs/architecture.md 描述了这样一个系统:一个 Go 单体 HTTP 服务器,外加一群"跑完即退"的专用 worker,所有协调都落在 Postgres 上。读完后你将掌握:职位数据从爬取到被搜索命中的完整链路、Meilisearch 索引批量化背后的磁盘 IO 原理、CV 工作区的证据门写路径、进程内 AI 助手的回合边界设计,以及会话、API Key 与通知系统的关键不变量。你不需要会 Go 也能读懂本文。

freehire 系统形态:爬虫源喂给 run-once 抓取 worker,写 Postgres 并在同事务写入 outbox;队列排空与全量重建 worker 推入 Meilisearch;API 服务器读 Postgres 与 Meilisearch 服务客户端

图为系统形态的折叠视图:Sources 折叠了四个爬取通道,Queue drains 折叠了 cmd/enrich、cmd/search-drain、cmd/embed、cmd/capture-apply-form,Clients 折叠了 SPA、浏览器扩展、机器人和第三方 API 消费者。完整扇出见各包自己的 AGENTS.md(下文链接)。

一、系统形态:单体 + 卫星式一次性 worker

freehire 是一个 Go 单体,外加一组单用途 worker 组成的"卫星群"。 HTTP 服务器只做一件事——提供 API,包括应用内 AI 助手在请求时刻发起的 LLM 调用;而每一次爬取、每一次后台 LLM 调用(富化、embedding)、每一次索引重建,都发生在一个 run-once-and-exit 的 worker 里:由 cron 定时启动,干完活就退出。系统里没有任务队列守护进程,没有长驻后台运行时;全程常驻的进程只有两个:cmd/server 和 cmd/mail-ingest(入站邮件监听器)。

这个选择决定了下游的一切。因为 worker 之间、worker 与服务器之间不共享内存,所有协调都发生在 Postgres 里——这就是为什么写路径上遍布事务 outbox:一行数据在与触发它的那次写入同一个事务里入队,之后由拥有该队列的 worker 排空。

1. 抓取(Ingest)

cmd/ingest 每次运行只处理一个 provider(greenhouse、lever 等),从 boards 目录中读取该 provider 的在线看板,于是每个 provider 按自己的节奏爬取,慢平台永远不会阻塞快平台。每一块看板在进入目录时就已经对照适配器注册表做过校验,早于任何网络请求发出。运行随后交给 pipeline.Runner:每块看板抓取一次,把职位归一化进单一 schema,去重并 upsert。去重键是 jobs 表上的唯一约束——可在 0001_init.sql 中找到:

ALTER TABLE ONLY public.jobs
    ADD CONSTRAINT jobs_source_external_id_key UNIQUE (source, external_id);

因此重跑一次爬取是零成本的。一块持续失败的看板会按记录的冷却时间退避,而不是每次运行都被猛打。绝大多数职位直接爬自雇主自己的 ATS 或招聘页;聚合器和 Telegram 只是同一条管道里较小的补充切片——精确比例见 README.md 的 "Sources" 一节(截至 2026-10-20 的快照:320 个来源,其中 ATS 平台 117 家、聚合器与求职板 133 家、公司招聘站 52 家)。

2. 存储(Storage)

Postgres 是一切的系统级事实源:职位目录、账户、CV、申请、邮件、助手转录。数据库访问层由 sqlc 提供 make sqlc 目标,通过 Docker 容器运行 sqlc)。migrations/ 是 schema 的唯一事实源,同时喂给 sqlc 的代码生成和 Postgres 的首次启动初始化。

3. 富化与索引:为什么批量推送不是"微优化"

一次爬取写入职位行的同时,在同一事务里把它入队:新职位进 enrichment_outbox,内容真正发生变化才进 search_outbox。第二个条件很关键——内容未变的复爬走一条只刷新 "last seen" 时间戳的廉价路径,整个目录不必每几小时全量重索引。cmd/enrich 通过一个带类型、经过校验的契约把富化队列排空给 LLM;cmd/search-drain 从存储行构建文档,把一个被认领的整波文档作为一个任务推给 Meilisearch。

这个批量化不是微优化。Meilisearch 每次推送都会跨整个在线倒排索引重新合并,与批次大小无关——在约 270 万文档的索引上,实测每次推送 90–180 秒。所以早期设计(约 169 个独立的按看板进程各自直接推送)会把主机磁盘 IO 打满。outbox 把许多小推送折叠成少数"胖"推送,正是针对这一点。

4. 搜索:一个索引,存完整 wire 形态

只有一个索引:jobs 是关键词与 facet 索引,它存的是职位的完整公开 wire 形态,而不是指向它的指针——所以搜索响应不需要任何数据库往返就能渲染。cmd/reindex 从零重建索引并原子换入,在线读永远不受重建影响,并且它是索引设置、压缩和已关闭职位文档移除的唯一事实源。

系统里没有语义/混合搜索模式:此前的 Meilisearch jobs_semantic 索引在其仅有的两个真实消费者不再需要在线索引后被移除——/jobs/:slug/similar 现在读预计算好的近邻表(jobs.similar_job_ids,由 cmd/similar-backfill 离线从 job_semantic_chunks 的 pgvector 查询填充),基于 CV 的推荐则被直接砍掉而非迁移。cmd/embed 仍然通过 TEI 把 semantic_outbox 排空进 Postgres——只写 job_semantic_chunks(那些 pgvector 查询读的就是它),但不再写任何搜索索引。

5. API:一种公共 wire 形态

一个 Fiber 服务器,一种公共 wire 形态。internal/job/jobview 拥有职位的唯一 JSON 表示,列表端点、详情端点、搜索索引共用它,所以这些面不可能漂移。响应约定:单项用 {"data": ...},列表用 {"data": ..., "meta": {...}},失败用 {"error": msg}。目录是公开的、免密钥的——GET /api/v1/jobs 不需要任何凭证。

二、仓库布局:cmd、internal、boards 目录与前端

freehire 仓库模块图:Go 后端各包(migrations、cmd、internal)生成类型、读取看板数据,喂给前端工作区(web、design-system、extension),前端经 HTTP 回调

docs/ 与 openspec/ 在图中省略——它们自身不承载代码级依赖边。

cmd/ 大约有 60 个入口点。其中只有两个是长驻的:cmd/server 与 cmd/mail-ingest。其余——爬虫、队列排空、回填、rollup、通知轮——一律接收 DATABASE_URL,跑一遍就退出,失败时以非零码退出。防止 cron worker 自我堆叠的不是文件锁,而是 systemd 的 Type=oneshot。

internal/ 是领域所在,一个包对应一个关切——并且每个包恰好落在十一个 block 之一里,block 构成八层。自下而上读:platform(db、worker 管道、transport——这里没有任何东西知道"职位"是什么)、dict(facet 字典)、ai 与 identity、candidate、job、application 与 search、engage 与 ingest,最顶层是 api。一个 block 只能 import 严格低于它的 block,同层的两个 block 互相看不见。违规的 import 行会被 depguard 当场判死;同一张分层表也维护在 internal/platform/arch/layering 中,可一次性报告整张依赖图。每个 block 带一份 AGENTS.md 说明它是什么、可以伸手够到哪里。读代码前先知道两条约定:internal/platform/db 是生成的(改 internal/platform/db/queries/*.sql 后跑 make sqlc);handler 是薄的——解析、调服务、渲染。所以加在 handler 里的规则,助手的工具永远遇不到,因为那些工具直接调的是同一批服务。

boards 目录是数据,不是代码,也是多数贡献者真正在添砖加瓦的地方:每行对应一个 (provider, board, region) 组合,携带其所属公司。一行可以由网站上的 "contribute a board" 表单添加(初始为 pending,靠首次爬取成功证明自身),或由 cmd/add-board 添加( curator 已人工核验,直接 active)。退役一块看板是把其行翻成 status='retired',从不删除——ingest 只爬在线行,退役就是一个状态位,犯错时把看板重新加回即可撤销。

web/ 是 SvelteKit 应用,生产环境与 API 同源部署,开发环境通过代理指向后端。它不手工维护后端类型的视图:cmd/gen-contracts 从 Go wire 结构和封闭词表(来源名、申请阶段、富化 facet)生成 web/src/lib/generated/contracts.ts,所以"Go 里加了个值而 SPA 的映射里漏了"会是一个 TypeScript 编译错误,而不是一个绿色上线的空白格——例如 activityGrid.test.ts 就直接 import 该生成文件。

design-system/ 是兄弟 pnpm 包,通过符号链接而非拷贝接入 web/ 与 extension/——构建任一消费者之前要先安装它,因为两个包管理器都不会替你装被链接包自身的依赖。

三、生态系统:三种截然不同的贡献通道

三种贡献通道喂给 freehire 目录及其派生信号:贡献者、源平台、已登录用户都喂目录;目录的派生信号扇出到幽灵职位信号、沉默阶梯、facet 与统计、CV 定制证据

freehire 由三种性质完全不同的贡献喂养,系统形态反映了其中哪些便宜、哪些昂贵。

贡献者主要添的是覆盖面,而覆盖面被刻意做成一行改动。对已经在 freehire 爬取的平台上的公司,添加它只需在该 provider 的看板文件里加一条目——这是任何人都能寄出的最有用的贡献。只有跑在不支持 ATS 上的公司才需要新适配器,即便如此,所有适配器也讲同一个 Source 接口,工作量是有界的。字典是第三条路径:技能、角色、地点和非技术职称词表都是人工策展的词表,并且生产环境 dict-only——系统从不猜测 facet,未知词一律不产出。

源平台是只读的公开 JSON API,默认免密钥,适配器从不向它们写。少数例外需要厂商凭证,而该凭证只门控爬取注册表,从不门控分类注册表——一个 provider 属于什么种类的源,不应当取决于这台主机恰好能不能爬它(README.md 也指出,源的类别是适配器自身 Go 类型的属性,internal/ingest/sources 无需任何网络调用即可分类所有 provider)。

用户贡献了爬取永远无法产出的唯一证据:有人申请之后发生了什么。这些数据喂给派生信号——最显眼的就是幽灵职位信号,它把关于职位形状的结构证据与来自申请者的结果证据结合,并且被刻意构造成:仅凭结构证据永远得不出它更强的那个结论。系统观察关于职位的事实,从不揣测雇主的意图,这一约束在代码中执行,而不是靠措辞。

四、流程一:找一份工作——零 Postgres 读取的结果页

搜索请求不触碰 Postgres 取负载:读者的搜索请求被翻译成 Meilisearch 过滤器并从索引应答;Postgres 只在之后被尽力查询,取该页的幽灵职位信号

搜索路径是系统里流量最大的代码,其定义性特征是:结果页的服务不触碰 Postgres 取负载。Meilisearch 文档就是职位的公开 wire 形态,索引自己就能回答整个查询。有四点在此承重。

索引存的是 wire 形态。 JobDocument 内嵌 jobview.Job——这一点在 internal/search/search/document.go 中可以直接核对:

type JobDocument struct {
    ID int64 `json:"id"`
    jobview.Job
    // PostedTS ... 只用于 "posted within N days" 的 Meilisearch 范围过滤
    PostedTS int64 `json:"posted_ts"`
    ...
}

命中项用和详情页相同的 SPA 组件渲染,无需水化。唯一的差别是描述:为把重建控制在"能在主机空闲磁盘内换入"的体积,索引里描述被截到 1000 个 rune(常量 maxIndexedDescriptionRunes = 1000),详情端点提供全文。独立的 GET /api/v1/agent/jobs/search 端点跑完全相同的查询,但会从 Postgres 重新水化完整描述,供希望一次调用筛查一批职位的程序化消费者。

Postgres 仍然被触碰,但只为幽灵信号。 该信号背后的"缺席印章"不可能活在索引里——爬取不写它们,它们自己永远到不了 Meilisearch。这次查找按设计是 best-effort:失败时页面上只是没有徽标,而不是搜索失败。

排序有立场。 无显式排序时:空查询默认最新优先——没有文本时"相关性"没有意义——而带文本的查询保持相关度排序。

深分页是被拒绝的,不是被减速的。 窗口守卫把 offset + limit 上限钉在 10,000——约 500 页,远超真实浏览深度;报告出来的 total 允许数出比窗口能达到的更高的值。实现就在 internal/api/handler/handler.go:maxPageWindow = 10000,且先查窗口、再查库(连 slug 查询也在内),顺序由 pagination_window_routes_test.go 断言。

一个值得记住的运维陷阱曾造成过故障:新增一个可过滤属性会打开一个窗口——应用开始发出活索引尚不接受的过滤器,Meilisearch 以 400 应答,handler 把它映射成 500,于是整页过滤视图挂掉而不是降级。对策:先推索引设置,或先 reindex 再发镜像。

五、流程二:定制 CV——写入路径里的证据门

定制 CV 的回合为它写入的每一处编辑引用经验银行:候选人的 CV 以追加方式导入经验银行;定制回合逐条遍历职位的任职要求,在银行里检索带评分的证据,把每处 CV 编辑经证据门编辑器写入,最后用 Typst 渲染

CV 工作区建立在一塑造其每一部分的规则之上:agent 不得写出候选人自己没做过的主张。执行它的不是一条 prompt 指令,而是写路径里的一道证据门,证据来自一个持久化存储——经验银行。

银行是存储,不是缓存。 候选人经历的其余一切都可推导、可替换——结构化抽取每次上传都重新生成,定制 CV 随职位一起丢弃——但银行只增:上传精简的一页 CV,不应弄丢已经建起的历史,所以导入是追加的。

来源(provenance)决定可发布性。 银行里每条成就都记录:这是候选人断言的,还是模型推断的?只有前者可以写进 CV;未知来源fail closed;检查住在服务路径里,而不是系统提示里。面试排练预设走得更远:agent 归于候选人名下的引语要与该会话中对方实际输入的文字逐字比对,转述会被盖上"模型推断"的章并被禁写。

写入者只有一个。 internal/candidate/cvedit 之外没有任何东西写已存储的 CV,且这道缝靠"缺席"守住——CV 包不声明任何可能绕开的写入方法。所有入口都经过它:编辑器自动保存、模板选择器、API 的 PATCH、助手的 cv_edit、种一份定制副本。整文档 PUT 是输入格式而不是第二条写路径——differ 从它导出操作,从编辑器的视角看它与 agent 的一批操作无法区分。每条编辑同时记录"做了什么"与"撤销它要做什么",并与文档在一个事务里对锁定行写入——这也是两个 agent 回合无法在同一份 CV 上交错的原因。

渲染是沙箱化的。 模板是内嵌在二进制里的 Typst 源文件。渲染器 shell 出到 Typst CLI,工作在一个临时根下:系统字体禁用、随包字体就位;候选人数据经一个 JSON 文件送达,从不经命令行参数。字体集刻意小,且与简历解析器期待的度量兼容。

六、流程三:问 AI 助手——进程内的有界回合

有界的工具调用循环,总以恰好一个终止事件结束:Runner 每轮用调用者自己的凭证调 LLM 网关,随后要么调工具并把结果流式送回,要么流式给出最终答案;每条路径都以恰好一个终止 SSE 事件收束

助手运行在本进程内。没有外部 agent 运行时,没有 shell,没有为它铸造的凭证:工具收到会话所有者的 user id,调用 HTTP handler 调用的同一个 Go 服务。agent 不该够得到的东西,干脆就是一个不存在的工具。

一个回合被两次限界——按工具调用轮数,按模型客户端的单次超时——且两个上限都选在服务端,因为客户端能调高的上限不是上限。零或负值回退到默认而不是"无界":在无界循环跑在按量计费网关上,结果就是失控账单。默认值可从 internal/ai/assistant/runner.go 核对:defaultMaxSteps = 8,if cfg.MaxSteps <= 0 { cfg.MaxSteps = defaultMaxSteps }。

每个回合恰好以一个终止事件结束,在每条路径上:答案、步数上限、取消、失败。收不到终止事件的客户端会永远等待。

回合比读者活得久。 一次失败的 SSE 写只意味着"这个读者不再听了"——手机冻住了后台页签、笔记本休眠了——而没有别的含义。回合跑到自己的尽头,转录无论有没有人读都会存下。把那次写误当"用户走了"曾把一次无人看管定制运行、25 处已提交 CV 编辑之后的报告整个扔掉。因此"停止"是一个独立请求,因为掉线无法与刻意的 Stop 区分。

转录即模型的历史——一张表同时装下两者,工具调用和工具结果都在内,没有任何东西可让两个存储漂移。

预设只选择 prompt 和工具集,仅此而已,这便是一个聊天组件同时服务网站、CV 定制工作区、经验面试和扩展侧边栏的原因。邮件工具很好地说明边界:没有工具能按 id 打开一条消息——那会把消息标记为已读,扫积压的 agent 会把所有者的未读数清零;也没有工具能发邮件——消息正文是攻击者可控文本,对 prompt 注入最可靠的回答就是它没有出站通道。每个回合都计费到调用者自己的网关凭证,按功能和预设打标签;归因是 fail-open——它从不拒绝或弄失败一次调用。

七、认证模型:cookie 会话、API Key 与 seizure 规则

会话是无状态的 HS256 JWT,装在 HttpOnly; SameSite=Lax 的 cookie 里——从不走 Bearer 头,从不进 localStorage——所以 SPA 读不到 token,浏览器自动带上。同源加 SameSite=Lax 本身就是 CSRF 防御,没有 CSRF token。token 携带 user id 和 tv(账户的会话代数),每次认证请求都与 users.token_version 比对:抬高它(全端登出、改密码、重置)会让所有在途 token 落单;这个版本读取刻意 fail closed,也正是它终结已删除账户在各地的会话——credential_revocation_integration_test.go 断言了"推进 token_version 使所有会话失效"这一性质。

API Key 是程序化凭证。存储时哈希(SHA-256 加一段短的非秘密前缀,使 Key 在列表里可辨认),创建时精确展示一次,scope 分 full 与 cv。铸造一个要求已证明的邮箱地址,且这道门住在 SQL 语句内部而不是旁边——注册在邮箱验证之前就发了会话,否则占着别人邮箱的 squatting 者能带走一份永不过期的凭证。Key 的管理是 cookie-only 的:泄漏的 Key 不应能再铸造更多 Key。Key 不携带 tv,所以全端登出不吊销它——刻意为之,Key 是持久凭证而非会话——正因如此,一次真实的接管是删除这些行而不是让它失效。

seizure 规则补上最后一个洞:一个注册时设了密码但从未验证的账户,一旦该地址来了一位 provider 验证过的 OAuth 身份,就立即被"没收"——密码清空、会话吊销、API Key 删除(见 accounts/AGENTS.md 与 oauth_merge_integration_test.go)。OAuth 解析本身是"先身份、再已验证邮箱链接、最后新建无密码用户",全在一个事务里,且从不基于未验证邮箱去链接或创建。

八、通知:三个独立引擎、一套通道词表

三个互不共享的投递引擎共享一套通道词表。internal/engage/notify 发送命中保存搜索的新职位摘要;internal/engage/reminder 在保存的职位变陈旧之前提醒;internal/engage/nudge 在生命周期事件上触发——一份申请在某阶段阈值后归于沉默,或刚好进入 interview。各自有独立的 run-once cron worker(cmd/notify、cmd/remind、cmd/nudge)。

三条通道承载它们:SES 邮件、Telegram bot 深链 token、Expo relay 的移动推送。推送无条件注册,因为 Expo 在自己那侧保管设备凭证;另外两条是配置门控的,未配置的通道是软跳过,绝非投递失败——把它升级成失败,会让没有 SES 的环境里每次运行都失败。

两个性质让通知量保持 sane:

  • 匹配是 O(不同查询数),不是 O(订阅者数):共享同一保存搜索的订阅被分组,无论多少人订阅,索引只命中一次;
  • 投递经两阶段账本幂等——MATCH 记录"匹配了什么",DELIVER 租约并标记"已发送"——所以重扫最近的职位永远不会投递两次。生命周期 nudge 在该去重之上加了一个"episode key":在可以重新通知之前必须改变的那个事实,这正是 matcher 能每轮重扫同一份仍然沉默的申请而不重复 ping 的原因。

投递由 cron 驱动且没有重试队列,所以一条通道故障会跳过该轮摘要;账本只会补投"从未被标记已发送"的部分。

九、职位生命周期:四个独立写 closed_at 的机制

一个职位在 closed_at IS NULL 时是开放的。关闭是软状态,生命周期从不删除:已关闭的行保留其公开 slug、富化和用户引用,且职位卷土重来时免费重开。列表、搜索和公司面都过滤到开放行,而详情端点仍服务已关闭职位,使链接与历史不碎。

四个互相独立的机制写这一列,各覆盖其他机制在结构上够不到的缺口:

机制 覆盖的缺口 证据性质
Ingest sweep 该 provider 48 小时未见、且限定在本次运行真正爬过的公司范围内的职位;自关闭源被排除 证据(看板未见)
Stream-driven self-close 发布增量变更 feed、显式发出"移除"的聚合器(它们只重报变化过的部分,故 sweep 够不到) 证据(源显式移除)
Liveness probe 无任何爬取会再访问的孤儿(纯启发式 URL 探测,无浏览器、无 LLM),连续两次"已过期"读才关闭 证据(页面探测)
Age rule 根本无从探测的——Telegram 帖子的寿命长于它advertised 的职位——45 天关闭 猜测

四者中三个凭证据关闭,第四个凭猜测关闭——这恰好解释了为什么每次关闭都记录哪个机制写的(jobs.closed_reason,CHECK 约束始于 0071_jobs_closed_reason.sql,后经 0147/0159/0165 等迁移扩值),使"猜测"可以作为一个集合被整体撤销。48 小时是默认窗口,个别源可覆盖(如 whatjobs 声明 14 天以免"关闭-重开"循环,gem 声明 24 小时——见 internal/ingest/sources/AGENTS.md)。

从源码结构看,还有一段历史值得知道:曾有一个活动 cmd/prune,把不属于 IT 职位板的职位移入 pruned_jobs 归档;目录变得比 IT 更宽之后它被退役。没有任何东西硬删除职位——被它移除的职位上的申请以 NULL job_id 存活下来。

十、深入阅读指南

本文只是地图;下面的文件是领地。AGENTS.md 携带完整的模块索引(三十多个带自身约定的包),是这里没列出的任何主题的下一站。

如果你在改…… 读
添加公司或 ATS 平台 internal/ingest/sources、README.md 的 "Adding a source"
爬取、去重、看板健康 internal/ingest/pipeline
搜索、索引、reindex 事故 internal/search、internal/search/searchdrain
HTTP 路由、错误渲染、中间件 internal/api/handler
SQL、迁移、sqlc internal/platform/db
会话、Key、OAuth internal/identity/auth、internal/identity/auth/oauth
CV 工作区 internal/candidate/cv、internal/candidate/cvedit、internal/candidate/experience
助手、其工具与预设 internal/ai/assistant
邮件摄取与申请关联 docs/agents/mail-stack.md
摘要、提醒、nudge docs/agents/notifications.md
关闭、修剪、liveness docs/agents/job-lifecycle.md
SPA web/AGENTS.md、design-system/AGENTS.md
浏览器扩展 extension/AGENTS.md
功能做什么(而非怎么做) docs/features.md

更旧的、手绘的 ingest 路径视图保留在 docs/diagrams/job-pipeline.excalidraw;本文引用的各 SVG 图已取代它。

登录后查看全文
freehire