freehire 技术详解:用 Go 构建开源求职搜索引擎——从源适配器、爬虫管线到分面搜索

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

freehire 技术详解:用 Go 构建开源求职搜索引擎——从源适配器、爬虫管线到分面搜索

本文基于 freehire 仓库的 README.md 及其源码展开,介绍这个"直接从企业 ATS 抓取职位"的开源求职搜索引擎:如何一键拉起完整技术栈(Go + Fiber + PostgreSQL/pgvector + Meilisearch + Redis + S3)、如何运行其"run-once"worker 体系(ingest、enrich、search-drain、reindex 等)、如何通过统一的 Source 接口与 boards 目录添加一个新数据源,以及它的公开 API、仓库布局与前端/扩展生态。读完你可以独立部署 freehire、读懂其爬虫到搜索的核心链路,并知道向项目贡献一个数据源的具体路径。

freehire 分面搜索演示:按地区、工作方式、专业方向与资历筛缩 330 万+条在线职位,每条直达公司自己的招聘页

freehire 解决什么问题

freehire 的定位是一句话:每一则 IT 职位都直接来自源头。它的核心主张可以归纳为四点(见 README.md "Why freehire" 一节):

  • Straight from the source(直采源头):每一则 listing 都从企业自有的 ATS——Workday、Greenhouse、Lever、Ashby、iCIMS 及大量长尾平台——直接爬取,并链接回原始职位页。没有招聘中介转帖、没有聚合站二传手、没有失效链接。
  • One schema, deduplicated(单一模式 + 去重):同一个职位发到三个招聘板,会被折叠成一条记录——所有 postings 归一化到统一结构,并按稳定键去重。从 内部架构文档 可以看到,去重键是 jobs.UNIQUE (source, external_id),因此重复跑一次抓取是"免费"的(幂等 upsert)。
  • Search that understands jobs(理解职位的搜索):在地区、工作方式、资历、技能、薪资等维度上做分面全文检索,这些 facet 值来自人工维护的字典(internal/dict 下的 location/classify/skilltag),从不靠猜测——字典里查不到就留空,而不是瞎填。
  • Actually open(真正开源):MIT 协议、可自托管,管线与数据模型全部公开;添加一家公司通常只是 boards 目录里的一行配置。

README 给出的规模数据(2026-10-20 快照):3,371,563 条去重后的在线职位,来自 477,323 家公司、320 个源,其中 304 个源当日仍在产出。逐源的完整拆分见 docs/sources.md。

除"找职位"这个目录(catalogue)之外,README 的 "Beyond the catalogue" 一节说明同一仓库还基于同一份数据构建了完整闭环:

环节 能力
Find(找) 分面搜索、精选合集(curated collections)、带邮件/Telegram 摘要的保存搜索、共享 board、市场分析、ghost-job(幽灵职位)信号
Apply(投) 带 ATS 安全 PDF 模板的 CV 编辑器、确定性的 CV↔职位匹配评分、AI 匹配度分析、"不编造内容"的 CV 定制、tracer 链接、内推
Track(跟) 带阶段(stage)的申请看板、能把 HR 来信关联到具体申请的邮件收件箱、append-only 事件账本、提醒
Ask(问) 进程内 Agent,五个预设(chat、browse、profile、CV tailoring、interview rehearsal),无 shell、不铸造任何凭据
Build on(构建) 免密钥公开 API、CLI、MCP server、表单自动填写的浏览器扩展、ChatGPT Actions

完整功能参考在 docs/features.md,其中说明了每项功能的代码位置、哪些需要配置 LLM 端点、哪些消耗 AI credits。

技术栈

