330 万条职位的数据流水线:freehire 的 225 个来源与 92 个 ATS 适配器

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

330 万条职位的数据流水线:freehire 的 225 个来源与 92 个 ATS 适配器

一个求职搜索引擎最难的部分,不是搜索框,而是搜索框背后那条把"公司官网上还挂着的一个职位"变成"索引里一条可筛选、可去重、可关闭的记录"的流水线。freehire 把这条流水线做成了开源代码:330 万条在招职位、47.7 万家公司,绝大多数不是从聚合站二手转发来的,而是直接从雇主自己的 ATS(Workday、Greenhouse、Lever、Ashby、iCIMS……)和招聘页上抓下来的。

标题里的"225 个来源 / 92 个 ATS 适配器"是某个时间点的目录快照。真正值得读的不是这两个数字,而是它们为什么会在半年里变成"320 个来源 / 117 个有职位的 ATS 平台 / 296 个适配器文件"——以及一个只有十几个人的开源项目,凭什么敢承诺"没有死链、没有重发"。答案在于把"来源"从配置文件挪进了数据库,把"平台差异"关进了一个只有两个方法的接口,并把"这条职位是不是真的没了"拆成了六条互相兜底的关闭路径。

数据版图:来源不是一个列表,而是一张表

freehire 的抓取入口只有一个 worker:cmd/ingest。它每次运行只处理一个 provider,从 Postgres 的 boards 表里读出该 provider 处于 pending / active 状态的看板,逐个抓取、归一化、去重、写入,然后退出。没有常驻的爬虫进程,也没有消息队列守护进程——调度由 cron / systemd 的 oneshot 单元负责,协调全部通过 Postgres 完成。

看板目录本身的 schema 说明了这套设计的取向(migrations/0123_boards.sql):

CREATE TABLE boards (
    id              bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    provider        text NOT NULL,
    board           text NOT NULL,
    region          text NOT NULL DEFAULT '',
    company         text NOT NULL,
    hub             boolean NOT NULL DEFAULT false,
    tenants         jsonb NOT NULL DEFAULT '{}'::jsonb,
    status          text NOT NULL DEFAULT 'pending'
                        CHECK (status IN ('pending', 'active', 'rejected', 'retired')),
    ...
);

CREATE UNIQUE INDEX boards_identity_key
    ON boards (provider, lower(board), region)
    WHERE status IN ('pending', 'active');

provider 是适配器键,board 是该平台上一个租户的标识,region 用来区分同一个看板 id 在不同地区分片下重复出现的情况(Adzuna 的 it-jobs 每个国家各有一份)。pending 并不意味着"待测试":它会被照常抓取,第一次没有发生看板级错误时由 pipeline 翻成 active;retired 也从不删除行,只是让这一行不再进入抓取集合——因此误删一个看板,重新加回来不会被自己的历史挡住。

更重要的是"一个来源属于哪一类"没有配置项。这个分类是 Go 类型的方法集推导出来的(internal/ingest/sources/classify.go):

func ProviderKind(reg map[string]Source, provider string) string {
	src, ok := reg[provider]
	if !ok {
		return KindOther
	}
	if _, ok := src.(aggregator); ok {
		return KindAggregator
	}
	if _, ok := src.(boardless); ok {
		return KindCompany
	}
	return KindATS
}

一个适配器只要实现了 aggregator() 标记方法,它就是聚合站;实现了 boardless(),它是单一雇主的招聘站;两者都不是,就是多租户 ATS。这个选择不是洁癖:sources.AggregatorProviders() 会被跨源去重直接使用——聚合站的副本可以被压制,第一方 ATS 的职位必须胜出。如果把"类型"写进配置,一处漏填就会让聚合站的转发长期压住雇主的原始职位,而且没有任何测试会失败。

按 docs/sources.md 的 2026-10-20 快照,版图是这样的:

