Resume Matcher 本地安装与配置完全指南：从 uv 后端、Next.js 前端到多 AI 提供商与 Docker 部署-北京尧图网络

Resume Matcher 本地安装与配置完全指南从 uv 后端、Next.js 前端到多 AI 提供商与 Docker 部署【免费下载链接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters more, locally with 100 LLMs support.项目地址: https://gitcode.com/GitHub_Trending/re/Resume-MatcherResume Matcher 是一套开源的 AI 简历加工工具链支持简历优化Tailoring、PDF 生成、求职信与面试准备等功能可在本地运行并接入 100 大语言模型。本文以官方安装指南SETUP.zh-CN.md为核心骨架结合仓库内 apps/backend/app/config.py、.env.example、docker-compose.yml 等真实源码与配置系统讲解从零搭建开发环境、配置云端或本地 AI 提供商、Docker 容器化部署的完整流程并给出常见故障的排查路径。读完后你将能够独立完成 Resume Matcher 的安装、配置、启动与排障并理解每个配置项背后的实现原理。前置条件开始安装前请确认本机已具备以下工具工具最低版本如何检查说明Python3.13python --version后端 FastAPI 应用的运行时仓库 pyproject.toml 中声明requires-python 3.13Node.js22node --version前端 Next.js 应用的运行时npm10npm --version随 Node.js 一起安装uv最新uv --versionPython 包与虚拟环境管理器Git任意git --version克隆仓库与版本管理安装 uvPython 包管理器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 uvuv sync会依据 apps/backend/pyproject.toml 自动创建虚拟环境并锁定安装全部依赖FastAPI、Uvicorn、LiteLLM、SQLAlchemy、Playwright、pdfminer 等比传统pip install -r requirements.txt更快且可复现性更强。快速开始如果你熟悉开发工具链想最快把应用跑起来按以下三个步骤即可# 1. 克隆仓库 git clone https://gitcode.com/GitHub_Trending/re/Resume-Matcher.git cd Resume-Matcher # 2. 启动后端终端 1 cd apps/backend cp .env.example .env # 从模板创建配置 uv sync # 安装 Python 依赖 uv run app # 启动 FastAPI 服务默认 0.0.0.0:8000 # 3. 启动前端终端 2 cd apps/frontend npm install # 安装 Node.js 依赖 npm run dev # 启动 Next.js 开发服务器Turbopack浏览器打开http://localhost:3000即可看到 Dashboard 界面。注意使用应用前必须先配置 AI 提供商详见下文「配置 AI 提供商」一节。从源码实现看uv run app之所以能直接启动是因为 pyproject.toml 中声明了[project.scripts] app app.main:main控制台脚本其底层调用 main.py 中的main()读取settings.host、settings.port、settings.reload后交给 Uvicorn 运行。逐步安装1. 克隆仓库git clone https://gitcode.com/GitHub_Trending/re/Resume-Matcher.git cd Resume-Matcher2. 后端配置后端是 Python FastAPI 应用负责 AI 调用、简历解析、数据存储与 PDF 渲染。进入后端目录cd apps/backend创建环境变量文件cp .env.example .env编辑.env# macOS/Linux nano .env # 或使用任意编辑器 code .env # VS Code最关键的配置是 AI 提供商。下面是一份 OpenAI 的最小示例配置LLM_PROVIDERopenai LLM_MODELgpt-5-nano-2025-08-07 LLM_API_KEYsk-your-api-key-here # 本地开发建议保持默认 HOST0.0.0.0 PORT8000 FRONTEND_BASE_URLhttp://localhost:3000 CORS_ORIGINS[http://localhost:3000, http://127.0.0.1:3000]这些变量由 config.py 中的Settings类基于 pydantic-settings解析。值得留意的实现细节LLM_PROVIDER是受约束的字面量类型合法值包括openai、openai_compatible、anthropic、openrouter、gemini、deepseek、groq、ollama若传入空字符串会被自动回退为openai。LLM_API_BASE默认为None专为 Ollama 或 OpenAI 兼容的自建服务器准备。CORS_ORIGINS的默认值是[http://localhost:3000, http://127.0.0.1:3000]同时 config.py 的effective_cors_origins属性会把FRONTEND_BASE_URL自动追加进允许名单因此生产部署时通常无需手工重复配置。RELOADtrue时uv run app会以热重载模式启动该值对应Settings.reload字段。.env模板中还包含以下常用参数详见 .env.example变量默认值说明RELOADfalse开发模式热重载开关仅建议本地开发开启LOG_LEVELINFO应用级 Python/Uvicorn 日志级别CRITICAL/ERROR/WARNING/INFO/DEBUGLOG_LLMWARNINGLiteLLM 日志级别DEBUG会明文打印 API Key勿在生产使用REASONING_EFFORT空对支持推理强度的模型如 OpenAI gpt-5 家族可设minimal/low/medium/high留空以保持最大兼容性LiteLLM 会对不支持的提供商自动丢弃该参数REQUEST_TIMEOUT_SECONDS240单次简历优化/改进请求的硬超时取值范围被钳制在 [30, 1800] 秒本地慢模型Ollama、llama.cpp通常需要调大FRONTEND_BASE_URLhttp://localhost:3000后端生成 PDF 时访问前端的地址CORS_ORIGINS见上JSON 数组格式的跨域白名单关于超时的联动REQUEST_TIMEOUT_SECONDS必须与前端 .env.sample 中的NEXT_PUBLIC_REQUEST_TIMEOUT_MS毫秒等于后端秒数 × 1000保持同步因为三层后端asyncio.wait_for、Next.js 代理proxyTimeout、客户端AbortController中最短的那一层会先中断请求——只调大后端而不同步前端问题依旧存在。安装 Python 依赖uv sync该命令会创建虚拟环境并安装所有必需依赖。若需安装开发依赖pytest、httpx、respx 等用于运行测试执行uv sync --group dev启动后端服务RELOADtrue uv run app你会看到类似输出INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRLC to quit) INFO: Started reloader process保持该终端运行然后为前端另开一个终端窗口。3. 前端配置前端是 Next.js 应用React 19 Turbopack版本信息见 package.json提供用户界面。进入前端目录cd apps/frontend可选创建前端环境变量文件仅当你的后端运行在不同端口时才需要cp .env.sample .env.local前端环境变量说明.env.sampleNEXT_PUBLIC_API_URL后端 API 地址默认/同源由 Next.js rewrites 代理。仅在后端运行于独立主机/端口时才需要修改。NEXT_PUBLIC_REQUEST_TIMEOUT_MS长耗时请求简历优化的超时毫秒数默认240000240 秒与后端REQUEST_TIMEOUT_SECONDS联动。安装 Node.js 依赖npm install启动开发服务器npm run dev你会看到▲ Next.js 16.x.x (Turbopack) - Local: http://localhost:3000浏览器打开http://localhost:3000你应该能看到 Resume Matcher 的 Dashboard 界面。配置 AI 提供商Resume Matcher 支持多种 AI 提供商。你可以在应用的 Settings 页面http://localhost:3000/settings中配置也可以直接编辑后端的.env文件。两种方式最终殊途同归UI 保存的配置含 API Key会落入后端data/config.json与加密的 SQLite 密钥存储见 config.py 与 crypto.py密钥以密文形式存放不会明文落盘而.env环境变量优先级最高。选项 A云端提供商提供商配置方式获取 API KeyOpenAILLM_PROVIDERopenaiLLM_MODELgpt-5-nano-2025-08-07在 OpenAI 平台的 API Keys 页面创建AnthropicLLM_PROVIDERanthropicLLM_MODELclaude-haiku-4-5-20251001在 Anthropic Console 创建Google GeminiLLM_PROVIDERgeminiLLM_MODELgemini/gemini-3-flash-preview在 Google AI Studio 创建OpenRouterLLM_PROVIDERopenrouterLLM_MODELdeepseek/deepseek-chat在 OpenRouter 的 Keys 页面创建DeepSeekLLM_PROVIDERdeepseekLLM_MODELdeepseek-chat在 DeepSeek 开放平台创建OpenAI-CompatibleLLM_PROVIDERopenai_compatibleLLM_MODELllama-3.1-8bLLM_API_BASEhttp://localhost:8080/v1—本地服务无需密钥OpenAI-Compatible适用于任何暴露 OpenAI Chat Completions API 的本地服务器例如 llama.cpp、vLLM、LM Studio 等。API Key 可选——当留空时后端会按 llm.py 中的逻辑自动填充一个哨兵值sentinel以通过客户端非空校验同时该提供商会被判定为无需鉴权的本地模式。Anthropic 的.env示例LLM_PROVIDERanthropic LLM_MODELclaude-haiku-4-5-20251001 LLM_API_KEYsk-ant-your-key-here从 llm.py 的源码结构看各提供商在内部有一个统一的 provider→key 映射表例如gemini对应的密钥槽位名为google不同提供商的请求会经由 LiteLLM 路由到不同的前缀如openai/、ollama_chat/因此切换提供商时只需修改上述三个变量。选项 B使用 Ollama 的本地 AI免费想在本机运行模型、避免 API 费用可以使用 Ollama全部推理在本机完成零成本、数据不出本地。第 1 步安装 Ollama从 Ollama 官方网站下载并安装对应平台的安装包。第 2 步拉取模型ollama pull gemma3:4b其他可选模型llama3.2、mistral、codellama、neural-chat等。第 3 步配置.envLLM_PROVIDERollama LLM_MODELgemma3:4b LLM_API_BASEhttp://localhost:11434 # Ollama 不需要 LLM_API_KEY第 4 步确保 Ollama 正在运行ollama serve通常安装后 Ollama 会自动启动可通过ollama list确认。说明从 llm.py 的实现看ollama与openai_compatible均被列入本地免密钥提供商集合当LLM_PROVIDERollama且未配置 API Key 时密钥校验会被跳过llm.py健康检查对该类提供商也总是返回可用。Docker 部署如果你更喜欢容器化部署Resume Matcher 已提供 Docker 支持见 Dockerfile 与 docker-compose.yml。使用 Docker Compose推荐# 构建并启动容器 docker compose up -d # 查看日志 docker compose logs -f # 停止容器 docker compose downDocker 环境变量镜像内部所有配置项均可通过环境变量覆盖默认值定义在 docker-compose.yml 与 apps/backend/app/config.py变量默认值说明PORT3000宿主机端口映射到容器内 3000 端口可用PORT4000 docker compose up -d修改LOG_LEVELINFO应用级日志级别ERROR/WARNING/INFO/DEBUGLOG_LLMWARNINGLiteLLM 日志级别DEBUG会让 LiteLLM 明文记录 API Key切勿在生产或共享环境使用LLM_PROVIDERopenaiAI 提供商LLM_MODEL—使用的模型推荐通过 Settings UI 配置LLM_API_KEY—API Key推荐通过 Settings UI 配置LLM_API_BASE—自定义 API 端点用于 Ollama 或代理FRONTEND_BASE_URLhttp://localhost:3000反代场景下的前端域名LOG_LEVEL与LOG_LLM的修改需要重启容器才能生效另外 LiteLLM 内部还会读取LITELLM_LOG环境变量做 handler 级过滤两者都必须放行日志才会输出因此设置LITELLM_LOG时请确保LOG_LLM级别与之相同或更低。在 Docker 中使用宿主机上的 Ollama容器内无法直接访问宿主机localhost需改用 Docker 的宿主机网关地址LLM_API_BASEhttp://host.docker.internal:11434 docker compose up -d然后到 Settings UI 中将提供商配置为 Ollama 即可macOS/Windows 原生支持host.docker.internalLinux 下请使用宿主机 IP 或--networkhost。使用 Docker Secrets容器支持与 PostgreSQL 风格一致的*_FILE环境变量来自 Docker Secrets。对敏感值可挂载密钥文件并指向它LLM_API_KEY_FILE/run/secrets/llm_api_key docker compose up -d支持的*_FILE变体变量*_FILE变体LOG_LEVELLOG_LEVEL_FILELOG_LLMLOG_LLM_FILELLM_PROVIDERLLM_PROVIDER_FILELLM_MODELLLM_MODEL_FILELLM_API_KEYLLM_API_KEY_FILELLM_API_BASELLM_API_BASE_FILE使用规则普通变量与*_FILE变体二选一两者同时设置时容器会以显式错误退出。Docker 重要说明API Key 通过 UI 配置http://localhost:3000/settings而不是.env文件配置会持久化在 Docker volume 中重启不丢失。数据保存在 Docker volumeresume-data中对应容器内路径/app/backend/data见 docker-compose.yml。容器采用前后端同源部署前端服务在/API 在/api。访问应用当后端与前端都启动后本地开发模式可通过以下地址访问URL说明http://localhost:3000主应用Dashboardhttp://localhost:3000/settings配置 AI 提供商http://localhost:8000后端 API 根路径http://localhost:8000/docs可交互的 API 文档Swagger UIhttp://localhost:8000/api/v1/health后端健康检查需要说明的是从 main.py 的源码看所有路由health、config、resumes、jobs、enrichment、applications、resume_wizard统一挂载在/api/v1前缀下因此本地开发模式下健康检查的完整路径为http://localhost:8000/api/v1/health而 Docker 模式下前后端同源统一通过http://localhost:3000/api/v1/health访问。首次配置检查清单打开 http://localhost:3000/settings选择你的 AI 提供商填写 API Key或配置 Ollama点击 Save Configuration点击 Test Connection 验证连通性回到 Dashboard上传你的第一份简历Settings 页面对应前端 settings 路由页面/settings/page.tsx)即apps/frontend/app/(default)/settings/page.tsx后端由apps/backend/app/routers/config.py提供配置读写接口仓库中的 test_config_api.py 覆盖了保存、读取与连接测试等端点的行为。常用命令速查后端命令cd apps/backend # 启动开发服务器自动热重载 RELOADtrue uv run app # 启动生产服务器 uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 # 安装依赖 uv sync # 安装开发依赖用于测试 uv sync --group dev # 运行测试 uv run pytest前端命令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 的数据统一存放在apps/backend/data/目录# 查看数据库文件 ls apps/backend/data/ # 备份数据 cp -r apps/backend/data apps/backend/data-backup # 重置数据重新开始——注意此操作会删除全部数据务必先备份 rm -rf apps/backend/data与文档的历史差异说明早期版本使用 TinyDBJSON 文件存储文件名为database.json而当前仓库的数据层已升级为基于 SQLAlchemy 的 SQLite 存储主库文件为resume_matcher.db另有一张加密的api_keys表存放密钥参见 database.py 的模块注释与 config.py 中的sqlite_path属性。后端启动时会通过 apps/backend/app/scripts/migrate_tinydb_to_sqlite.py自动把遗留的 TinyDB JSON 数据幂等迁移进 SQLite迁移失败会快速失败避免以空库启动造成数据丢失假象同时把 config.json 中的明文旧密钥折叠进加密密钥库config.py。因此直接查看apps/backend/data/目录即可看到resume_matcher.db、config.json等文件。故障排查后端无法启动错误ModuleNotFoundError确认使用uv启动确保依赖安装在 uv 管理的虚拟环境中uv run uvicorn app.main:app --reload错误LLM_API_KEY not configured检查你的.env是否为所选提供商配置了有效的 API Key。注意ollama与openai_compatible属于本地免密钥提供商无需配置其余云端提供商必须提供有效密钥。前端无法启动错误页面加载时报ECONNREFUSED后端未运行请先启动后端cd apps/backend uv run uvicorn app.main:app --reload错误构建或 TypeScript 报错清理 Next.js 缓存后重试rm -rf apps/frontend/.next npm run devPDF 下载失败错误Cannot connect to frontend for PDF generation后端无法访问前端请检查前端正在运行.env中的FRONTEND_BASE_URL与前端 URL 一致CORS_ORIGINS包含前端 URL如果前端运行在 3001 端口FRONTEND_BASE_URLhttp://localhost:3001 CORS_ORIGINS[http://localhost:3001, http://127.0.0.1:3001]后端会自动把FRONTEND_BASE_URL追加进 CORS 允许名单因此这里只需保证两者指向一致。Ollama 连接失败错误Connection refused to localhost:11434确认 Ollama 在运行ollama list如有需要手动启动ollama serve确认模型已下载ollama pull gemma3:4b若在 Docker 中运行还需注意容器内访问宿主机要使用http://host.docker.internal:11434而非localhost。项目结构概览Resume-Matcher/ ├─ apps/ │ ├─ backend/ # Python FastAPI 后端 │ │ ├─ app/ │ │ │ ├─ main.py # 应用入口点 │ │ │ ├─ config.py # 环境配置pydantic-settings │ │ │ ├─ database.py # SQLAlchemy/SQLite 数据层 │ │ │ ├─ llm.py # AI 提供商集成LiteLLM 路由 │ │ │ ├─ routers/ # API 端点/api/v1 │ │ │ ├─ services/ # 业务逻辑 │ │ │ └─ schemas/ # 数据模型 │ │ ├─ prompts/ # LLM 提示词模板 │ │ ├─ data/ # 数据库存储自动创建 │ │ ├─ .env.example # 环境变量模板 │ │ └─ pyproject.toml # Python 依赖 │ └─ frontend/ # Next.js React 前端 │ ├─ app/ # 页面dashboard、builder 等 │ ├─ components/ # 可复用 React 组件 │ ├─ lib/ # 工具与 API 客户端 │ ├─ .env.sample # 环境变量模板 │ └─ package.json # Node.js 依赖 ├─ docs/ # 附加文档 ├─ docker-compose.yml # Docker 编排配置 ├─ Dockerfile # 容器构建指令 └─ README.md # 项目总览获取帮助与推荐文档如果遇到问题可以从以下渠道获得支持社区频道项目官方 Discord 社区提问与讨论都比较活跃仓库 Issues在仓库 Issues 中反馈 bug 或提出功能需求推荐文档文档说明backend-guide.md后端架构与 API 细节frontend-workflow.md用户流程与组件架构swiss-design-system/README.mdUI 设计系统Swiss International Style便携包docs/agent/面向开发者的详细指南合集至此你已经完成了 Resume Matcher 从本地开发到 Docker 部署的完整安装配置。核心要点回顾后端用uv管理依赖并读取.env决定 AI 提供商前端用 npm 启动 Next.js 界面两者通过FRONTEND_BASE_URL与CORS_ORIGINS协作完成 PDF 生成AI 侧既可接云端多家模型也可用 Ollama 实现完全本地化、零成本的推理Docker 模式下则统一由 3000 端口提供前端与 API数据持久化于 volume。遇到问题时按故障排查清单逐项核对环境变量与进程状态通常都能快速定位。【免费下载链接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters more, locally with 100 LLMs support.项目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Resume Matcher 本地安装与配置完全指南：从 uv 后端、Next.js 前端到多 AI 提供商与 Docker 部署

相关推荐

Zero gap电解槽多物理场建模与优化实践

并行AI Coding工程化：任务切分、调度与验证全指南

Lexical Markdown 集成指南：@lexical/markdown 的导入导出、快捷键与 Transformers 深度解析

更多资讯

社区团购小程序开发：定制与模板选型指南

Midscene 三步自然语言浏览器自动化

Apache DolphinScheduler API 接入与集成：5 大场景跑通完整流程

5步翻译日文视觉小说：LunaTranslator视觉小说翻译器完整教程

宏智树AI论文写作工具：智能文献管理与格式自动排版实战

太极拳姿态识别系统：从骨骼关键点到动作分类实战解析

今日更新

SpacetimeDB C++ 模块库实战：用 C++20 在数据库内构建 WebAssembly 模块

别踩雷！不是所有 AI 写作工具都靠谱，2026 高校认可工具精选

SSM+MySQL幼儿园管理系统源码解析：从部署到优化

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？