freehire 是一个开源的工作搜索引擎（job search engine），从数百个 ATS 招聘平台持续抓取职位，提供面状筛选、申请跟踪与 AI 分析能力。这篇指南帮助新贡献者从零搭起本地开发环境：涵盖最实用的make命令速查、sqlc代码再生成流程，以及一套与 CI 完全对齐的 pre-commit 检查清单。

一、安装前置依赖

在动手之前，先确认本机具备以下工具（详见 CONTRIBUTING.md 与 AGENTS.md）：

克隆仓库并进入根目录：

git clone https://gitcode.com/gh_mirrors/fr/freehire cd freehire

💡 约定俗成的第一条规则：你必须理解自己提交的代码。小 PR 评审最快；架构级改动建议先开 issue 对齐方案。

二、make up 一键启动本地环境

freehire 的所有本地服务（Postgres + Meilisearch + Redis + S3 + API + 前端）都由 docker-compose.yml 编排，一条命令即可拉起：

make up # 等价于 docker compose up --build -d curl localhost:8080/health curl localhost:8080/api/v1/jobs

各服务与端口一览：

首次初始化卷时，migrations/目录会挂载进/docker-entrypoint-initdb.d，全部迁移自动执行。启动成功后，本地职位列表页面长这样：

两个高频运维命令：

make down # 停止并移除容器 make logs # 跟踪应用日志（compose logs -f app）

⚠️注意：修改已存在的迁移文件不会重新应用到已有卷上。需要重置数据库时执行docker compose down -v && make up，或对已有卷手动补跑make migrate。

三、两种本地开发模式

1. 全 Docker 模式：make up，前后端全部跑在容器里，适合快速验证功能。
2. 宿主机进程模式：数据库仍用容器，服务器跑在宿主机上，调试体验更好：

docker compose up -d db # 只启动数据库 make run # 宿主机上运行 server，读取 DATABASE_URL

宿主机模式下，把 .env.example 复制为.env按需调整——JWT_SECRET是必填项（缺失或不足 32 字节时服务器直接拒绝启动）；OAuth 与 LLM 凭据均为可选项，不配置时对应功能自动降级为禁用。

如果服务器跑在宿主机上，部分功能还需要这些可执行文件在PATH中：

启动整套服务后，你可以像真实用户一样体验 freehire 的面状筛选与保存过滤器：

四、Make 命令速查表

Makefile 提供了完整开发工作流，执行make help可随时查看全部命令：

五、sqlc 代码再生成流程

freehire 用 sqlc 实现"类型安全的数据库访问"：你不写 ORM，你写 SQL，Go 代码由 sqlc 生成。关键路径：

• 查询源文件：internal/platform/db/queries/（每个领域一张.sql文件）
• 模式来源：migrations/
• 生成物（已提交入库）：internal/platform/db/

sqlc.yaml 将模式指向migrations、查询指向internal/platform/db/queries，输出到internal/platform/db，驱动为pgx/v5。

贡献者的铁律：

1. 永远编辑queries/*.sql，不要手改internal/platform/db/下的生成代码；
2. 每次修改查询或迁移后，立即执行make sqlc并提交再生成结果——该命令通过容器运行固定版本（1.31.1）的 sqlc，团队之间零版本漂移；
3. 永远不要修改已应用的迁移，一律新增迁移文件（expand/contract 策略）。

make sqlc # 一行完成：docker run sqlc generate

pre-commit 阶段有专门的sqlc-drift钩子替你兜底：它会重新执行make sqlc，如果发现 internal/platform/db/ 下出现未暂存的漂移（包括从未提交的新文件），直接拦截提交——"改了查询却没再生成"这种事故在本地就会被拦下。

六、安装 pre-commit 钩子（lefthook）

钩子配置集中在 lefthook.yml，每个克隆只需安装一次：

go install github.com/evilmartians/lefthook@latest lefthook install

主要检查项按职责分组：

💡 棘轮策略与 CI 完全一致，所以本地通过 ≈ CI 通过；gitleaks与 CI 的gitleaksworkflow 是"两道闸门、两个时刻"，--no-verify跳过本地钩子后，CI 仍会扫描全部历史。

七、提交前自检清单（与 CI 对齐）

改完代码、推送之前，把这组命令跑一遍（摘自 CONTRIBUTING.md）：

gofmt -l . # 必须无输出 go build ./... go vet ./... go test ./... # 单元测试（无外部依赖） go vet -tags=integration ./... # 廉价守卫：编译带 integration 标签的文件，秒级

如果改动涉及 Docker 依赖行为（查询、schema、handler），再跑完整集成套件：

go test -tags=integration ./... # 需要 Docker（testcontainers）

⚠️go test ./...不会编译任何//go:build integration文件——只改签名也能骗过前三条命令，vet -tags=integration是防漏网的最便宜保险，建议每次推送前都执行。

前端改动（web/）则按顺序构建，design-system 必须先于消费方：

cd design-system && pnpm install && pnpm build cd ../web && pnpm install && pnpm run check && pnpm run build

提交前再生成清单——源变了，产物必须一起提交：

• 改了internal/platform/db/queries/*.sql或migrations/→ 执行make sqlc
• 改了 Go 契约类型 → 执行make gen-contracts

八、常见问题速答

• 8080 端口被占用？换宿主机端口再启动：HIRE_HOST_PORT=8090 make up（DB_HOST_PORT、MEILI_HOST_PORT同理）。
• 改了迁移但数据库没生效？已初始化的卷不会重放迁移：docker compose down -v && make up重置，或make migrate手动补跑。
• 钩子报 "Generated code was stale"？说明make sqlc刚替你修好了漂移，把结果git add进本次提交即可。
• 能用--no-verify跳过钩子吗？能，但 CI 会重新检查并扫描完整历史——本地跳过只是让红色结果来得更早一点。

环境就绪后，从一个小 PR 开始：修一个 typo、补一个测试、给 cmd/ 下某个 worker 加文档，都是被欢迎的贡献方式。祝提交顺利 🚀