类别 有职位的来源数 在招职位
ATS 平台 117 2,936,676
聚合站与职位板 133 444,654
公司自建招聘站 52 23,293

合计 3,371,563 条去重在招职位,来自 477,323 家公司;注册在 sources.All 里的适配器共 320 个,其中 304 个当天确实带着职位。分项相加会略高于总数,因为一条职位被两个来源同时收录时,会在两个分类里各计一次,而总数只算一次。

这里能看出数字为什么会漂移:2025 年 9 月的社区文章还在说"225 个来源、92 个 ATS、29.4 万家公司",一年后变成 320 / 117 / 47.7 万。增长不是靠改 README,而是靠往 boards 表插行——大多数公司已经在某个被支持的 ATS 上,新增一家公司就是一行目录数据,只有遇到全新的 ATS 才需要写适配器。

freehire 的系统形态:来源经 run-once ingest worker 写入 Postgres,并在同一事务里写入 outbox,队列 drain 与全量 reindex 再推入 Meilisearch,API 服务同时读 Postgres 与索引

适配器工程:两个方法的接口,装下 92 种平台方言

所有适配器共用一个极小的契约(internal/ingest/sources/source.go):

type Source interface {
	Provider() string
	Fetch(ctx context.Context, e CompanyEntry) ([]Job, error)
}

一个 provider 键、一次按看板抓取、返回一批归一化前的 Job。真正的工程量全在 Job 这个结构体的注释里——它是整个项目最值得读的一段代码,因为它把"什么算事实、什么算猜测"写成了类型契约。

type Job struct {
	ExternalID  string
	URL         string
	Title       string
	Company     string
	Location    string
	Description string
	Remote      bool
	PostedAt    *time.Time
	// WorkMode is the work arrangement when the platform states it in a STRUCTURED
	// field (a workplace-type enum or an explicit remote flag) — "remote",
	// "hybrid", or "onsite", else "". ...
	WorkMode string
	// Seniority, Category, EmploymentType, Skills ... are the platform's STRUCTURED
	// facet signals ... an adapter sets them only when the platform states the value
	// in a structured field ... never a heuristic inferred from free text
	Seniority          string
	Category           string
	EmploymentType     string
	Skills             []string
	ExperienceYearsMin *int
	...
	// Removed marks a posting the source reports as taken down ...
	Removed bool
	// SeenRefresh marks a posting a HydratingSource re-listed but did NOT fetch fresh
	// content for ...
	SeenRefresh bool
	// Unreadable marks a posting the board's listing NAMED but whose detail request
	// could not be READ ...
	Unreadable bool
}

这套"结构化字段才算数"的规则直接决定了搜索质量。Lever 的 commitment、SmartRecruiters 的 typeOfEmployment、Greenhouse 雇主自己配置的 "Employment Type" 自定义字段,都是平台明确标注过的枚举或受控值,适配器才把它们映射进 freehire 的词表;如果描述里写着 "remote-friendly",那是自然语言,交给下游的词典与 LLM 富化流程,适配器不许在这里"顺手猜一个"。原因很实际:一个适配器猜出来的 remote 会被写进索引成为可筛选事实,而筛选错误是用户能直接看见的。

第二层是可选能力,用 Go 的接口断言在运行时发现,而不是把签名撑大:

  • StreamingSource:边抓边发,长抓取中断后已完成的部分不回滚(eightfold 这类大目录适配器);
  • HydratingSource:只为"目录里还没有"的职位请求详情。Workday 一个 2.4 万职位的看板,如果不做增量水合,每轮就要为已存的描述重复发两万多个请求,足以被平台限流到失败,然后看板再也见不到、整批职位永久泄漏为"开着";
  • CoverageGated:在付费请求详情之前,先问一句"这家雇主的职位我们是否已经通过第一方 ATS 抓到了"。JobStreet 的列表本身就带雇主名,已覆盖的职位就只发列表项、不花 GraphQL 配额。

