SETUP.zh-CN.md

Resume Matcher 安装与配置指南

English | Español | 简体中文 | 日本語

欢迎！本指南将带你在本地完成 Resume Matcher 的安装与配置。无论你是想参与开发，还是只想在本机运行应用，都可以按本文档完成上手。

---

目录

• 前置条件
• 快速开始
• 逐步安装
  • 1. 克隆仓库
  • 2. 后端配置
  • 3. 前端配置
• 配置 AI 提供商
  • 选项 A：云端提供商
  • 选项 B：使用 Ollama 的本地 AI（免费）
• Docker 部署
• 访问应用
• 常用命令速查
• 故障排查
• 项目结构概览
• 获取帮助

---

前置条件

开始前请确保系统已安装以下工具：

工具	最低版本	如何检查	安装
Python	3.13+	python --version	python.org
Node.js	22+	node --version	nodejs.org
npm	10+	npm --version	随 Node.js 一起安装
uv	最新	uv --version	astral.sh/uv
Git	任意	git --version	git-scm.com

安装 uv（Python 包管理器）

Resume Matcher 使用 uv 来实现更快、更稳定的 Python 依赖管理。可通过以下方式安装：

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或通过 pip
pip install uv

---

快速开始

如果你对开发工具比较熟悉，想快速跑起来：

# 1. 克隆仓库
git clone https://github.com/srbhr/Resume-Matcher.git
cd Resume-Matcher

# 2. 启动后端（终端 1）
cd apps/backend
cp .env.example .env        # 从模板创建配置
uv sync                      # 安装 Python 依赖
uv run uvicorn app.main:app --reload --port 8000

# 3. 启动前端（终端 2）
cd apps/frontend
npm install                  # 安装 Node.js 依赖
npm run dev                  # 启动开发服务器

浏览器打开 http://localhost:3000 即可。

注意： 使用应用前需要先配置 AI 提供商。见下方 配置 AI 提供商。

---

逐步安装

1. 克隆仓库

先把代码拉到本机：

git clone https://github.com/srbhr/Resume-Matcher.git
cd Resume-Matcher

2. 后端配置

后端是 Python FastAPI 应用，负责 AI 调用、简历解析以及数据存储。

进入后端目录

cd apps/backend

创建环境变量文件

cp .env.example .env

使用你偏好的编辑器编辑 .env

# macOS/Linux
nano .env

# 或使用任意编辑器
code .env   # VS Code

最关键的配置是 AI 提供商。下面是 OpenAI 的最小示例配置：

LLM_PROVIDER=openai
LLM_MODEL=gpt-4o-mini
LLM_API_KEY=sk-your-api-key-here

# 本地开发建议保持默认
HOST=0.0.0.0
PORT=8000
FRONTEND_BASE_URL=http://localhost:3000
CORS_ORIGINS=["http://localhost:3000", "http://127.0.0.1:3000"]

安装 Python 依赖

uv sync

该命令会创建虚拟环境并安装所有必需依赖。

启动后端服务

uv run uvicorn app.main:app --reload --port 8000

你会看到类似输出：

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process

保持该终端运行，然后为前端另开一个终端窗口。

3. 前端配置

前端是 Next.js 应用，提供用户界面。

进入前端目录

cd apps/frontend

（可选）创建前端环境变量文件

仅当你的后端运行在不同端口时需要：

cp .env.sample .env.local

安装 Node.js 依赖

npm install

启动开发服务器

npm run dev

你会看到：

▲ Next.js 16.x.x (Turbopack)
- Local:        http://localhost:3000

浏览器打开 http://localhost:3000，你应该能看到 Resume Matcher 的界面。

---

配置 AI 提供商

Resume Matcher 支持多种 AI 提供商。你可以在应用的 Settings 页面中配置，也可以直接编辑后端的 .env 文件。

选项 A：云端提供商

提供商	配置方式	获取 API Key
OpenAI	LLM_PROVIDER=openai LLM_MODEL=gpt-4o-mini	platform.openai.com
Anthropic	LLM_PROVIDER=anthropic LLM_MODEL=claude-3-5-sonnet-20241022	console.anthropic.com
Google Gemini	LLM_PROVIDER=gemini LLM_MODEL=gemini-1.5-flash	aistudio.google.com
OpenRouter	LLM_PROVIDER=openrouter LLM_MODEL=anthropic/claude-3.5-sonnet	openrouter.ai
DeepSeek	LLM_PROVIDER=deepseek LLM_MODEL=deepseek-chat	platform.deepseek.com

Anthropic 的 .env 示例：

LLM_PROVIDER=anthropic
LLM_MODEL=claude-3-5-sonnet-20241022
LLM_API_KEY=sk-ant-your-key-here

选项 B：使用 Ollama 的本地 AI（免费）

想在本机运行模型、避免 API 费用？可以使用 Ollama。

第 1 步：安装 Ollama

从 ollama.com 下载并安装。

第 2 步：拉取模型

ollama pull llama3.2

其他可选模型：mistral、codellama、neural-chat

第 3 步：配置 .env

LLM_PROVIDER=ollama
LLM_MODEL=llama3.2
LLM_API_BASE=http://localhost:11434
# Ollama 不需要 LLM_API_KEY

第 4 步：确保 Ollama 正在运行

ollama serve

