.. _open-crawlhuaban:

.. _tdi-usgae:

==========================
花瓣、堆糖远程下载接口说明
==========================

对于open.saintic.com而言，这是一个插件提供的功能，主要是两方面

    - 1. 丰富了"花瓣网下载"、"堆糖网下载"两个油猴脚本的下载方法————远程下载。

        - 应用场景主要是在不方便使用文本方式(迅雷)下载时；

        - 图片太多不适合使用本地方式直接保存时；

        - 需要下载很多时，此时比较麻烦，则直接选择远程，后续可以发出邮件提醒、控制台历史记录等。

    - 2. 针对远程下载，提供了第三方接入的页面。

        - 地址是：https://open.saintic.com/CrawlHuaban/Register

        - 文档首页有提过，我的大部分Python Web是基于Flask-PluginKit的，这个CrawlHuaban就是Flask-PluginKit的插件

        - 此页面专门用来接入Tdi程序，分担第一个功能：远程下载。

Tdi: 即为花瓣网下载和堆糖网下载两个油猴脚本提供远程下载服务的专项程序，通过open.saintic.com调度请求。

本篇内容旨在使用说明，包括Tdi for Python、Tdi for PHP、Tdi for Node、Tdi for Golang等数个语言版本，其他编程语言可能、大概还不会~~~

不过后续可能会将请求流程写出文档，基于文档可以用其他语言实现，逻辑其实是很简单的。

--------------

**当您部署完成并正常提供服务后，用户下载请求并不会发送到程序中，您需要接入到官方系统中，步骤如下：**

这里假设您提供服务的域名是\ ``http://tdi.demo.com``\ ，令牌是\ ``secret``\ 。

.. _tdi-join:

**注册接入**
------------------

1. 打开开放平台的服务接入页面中： https://open.saintic.com/CrawlHuaban/Register
    |image0|

2. 填写接入申请表单：

    - 域名即假设的\ ``http://tdi.demo.com``
    - 令牌即假设的\ ``secret``
    - 您可以点击\ ``资源限制``\ ，展开表单，可以设置内存、负载、磁盘，这是用户级限制，与系统级限制相辅相成。

    2.1 域名：虽然可以用IP:PORT形式，但是这种情况除非您特意设置了nginx，否则可能无法下载；

    2.2 令牌：长度要求大于2小于32字节，且以英文字母开头加英文字母、数字、下划线组成；

    2.3 资源限制：

        - 系统级限制默认上限是：内存使用率80%、五分钟负载5、程序下载目录所在磁盘使用率80%！
        - 用户级限制默认为0，即不限制，且仅能设置数字，0-100间的正整数。
        - 权重：中心端分发请求算法的配置值，要求1-9(包含)之间的数字。
            - 其中9权重最大，1是默认权重；
            - 权重越大，分发的请求越多；
            - 专属和公共均使用权重；
            - 如果您认为自己的机器配置高、较空闲，可以适量增加权重。

    2.4 私有：您可以点击开关开启私有属性，开启后，此Tdi服务只为您的账号提供服务，您需要创建密钥，并在花瓣网、堆糖网的脚本功能设置中填写密钥，详情查看下方 :ref:`tdi-private` 的介绍！

填写无误后，立即提交，系统会发送一次GET请求您的域名地址，令牌验证通过后，接入成功。

.. _tdi-clean:

**过期清理**
----------------------

不论是普通部署还是使用Docker部署，接入服务后，下载请求就来了，压缩包会在本地存储，依照规则，目前保留压缩文件12h，过期后可以删除，避免占用磁盘空间。

.. _tdi-clean-process:

**清理过期文件流程：**

1. 遍历downloads目录，根据文件名查询创建时间，根据过期时长(12h)和文件创建时间决定是否删除。
2. 判定过期后，删除压缩文件，可选地删除redis存储的key，并回调给开放平台接口。

.. note::

    在Tdi for Python的v0.2.2版本后，清理时增加了一重判断，即同时需要满足 **压缩文件创建之后超过了过期时长(12h)** 才予以删除！
    Tdi-php、Tdi-node、Tdi-go初始版本已经包含此判断。

.. _tdi-clean-command:

**清理过期文件命令：**

1. 普通部署：

    - Tdi for Python

        进入程序目录src下，执行\ ``./cleanDownload.py``\ ，可使用\ ``-h``\ 查看帮助，目前支持\ ``--hours``\ 参数手动设置过期时长，其默认值是12，单位h

        请注意解释器，最新版是 ``/usr/bin/env python`` 自动选择python执行，注意命令路径与版本。

    - Tdi for PHP

        进入程序目录src下，执行\ ``./cleanDownload.php``\ ，目前支持传递一个位置参数设置过期时长，其默认值是12，单位h

        请注意解释器，目前是 ``/usr/bin/env php`` 自动选择php执行，注意命令路径与版本。

    - Tdi for Node

        进入程序根目录，执行 ``yarn run clean`` 或 ``npm run clean`` 即可，其会进入src目录，使用node命令执行cleanDownload.js脚本，所以也可以直接调用。

    - Tdi for Golang

        不可手动执行，启动进程后自动执行