README 列出的 Stack 部分,配合 go.mod 可以一一核对到实际依赖:

  • Go + Fiber v2(gofiber/fiber/v2 v2.52.15)——HTTP 服务器;
  • PostgreSQL + pgvector——存储、过滤、语义嵌入(迁移 0092 会执行 CREATE EXTENSION vector,见 docker-compose.yml 注释);
  • sqlc——从手写 SQL 生成类型安全的 DB 访问代码,无 ORM;
  • Meilisearch(meilisearch-go v0.36.3)——职位全文与分面搜索;
  • langchaingo——面向任意 OpenAI 兼容端点的 LLM 访问,不绑定供应商;
  • Bifrost——LLM 网关:每用户虚拟密钥、跨供应商回退、花费追踪;
  • Langfuse——LLM 调用链追踪与可观测性;
  • SvelteKit 2(Svelte 5 runes)+ Tailwind 4——web/ 下的服务端渲染前端;
  • Redis——限流与实时扇出;S3 兼容对象存储——CV、头像、预览文件;
  • Prometheus + Grafana——ingest/LLM 基础设施的指标与看板;
  • Docker Compose——本地开发环境。

快速开始:一条命令拉起全栈

make up        # 构建并通过 Docker 启动整套栈:
               # api, web, postgres, meilisearch, redis, s3
curl localhost:8080/health
curl localhost:8080/api/v1/jobs

从 Makefile 看,make up 实际执行 $(COMPOSE) up --build -d,且 Makefile 优先探测 docker、缺失时自动回退 podman(也可用 make DOCKER=podman up 强制覆盖)。

docker-compose.yml 定义了六个服务,值得注意的设计细节:

  • db:pgvector/pgvector:pg18(不是官方 postgres 镜像,因为 pgvector 无 Alpine 版);./migrations 挂载到 /docker-entrypoint-initdb.d,迁移在卷首次初始化时自动应用;
  • meilisearch:getmeili/meilisearch:v1.49.0,开发密钥默认 dev-insecure-meili-key;
  • redis:限流计数是无状态 TTL 数据,因此不给卷——重启丢失等价于 fail-open,不算数据丢失;
  • s3:本地用 adobe/s3mock(内存版 S3),配一个 s3-init 容器先建好 hire-resumes bucket,app 依赖的是 init 完成而非 server 本身;
  • app:DATABASE_URL 指向 db 服务,PORT=8080,宿主端口可用 HIRE_HOST_PORT 覆盖;
  • web:SvelteKit SSR,由 nginx 同时前置 Node SSR 与 Go API,保证同源(auth cookie 需要),宿主端口默认 8090。

迁移的行为约定(README 明确写出):迁移只在 Postgres 卷首次初始化时自动应用。修改某个迁移文件不会重放到已有卷上——要么 docker compose down -v && make up 重建卷,要么用 make migrate 手动把 migrations/ 里的文件逐条应用到现有库。

端口冲突:如果 8080 已被占用,换一个宿主端口:

HIRE_HOST_PORT=8090 make up

本地开发

docker compose up -d db   # 只启动数据库
make run                  # 在宿主机上跑 server,读取 DATABASE_URL

make run 即 go run ./cmd/server。配置入口是环境变量:把 .env.example 复制为 .env 按需修改。关键约束:

  • JWT_SECRET 是 server 启动的硬性要求——未设置或少于 32 字节时快速失败(fail fast);
  • OAuth 与 LLM 凭据都是可选的:对应特性在凭据缺省时保持关闭(例如未配置 OAUTH_GOOGLE_* 时登录按钮不出现、路由 404;LLM_BASE_URL/LLM_API_KEY/LLM_MODEL 为空时所有模型相关表面优雅降级)。

从 docker-compose.yml 的环境变量块还能看到一批可选旋钮:ASSISTANT_MODEL(assistant 专用模型,缺省回退 LLM_MODEL)、CV_MAX_BULLETS(每条经历/项目允许的 bullet 数,<1 时按 20 处理)、MATCH_ANALYSIS_MAX_*(匹配度分析对模型输出的字符上限,未设则用 internal/matchanalysis 的默认边界)、PII_FILTER_URL(PII 过滤服务,本地无默认值即视为关闭,简历结构化优雅降级)。

常用命令

README "Commands" 一节列出的核心命令,均可在 Makefile 中核对:

make help      # 列出全部命令
make sqlc      # 从 SQL 重新生成代码(经 Docker 运行 sqlc:1.31.1,本机无需安装)
make tidy      # go mod tidy
make psql      # 进入 DB 容器的 psql(psql -U hire -d hire)
make reindex   # 从 Postgres 重建 Meilisearch 索引
make migrate   # 向已有卷手动应用 migrations/*.sql

Makefile 中还有 README 未展开的一组生成器命令,它们体现了"数据即代码"的约定:

  • make gen-contracts——从 Go 的 wire 结构体与封闭词表重新生成 web/src/lib/generated/contracts.ts,前端类型不再手维护;
  • make gen-cities / make gen-metros——从 GeoNames 等数据源再生成 internal/location 与 internal/dict/location 的城市/都会区词表;
  • make gen-skill-descriptions——为技能词表起草下一批描述(打印到 stdout,必须人工逐行审阅后才提交进 internal/dict/skilltag/descriptions.tsv);
  • make cover / make cover-integration——分别产出单测与集成(testcontainers)覆盖率报告。

Workers:只有两个常驻进程,其余全是 run-once

freehire 最显著的结构决策(README.md "Workers" 与 docs/architecture.md 一致):server 只负责提供 API;其余一切——爬取、富化、索引、通知——都是独立的、跑完即退出的 worker,为 cron 而生:爬一次或排空一次队列,然后退出。

go run ./cmd/migrate       # 应用挂起的迁移(部署读取新 schema 的代码前必须先跑)
go run ./cmd/ingest greenhouse  # 抓取某 provider 的目录板并 upsert 职位(也可用 INGEST_PROVIDER)
go run ./cmd/enrich        # 排空富化队列(LLM);需要 LLM_* 配置
go run ./cmd/embed         # 排空语义队列,写入 pgvector 分块
go run ./cmd/search-drain  # 把队列中的职位写入写入实时搜索索引(建议每 1-2 分钟跑一次)
go run ./cmd/reindex       # 从 Postgres 整体重建 Meilisearch 索引(原子换入)
go run ./cmd/tg-ingest     # 抓取 telegram_channels 表中的活跃频道
go run ./cmd/tg-extract   # 用 LLM 从已抓取的 Telegram 帖子里抽取职位
go run ./cmd/capture-apply-form  # 抓取排队职位的 ATS 申请表单
go run ./cmd/backfill-derive     # 一次性 keyset 遍历,重派生所有确定性列
                               # (facet、指纹、slug),随后 make reindex

几条值得记住的不变量:

  1. 每个 worker 都要求 DATABASE_URL,失败时以非零码退出。生产上防止 worker 自我叠加的是 systemd 的 Type=oneshot,而不是文件锁(见 docs/architecture.md)。
  2. 没有任何 worker 硬删职位——生命周期只做"软关闭"(soft-close)。
  3. 整个仓库只有 cmd/server 和 cmd/mail-ingest(入站邮件监听)两个长驻进程;worker 之间、worker 与 server 之间不共享内存,所有协调都发生在 Postgres 里——这就是为什么写路径上到处是"事务性 outbox":引发写入的事务里同时入队一条 outbox 行,之后由对应 worker 排空。

从 Dockerfile 可以确认生产镜像确实只打包了"server + 一组 run-once worker":/app/hire 是默认入口,/app/ingest、/app/enrich、/app/reindex、/app/tg-ingest 等由 docker compose run --rm app /app/<worker> 按调度调用,镜像里还内嵌了静态编译的 typst 二进制用于渲染 CV PDF。

ingest worker 的内部链路

