Merge pull request SpiderClub#7 from ResolveWang/master

add usage doc support

README.md

@@ -91,7 +91,7 @@
 ![](static/workflow.png)
 
 # 开发者文档
-为了方便用户针对自身需求进行定制化，`haipproxy`提供了丰富的文档支持。所以文档详见[项目wiki](https://github.com/SpiderClub/haipproxy/wiki)
+为了方便用户针对自身需求进行定制化，`haipproxy`提供了丰富的文档支持。所有文档详见[项目wiki](https://github.com/SpiderClub/haipproxy/wiki)
 
 # 效果测试
 以单机模式部署`haipproxy`和[测试代码](examples/zhihu/zhihu_spider.py)，以知乎为目标请求站点，

client/py_cli.py

@@ -14,6 +14,9 @@
     LOWEST_SCORE, DATA_ALL)
 
 
+__all__ = ['ProxyFetcher']
+
+
 class Strategy:
     strategy = None
 

docs/haipproxy中的任务类型和作用.md

@@ -0,0 +1,55 @@
+本文简要haipproxy支持的所有任务及其相关意义。
+
+---
+
+### 代理采集爬虫
+代理采集爬虫相关实现见[crawler/spiders](https://github.com/SpiderClub/haipproxy/tree/master/crawler/spiders)部分
+
+一共包含四种类型的爬虫
+
+- `common`: 该类爬虫支持爬取普通类型的代理IP网站，即不需要做ajax渲染，也不需要翻墙的网站。
+
+- `ajax`: 该类爬虫支持爬取需要ajax渲染的代理IP网站，需要安装[scrapy-splash](https://github.com/scrapy-plugins/scrapy-splash)
+并在设置里提供`SPLASH_URL`
+
+- `gfw`: 该类爬虫用于爬取需要翻墙但是不需要ajax渲染的代理IP网站，需要在设置里提供`GFW_PROXY`，并且需要支持http协议
+
+- `ajax_gfw`: 该类爬虫用于爬取需要翻墙同时也需要ajax渲染的代理IP网站，需要同时设置`GFW_PROXY`和`SPLASH_URL`
+
+`haipproxy`支持通过启动命令来指定启动具体的爬虫实例，比如我们只想启动`common`和`ajax`相关的代理抓取爬虫，那么启动命令为
+> python crawler_booter.py --usage crawler common ajax
+
+同时，我们也可以在定时任务调度器中指定相关的定时任务
+> python scheduler_booter.py --usage crawler common ajax
+
+如果不指定具体的任务，默认会启动所有爬虫实例和定时任务调度
+
+### 代理IP校验器
+代理IP校验器具体实现见[crawler/validators](https://github.com/SpiderClub/haipproxy/tree/master/crawler/validators)
+
+该类型的任务根据代理IP的具体用处可以进行定制，具体方法参考[针对特定站点添加校验器](https://github.com/SpiderClub/haipproxy/blob/master/docs/%E9%92%88%E5%AF%B9%E7%89%B9%E5%AE%9A%E7%AB%99%E7%82%B9%E6%B7%BB%E5%8A%A0%E6%A0%A1%E9%AA%8C%E5%99%A8.md)。
+`haipproxy`默认支持的校验任务包括
+
+- `init`: 该校验器的主要目的是对所有新采集到的ip进行初始校验，过滤掉透明IP并将代理IP放入后面需要使用的队列中
+
+- `http`: 该校验器用于校验`http`代理，以[http://httpbin.org/ip](http://httpbin.org/ip)为校验对象，你也可以自己搭建相关的http校验站点
+
+- `https`: 该校验器用于校验`https`代理，以[https://httpbin.org/ip](http://httpbin.org/ip)为校验对象，你也可以自己搭建相关的https校验站点
+
+- `weibo`: 该校验器用于校验`weibo`的代理
+
+- `zhihu`: 该校验器用于校验`zhihu`的代理
+
+同样，`haipproxy`支持通过命令启动特定校验器的爬虫实例，比如我们只想`init`和`zhihu`的代理校验器，那么启动命令为
+> python crawler_booter.py --usage validator init zhihu
+
+同时，我们也可以在定时任务调度器中指定相关的定时任务
+> python scheduler_booter.py --usage validator zhihu
+
+不过需要注意两点
+
+- `init`校验器属于特殊校验器，无论单机还是分布式部署`haipproxy`的时候，都必须启动至少一个`init`校验器实例。建议部署足够多的`init`校验器
+实例，因为通过实践发现，一个`init`校验器往往不够用
+- `init`校验器并没有相应的定时任务调度，它的资源获取是代理IP爬虫直接操作的
+
+

docs/haipproxy具体使用说明.md

@@ -3,5 +3,89 @@
 
 ---
 
+`haipproxy`只在Linux和Mac OS上做过测试，windows系统不保证程序的稳定运行。
+
+## 服务端
 ### 单机部署
-以前
+1.Python3和安装Redis。小白可以阅读[这篇文章](https://github.com/SpiderClub/weibospider/wiki/%E5%88%86%E5%B8%83%E5%BC%8F%E7%88%AC%E8%99%AB%E7%8E%AF%E5%A2%83%E9%85%8D%E7%BD%AE)
+的相应部分来进行安装
+
+2.根据`redis.conf`中对Redis做的设置修改[setting.py](https://github.com/SpiderClub/haipproxy/blob/master/config/settings.py)中`REDIS_HOST`和`REDIS_PASSWORD`等参数
+
+3.安装Docker，根据[Docker官网的文档](https://docs.docker.com/install/)进行安装
+
+4.安装[scrapy-splash](https://github.com/scrapy-plugins/scrapy-splash)
+  > docker run -p 8050:8050 -d --name mysplash --restart=always scrapinghub/splash
+  然后根据实际情况配置文件[config/settings.py](config/settings.py)中的`SPLASH_URL`
+
+5.安装项目相关依赖
+  > pip install -r requirements.txt
+
+6.启动*scrapy worker*，包括代理IP采集器和校验器
+  > python crawler_booter.py --usage crawler
+
+  > python crawler_booter.py --usage validator
+
+  注意，我们可以只指定启动特定的代理IP采集器和校验器实例。
+  代理IP采集器包括`common`、`ajax`、`gfw`和`ajax_gfw`四种任务。他们的具体意义和使用方法见[haipproxy中的任务类型和作用]()
+
+7.启动*调度器*，包括代理IP定时调度和校验
+  > python scheduler_booter.py --usage crawler
+
+  > python scheduler_booter.py --usage validator
+
+  注意，我们可以只启动特定的代理IP抓取调度器和校验调度器。具体操作请阅读[haipproxy中的任务类型和作用]()
+
+### Docker部署
+1.安装Docker，根据[Docker官网的文档](https://docs.docker.com/install/)进行安装
+
+2.安装*docker-compose*
+  > pip install -U docker-compose
+
+3.根据配置文件的注释提示修改[settings.py](config/settings.py)中的`SPLASH_URL='http://splash:8050'`和`REDIS_HOST='redis'`参数
+
+4.使用*docker-compose*启动各个应用组件
+  > docker-compose up
+
+
+### 集群部署
+由于精力有限，目前只能通过手动部署`haipproxy`集群。部署方式并没有什么特别的，配置文件根据实际情况进行改动即可。无论是代理IP采集器、代理IP定时任务
+调度器，还是代理IP校验器和代理IP校验定时任务调度器，都可以分布式部署到多台服务器上，并且可以根据实际情况，部署M:N的代理采集和校验节点。也可以在不同
+爬虫节点上指定不同的任务，以充分利用服务器资源。由于实现了分布式锁，所以不用担心*scrapy worker*执行到重复的任务。
+
+自动化部署方式笔者还需要继续考察，目前的思路有:
+1.根据`scrapyd`来做集群部署
+2.使用`ansible`做集群部署
+3.使用`k8s`做集群部署
+
+### 客户端
+
+#### 调用Python客户端
+示例代码见[examples/zhihu/](https://github.com/SpiderClub/haipproxy/blob/master/examples/zhihu/crawler.py)
+
+
+#### 调用squid作为二级代理
+1.安装squid，备份squid的配置文件并且启动squid，以ubuntu为例
+  > sudo apt-get install squid
+
+  > sudo sed -i 's/http_access deny all/http_access allow all/g'
+
+  > sudo cp /etc/squid/squid.conf /etc/squid/squid.conf.backup
+
+  > sudo service squid start
+
+2.根据操作系统修改项目配置文件[config/settings.py](config/settings.py)中的`SQUID_BIN_PATH`、
+`SQUID_CONF_PATH`、`SQUID_TEMPLATE_PATH`等参数,参数的详细意义见[配置文件的参数和意义](https://github.com/SpiderClub/haipproxy/blob/master/docs/%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6%E5%8F%82%E6%95%B0%E5%92%8C%E6%84%8F%E4%B9%89.md)
+
+3.启动`squid conf`的定时更新程序
+  > sudo python squid_update.py
+
+4.使用squid作为代理中间层请求目标网站,默认代理URL为'http://squid_host:3128',用Python请求示例如下
+  ```python3
+  import requests
+  proxies = {'https': 'http://127.0.0.1:3128'}
+  resp = requests.get('https://httpbin.org/ip', proxies=proxies)
+  print(resp.text)
+  ```
+
+如果您使用的是项目提供的docker compose的方法，那么squid就不用安装了，直接就可以做请求