2. Docker部署：

    - Tdi for Python

        假设容器名是tdi，在宿主机执行\ ``docker exec tdi cleanDownload.py``\ 或者是\ ``docker exec tdi ./cleanDownload.py``\ 即可，参数同上。

3. *专属Tdi* ：

    如果是您专属，您可以不执行这个定时任务，这样下载的图片压缩包将不会过期。

.. tip::

    **可将上述清理过期文件命令加入定时任务中，每分钟执行一次！**

    需要注意的是，Tdi-node的正式环境使用的是pm2，已经包含了配置，每过60s自动执行清理脚本，不需要加入定时任务。

    Tdi-go也是自动清理，不需要加入定时任务。

.. _tdi-check:

**定时检测**
----------------------

.. note::

    此功能不是Tdi程序本身所有的，而是中心端定时检测接入的URL，更新其状态、资源等。

- 所以如果您想暂时停止服务，可以将状态设置为tardy，如此定时检测（目前1分钟）后将更新此服务状态，将不再发送请求；若想恢复，需要此值设置ready，重启等待定时检测生效。

    - Tdi for Python

        可参考 :ref:`tdi-config`，设置环境变量 ``export crawlhuabantdi_status=tardy`` ，重启Web进程

    - Tdi for PHP

        需要修改config.php文件，设置STATUS参数值为tardy即可，如果不生效或有缓存扩展，可以重载php-fpm进程

    - Tdi for node

        可以修改config.json文件，设置status值为tardy；或者 ``export crawlhuabantdi_status=tardy`` 设置环境变量，这是允许的。
        重载Web进程： ``yarn prod:reload``

    - Tdi for golang

        tdi --status tardy --other-flags

- 您的服务可以随意停止，如果中心端接收到请求并转发到了您的程序，但程序无法正确响应，此时会由中心端本身提供下载。【另外，您现在也可以随时在控制台中直接删除接入的Tdi服务！】

- 接收到请求时，将任务放到队列中，由rq进程处理，下载前检测磁盘使用率，大于80则停止下载，下载中亦检测，非正常停止下载会给出README.txt文件（同样在压缩包内），内含说明原因。

.. _tdi-private:

**私有属性（专属的远程下载服务）**
-----------------------------------------------

.. note::

    此功能也不是Tdi程序本身所有的！

    现已支持随时将公有Tdi设置为私有，也可以将私有设置为公有，且可以随时删除！

1. 接入专属：您在填写接入表单时，打开"私有"开关，此Tdi即为您账号专属，只有此账号下的密钥能使用此Tdi远程下载。

2. 创建密钥：登录到\ `控制台 <https://open.saintic.com/control/>`__\ ，在“我的密钥”旁边有创建按钮，点击可打开表单，再点击 `立即提交` 按钮：

    |image1|

3. 脚本设置：前两步完成后，系统并不能知道哪次请求隶属于您的账号，所以两个油猴脚本（花瓣网下载和堆糖网下载）需要进行功能设置，此设置要求油猴脚本的版本\ ``v1.0.0+``。

    在脚本生效页面（花瓣网画板页或个人主页、堆糖网专辑页），下载按钮旁有相应的脚本设置按钮，点击"设置"按钮在弹窗中选择“设置提醒“，填写并保存密钥即可（如图以堆糖网设置为例）：

    |image2|

.. _tdi-alert:

**下载异常报警**
----------------

Tdi for Python的v0.2.2+（Tdi-php、Tdi-node开发时已存在此参数）添加了异常队列（即failed队列，下载任务异常时进入此队列）上报参数，同时增加了报警邮箱的配置 *ALARMEMAIL* ，当中心端检测到Tdi存在异常队列时，根据报警邮箱发送报警邮件。

报警邮箱的配置可不填，则视为放弃报警。

Tdi for Golang此项无效或并无此项，因为不是依靠队列下载，而是协程，仅手动判断是否下载完成（日志，是否出现压缩文件）

.. _tdi-weight:

**加权轮询分发**
----------------

.. note::

    此功能也不是Tdi程序本身所有的！

    轮询算法即提供同质服务的节点逐个对外提供服务；加权轮询算法就是在轮询算法的基础上，考虑到机器的差异性，分配给机器不同的权重，能者多劳。

1. 前面提到过Tdi只有接入到中心端才会分发请求，怎么分发呢？

    之前是随机，碰运气，这可能导致某一个接收到太多请求，所以2019-05-30后上线权重功能，使用加权轮询算法，依据权重分发请求。

2. 如何设置权重？

- 在接入时可以手动设置权重（在资源限制的隐藏表单中），也可以忽略，默认为1。

- 已接入的可以在控制台随时调整权重值，1-9之间的数字，包含1和9。

- 权重是针对Tdi整个程序的，所以无论是专属还是公共，其效果一致。


.. _tdi-todo:

**更多功能待开发**
--------------------------

若您有有趣的功能或建议，可以在文档首页找到QQ群，当然也可以反馈问题。

.. |image0| image:: /_static/images/20190307120155.png
.. |image1| image:: /_static/images/20190307133835.png
.. |image2| image:: /_static/images/20190307134421.png