第三层是标记接口,它们不改变行为,只向 pipeline 声明"这个适配器的抓取具有什么性质":

func SelfClosingProviders(reg map[string]Source) []string      // 自己发删除信号,跳过 unseen 扫描
func FullCatalogProviders(reg map[string]Source) []string       // 每轮列全量目录,可按 source 关闭
func FullBoardListingProviders(reg map[string]Source) map[string]bool // 结构性证明列全了一个看板
func SweepGraceWindows(reg map[string]Source) map[string]time.Duration // 自定义关闭宽限期
func BoardKeyedProviders(reg map[string]Source) []string        // 按看板寻址(非 boardless)

fullBoardListing 是其中门槛最高的一个,也是踩过事故换来的。solidjobs 的适配器只抓一个看板的前 500 条,然后把这次截断当成"成功"返回;一次上线在 18 分钟内关掉了 110 条仍然在招的职位,随即回滚。现在的规则是结构性的:要么把抓取数量与平台自报的总数核对,要么分页到平台的自然结束;适配器自己的页数上限可以存在,但到达上限必须让这次 Fetch 失败,不能作为另一种静默的成功路径。hh 就被审计后刻意排除在外——它自己的搜索 UI 把任何查询的可达深度限制在约 2000 条,把这个上限当失败会让一个繁忙看板每轮都抓取失败。

三种真实的平台方言

抽象层之外,每个适配器都是一份与平台博弈的现场记录。下面三例能说明"92 个 ATS"这个数字背后到底是什么工作量。

Workday:2000 条的上限与切面细分。 Workday 的公开 CXS API 每页 20 条,且部分租户在职位总数超过 2000 时不是报错、也不是返回空页,而是静默地绕回第一页。适配器把这个常量写在了代码顶部(internal/ingest/sources/workday.go):

const (
	workdayPageLimit = 20
	// workdayCapTotal is the `total` some Workday tenants report once a board exceeds this
	// size — past offset=2000 those tenants silently loop back to page 1 instead of erroring
	// or returning an empty page. A board whose total is exactly this must be walked by facet
	// (see listPostings), not paged directly.
	workdayCapTotal = 2000
	// maxFacetDepth bounds how many facet dimensions can be combined while subdividing a
	// capped board.
	maxFacetDepth = 3
)

于是抓取路径分成两条:未封顶的看板按平台自报总数逐页走完;恰好命中 2000 的看板改为按 facet 维度递归细分(部门、地点……最多三层),直到每个子集都低于上限。细分不成功就让整次抓取失败,绝不返回部分结果——因为部分结果会被下游的关闭机制读成"剩下的职位都没了"。

Greenhouse:一次请求拿全量。 另一端是极简情形。Greenhouse 的 boards API 支持 ?content=true 把描述内联在列表里:

func (g greenhouse) Fetch(ctx context.Context, e CompanyEntry) ([]Job, error) {
	url := fmt.Sprintf("%s/%s/jobs?content=true", greenhouseBaseURL, e.Board)
	...
}

没有分页循环,也就不存在"循环提前结束"这种缺陷,适配器因此直接声明 fullBoardListing()。同一个文件里还实现了可选的 CompanyDescription:单独请求看板元数据端点拿雇主自己写的 "about us",一次抓取一次请求,而不是每条职位一次。

SEEK / JobStreet:限流是 HTTP 200。 最难缠的一类平台不按常理出牌。SEEK 网络(含 sg.jobstreet.com、th.jobsdb.com 等六个市场)在超预算后并不返回 429,而是返回 HTTP 200,body 里是:

{"errors":[{"message":"Too many requests.","path":["jobDetails","job"],
  "extensions":{"code":"RATE_LIMITED"}}],"data":{"jobDetails":null}}

