Resume-Matcher 本地快速上手指南构建、运行与测试完整实战【免费下载链接】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本文是 Resume-Matcher 项目的快速上手Quickstart指南。你将了解如何在本地环境中完成前后端依赖安装、以开发模式启动 FastAPI 后端与 Next.js 前端、执行代码质量检查与自动化测试并完成首次运行的 LLM 提供方配置。读完本文你可以独立从零搭建一套可运行的本地简历定制Resume Tailoring与 PDF 生成工作流并理解启动过程中数据库迁移、密钥加密存储等关键机制为后续接入 100 LLM 提供方通过 LiteLLM打下基础。一、环境前置要求在开始之前请确保本机满足以下版本要求Node.js 22用于运行前端Next.js 16 React 19。Python 3.13用于运行后端FastAPI uvicorn。uvPython 包管理器用于同步后端依赖与运行 Python 命令。版本要求有明确依据后端项目的 pyproject.toml 声明了requires-python 3.13前端 package.json 中使用了 Next.js 16 与 React 19 等较新的依赖栈。使用 uv 而非传统 pip 是本仓库的默认工作流——所有后端命令均通过uv run进入项目虚拟环境执行。提示如果你不想在宿主机上安装 Node/Python 环境也可以走 Docker 路线见 docker-compose.yml 与 Dockerfile本文聚焦本地源码运行方式。二、安装依赖后端与前端从仓库根目录执行以下命令分别安装后端 Python 依赖与前端 npm 依赖# Backend (from repo root) cd apps/backend uv sync # Frontend (from repo root) cd apps/frontend npm install关于uv sync你需要知道的两点依赖分组安装uv sync默认安装[project.dependencies]中的核心依赖FastAPI、uvicorn、LiteLLM、SQLAlchemy、Playwright 等同时会安装dev可选依赖组pytest、pytest-asyncio、httpx、respx——这正是后续运行测试所需的工具链见 pyproject.toml。e2e-monitor 组可选仓库还定义了e2e-monitor依赖组pypdf、httpx用于端到端监控脚本的非空白 PDF 渲染探测。若你需要运行apps/e2e_monitor/下的监控流程可额外执行uv sync --extra e2e-monitor。前端安装完成后npm install会依据 package-lock.json 锁定版本。若遇到依赖冲突package.json 中的overrides字段如 undici、postcss可用于强制统一传递依赖版本。三、配置环境变量快速上手的第一步是复制示例环境变量文件# Backend cp apps/backend/.env.example apps/backend/.env # Frontend cp apps/frontend/.env.sample apps/frontend/.env.local后端 .env 关键配置后端通过 pydantic-settings 在启动时读取.env默认路径为apps/backend/.env核心配置类见 app/config.py。下表梳理了最常用的变量变量默认值说明LLM_PROVIDERopenai支持的提供方openai、openai_compatible、anthropic、openrouter、gemini、deepseek、groq、ollamaLLM_MODELgpt-5-nano-2025-08-07具体模型名Ollama 可填gemma3:4bOpenRouter 可填deepseek/deepseek-chatLLM_API_KEY空若未配置也可通过界面设置openai_compatible/ollama可留空LLM_API_BASE空Ollama 填http://localhost:11434llama.cpp/vLLM/LM Studio 填如http://localhost:8080/v1LOG_LEVELINFO应用日志级别CRITICAL/ERROR/WARNING/INFO/DEBUGLOG_LLMWARNINGLiteLLM 日志级别同上取值FRONTEND_BASE_URLhttp://localhost:3000前端地址用于 PDF 生成与 CORS 白名单REQUEST_TIMEOUT_SECONDS240单次简历优化请求的硬超时取值范围[30, 1800]CORS_ORIGINS[http://localhost:3000,http://127.0.0.1:3000]JSON 数组格式的跨域白名单REASONING_EFFORT空对支持推理模型gpt-5 家族、Claude 3.7、DeepSeek R1设置minimal/low/medium/high留空最兼容完整的带注释示例见 apps/backend/.env.example。超时参数的三层同步陷阱REQUEST_TIMEOUT_SECONDS必须与前端NEXT_PUBLIC_REQUEST_TIMEOUT_MS毫秒值 秒值 × 1000保持同步。后端把优化流程包在asyncio.wait_for里而前端 Next.js 代理proxyTimeout与客户端 AbortController 各有一层超时——哪一层最短就先中断。只调高后端而不同步前端超时会由前端先触发问题依旧存在这是 issue #776 后端单独修改无效的原因。慢速本地模型Ollama、llama.cpp建议调高见 app/config.py 与 frontend/.env.sample。前端 .env.local 关键配置前端 apps/frontend/.env.sample 中可选配置NEXT_PUBLIC_API_URL默认/同源由 Next.js rewrites 代理到后端。仅当后端跑在独立主机/端口时才需要修改。NEXT_PUBLIC_REQUEST_TIMEOUT_MS长耗时请求简历定制的超时毫秒数默认240000范围[30000, 1800000]需与后端秒值同步。若修改前端端口如npm run dev -- -p 3001必须同步更新后端CORS_ORIGINS与FRONTEND_BASE_URL。四、开发模式启动两个终端并行终端 1启动后端# Backend (Terminal 1, from repo root) cd apps/backend uv run uvicorn app.main:app --reload --port 8000启动后FastAPI 应用会监听0.0.0.0:8000--reload开启热重载。API 文档可在http://localhost:8000/docs查看。启动过程中的关键机制可在 app/main.py 的 lifespan 逻辑中看到数据目录自动创建settings.data_dir默认apps/backend/data不存在时自动创建。TinyDB → SQLite 自动迁移若存在遗留的data/database.json启动时自动执行幂等迁移app/scripts/migrate_tinydb_to_sqlite.py将 resumes/jobs/improvements 1:1 复制到 SQLite主数据存储为data/resume_matcher.db并强制单一主简历不变量迁移成功后将旧文件重命名为database.json.migrated作为回滚依据。此设计保证升级老版本数据不会丢失。遗留明文 API Key 迁移migrate_legacy_keys()会把 config.json 中的旧明文密钥折叠进加密的 SQLite 密钥库幂等、不覆盖已有槽位再从配置文件中剥离——API 密钥只存在于加密存储中见 app/config.py 与 app/crypto.py。终端 2启动前端# Frontend (Terminal 2, from repo root) cd apps/frontend npm run devdev脚本使用next dev --turbopack见 package.json默认监听http://localhost:3000。前端通过 Next.js rewrites 将/api代理到后端 8000 端口。五、首次运行配置接入 LLM 提供方前后端就绪后打开http://localhost:3000/settings完成首次配置选择 AI 提供方如 OpenAI、Anthropic、Gemini、DeepSeek、Ollama 等。输入对应 API Key也可直接粘贴进后端.env的LLM_API_KEY。点击Test Connection验证连通性。上传你的第一份简历开始使用这部分由后端 app/routers/config.py 提供 API 支撑核心端点包括PUT /api/v1/config/llm-api-key保存提供方/模型/Base URL/推理力度。API Key 不再写入该接口——密钥通过POST /api/v1/config/api-keys存入加密密钥库避免多提供方互相覆盖见 app/routers/config.py 的注释说明。POST /api/v1/config/llm-test用当前或给定配置发起一次探测请求测试 prompt 为 Hi返回健康状态与细节对应界面上的 Test Connection 按钮。GET /api/v1/config/api-keys返回各提供方密钥状态密钥仅显示后 4 位。密钥解析的优先级是环境变量/设置值 config.json加密库解密 空字符串见Settings.get_effective_api_key()app/config.py与resolve_api_key()app/llm.py。六、质量检查Lint 与格式化在apps/frontend目录下执行# From apps/frontend npm run lint # Lint frontend npm run format # Prettierlint对应eslint .基于 ESLint 9 eslint-config-next配置见 apps/frontend/eslint.config.mjs。format对应prettier --write .会自动格式化整个前端代码库。七、后端测试cd apps/backend uv run uvicorn app.main:app --reload --port 8000 # 另开终端时使用 uv run pytestuv run pytest会执行全部测试。pytest 配置apps/backend/pyproject.toml值得关注测试发现规则测试目录为tests文件匹配test_*.py启用asyncio_mode auto无需显式 async 插件标记。默认排除 eval 标记addopts中带-m not eval默认跳过 LLM-as-judge 评估用例这类用例可能调用真实 LLM 且结果不确定。需要时可用uv run pytest -m eval手动运行。Markers 分层unit纯函数、servicemock LLM 的服务层、integrationhttpx AsyncClient 的 API 端点测试、eval提示词质量评估。仓库测试覆盖了后端 API 集成tests/integration/、服务层tests/service/与单元测试tests/unit/包括 LLM 合同、PDF 渲染、TinyDB 迁移、简历差异等主题。前端也有对应的 Vitest 测试套件npm run test即vitest run见 apps/frontend/package.json。八、生产/容器化运行方式可选如果希望以容器方式运行而不是本地源码启动仓库提供了两条路径docker-compose 一键启动根目录 docker-compose.yml 定义resume-matcher服务映射${PORT:-3000}:3000挂载resume-data卷到/app/backend/data并通过环境变量LLM_PROVIDER、LLM_MODEL、LLM_API_KEY、LLM_API_BASE、LOG_LEVEL、LOG_LLM、FRONTEND_BASE_URL等注入配置支持*_FILE形式的 Docker Secret 挂载如LLM_API_KEY_FILE。Ollama 跑在宿主机时将LLM_API_BASE设为http://host.docker.internal:11434。start.sh 启动脚本容器内执行 docker/start.sh负责加载环境变量与*_FILE密钥、校验日志级别、创建数据目录、检测并安装 Playwright ChromiumPDF 导出依赖然后先后启动 uvicorn 后端8000与 Next.js standalone 前端3000并处理优雅退出。九、常见问题排查速查症状排查方向前端能打开但请求 500检查后端是否在 8000 端口运行、LLM_API_KEY是否已配置Test Connection 失败核对LLM_PROVIDER/LLM_MODEL拼写Ollama 确认LLM_API_BASE指向正确端口openai_compatible需填写http://…/v1格式 Base URL简历优化总是提前中断检查REQUEST_TIMEOUT_SECONDS后端与NEXT_PUBLIC_REQUEST_TIMEOUT_MS前端是否同步慢速本地模型适当调大PDF 导出不工作确认 Playwright Chromium 已安装容器内docker/start.sh会自动安装宿主机可执行python -m playwright install chromium老版本数据消失属于预期行为启动时 TinyDB 数据已迁移至 SQLitedata/resume_matcher.db旧文件被重命名为database.json.migrated十、总结本文完整覆盖了 Resume-Matcher 本地快速上手的全流程环境准备 → 依赖安装uv sync/npm install→ 环境变量配置后端.env与前端.env.local→ 双终端开发启动uvicorn Next.js→ 首次 LLM 配置Settings 界面 加密密钥库→ 质量检查lint/format→ 自动化测试pytest / vitest并深入解释了启动时的 TinyDB→SQLite 自动迁移、密钥加密存储、三层超时同步等底层机制。按照上述步骤操作你就能在本地完整跑通上传简历 → 分析职位描述 → AI 定制优化 → 生成 PDF的核心工作流并随时通过/docs与/api/v1/health验证服务状态。【免费下载链接】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），仅供参考