# ai_resume

**Repository Path**: he7/ai_resume

## Basic Information

- **Project Name**: ai_resume
- **Description**: AI简历求职大师
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 智能简历求职大师

> 简历优化 · 模拟面试 · 职业测评 — 一站式 AI 求职平台

---

## 目录

- [方案快速选择](#方案快速选择)
- [项目如何运行（运行机制总览）](#项目如何运行运行机制总览)
- [方案一：Windows 本地运行](#方案一windows-本地运行推荐本地开发演示)
- [方案二：Linux + Nginx 运行（生产）](#方案二linux--nginx-运行生产推荐)
- [方案三：宝塔面板部署（生产 GUI 操作）](#方案三宝塔面板部署生产-gui-操作最详细)
- [统一运行机制：健康检查（三平台通用）](#统一运行机制健康检查三平台通用)
- [端口配置（多项目共存）](#端口配置多项目共存)
- [环境变量说明](#环境变量说明)
- [接入真实 AI 模型](#接入真实-ai-模型)
- [接入支付宝当面付](#接入支付宝当面付)
- [默认账号](#默认账号)
- [常见问题](#常见问题)
- [项目结构](#项目结构)
- [技术支持](#技术支持)

---

## 方案快速选择

| 你的场景 | 推荐方案 | 一键命令 | 是否需要 Nginx |
|---------|---------|---------|--------------|
| 本机开发 / 演示 / 测试 | **方案一 Windows** | 双击 `start.bat` 或 `scripts\serve.bat` | 不需要 |
| 云服务器生产（纯命令行） | **方案二 Linux+Nginx** | `./deploy/install.sh` | 自动安装并配置 |
| 有宝塔面板，习惯图形界面 | **方案三 宝塔面板** | 图形界面 + 可选 `./deploy/baota_install.sh` | 宝塔网站反代 |

> 无论哪种方案，**核心运行机制完全相同**：后端（FastAPI）启动后**同时托管前端页面和 API**，默认端口 `8800`，通过 `/api/health` 判断项目是否成功启动。下面三个方案的区别只在于「如何启动」和「如何对外暴露」，验证手段完全一致。

---

## 项目如何运行（运行机制总览）

理解下面 4 点，所有部署方案都不迷路：

1. **一个进程，前后端一体**
   后端 `uvicorn`/`gunicorn` 启动后，会同时做两件事：
   - 提供 API：`/api/...`（如 `/api/health`、`/api/models`、`/api/resume/...`）
   - 托管前端：访问 `/` 返回 `index.html`，`/assets/...` 返回 CSS/JS
   
   所以**不需要单独部署前端**，也没有"前端怎么连后端"的问题——前端用相对路径调用同域 API。

2. **默认端口 8800**
   端口由 `backend/.env` 的 `PORT` 控制（默认 8800）。改端口只需改 `.env` 的 `PORT` 并重启。

3. **健康检查端点 = 项目是否启动的唯一标准**
   ```
   GET /api/health   →  返回 {"status":"ok"}  表示后端活着
   GET /             →  返回 200 且含页面标题    表示前端页面正常
   GET /api/models   →  返回 200              表示业务 API 可用
   ```
   本项目提供统一的 **`scripts/healthcheck.py`** 脚本，一条命令同时检查「端口是否监听 / 前端页面 / API 健康检查 / 业务 API / API 文档」五项，全部通过即代表**项目成功启动**。

4. **Redis 不是必须的**
   `USE_REDIS=false`（默认）时系统用内存替代，不装 Redis 也能完整运行。只有当你在 `.env` 把 `USE_REDIS=true` 时才需要单独安装 Redis。

---

## 方案一：Windows 本地运行（推荐：本地开发 / 演示）

> 零配置，双击即用。适合在本机看效果、做演示、写代码。

### 第 1 步：安装 Python（若已装请跳过）

去官网 https://www.python.org/downloads/ 下载并安装 **Python 3.10+**。

**安装时必须勾选** `Add Python to PATH`：

```
☑ Add Python 3.x to PATH
```

验证（在命令提示符 / PowerShell 中）：

```cmd
python --version
```

能看到版本号（如 `Python 3.13.12`）即成功。

### 第 2 步：一键启动

项目提供两种启动方式，按需选择：

| 方式 | 命令 | 说明 |
|------|------|------|
| **前台启动**（看日志） | 双击 `start.bat` 或 `start.bat 9000` | 阻塞窗口，关闭窗口即停止；适合开发调试 |
| **后台启动 + 自动检查 + 开浏览器** ✅推荐 | 双击 `scripts\serve.bat` 或 `scripts\serve.bat 9000` | 新窗口后台跑服务，自动等待并健康检查，全部通过后自动打开浏览器 |

> `serve.bat` 是真正的"一键启动"体验：它会在后台拉起服务 → 自动检测端口/前端/API 是否正常 → 正常就帮你打开浏览器。首次运行会自动创建虚拟环境 + 安装依赖（约 1–3 分钟），请耐心等待。

也可以用 Python 命令直接启动：

```cmd
:: 默认端口
python run.py

:: 指定端口
python run.py --port 9000

:: 仅本机访问（不对外暴露）
python run.py --host 127.0.0.1 --port 8800
```

> **稳定性 / 崩溃自愈（重要）**
> 直接用 `python run.py` 或 `serve.bat` 启动的服务，进程挂靠在启动它的会话/终端上，**会话结束（如远程桌面断开、SSH 退出、脚本窗口关闭）时进程会被回收，表现为"运行着突然无法访问"**。
> 如需服务长期存活、且 uvicorn 万一崩溃能自动拉起，请改用**脱离会话的看门狗**：
>
> ```cmd
> :: 一键：脱离会话启动 + 崩溃后 3 秒自动重启
> scripts\start-detached.bat
>
> :: 停止
> powershell -File scripts\stop-detached.ps1
> ```
> 原理：`scripts\run-server.py` 是一个 Python 看门狗，循环 `subprocess` 启动 uvicorn，进程退出即 3 秒后重启；由 `Start-Process` 脱离会话启动，不会随启动方退出被回收。日志写入 `logs\watchdog.log`。
> （在真实 Windows 服务器 / 宝塔环境，更推荐用 **systemd** 或 **Supervisor** 托管，见方案二、三。）

### 第 3 步：运行机制 —— 如何确认「项目成功启动」

Windows 下有三种方式确认项目真的跑起来了：

**① 自动检查（serve.bat 已内置）**
`scripts\serve.bat` 启动后会自动调用健康检查，看到绿色 `✅ 结论：项目已成功启动` 即成功，并自动打开浏览器。

**② 手动一键检查（服务已在运行时）**
```cmd
:: 默认 8800
scripts\check.bat

:: 指定端口
scripts\check.bat 9000

:: 输出 JSON（便于脚本/CI）
scripts\check.bat 8800 --json
```
`check.bat` 会打印一份清晰报告，逐项显示：

```
  [✔ PASS] 端口监听        127.0.0.1:8800   端口已处于监听状态
  [✔ PASS] 前端页面        http://127.0.0.1:8800/    HTTP 200，页面已正常返回
  [✔ PASS] API 健康检查    http://127.0.0.1:8800/api/health   HTTP 200，{"status":"ok"}
  [✔ PASS] 业务 API（模型列表） ... HTTP 200，接口可用
  [✔ PASS] API 文档        ... HTTP 200，文档可访问
  ✅ 结论：项目已成功启动，前端与后端 API 均正常运行。
```

**③ 手动看端口（排查占用）**
```cmd
netstat -ano | findstr 8800
```
能看到 `LISTENING` 状态的行即代表端口在运行；`findstr` 无输出则端口未占用/服务未起。

### 第 4 步：打开浏览器验证

启动成功后在浏览器访问：

```
http://localhost:8800            ← 完整应用
http://localhost:8800/docs       ← API 文档（Swagger）
```

> 若浏览器白屏：① 确认启动窗口还开着（关了=停了服务）；② 确认地址端口正确；③ 按 F12 看控制台报错。

---

## 方案二：Linux + Nginx 运行（生产推荐）

> 适合有云服务器的命令行部署。脚本会自动完成：建虚拟环境 → 装依赖 → 注册 systemd 开机自启 → 安装并配置 Nginx 反代 → 放行防火墙 → **自动健康检查**。

### 第 1 步：准备服务器

- 一台 Linux 服务器（Ubuntu / Debian / CentOS / RHEL 等，建议 2G+ 内存）
- 已安装 **Python 3.10+**
- 有 `root` 或 `sudo` 权限

检查 Python：

```bash
python3 --version   # 需 3.10+
```

### 第 2 步：上传项目代码

用 Git 或 SFTP 把整个项目放到服务器，例如 `/www/wwwroot/resume-master/` 或 `/opt/resume-master/`。

```bash
cd /www/wwwroot/resume-master
ls            # 应能看到 index.html、backend/、scripts/、deploy/ 等
```

### 第 3 步：一键部署（推荐）

```bash
# 进入项目目录
cd /www/wwwroot/resume-master

# 赋予执行权限
chmod +x deploy/install.sh scripts/health-check.sh

# 一键部署（默认端口 8800）
./deploy/install.sh

# 或指定端口 + 域名
./deploy/install.sh 9000 mydomain.com
```

脚本会自动完成上述全部步骤，最后打印健康检查报告和访问地址。

### 第 4 步：手动分步部署（想完全掌控时）

如果你不想用一键脚本，按下面 9 步来，每一步都可独立验证。

**步骤 1 — 创建虚拟环境并装依赖**
```bash
cd /www/wwwroot/resume-master/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install gunicorn "bcrypt==4.2.1"   # bcrypt 需锁 4.2.1 以兼容 passlib
```

**步骤 2 — 生成 .env 配置**
```bash
cp .env.example .env
# 编辑 .env，至少确认：
#   HOST=127.0.0.1      ← 只监听本机，由 Nginx 对外
#   PORT=8800
#   APP_ENV=prod
#   USE_REDIS=false
```

**步骤 3 — 注册 systemd 服务（开机自启 + 崩溃自动重启）**
创建 `/etc/systemd/system/resume-master.service`：

```ini
[Unit]
Description=AI Resume Job-hunting Master
After=network.target

[Service]
Type=simple
User=www-data                       # CentOS 改为 nginx
WorkingDirectory=/www/wwwroot/resume-master/backend
EnvironmentFile=/www/wwwroot/resume-master/backend/.env
ExecStart=/www/wwwroot/resume-master/backend/venv/bin/gunicorn main:app -c gunicorn.conf.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
systemctl daemon-reload
systemctl enable resume-master
systemctl start resume-master
```

> 不想用 systemd？也可以直接用 `nohup`：`nohup venv/bin/gunicorn main:app -c gunicorn.conf.py > logs/gunicorn.out.log 2>&1 &`

**步骤 4 — 确认后端已起**
```bash
systemctl status resume-master
```

**步骤 5 — 安装 Nginx**
```bash
# Ubuntu/Debian
apt-get update && apt-get install -y nginx
# CentOS/RHEL
yum install -y nginx        # 或 dnf install -y nginx
```

**步骤 6 — 配置 Nginx 反向代理**
将以下内容写入 `/etc/nginx/conf.d/resume-master.conf`（把域名和端口改掉）：

```nginx
upstream resume_master_backend {
    server 127.0.0.1:8800;   # ← 与 .env 的 PORT 一致
}

server {
    listen 80;
    server_name your-domain.com;        # ← 改成你的域名或 _

    client_max_body_size 50M;

    location / {
        proxy_pass http://resume_master_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";   # WebSocket 支持（面试对话）
        proxy_connect_timeout 60s;
        proxy_send_timeout 120s;
        proxy_read_timeout 120s;
    }

    location /api/health {
        proxy_pass http://resume_master_backend;
        access_log off;
    }
}
```

（也可直接使用项目自带的模板 `deploy/nginx.conf`，按需改 `server_name` 和 `upstream` 端口。）

```bash
nginx -t            # 测试配置语法
systemctl restart nginx
```

**步骤 7 — 放行防火墙**
```bash
# Ubuntu (ufw)
ufw allow 80/tcp
ufw allow 8800/tcp

# CentOS (firewalld)
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=8800/tcp
firewall-cmd --reload
```

**步骤 8 — 运行机制：健康检查确认项目成功启动**
```bash
# 一键检查（默认 8800）
./scripts/health-check.sh

# 指定端口
./scripts/health-check.sh 9000

# JSON 输出
./scripts/health-check.sh 8800 --json
```
看到 5 项全 `✔ PASS` 且 `✅ 结论：项目已成功启动` 即成功。
也可直接看端口：
```bash
ss -ltnp | grep 8800      # 或 lsof -i:8800
```

**步骤 9 — 浏览器验证**
```
http://你的域名        ← 经 Nginx（80 端口）
http://服务器IP:8800   ← 直连后端
```

### 第 5 步：生产环境常用命令

```bash
systemctl status resume-master     # 查看状态
systemctl restart resume-master    # 重启
systemctl stop resume-master       # 停止
journalctl -u resume-master -f     # 实时日志
./scripts/health-check.sh          # 运行状态检查
```

---

## 方案三：宝塔面板部署（生产 GUI 操作，最详细）

> 适合习惯图形界面的用户。下面每一步都是宝塔面板里的实际点击操作，照着做即可。

### 前置准备

1. 已安装宝塔面板（官方：https://www.baota.cn/）
2. 在宝塔 **软件商店** 安装：
   - **Nginx**（Web 服务）
   - **Python 项目管理器**（或直接用 SSH 手动建 venv，下文都给）
   - 可选：**Supervisor 管理器**（用于进程保活，强烈推荐）
3. 解析一个域名到服务器（可选，也可用 `IP:端口` 访问）

### 步骤 1 — 上传项目代码

- 方式 A：宝塔 **文件** 管理器，把项目压缩包上传到 `/www/wwwroot/` 并解压，例如 `/www/wwwroot/resume-master/`
- 方式 B：服务器 SSH 用 `git clone` 或 `scp` 上传到同上目录

确认目录结构包含 `index.html`、`backend/`、`scripts/`、`deploy/`。

### 步骤 2 — 准备 Python 运行环境

**方法 A（推荐，最省事）：SSH 手动建虚拟环境**

```bash
cd /www/wwwroot/resume-master/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install gunicorn "bcrypt==4.2.1"
cp .env.example .env
# 编辑 .env：HOST=127.0.0.1, PORT=8800, APP_ENV=prod, USE_REDIS=false
```

**方法 B：宝塔 Python 项目管理器**

1. 宝塔 → **Python 项目管理器** → **添加项目**
2. 填写：
   ```
   项目名称: resume-master
   Python 版本: 3.10+（先在管理器的"版本管理"里安装）
   框架: FastAPI
   启动方式: Gunicorn
   项目路径: /www/wwwroot/resume-master/backend
   启动文件/对象: main:app
   端口: 8800
   安装依赖: 勾选（自动读 requirements.txt）
   ```
3. 点击 **确定**，等待依赖安装完成后 **启动**

> 无论用哪种方法，最终都要保证 `backend/venv/bin/gunicorn` 存在、`.env` 中端口与后续反代一致。

### 步骤 3 — 用 Supervisor 守护进程（关键：保证一直运行 + 开机自启）

宝塔容器通常没有 systemd，因此用 **Supervisor 管理器** 保活最稳妥。

1. 宝塔 → **软件商店** → 安装 **Supervisor 管理器**
2. 打开 **Supervisor 管理器** → **添加守护进程**：
   ```
   名称:        resume-master
   启动用户:    www
   运行目录:    /www/wwwroot/resume-master/backend
   启动命令:    /www/wwwroot/resume-master/backend/venv/bin/gunicorn main:app -c gunicorn.conf.py
   ```
3. 点击 **确定**，状态显示 `RUNNING` 即成功

> 启动命令也可直接复制项目提供的 `deploy/supervisor.conf` 里的 `command=` 内容。
> `autostart=true` + `autorestart=true` 已内置，服务器重启后进程会自动拉起。

### 步骤 4 — 添加网站并配置反向代理

1. 宝塔 → **网站** → **添加站点**
   - 域名：填你的域名（如 `resume.example.com`）；若只有 IP，可填 `你的IP:8800` 或随便填一个域名后续改 hosts 测试
   - 其他选项默认，PHP 版本选「纯静态」即可（我们不靠宝塔跑 PHP）
2. 进入该站点 → **设置** → **反向代理** → **添加反向代理**：
   ```
   代理名称:   resume-master
   目标URL:    http://127.0.0.1:8800      ← 与 .env 的 PORT 一致
   发送域名:   $host
   ```
3. 保存。现在访问 `http://你的域名` 就会转发到后端 8800。

> 反向代理本质上就是 Nginx 把请求 `proxy_pass` 到 127.0.0.1:8800，和方案二的 Nginx 配置等价。你也可以不填宝塔反代，而是直接把 `deploy/nginx.conf` 的内容粘贴到站点 **配置文件** 里。

### 步骤 5 — 配置 SSL（HTTPS，可选但推荐）

1. 站点 → **设置** → **SSL** → **Let's Encrypt**
2. 勾选域名，点击 **申请**。免费证书自动签发并启用
3. 开启 **强制 HTTPS**（可选）

> Let's Encrypt 需要域名已正确解析到本机且 80 端口可达。

### 步骤 6 — 开机自启

使用 Supervisor 管理器后，**进程保活和开机自启已由 Supervisor 负责**，无需额外配置。
（若用宝塔 Python 项目管理器启动，它也会在面板重启时自动拉起。）

### 步骤 7 — 运行机制：确认「项目成功启动」

宝塔里确认项目跑起来有三种办法：

**① 宝塔面板内看状态**
- **Supervisor 管理器** 里 `resume-master` 状态为 `RUNNING`
- **网站** 站点状态为 `已启用`，反代显示正常

**② SSH 跑一键健康检查（最准确）** ✅推荐
```bash
cd /www/wwwroot/resume-master
chmod +x scripts/health-check.sh
./scripts/health-check.sh 8800
```
看到 5 项全 `✔ PASS` 即项目成功启动。

**③ 直接查端口**
```bash
ss -ltnp | grep 8800
# 或
curl -s http://127.0.0.1:8800/api/health     # 应返回 {"status":"ok"}
```

### 步骤 8 — 验证访问

浏览器打开：
```
https://你的域名          ← 经宝塔 Nginx + 反代 + SSL
http://你的IP:8800        ← 直连后端端口（需安全组/防火墙放行 8800）
```

### 步骤 9 —（可选）用一键脚本代替手动操作

如果不想一步步点，可 SSH 直接跑：
```bash
cd /www/wwwroot/resume-master
chmod +x deploy/baota_install.sh
./deploy/baota_install.sh 8800
```
脚本会自动建 venv、装依赖、生成 `.env`，并按"有 systemd 用 systemd / 无 systemd 用 nohup"智能启动，**最后自动跑健康检查**并打印访问信息。之后你再补做步骤 4（反代）和步骤 5（SSL）即可。

### 宝塔常见问题

- **外网打不开**：① 云厂商安全组放行 80/443（或 8800）；② 宝塔 **安全** 页放行对应端口；③ 确认域名已解析。
- **反向代理 502**：后端没起或端口不一致。检查 Supervisor 状态、`ss -ltnp | grep 8800`、`.env` 的 `PORT` 是否与反代目标端口一致。
- **静态资源 404**：确认 `backend/.env` 的 `HOST`/`PORT` 正确，且项目根目录有 `index.html` 和 `assets/`。

---

## 统一运行机制：健康检查（三平台通用）

无论 Windows / Nginx / 宝塔，**验证"项目是否成功启动"都用同一个工具** `scripts/healthcheck.py`（纯 Python 标准库，跨平台）。

### 它检查什么（5 项）

| 检查项 | 地址 | 通过条件 |
|--------|------|---------|
| 端口监听 | `HOST:PORT` | TCP 能连上 |
| 前端页面 | `GET /` | HTTP 200 且页面含标题 |
| API 健康检查 | `GET /api/health` | HTTP 200 且返回 `{"status":"ok"}` |
| 业务 API | `GET /api/models` | HTTP 200 |
| API 文档 | `GET /docs` | HTTP 200 |

**5 项全过 = 项目成功启动**。脚本退出码：`0` 成功 / `1` 失败（可接入 CI 或监控脚本）。

### 各平台调用方式

```cmd
:: Windows
scripts\check.bat 8800                :: 或直接 python scripts\healthcheck.py --port 8800
```

```bash
# Linux / 宝塔
./scripts/health-check.sh 8800        # 或直接 python3 scripts/healthcheck.py --port 8800
```

### 常用参数

```bash
python scripts/healthcheck.py --port 8800          # 默认 127.0.0.1:8800
python scripts/healthcheck.py --host 0.0.0.0 --port 8800
python scripts/healthcheck.py --port 8800 --wait 30   # 启动后最多等 30s（每 2s 探一次端口）
python scripts/healthcheck.py --port 8800 --json      # JSON 输出
```

> `--wait` 特别适合写进"启动脚本"：服务刚拉起时端口还没就绪，`--wait 30` 会自动轮询直到就绪或超时，再判定前端/API 是否正常。本项目的 `serve.bat`、`install.sh`、`baota_install.sh` 都已内置此机制。

---

## 端口配置（多项目共存）

一台机器部署多个实例，用不同端口即可。

### 方法 1：命令行指定
```cmd
:: Windows
start.bat 8801
scripts\serve.bat 8801

:: Linux
./deploy/install.sh 8801
python3 run.py --port 8801
```

### 方法 2：修改 .env
编辑 `backend/.env`：
```ini
HOST=127.0.0.1      # 配合 Nginx/宝塔反代时用 127.0.0.1；直接对外用 0.0.0.0
PORT=8801
```

### 方法 3：宝塔改端口
1. 改 `backend/.env` 的 `PORT`
2. 重启服务（Supervisor 里重启 / `systemctl restart resume-master`）
3. 修改网站 **反向代理** 的目标 URL 端口为一致

### 查看端口占用
```bash
# Linux
ss -ltnp | grep 8800
lsof -i:8800

# Windows
netstat -ano | findstr 8800
```

---

## 环境变量说明

所有配置在 `backend/.env`（首次运行自动从 `.env.example` 复制）。

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `HOST` | `0.0.0.0` | 监听地址。`0.0.0.0`=外网可达；`127.0.0.1`=仅本机（配 Nginx/反代用） |
| `PORT` | `8800` | 服务端口 |
| `APP_ENV` | `dev` | `dev` 或 `prod` |
| `SECRET_KEY` | 随机串 | JWT 密钥，**生产必须改** |
| `DATABASE_URL` | `sqlite+aiosqlite:///./resume_master.db` | 默认 SQLite；可换 PostgreSQL |
| `USE_REDIS` | `false` | `false`=内存替代，不依赖 Redis |
| `DEEPSEEK_API_KEY` | 空 | DeepSeek 密钥 |
| `TONGYI_API_KEY` | 空 | 通义千问密钥 |
| `ALIPAY_APP_ID` | 空 | 支付宝应用 ID |
| `CORS_ORIGINS` | `*` | 允许跨域来源 |

> **不填 AI 密钥也能运行**：系统自动返回模拟数据，方便测试。

---

## 接入真实 AI 模型

### DeepSeek（推荐，最便宜）
1. 注册 https://platform.deepseek.com/ → 创建 API Key
2. 写入 `backend/.env`：
   ```ini
   DEEPSEEK_API_KEY=sk-你的密钥
   DEFAULT_AI_PROVIDER=deepseek
   ```

### 通义千问
1. 注册 https://dashscope.aliyun.com/ → 创建 Key
2. 写入：
   ```ini
   TONGYI_API_KEY=sk-你的密钥
   DEFAULT_AI_PROVIDER=tongyi
   ```

### 多模型自动降级
主模型失败 → 自动切换备用模型。同时配置多个 Key 即可：
```ini
DEEPSEEK_API_KEY=sk-主
TONGYI_API_KEY=sk-备
DEFAULT_AI_PROVIDER=deepseek
```

---

## 接入支付宝当面付

1. 登录 https://open.alipay.com/ → 创建应用 → 获取 `APP_ID`、应用私钥、支付宝公钥
2. 写入 `backend/.env`：
   ```ini
   ALIPAY_APP_ID=2021000xxxxxxxxx
   ALIPAY_APP_PRIVATE_KEY=应用私钥
   ALIPAY_ALIPAY_PUBLIC_KEY=支付宝公钥
   ALIPAY_SANDBOX=false
   ALIPAY_NOTIFY_URL=https://你的域名/api/payment/alipay/notify
   ```
> 不填也能运行（返回模拟支付二维码）。

---

## 默认账号

首次启动自动建管理员：

| 类型 | 手机号 | 密码 | 说明 |
|------|--------|------|------|
| 管理员 | `13800000000` | `admin123` | 管理后台，9999 积分 |
| 普通用户 | 注册获取 | 注册时设 | 注册即送 5 积分 |

> **生产环境部署后请立即修改管理员密码！**

---

## 常见问题

**Q: 启动报错 "python 不是内部或外部命令"**
A: Python 没加 PATH。重新安装并勾选 "Add Python to PATH"。

**Q: 端口被占用**
A: 换端口 `start.bat 9000` 或 `./deploy/install.sh 9000`；或查杀占用：
```bash
# Linux
lsof -i:8800 && kill -9 <PID>
# Windows
netstat -ano | findstr 8800   # 记下 PID，任务管理器结束它
```

**Q: 首次启动很慢**
A: 首次需建虚拟环境 + 装依赖，约 1–3 分钟，之后几秒。

**Q: 浏览器白屏**
A: ① 启动窗口是否还开着；② 端口是否正确；③ F12 看控制台报错；④ 用 `scripts/check.bat` 或 `health-check.sh` 确认服务真的起来了。

**Q: 健康检查某一项 FAIL**
A:
- `端口监听` FAIL → 服务没起 / 端口不对。看启动日志。
- `前端页面` FAIL → 项目根目录缺 `index.html` 或 `assets/`。
- `API 健康检查` FAIL → 后端进程异常，看 `backend/logs/` 或 `journalctl -u resume-master`。
- `业务 API / API 文档` FAIL → 通常伴随上面问题，优先解决端口与后端。

**Q: AI 返回假数据**
A: 正常，未配置 Key 时返回模拟数据。见「接入真实 AI 模型」。

**Q: Redis 报错**
A: 不需要 Redis。确认 `.env` 中 `USE_REDIS=false` 即可，无需安装 Redis。

**Q: bcrypt 相关报错**
A: `pip install "bcrypt==4.2.1"`。所有一键脚本已自动处理。

**Q: 数据库在哪 / 如何备份 / 如何重置**
A: 文件 `backend/resume_master.db`。备份=复制该文件；重置=删掉它重启自动重建。

**Q: 宝塔外网访问不了**
A: ① 云安全组放行 80/443（或 8800）；② 宝塔**安全**放行；③ 域名已解析；④ 反代目标端口与 `.env` 的 `PORT` 一致。

---

## 项目结构

```
resume-master/
├── index.html                  前端入口页面
├── start.bat                   Windows 一键启动（前台）
├── run.py                      统一启动入口（自动建环境+装依赖+启动）
├── scripts/
│   ├── healthcheck.py          跨平台健康检查（端口/前端/API）★运行机制核心
│   ├── check.bat               Windows 健康检查入口
│   ├── serve.bat               Windows 一键启动(后台+自检+开浏览器)
│   └── health-check.sh         Linux 健康检查入口
├── assets/                     前端资源 (css/ js/ uploads/)
├── backend/
│   ├── main.py                 FastAPI 入口（同时托管前端静态文件）
│   ├── config.py / database.py / models.py / schemas.py / deps.py
│   ├── gunicorn.conf.py        生产 Gunicorn 配置
│   ├── requirements.txt
│   ├── .env.example
│   ├── routers/                API 路由
│   └── services/               AI 适配器 / 支付
├── deploy/
│   ├── install.sh              Linux+Nginx 一键部署（systemd+nginx+健康检查）
│   ├── baota_install.sh        宝塔/Linux 一键部署（智能 systemd/nohup+健康检查）
│   ├── nginx.conf              Nginx 反代模板
│   ├── resume-master.service   systemd 服务模板（参考）
│   └── supervisor.conf         宝塔 Supervisor 守护配置（参考）
└── backup/                     前端历史备份
```

---

## 技术支持

部署或使用中遇到问题，按以下顺序排查：
1. 本文档 **常见问题** 章节
2. 运行对应平台的健康检查（`scripts/check.bat` 或 `health-check.sh`）看 FAIL 项
3. 浏览器 F12 控制台报错
4. 后端日志：`backend/logs/`（nohup/gunicorn）或 `journalctl -u resume-master`（systemd）

---

> 本项目默认 SQLite，零配置即跑。生产如需更高性能，修改 `.env` 的 `DATABASE_URL` 切换到 PostgreSQL 即可。Redis 默认不启用，无需安装。