适配器最初把它读成"没有内容",于是下一轮又发出去约 8000 个被拒请求、持续 50 分钟、存下 0 条职位,还极可能让封禁维持下去。修正后的策略是网络级的:同一网络里任何一个 provider 首次被拒,后续所有详情请求切到代理通道并使用独立的 pacer;代理也被拒或未配置代理,则本次运行剩余时间停止水合;每次运行最多花 1500 个详情请求预算。这些状态都写在 seekdetail.go 与 internal/ingest/sources/AGENTS.md 的实测记录里——包括"哪个市场用哪个 tuple"、"哪个分类号是 ICT"。

与单请求限流并行的还有主机级 429 退避(internal/ingest/sources/hostbackoff.go)。因为一个 provider 会以 8 路并发抓上千个看板,按请求遵守 Retry-After 是不够的:撞上 429 的那个请求在等,另外七个继续往里撞。实测在 workable 上,预算被触发后约 1500 个看板在三分钟内全部失败、两天累计 18,520 次拒绝。现在 429 会按住整个 host,指数退避到 60 秒上限,由下一个 2xx 重置;同时各平台的令牌桶 pacer(pacer.go)限制聚合请求速率。这两层机制解释了为什么这个项目能在没有分布式队列的情况下,把上千个租户的抓取压在平台可接受的速率内。

质量保障:把"看不见"和"不存在"分开

"没有死链、没有重发"这句承诺,在代码里对应两个不同的问题:一条职位重复出现怎么办,一条职位消失了怎么办。前者容易,后者才是真正的雷区。

去重:一条职位只有一个身份

去重键是 jobs.UNIQUE (source, external_id),而 external_id 的格式由一个包统一定义(internal/platform/externalid/externalid.go):

func Namespace(board, externalID string) string {
	return fmt.Sprintf("%s:%s", board, externalID)
}

用看板而不是公司名做命名空间,是因为多租户 ATS 上一个租户的职位 id 只在自己租户内唯一;同时,Telegram 链接解析出来的职位也走同一个 Namespace,这样同一条职位从两条路径进来会 ON CONFLICT 到同一行,而不是各存一份。BoardPattern 负责把这层前缀转成 LIKE 模式,并转义 % 与 _——三分之一的 Workday 看板名带下划线(Capital_One),不转义就会把兄弟看板的职位算成自己的。

SQL 唯一索引之外还有一层 Go 侧的形态折叠:iCIMS 同一个看板既可能写作 vet 也可能写作 careers-vet.icims.com,Dayforce 的可选 culture 段会让同一个站点有两种写法,Gusto 的旧 slug 与新 slug 指向同一个 uuid。这些折叠由 sources.BoardDedupeKey 完成,在写目录时比较——因为 pipeline 用字面看板名做 external_id 前缀,两种拼写会存成两套职位,而按公司作用域的关闭扫描又会因为刷新了其中一种拼写而关掉另一种拼写下的在招职位。这不是重复,是误关。

第三条去重是同公司同角色的多城复制。一家公司把一个岗位在 N 个城市各发一次,会得到 N 个共享 role_fingerprint(指纹不含地点)的看板身份;cmd/reindex 批量把除 min(id) 之外的行标成 duplicate_of。因为批量几小时才跑一次,而写入是持续的,cmd/ingest 在插入事务里同步问一次 jobdedup.CanonicalForRole,被标记的行既不进搜索队列也不进富化队列。同步路径刻意拒绝选择一个比当前行更新的 canon——批量选 min(id),若同步选了更新的兄弟,下一次 reindex 会把结论反转。

关闭:六条路径,每条都要能说清证据

