# house-finder

**Repository Path**: Tianyu201809/house-finder

## Basic Information

- **Project Name**: house-finder
- **Description**: 贝壳二手房/新房交互式命令行爬虫程序
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 1
- **Created**: 2024-04-26
- **Last Updated**: 2026-02-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🏠 贝壳找房数据爬虫工具 - 桌面版

一个基于 Electron + Vue 3 + Koa 的贝壳找房数据爬虫桌面应用，支持爬取二手房、新房、二手房成交等数据，并导出为 Excel 文件。

## ✨ 功能特点

- 🖥️ **桌面应用** - 基于 Electron，一键启动，无需配置环境
- 🏙️ **全国城市支持** - 支持全国 197+ 城市，覆盖所有贝壳开通的城市
- 📊 **多种房源类型** - 支持二手房、新房、二手房成交数据
- 📍 **区域筛选** - 支持按省/市/区三级联动筛选
- 📄 **Excel 导出** - 自动生成 Excel 文件，方便数据分析
- 📈 **实时进度** - 任务执行过程中可查看实时日志和进度
- 🎨 **现代化 UI** - 基于 Naive UI 的美观界面

## 📸 界面预览

应用主界面包含：
- Cookie 配置区域（含获取教程）
- 任务创建表单（房源类型、省/市/区选择、页数设置）
- 任务列表（状态、进度、操作）
- 实时日志终端窗口

## 🏗️ 项目结构

```
house-finder/
├── electron/                # Electron 主进程
│   └── main.js              # 主进程入口，窗口管理和服务器启动
├── server/                  # 后端服务 (Koa)
│   ├── server.js            # 服务器入口
│   └── src/
│       ├── routes/          # API 路由
│       │   ├── task.js      # 任务相关接口
│       │   ├── file.js      # 文件下载接口
│       │   └── auth.js      # 健康检查接口
│       ├── services/
│       │   └── TaskManager.js  # 任务管理器
│       ├── Core/            # HTML 解析核心
│       ├── Finder/          # HTTP 请求模块
│       ├── Store/           # Excel 存储模块
│       ├── TaskPublisher/   # URL 生成器
│       ├── Worker.js        # 爬虫工作器
│       ├── constant/        # 常量定义
│       └── json/            # 城市/区域数据
│           ├── city.json    # 城市代码映射
│           └── area.json    # 区域代码映射
├── web/                     # 前端 (Vue 3 + Vite)
│   ├── src/
│   │   ├── views/
│   │   │   └── Home.vue     # 主页面
│   │   ├── api/             # API 封装
│   │   ├── router/          # 路由配置
│   │   └── stores/          # Pinia 状态管理
│   └── vite.config.js       # Vite 配置
└── package.json             # 项目配置和打包配置
```

## 🚀 快速开始

### 环境要求

- Node.js >= 18.x
- npm >= 9.x

### 安装依赖

```bash
# 一键安装所有依赖（根目录、server、web）
npm run install:all
```

### 开发模式

```bash
# 启动开发环境（自动启动 server、web、electron）
npm run dev
```

开发模式下会同时启动：
- 后端服务器：http://localhost:3000
- 前端开发服务器：http://localhost:5173
- Electron 窗口（自动打开开发者工具）

### 生产打包

```bash
# 打包 Electron 应用
npm run build:electron
```

打包产物位于 `dist/` 目录：
- `win-unpacked/` - Windows 免安装版
- `*.exe` - Windows 安装包 (NSIS)

## 📖 使用说明

### 1. 获取 Cookie

由于贝壳有反爬机制，需要使用通过人机验证后的 Cookie：

1. 打开 [贝壳找房官网](https://ke.com/?freeze=1)
2. 登录并完成人机验证
3. 按 F12 打开开发者工具
4. 切换到 Network 选项卡
5. 刷新页面，点击任意请求
6. 在 Headers 中找到 Cookie 并复制

⚠️ **注意**：每次切换城市后需要重新获取该城市的 Cookie

### 2. 创建任务

1. 粘贴 Cookie 到输入框
2. 选择房源类型（二手房/新房/二手房成交）
3. 选择省份 → 城市 → 区域（可选）
4. 设置爬取页数（1-100）
5. 点击"创建爬虫任务"

### 3. 查看进度

- 任务列表显示所有任务状态
- 点击进行中任务的"查看"按钮可查看实时日志
- 任务完成后可下载 Excel 文件

## 🔧 API 接口

### 任务相关

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/task/create` | POST | 创建爬虫任务 |
| `/api/task/list` | GET | 获取任务列表 |
| `/api/task/:taskId/status` | GET | 获取任务状态 |
| `/api/task/:taskId/logs` | GET | 获取任务日志 |
| `/api/task/provinces` | GET | 获取省份列表 |
| `/api/task/cities/:province` | GET | 获取城市列表 |
| `/api/task/areas/:city` | GET | 获取区域列表 |

### 文件相关

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/file/:taskId/download` | GET | 下载任务结果 |

## 📦 技术栈

### 前端
- **Vue 3** - 渐进式 JavaScript 框架
- **Vite** - 下一代前端构建工具
- **Naive UI** - Vue 3 组件库
- **Pinia** - Vue 状态管理
- **Vue Router** - 路由管理
- **Axios** - HTTP 客户端

### 后端
- **Koa** - Node.js Web 框架
- **Cheerio** - HTML 解析库
- **node-xlsx** - Excel 文件生成
- **Axios** - HTTP 请求
- **dayjs** - 日期处理

### 桌面端
- **Electron** - 跨平台桌面应用框架
- **electron-builder** - 应用打包工具

## 📋 数据字段

爬取的数据包含以下字段：

| 字段 | 说明 |
|------|------|
| 标题 | 房源标题 |
| 小区名称 | 所属小区 |
| 区域 | 所在区域 |
| 户型 | 房屋户型 |
| 面积 | 建筑面积 |
| 朝向 | 房屋朝向 |
| 装修 | 装修情况 |
| 楼层 | 楼层信息 |
| 建筑年代 | 建成年份 |
| 总价 | 房屋总价 |
| 单价 | 每平方米单价 |
| 链接 | 详情页链接 |

## ⚠️ 免责声明

本工具仅供学习研究使用，请勿用于商业用途或其他非法目的。使用本工具爬取数据时，请遵守相关法律法规和网站的服务条款。

## 📄 开源协议

MIT License