Vodo
====

移动开发盛行的背景下，一个好用的 HTTP[S] 请求抓包工具。然而现存的软件当中，Fiddler、Charles都是收费软件，开源的工具功能都太简单，没有可比性。自制这个抓包工具一是为了提供一个功能比较强大的开源方案，另一方面也解决诸如 Fiddler 对 Mac 兼容性不好，Charles不支持 HTTPS 转发HTTP 等问题，更重要的是，这个项目中文优先。

![](https://raw.githubusercontent.com/davidaq/vodo/master/doc/images/main-window.png)

## 支持的功能

 - 通过代理实现请求记录
 - 仿照 Charles 的树形请求记录列表
 - 保存请求记录
 - 请求转发
 - Mock 请求结果
 - HTTPS 请求转发给 HTTP 服务端或相反
 - HTML 页面注入 JS 脚本
 - JSON 数据结构化显示
 - Gzip 包装，节省网络带宽

## 开发中功能功能
 
 - 请求记录筛选
 - 慢速、不稳定网络环境模拟
 - 注入 Vorlon 远程调试

## 已知问题

 - 极偶然的情况下，软件界面上一些图标会显示不出来。遇到这种情况，重新打开软件即可
 - 电脑进入睡眠状态再唤醒后，代理服务器可能会关闭。遇到这种情况，重新打开软件即可

使用说明
=======

## 安装方法

本软件开箱即用，解压下载的压缩包后，Mac 双击直接启动，Windows 双击Vodo.exe 启动。Mac 系统想将 vodo 添加到 Luanch Pad，直接将应用拖放至 Application 文件夹里即可。

## 基本抓包方法

Vodo 是通过代理的方式来截取网络请求，工作原理与 Fiddler、Charles 一样，所以使用方法也类似:

 1. 启动 Vodo，代理服务器会自动开始启动
 1. 代理服务器启动成功后，主窗口的右上角会显示“代理已启动”。同时本机的 IP 地址以及代理服务器的端口也会在右上角显示
 1. 按照右上角提示的代理地址，在需要抓取请求的设备上设置代理
 1. 有些设备或 App 需要重启需要调试的 App
 1. 请求记录会开始出现在主界面的左侧列表当中

![](https://raw.githubusercontent.com/davidaq/vodo/master/doc/images/proxy-addr.png)

### 列表模式

左侧列表有两种展示模式：

 - **结构树：** 将记录到的请求路径以“／”分列，以文件夹的形式展示
 - **时序列表：** 以列表的形式按请求开始时间顺序依次列出所有请求记录

![](https://raw.githubusercontent.com/davidaq/vodo/master/doc/images/record-tree.png)

![](https://raw.githubusercontent.com/davidaq/vodo/master/doc/images/record-list.png)

### 请求基本信息

点击查看某个请求的详情，首先会看到请求的“基本信息”。在此可以见到本次请求的摘要、请求头、响应头。

![](https://raw.githubusercontent.com/davidaq/vodo/master/doc/images/request-basic-info.png)

### 请求数据

请求数据分两部分：

 - **地址参数：** 直接在请求 url 里放置的参数，PHP 中 `$_GET` 参数
 - **发出数据：** 在请求体力发出的数据，可能是上传的文件，也可能是 PHP 中 `$_POST` 参数

### 响应数据

响应数据可能是有多重情况：

 - **JSON：** 会结构化展示
 - **图片：** 会提供图片预览
 - **文本：** 会直接以文本形势展示
 - **其他或者过大的内容：** 不提供展示，内容上限默认为1MB，可在设置里提升

## 处理HTTPS

很多网站、App 选择使用 HTTPS 请求来保证信息安全，在谷歌等大公司的推动下，很多场景必须使用 HTTPS。设备设置了代理之后，可能会出现网络无法正常使用的情况，这是因为 Vodo 通过证书伪造截取并解读了 HTTPS 请求。伪造的证书设备默认是不会信任的，可能会弹出安全提示也可能直接提示网络异常。

遇到这种情况，可以有两个选择：

 1. 打开设置（主窗口右上角的齿轮按钮），勾选“忽略HTTPS”，这样可恢复 HTTPS 的正常访问，但是 Vodo 将不会解读 HTTPS 请求的内容
 1. 在设备上安装并信任 Vodo 的 SSL 根证书，安装方法见下文

## 安装 Vodo SSL 根证书

在第一次启动 Vodo 的时候，会生成一个 SSL 根证书，Vodo 会使用这个根证书来声场伪造的网站 SSL 证书。设备信任了这个根证书，就会信任所有 Vodo 所伪造出来的证书。

Vodo 给每个用户生成的根证书都是不一样的，也不会以任何形式将秘钥公开，所以你不必担信任根证书会有产生不安全的问题。

![](https://raw.githubusercontent.com/davidaq/vodo/master/doc/images/download-ssl.png)

### 安卓系统安装证书

 1. 在 Wi-Fi 设置里配置代理
 1. 在系统自带浏览器里打开网址 [vo.do](http://vo.do)（支持文件下载的QQ浏览器等第三方浏览器也可以）
 1. 点击下载“SSL证书”（有的手机系统会自动安装证书，可跳过后续步骤）
 1. 在 系统设置 - 更多 or 高级 - 系统安全 - 从存储设备安装 里选择下载的 .cer 文件

有的安卓系统无法从浏览器直接下载安装证书，可以在开启 Vodo 的桌面系统上通过 [http://127.0.0.1:8888/vodo.cer]() 下载证书文件，然后通过 USB 将证书传输给设备。

**特别说明：**如果安卓系统是 7.0 或以上，即便安装了根证书也不一定能正常使用 HTTPS。这是因为安卓从 7.0 开始，应用可以选择是否信任用户自己安装的根证书。大部分从市场下载的应用不会选择信任，请确保你所要调试的 App 是信任用户证书的版本。

### iOS系统安装证书

 1. 在 Wi-Fi 设置里配置代理
 1. 在 Safari 里打开网址 [vo.do](http://vo.do)
 1. 点击下载“SSL证书”，选择安装该证书
 1. 在 系统设置 - 通用 - 关于本机 - 证书信任设置 里打开对 Vodo 证书的信任

### Win10系统安装证书

 1. 在系统设置或者浏览器设置里配置代理
 1. 使用浏览器访问 [vo.do](http://vo.do)
 1. 下载证书
 1. 双击下载下来的 .cer 文件
 1. 点击“安装证书”
 1. 选择“当前用户”，下一步
 1. 选择将“将所有的证书放入下列存储”
 1. 点击浏览，选择“受信任的根证书颁发机构”，下一步
 1. 完成

### MacOS系统安装证书

 1. 在系统设置或者浏览器设置里配置代理
 1. 使用浏览器访问 [vo.do](http://vo.do)
 1. 下载证书
 1. 双击证书进行安装
 1. 打开钥匙串
 1. 双击 vodo 证书
 1. 选择信任所有

## 请求替换规则

![](https://raw.githubusercontent.com/davidaq/vodo/master/doc/images/replace-rule-prompt.png)

除了抓包，求情替换也是 Vodo 的核心功能。转发有两种：

 1. 将请求转发给其他服务端
 1. 直接使用本地文件作为请求的返回内容

匹配有两种模式：
 
 - **准确：** 只有请求路径与设置的完全一样时才算命中
 - **扩展：** 只要请求的路径以设置的路径为开头就算命中

替换也有两种模式：
 
 - **准确：** 转换后的请求路径与设置的完全一样
 - **扩展：** 转换后的请求会附加实际请求路径匹配后剩余的内容

替换规则会按照顺序依次检查。

## 页面注入JS脚本

在 Vodo 的设置里可以选择开启注入JS脚本，开启后，设置代理的设备在打开任何 html 页面的时候会首先执行设置的脚本。如果开启了“忽略HTTPS”，使用 HTTPS 的网站将不会被注入。