职位"关闭"只是 closed_at 一个可空列,永远不会物理删除;行保留 slug、富化结果和用户引用,职位重新出现时通过 upsert 免费重开。写这个列的有六条独立路径,每条覆盖其他路径结构上够不到的空隙(docs/agents/job-lifecycle.md):

  1. 抓取后扫描:按 provider 关闭 48 小时未被看见的职位,作用域是本次真的抓到的公司。
  2. 看板作用域关闭:公司作用域救不回"某公司的最后一条职位从仍在抓的看板上掉下来"——它的 slug 再也不会出现在 company_slugs 里。
  3. 流式自关闭:增量订阅源(如 jobtech)发 Job{Removed: true},按 (source, external_id) 关闭,并被排除在 unseen 扫描外。
  4. 存活探测:cmd/liveness 对没有抓取路径的孤儿职位做纯 HTTP 探测,连续两次判定失效才关闭,只关闭、不重开。
  5. 长期不可达看板:60 天未能成功抓取的看板,由 cmd/close-chronic-boards 兜底。
  6. 空 feed 看板:抓取一直成功、但 30 天没有产出任何职位的看板——这一条在 2026-09-10 有过真实案例:某 WhatJobs 市场的发布账号被清空,每轮抓取都返回 200 和零结果,consecutive_failures = 0、last_success_at 每轮刷新,107 条职位在一个已经不再收录它们的 feed 上挂了整整一个月。

每次关闭都写入 closed_reason(unseen / feed_empty / board_unreachable / expired …),重开时清空。这不是日志洁癖:expired 是唯一基于"猜"的关闭(Telegram 的帖子 URL 在职位招满后依然可访问,没有任何证据可读,只能按 45 天有效期处理),有了这个标签,猜错的那批行可以作为一个集合被找回并恢复。

而真正的技术难点是:"我没读到"不等于"它不在了"。对 jazzhr、icims、careerplug、jobvite、successfactors、breezy、bamboohr、smartrecruiters 这类详情请求是职位唯一来源、且不做增量水合的适配器,每一轮都会重新请求每条已存职位的详情。过去一个超时或拒绝会被直接丢弃:Fetch 返回更短的列表,Stats.Failed 仍是 0,看板被记录为健康,于是这条职位在 48 小时窗口后被两条路径同时判为 unseen,从索引删除,还在 job_daily_stats 里记一笔幽灵移除。

修正划分了一条明确的线(sources.detailUnreadable):404/410 是平台在说"没这条了",仍然丢弃;超时、403/429、5xx、无法解码的响应体、返回 200 却没有职位内容,都是没有答案,返回 Job{Unreadable: true},计入 Stats.Unreadable。pipeline 的门槛写在 internal/ingest/pipeline/board_scope.go:

// maxUnreadablePercent is the share of a board's listed postings that may be unreadable
// before the crawl stops counting as evidence of what is on that board.
const maxUnreadablePercent = 5

func boardReadWhatItListed(...) bool {
	return st.Unreadable*100 <= listed*maxUnreadablePercent
}

一旦超过 5%,这次运行撤回该看板的两个关闭作用域(看板级通过 boardQualifies,公司级通过 Stats.UnprovenCompanies),但照常写入所有真正读到的职位。注意它故意不把看板判为失败:判失败会把看板冷却到 24 小时上限、冻结整个目录,比原来的 bug 更糟。5% 这个数字也是推出来的,不是拍的——单条职位的失败是独立的,在一个 5000 条的看板上,即使 0.1% 的失败率,也很难有一次零失败运行;而真正需要拦住的故障都是成片的(拒绝的源站、退租的租户、限流爆发、改版),SEEK 首次生产抓取的失败率是 87%。

看板级的健康状态另有独立机制:连续失败 3 次以下不冷却(小时级 cron 本身就是重试),从第 3 次起按 6h·2^(f-3) 指数退避、上限 24 小时,成功即自愈(internal/ingest/pipeline/cooldown.go)。冷却中的看板在触碰适配器之前就被跳过,计入 Cooled 而不是 Failed。

索引:为什么写库和搜索之间要隔一个 outbox

抓取路径从不直接与 Meilisearch 对话。一次插入或内容变更,会在同一个事务里写入 search_outbox(只存 job_id),并同时写入 enrichment_outbox。cmd/search-drain 按自己的节奏排空队列,把一批文档作为一个 Meili 任务推送。