cmd/ingest 的 main.go 头部注释把链路讲得很清楚:

  1. 每次运行只处理一个 provider(第一个位置参数,或 INGEST_PROVIDER),从 boards 表加载该 provider 的 pending/active 板——每个 provider 按自己的节奏爬,慢平台不会阻塞快平台;
  2. 支持 --shard=i/n(对板做 round-robin 切片,供 workday 这类板数超大的 provider 错峰并行)与 --board=<id>(配合 --region=<code>,手工重同步单一公司/关键词);
  3. 每个 board 的入表时校验(provider 已注册、非 boardless 时 board id 非空)在进 catalog 时就已经完成(internal/ingest/boardcatalog),worker 不重复校验;
  4. 拉取、归一化、去重、upsert 交给 internal/ingest/pipeline 的 Runner,新职位或内容变化的职位在同一个事务里写入 search_outbox(供实时索引)与富化 outbox;
  5. 抓取后对该 provider 的过期职位做 sweep(关闭窗口默认 48h,adapter 可自声明更宽/更窄的窗口,见 internal/ingest/sources/source.go 中 DefaultSweepGrace 与各 marker 的说明);
  6. 索引推送之所以走 outbox 而不是直推,是因为 Meilisearch 每次 push 都会对整个活索引做重合并——按 docs/architecture.md 的测量,约 270 万文档的索引单次 push 就要 90–180 秒,"很多小推送合并成少数大推送"是关键优化。

仓库布局

README "Layout" 一节给出的目录地图(保留原结构),internal/ 下约 130 个领域包:

cmd/                 入口:server + 上述独立 worker
migrations/          SQL schema(sqlc 与 initdb 的单一事实源)
web/                 SvelteKit 前端
extension/           Chrome 侧边栏扩展
design-system/       共享 token 与组件,以 symlink 链接进 web/ 与 extension/
internal/            ~130 个领域包,承重者:
  config/            环境配置
  database/ db/      pgxpool 连接池;生成的 sqlc 代码 + queries/*.sql
  handler/           HTTP handler
  auth/              认证原语(JWT cookie、API key)+ OAuth 登录
  sources/           源适配器(greenhouse / lever / adzuna / …)+ 注册表
  boardcatalog/      boards 目录:哪家公司在哪个 ATS、用什么 board id
  pipeline/          ingest 执行器(fetch → normalize → dedup → upsert)
  linksource/        解析 Telegram 帖子里出现的外链职位
  telegram/          Telegram 频道抓取 + LLM 职位抽取
  enrich/            类型化 AI 富化契约 + 队列排空 runner
  search/ searchdrain/  Meilisearch 索引与查询;写入队列的增量排空
  embed/             语义分块嵌入写 pgvector
  location/ classify/ skilltag/  人工维护的 facet 字典——不猜测,查不到就留空
  ghost/             "这职位是不是真的"背后的发布现实信号
  jobview/           职位的单一公开 wire 结构
  cv/ cvedit/        结构化 CV + PDF 渲染;cvedit 是其唯一写入者
  experience/        持久化经历 + 支撑每条 CV 声明的证据原子
  cvmatch/ matchanalysis/  确定性 CV↔职位评分;LLM 匹配度分析叠在其上
  applyform/        以平台自身词汇捕获的 ATS 申请表单
  userjob/ appevent/ 每用户追踪(view/apply/save/stages)+ 事件账本
  inbox/             HR 来信 → 分类 → 关联到具体申请
  assistant/        进程内 agent:turn 循环、工具、转录
  browsertools/     agent 与浏览器扩展之间的工具帧中继
  referral/ collections/  内推;精选公司标签
  llm/ llmkey/      供应商无关 LLM 客户端 + 每用户花费归因

注意 internal/ingest/pipeline/AGENTS.md 这类 per-package 文档是 docs/architecture.md 所指"territory"的落点——每个承重包都带自己的 AGENTS.md 说明不变量与陷阱。

架构:从爬虫到搜索的拓扑

docs/architecture.md 是仓库自带的全局地图,核心论点浓缩为:

  • Go 单体 + run-once worker 星座。HTTP server 只做一件事:提供 API(含 assistant 的请求时 LLM 调用)。没有队列守护进程、没有长驻后台运行时。
  • Postgres 是系统之纪(system of record):目录、账号、CV、申请、邮件、assistant 转录全在其中;internal/platform/db 是 sqlc 生成代码且已提交(仓库不装 sqlc 也能构建);migrations/ 同时喂养 sqlc codegen 与 Postgres 首次启动的 initdb。
  • 写入即入队:爬虫写入 posting 的同一事务里,若是新职位进 enrichment_outbox,若内容变化进 search_outbox——内容未变的重爬走廉价路径只刷新 last_seen_at,避免整个目录每几小时被重索引一遍。
  • 搜索只建一个索引:jobs 索引存储的是职位的完整公开 wire 结构(而非指针),所以搜索结果页无需回 Postgres 取数即可渲染;cmd/reindex 从零重建并原子换入,在线读取不受重建影响。
  • API 单一 wire 形状:internal/job/jobview 同时服务列表接口、详情接口与搜索索引,三者不可能漂移;响应统一为 {"data": ...}(单个)、{"data": ..., "meta": {...}}(列表)、{"error": msg}(失败)。

公开 API:免密钥的目录 API

目录通过公开、免密钥的 HTTP API 提供——GET /api/v1/jobs 不需要任何凭据。寻址规则:jobs 与 companies 一律使用其公开 slug。响应信封三选一:{"data": ...} / {"data": ..., "meta": {...}} / {"error": msg}。

完整端点参考(每个端点的参数、鉴权模式、全部搜索过滤词表)见 docs/API.md。限流相关行为可以从 .env.example 看到:匿名读取默认 600/min、agent search 300/min;设置 PUBLIC_ANON_LIMITS=strict 则收敛为共享的 120/min + 2000/day/IP。

数据源:三种 kind,分类由代码"长出来"

README "Sources" 一节给出的快照(2026-10-20)与三个 kind:

Kind 含义 当日有产出的规模
ATS platforms 每个多租户 ATS 一个适配器,一家适配很多公司(Workday、Greenhouse、Lever、iCIMS…) 117 个平台 · 2,936,676 条在线职位
Aggregators & job boards 第三方 feed,重发多家公司职位(Adzuna、trudvsem、himalayas、97 个 Telegram 频道…) 133 个 · 444,654 条
Company career sites 直接从公司自有招聘页抓取的单公司 feed(Amazon、Apple、Google、Yandex、Sber…) 52 个 · 23,293 条

Kind 不是配置,而是适配器 Go 类型的属性。从 internal/ingest/sources/classify.go 看,分类完全由 adapter 的 marker 接口推导:实现了 aggregator marker 的就是聚合站;实现了 boardless marker 且非聚合的是单公司站点;其余(带 per-tenant board id 的)即多租户 ATS。这个"从源码结构看"的机制意味着分类与配置无关、与网络调用无关,internal/ingest/sources 可以在不发起任何请求的情况下对整个 provider 分类。逐源的开放职位数明细在 docs/sources.md(如 workday 596,262、trudvsem 347,656、oracle 287,895 等)。

适配器注册表在 internal/ingest/sources/registry.go 的 All(c HTTPClient) 中组装:一个 HTTP client 在数百个适配器间共享;重复的 provider key 会直接 panic(两个适配器认领同一平台属于编程错误)。从该文件还能看到大量工程细节:按 IP 限速的平台各自挂 paced* 限流器(如 ADP 的 ~2800 个 board 共享一个 metered host)、需要 cookie 会话的平台走 cookieSessionSource、被边缘节点拒绝默认指纹的平台(meta、uber、gusto 等)使用 Chrome 指纹传输、俄罗斯可信根 CA 的三家银行共享一个额外信任根。Taxonomy()(即 All(nil))则构建无传输的纯分类注册表——凭据只门控"爬取注册表",从不断供"分类注册表",保证一个没有凭据的主机对源 kind 的判断与有凭据的主机完全一致。

添加一个数据源:一行配置或一个适配器

这是 README 着墨最多、也是贡献者最重要的路径,分两级:

加一家公司:boards 目录里的一行

boards 目录现在是数据而非代码(一行一个 company + provider + board),由数据库表承载(internal/ingest/boardcatalog),取代了早期的 sources/*.yml。两条添加入口:

  • 站点上的 "contribute a board" 表单——众包提交进入 pending 状态,由首次成功爬取证明后转 active;
  • 策展人命令行(cmd/add-board/main.go):
go run ./cmd/add-board --provider=… --board=… --company=… --apply

不带 --apply 时只校验并打印候选行,不落库。该命令还支持 --retire(把行置为 retired 而不是删除,保留历史)、--rename(修正公司名称)、--region(区域 host 用)、--hub 与 --tenants(社区/中介 hub 板用)。

入表时校验先于一切爬取:boardcatalog.Validate(catalog.go)把候选行包装成 sources.Config,检查 provider 已注册、非 boardless 平台必须有 board id——这就是 README 所说"board 在进入目录时就被注册表校验,任何请求发出之前"。

加一个 ATS 平台:新适配器 + 注册表一行

当目标公司运行在尚未覆盖的 ATS 上,才需要新 provider:在 internal/ingest/sources 写一个新适配器,并在 All 里加一行。所有适配器都说同一个 Source 接口(internal/ingest/sources/source.go):

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

Job 结构体现了"结构化信号优先"的契约:WorkMode、Seniority、Category、EmploymentType、Skills、薪资字段等只允许在平台以结构化字段显式给出时填写(例如 ATS 的枚举/remote flag),自由文本位置串一律留空交给管线里的字典判定;此外还有 StreamingSource(边爬边持久化)、HydratingSource(只为目录里没有的新职位拉详情)、CoverageGated(对反正会被丢弃的职位跳过详情请求以省成本)等可选增强接口,adapter 按需实现。

README 建议:想加源就先开 issue,写清公司与招聘页 URL,维护者会先确认这是"一行配置"还是"新 provider",再动手。

前端与浏览器扩展

  • 前端:web/ 下是一个服务端渲染的 SvelteKit 2 应用(Svelte 5 runes、Tailwind 4、adapter-node),与 API 同源消费;开发期由 Vite proxy 把 /api 转发到后端。共享 token 与组件来自姊妹包 design-system/——它是 symlink 进 web/ 与 extension/ 的,不是复制,因此构建 web/ 或 extension/ 之前必须先安装它(包管理器不会替你装被链接包的依赖)。详见 web/AGENTS.md。
  • 浏览器扩展:extension/ 下的 Chrome 扩展把求职申请 agent 放进侧边栏,贴在你正在浏览的任意职位页旁:你提问时它读取当前页面、展示与你 freehire 档案的确定性技能覆盖匹配,并可以替你填写申请表单。源码入口见 extension/AGENTS.md。

贡献、文档与协作约定

README "Contributing" 一节的立场:Issues 与 PR 对所有人开放,没有 allowlist、没有审批环节。最高价值的贡献就是加一个你本会去投递的公司的 board——它只需要一个 URL。半成品想法也欢迎直接进 Discussions;大的改动建议先开 issue 对齐方向,但从不阻止直接提 PR。CI 的检查项见 CONTRIBUTING.md,架构与代码约定见根目录 AGENTS.md。

安全漏洞通过私有渠道报告——见 SECURITY.md,不要为安全敏感问题开公开 issue。项目采用 MIT 许可证。

小结

freehire 的价值密度集中在三个可复制的工程模式上:其一,"run-once worker + 事务性 outbox"的无队列后台体系——不引入消息中间件,用 Postgres 表承担全部协调,worker 失败即非零退出、由 cron/systemd oneshot 负责重试与防叠加;其二,适配器注册表 + boards 数据目录——把"支持一家新公司"压缩为一次带校验的入库,把 kind 分类做成 adapter 类型的静态属性,使分类、去重、限流策略都能与具体运行主机解耦;其三,"字典优先、绝不猜测"的 facet 派生——结构化信号 > 字典派生 > 留空,配合 (source, external_id) 幂等去重与软关闭生命周期,让大规模重爬始终安全。从 make up 拉起的本地栈,到 cmd/ingest、cmd/search-drain、cmd/reindex 组成的离线流水线,再到免密钥的 /api/v1/jobs,这套链路在仓库内全部可运行、可验证。

登录后查看全文
freehire