📦 Job Seek 详细部署教程

Job Seek 是一个开源的求职信息聚合平台，它监控超过 5,300 家公司的官方招聘页面和 ATS 系统，将职位信息规范化后，通过一个统一的仪表板呈现，方便你搜索和追踪。

重要提示：Job Seek 是一个面向开发者和高级用户的自托管系统。它不是一个一键安装的应用，而是由多个分布式服务组成的系统，部署和维护需要一定的技术背景。不建议没有运维经验的用户尝试。

⚙️ 部署前准备

Job Seek 由多个组件构成，在开始前，你需要准备并配置好以下完整的基础设施：

组件 用途 备注
PostgreSQL 数据库 (两个) 一个给爬虫使用，一个给 Web 应用使用。 可运行在同一服务器，但需不同的数据库名。
Redis 用于爬虫的调度和缓存。 必需。
Typesense 搜索引擎，提供快速的职位搜索。 必需。
S3 兼容对象存储 存储完整的职位描述文本。 例如 MinIO、AWS S3、Cloudflare R2。
Python 3.13+ 爬虫运行环境。 建议使用 uv 管理。
Node.js 22+ Web 应用运行环境。 建议使用 pnpm 管理。

环境变量配置

你需要为爬虫 (apps/crawler/.env.local) 和 Web 应用 (apps/web/.env.local) 分别创建配置文件。核心环境变量如下：

爬虫侧 (apps/crawler/.env.local)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 数据库
LOCAL_DATABASE_URL=postgresql://user:pass@host:5432/crawler_db
# Redis
REDIS_URL=redis://:password@host:6379/0
# Typesense (写入)
TYPESENSE_HOST=typesense.example.com
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_OPERATIONS_KEY=your-admin-key
# 对象存储 (如 R2)
R2_ENDPOINT_URL=https://your-bucket.r2.cloudflarestorage.com
R2_ACCESS_KEY_ID=your-access-key
R2_SECRET_ACCESS_KEY=your-secret-key
R2_BUCKET=your-bucket-name
R2_DOMAIN_URL=https://your-bucket.r2.dev

Web 应用侧 (apps/web/.env.local)

1
2
3
4
5
6
7
# 数据库
DATABASE_URL=postgresql://user:pass@host:5432/web_db
# Typesense (搜索)
TYPESENSE_SEARCH_KEY=your-search-key
# Next.js 认证
BETTER_AUTH_SECRET=your-auth-secret  # 生成方法: openssl rand -base64 32
BETTER_AUTH_URL=http://localhost:3000

🚀 部署步骤

步骤 1: 克隆仓库与安装依赖

1
2
3
4
5
6
git clone https://github.com/colophon-group/jobseek.git
cd jobseek

# 启用 pnpm
corepack enable
pnpm install

步骤 2: 初始化 Web 应用数据库

1
2
cd apps/web
pnpm db:migrate

步骤 3: 初始化爬虫数据库及搜索索引

1
2
3
4
5
6
7
8
9
cd ../crawler
# 安装 Python 依赖
uv sync
# 安装 Playwright 浏览器 (用于渲染页面)
uv run playwright install chromium-headless-shell
# 执行数据库迁移
uv run alembic -c src/migrations/alembic.ini upgrade head
# 在 Typesense 中创建集合
uv run crawler setup-typesense

步骤 4: 启动爬虫服务

爬虫需要运行四个常驻进程，建议使用 systemd 或 supervisor 管理。在 apps/crawler 目录下，分别启动：

1
2
3
4
uv run crawler run          # HTTP 工作进程
uv run crawler run-browser  # Playwright 浏览器工作进程（需要主机资源）
uv run crawler export       # 将数据从 Postgres 同步到 Typesense (CDC)
uv run crawler drain        # 将描述文本上传到对象存储

步骤 5: 启动 Web 应用 (开发/测试模式)

1
2
3
# 回到项目根目录
cd ../../
pnpm dev

Web 应用默认运行在 http://localhost:3000。

🧩 高级功能与用法

使用托管 MCP 服务器 (无需自托管)

Job Seek 提供了一个托管的 MCP (模型上下文协议) 服务器，供 AI 工具直接访问职位数据，无需你自行部署。

  • 端点：https://jseek.co/mcp
  • 使用方式：在支持 MCP 的客户端（如 Claude Desktop、Codex）中，将此 URL 添加为自定义 MCP 连接器。或通过 npx @jseek/mcp-server 在本地运行。

添加新公司 (贡献)

项目通过 GitHub Issue 管理公司添加请求。如果你希望添加一个公司，可以：

  1. 创建一个新的 company-request 标签的 Issue。
  2. 项目使用一个自动化的 ws 工具来处理请求。贡献者可以运行 ws task --issue <编号> 来引导一个编码代理完成研究、验证和提交 PR 的整个流程。

❓ 常见问题与排查建议

  • 部署复杂度过高：如果以上步骤让你感到困难，说明 Job Seek 的自托管门槛较高。一个替代方案是直接使用官方提供的 托管服务 jseek.co。
  • 爬虫无法工作：
    • 检查所有外部服务（Postgres, Redis, Typesense, S3）的网络连通性和凭证。
    • 查看爬虫日志，确认 Playwright 浏览器已正确安装。
    • 确保 crawler sync 命令成功执行，同步了公司配置。
  • Typesense 搜索无结果：
    • 确认 crawler export 进程正在运行，负责将数据从 Postgres 同步到 Typesense。
    • 检查 Typesense 服务状态和集合是否存在。
  • 权限与密钥：仔细检查 .env.local 文件中的密钥，特别是 Typesense 的 OPERATIONS_KEY 和 SEARCH_KEY 权限级别是否正确。

更详细的架构说明、运维手册和故障恢复指南，请务必查阅项目 docs/ 目录下的文档。