这不是微优化,而是被生产事故逼出来的。Meilisearch 每次推送都会对整个倒排索引与 facet 结构做一次全量再合并,与批量大小几乎无关:在 270 万文档的索引上实测单次 90–180 秒。早期设计里约 169 个按看板并发的 worker 各自直推,直接把宿主磁盘 IO 打满。改成 outbox 之后,"推送次数"从每看板每轮一次降到每 drain 周期一次。

同一套机制还有一个镜像队列:search_delete_outbox,专门记录"把这条文档从索引删掉"。cmd/search-drain 在一次排空里先处理删除、再处理写入,顺序是硬性的。反过来会怎样?2026-09-06 的实测:索引队列到达 2504 条/分钟、排空 2614 条/分钟,一次 5 小时的 reindex 让队列积压到五小时深度,索引阶段两小时没返回;因为 Type=oneshot 不会起第二个实例,删除阶段在那段时间一次都没跑,13.4 万条已关闭职位仍然在搜索结果里可见。索引侧全程健康(failed=0、dead=0),问题纯粹是被写入阶段饿死。

另一个容易踩的运维陷阱写在 internal/search/searchdrain/AGENTS.md 里:每一条关闭职位的 SQL 都必须同时把移除请求写进 search_delete_outbox,并且由 TestEveryClosingQueryQueuesTheRemoval 枚举所有关闭查询——这个测试是一份手写清单,而 cmd/liveness 的两条关闭查询曾经既不在测试里、也不在队列里,直到 2026-09-06 才补上。

这套流水线真正的产出:可被检验的筛选

把上面这些拼起来,才能理解为什么一个"职位搜索引擎"值得写 296 个适配器文件。

用户在界面上看到的是一组分面:地区、工作形式、专业方向、资历。每一个分面都必须来自结构化信号或受控词典,而不是从标题里猜。freehire 的词典在 internal/dict/ 下(地点、技能、职级、非技术标题),并且是只按词典、不猜:遇到词典不认识的词,就什么都不输出。抓取过滤器同样如此——一个被抓到、被标题词典确认为非技术、且没有解析出任何类别的职位,会在写入之前被拒绝并计入 Stats.Rejected(拒绝是过滤器在工作,跳过才是哪里坏了),而一个护士职位因为被归到 healthcare 类目反而会被保留,因为目录本身比 IT 更宽。

freehire 搜索界面:左侧按地区、工作形式、专业方向、资历逐层收窄,右侧每条职位直接链接到雇主原始招聘页

这也解释了"没有重发"的实际含义。它不是承诺全网唯一——同一条职位在不同聚合站上的转发是客观存在的;它承诺的是:在 freehire 的目录里,同一条职位只有一个身份,只有一份文档,只有一个可点击的原始链接。 做到这一点需要三样东西同时成立:external_id 的看板命名空间、跨源聚合站压制、以及角色簇去重;缺一个,用户就会在同一次搜索里看到同一份工作三次。

同理,"没有死链"也不是靠定期跑一遍链接检查器。它是六条关闭路径加上"不可读不等于不存在"的区分共同保证的:一条职位只有在有证据时才会被关掉,没有证据时它会继续留在目录里——因为对一个求职者来说,一条暂时读不到的职位,远好过一条被误删的职位。solidjobs 那 18 分钟、110 条职位的误关,就是这条原则的价格标签。

数据规模会继续变:225 → 320 个来源,92 → 117 个有产出的 ATS,29.4 万 → 47.7 万家公司。但支撑这些数字的机制是稳定的——一个两方法的接口、一份存在数据库里的看板目录、一套"结构化才算事实"的字段契约,以及一组宁可少关、不可错关的关闭规则。要复现这套流水线的难度不在代码量,而在于愿不愿意为每一种平台方言写下它真实的行为,包括那条返回 HTTP 200 的限流响应。

登录后查看全文
freehire