通常安装后 Ollama 会自动启动。

---

Docker 部署

如果你更喜欢容器化部署，Resume Matcher 已提供 Docker 支持。

使用 Docker Compose（推荐）

# 构建并启动容器
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止容器
docker-compose down

Docker 重要说明

• API Key 通过 UI 配置：http://localhost:3000/settings（不是通过 .env 文件）
• 数据会保存在 Docker volume 中
• 暴露前端（3000）与后端（8000）端口

更详细的 Docker 指南见：docs/agent/60-docker/docker.md。

---

访问应用

当后端与前端都启动后，可通过以下地址访问：

URL	说明
http://localhost:3000	主应用（Dashboard）
http://localhost:3000/settings	配置 AI 提供商
http://localhost:8000	后端 API 根路径
http://localhost:8000/docs	可交互的 API 文档
http://localhost:8000/health	后端健康检查

首次配置检查清单

1. 打开 http://localhost:3000/settings
2. 选择你的 AI 提供商
3. 填写 API Key（或配置 Ollama）
4. 点击 “Save Configuration”
5. 点击 “Test Connection” 验证连通性
6. 回到 Dashboard，上传你的第一份简历

---

常用命令速查

后端命令

cd apps/backend

# 启动开发服务器（自动热重载）
uv run uvicorn app.main:app --reload --port 8000

# 启动生产服务器
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000

# 安装依赖
uv sync

# 安装开发依赖（用于测试）
uv sync --group dev

# 运行测试
uv run pytest

# 查看数据库文件（JSON 存储）
ls -la data/

前端命令

cd apps/frontend

# 启动开发服务器（Turbopack 快速刷新）
npm run dev

# 生产构建
npm run build

# 启动生产服务器
npm run start

# 运行 linter
npm run lint

# 使用 Prettier 格式化
npm run format

# 指定其他端口运行
npm run dev -- -p 3001

数据库管理

Resume Matcher 使用 TinyDB（JSON 文件存储）。数据位于 apps/backend/data/：

# 查看数据库文件
ls apps/backend/data/

# 备份数据
cp -r apps/backend/data apps/backend/data-backup

# 重置数据（重新开始）
rm -rf apps/backend/data

---

故障排查

后端无法启动

错误： ModuleNotFoundError

确认使用 uv 启动：

uv run uvicorn app.main:app --reload

错误： LLM_API_KEY not configured

检查你的 .env 是否为所选提供商配置了有效的 API Key。

前端无法启动

错误： 页面加载时报 ECONNREFUSED

后端未运行，请先启动后端：

cd apps/backend && uv run uvicorn app.main:app --reload

错误： 构建或 TypeScript 报错

清理 Next.js 缓存：

rm -rf apps/frontend/.next
npm run dev

PDF 下载失败

错误： Cannot connect to frontend for PDF generation

后端无法访问前端，请检查：

1. 前端正在运行
2. .env 中的 FRONTEND_BASE_URL 与前端 URL 一致
3. CORS_ORIGINS 包含前端 URL

如果前端运行在 3001 端口：

FRONTEND_BASE_URL=http://localhost:3001
CORS_ORIGINS=["http://localhost:3001", "http://127.0.0.1:3001"]

Ollama 连接失败

错误： Connection refused to localhost:11434

1. 确认 Ollama 在运行：ollama list
2. 如有需要手动启动：ollama serve
3. 确认模型已下载：ollama pull llama3.2

---

项目结构概览

Resume-Matcher/
├─ apps/
│  ├─ backend/                 # Python FastAPI backend
│  │  ├─ app/
│  │  │  ├─ main.py            # Application entry point
│  │  │  ├─ config.py          # Environment configuration
│  │  │  ├─ database.py        # TinyDB wrapper
│  │  │  ├─ llm.py             # AI provider integration
│  │  │  ├─ routers/           # API endpoints
│  │  │  ├─ services/          # Business logic
│  │  │  └─ schemas/           # Data models
│  │  ├─ prompts/              # LLM prompt templates
│  │  ├─ data/                 # Database storage (auto-created)
│  │  ├─ .env.example          # Environment template
│  │  └─ pyproject.toml        # Python dependencies
│  └─ frontend/                # Next.js React frontend
│     ├─ app/                  # Pages (dashboard, builder, etc.)
│     ├─ components/           # Reusable React components
│     ├─ lib/                  # Utilities and API client
│     ├─ .env.sample           # Environment template
│     └─ package.json          # Node.js dependencies
├─ docs/                        # Additional documentation
├─ docker-compose.yml           # Docker configuration
├─ Dockerfile                   # Container build instructions
└─ README.md                    # Project overview

---

获取帮助

如果遇到问题，可以从以下渠道获得支持：

• Discord 社区： dsc.gg/resume-matcher - 提问与讨论都很活跃
• GitHub Issues： 提交 Issue 反馈 bug 或提出需求
• 项目文档： 查看 docs/agent/ 获取更详细的指南

推荐文档

文档	说明
backend-guide.md	后端架构与 API 细节
frontend-workflow.md	用户流程与组件架构
docker.md	Docker 部署指南
style-guide.md	UI 设计系统（Swiss International Style）

---

祝你简历制作顺利！如果 Resume Matcher 对你有帮助，欢迎 给仓库点个 Star，以及 加入我们的 Discord。