Swagger 生成 PHP restful API 接口文档

发布于

需求:

为客户端同事写接口文档的各位后端同学,已经在各种场合回忆了使用自动化文档工具前手写文档的血泪史.
我的故事却又不同,因为首先来说,我在公司是 Android 组负责人,属于上述血泪史中催死人不偿命的客户端阵营.
但血泪史却是相通的,没有自动化文档的日子,对接口就是开发流程中最低效的环节.
因此决定使用 swagger 搭建由php注释生成文档的流程.

背景:
我们的 restful api 项目采用 phalcon 框架,整体结构很简单,我们只需要用 swagger 扫描 controller 目录即可.
下简称我们的 php api 项目为 php_api_project.
服务器采用 nginx.

搭建:

先说下最终的文档生成流程会是什么样子,以便先有个整体的认识:
搭建完成后, 整个流程, 从文档生成到前端展现, 大体如下:

  1. 在php文件中写 swagger 格式的 /** 注释 */
  2. 用 swagger-php 内的 bin/swagger.phar 命令扫描 php controller 所在目录, 生成 swagger.json 文件
  3. 将 swagger.json 文件拷贝到 swagger-ui 中 index.html 指定的目录中
  4. 打开 swagger-ui 所在的 url, 就可以看到文档了. 文档中的各个 api 可以在该网址上直接访问得到数据.

实现此需求只需要 swagger 的如下两个项目:
swagger-php: 扫描 php 注释的工具. 内含一个不错的例子.
swagger-ui: 用以将扫描工具生成的 swagger.json 文件内容展示在网页上.

首先将这两个项目下载到本地:

$ git clone https://github.com/swagger-api/swagger-ui.git
$ git clone https://github.com/zircote/swagger-php.git

文档生成工具部署:

说是部署,主要就是产生 bin/swagger 这个用来生成 swagger.json 文件的命令.
主要工作,就是用 composer 解决下依赖就可以了.
因为国内直接用 composer 比较蛋疼,所以最好设置下国内的那个 composer 源.
这样的话, 整个 文档生成工具的部署 就是下面三行命令:

$ cd swagger-php
$ composer config repo.packagist composer https://packagist.phpcomposer.com
$ composer update

只要中间不报错,就算部署完成了. 完成后可以生成一份文档试一下.
swagger-php 项目下的 Examples 目录下有一个示例php工程,里面已经用 swagger 格式写了各种接口注释, 我们来尝试生成一份文档.
执行下面命令:

$ cd swagger-php
$ mkdir json_docs
$ php ./bin/swagger ./Examples -o json_docs/

上面命令会扫描 Examples 目录中的php文件注释, 然后在 json_docs 目录下生成 swagger.json 文件.
这个 swagger.json 文件就是前端 swagger-ui 用来展示的我们的api文档文件.
NOTE: swagger-php 只是个工具,放在哪里都可以.

前端 swagger-ui 部署:

部署方法很简单,就三步:

1. 将 swagger-ui 项目中的 dist 文件夹拷贝到 php_rest_api 根目录下.

NOTE1: 只需要拷贝dist这一个文件夹就可以了.最好重命名下,简单起见,这里不再重命名.
NOTE2: 我们的项目根目录和 nginx 配置的 root 是同一个目录.其实不用放跟目录,只要放到一个不用跨域就跨域访问的目录就可以了. 为啥有跨域问题? 后面会讲.

2. 修改 dist 文件夹下的 index.html 文件,指定 swagger.json 所在目录

只改一行就可以.
简单起见,这里直接将 swagger.json 目录指定在 dist 目录下即可. 我们这里屡一下预设条件:
假设 php_api_project 项目的 host 是 api.my_project.com;
假设 php_api_project 项目在 nginx 中指定的 root 即为其根目录;
假设 swagger-ui 里的 dist 文件夹放在上述根目录中;
假设 swagger.json 文件就打算放在上述 dist 目录下 (php_api_project/dist/swagger.json) ;
那么 index.html 中把下面的片段改成这样:

      var url = window.location.search.match(/url=([^&]+)/);
      if (url && url.length > 1) {
        url = decodeURIComponent(url[1]);
      } else {
        <!-- 就是这行,改成你生成的 swagger.json 可以被访问到的路径即可 -->
        url = "http://api.my_project.com/dist/swagger.json";
      }

3. 拷贝 swagger.json 到上述目录中.

# 把 swagger-php_dir 这个,换成你的 swagger-php 录即可
cp swagger-php_dir/json_docs/swagger.json php_api_project/dist/

上述步骤完成后, 访问 http://api.my_project.com/dist/index.html 就可以看到 Examples 那个小项目的 api 文档了.

编写 PHP 注释:

swagger-php 项目的 Example 中已经有了很多相关例子,照着复制粘贴就可以了.
更具体的相关注释规则的文档,看这里:
http://bfanger.nl/swagger-explained/#/swaggerObject

假设我的项目 controller 所在目录为 php_api_project/controller/, 那么我只需要扫描这个目录就可以了,不用扫描整个 php 工程.
为了在 swagger.json 中生成某些统一的配置, 建立 php_api_project/controller/swagger 目录. 目录存放一个没有代码的php文件,里面只写注释.
我给这个文件取名叫 Swagger.php, 大体内容如下:

<?php

/**
 * @SWG\Swagger(
 *   schemes={"http"},
 *   host="api.my_project.com",
 *   consumes={"multipart/form-data"},
 *   produces={"application/json"},
 *   @SWG\Info(
 *     version="2.3",
 *     title="my project doc",
 *     description="my project 接口文档, V2-3.<br>
以后大家就在这里愉快的对接口把!<br>
以后大家就在这里愉快的对接口把!<br>
以后大家就在这里愉快的对接口把!<br>
"
 *   ),
 *
 *   @SWG\Tag(
 *     name="User",
 *     description="用户操作",
 *   ),
 *
 *   @SWG\Tag(
 *     name="MainPage",
 *     description="首页模块",
 *   ),
 *
 *   @SWG\Tag(
 *     name="News",
 *     description="新闻资讯",
 *   ),
 *
 *   @SWG\Tag(
 *     name="Misc",
 *     description="其他接口",
 *   ),
 * )
 */

如上所示,我的这个php文件一行php代码也没有,就只有注释,为了定义一些全局的swagger设置:
schemes: 使用协议 (可以填多种协议)
host: 项目地址, 这个地址会作为每个接口的 url base ,拼接起来一期作为访问地址
consumes: 接口默认接收的MIME类型, 我的例子中的 formData 对应post表单类型. 注意这是项目默认值,在单个接口注释里可以复写这个值.
produces: 接口默认的回复MIME类型. api接口用的比较多的就是 application/json 和 application/xml.
@SWG\Info: 这个里面填写的东西,会放在文档的最开头,用作文档说明.
@SWG\Tag: tag是用来给文档分类的,name字段必须唯一.某个接口可以指定多个tag,那它就会出现在多组分类中. tag也可以不用在这里预先定义就可以使用,但那样就没有描述了. 多说无益,稍微用用就啥都明白了.

然后就是给每个接口编写 swagger 格式的注释了.还是举个栗子吧:

    /**
     * @SWG\Post(path="/user/login", tags={"User"},
     *   summary="登录接口(用户名+密码)",
     *   description="用户登录接口,账号可为 用户名 或 手机号. 参考(这个会在页面产生一个可跳转的链接: [用户登录注意事项](http://blog.csdn.net/liuxu0703/)",
     *   @SWG\Parameter(name="userName", type="string", required=true, in="formData",
     *     description="登录用户名/手机号"
     *   ),
     *   @SWG\Parameter(name="password", type="string", required=true, in="formData",
     *     description="登录密码"
     *   ),
     *   @SWG\Parameter(name="image_list", type="string", required=true, in="formData",
     *     @SWG\Schema(type="array", @SWG\Items(ref="#/definitions/Image")),
     *     description="用户相册. 好吧,没人会在登录时要求填一堆图片信息.这里是为了示例 带结构的数据, @SWG\Schema ,这个结构需要另行定义,下面会讲."
     *   ),
     *   @SWG\Parameter(name="video", type="string", required=true, in="formData",
     *     @SWG\Schema(ref="#/definitions/Video"),
     *     description="用户 呃... 视频? 同上,为了示例 @SWG\Schema ."
     *   ),
     *   @SWG\Parameter(name="client_type", type="integer", required=false, in="formData",
     *     description="调用此接口的客户端类型: 1-Android, 2-IOS. 非必填,所以 required 写了 false"
     *   ),
     *   @SWG\Parameter(name="gender", type="integer", required=false, in="formData",
     *     default="1",
     *     description="性别: 1-男; 2-女. 注意这个参数的default上写的不是参数默认值,而是默认会被填写在swagger页面上的值,为的是方便用swagger就地访问该接口."
     *   ),
     * )
     */
    public function loginAction() {
        // php code
    } 

    /**
     * @SWG\Get(path="/User/myWebPage", tags={"User"},
     *   produces={"text/html"},
     *   summary="用户的个人网页",
     *   description="这不是个api接口,这个返回一个页面,所以 produces 写了 text/html",
     *   @SWG\Parameter(name="userId", type="integer", required=true, in="query"),
     *   @SWG\Parameter(name="userToken", type="string", required=true, in="query",
     *     description="用户令牌",
     *   ),
     * )
     */
    public function myWebPageAction(){
        // php code
    }

规则简单明了,看着代码大家就都懂了.不懂的话,去看文档吧...
上面 login 接口中用到了两个有结构的数据, 一个是 image 类型的数组, 一个是 video 类型的结构.
(其实结构化的参数只能在 in="body" 时才可以用,但这并不妨碍我们为了简化问题,把结构化数据格式化为 json 当字符串传递. 我们只要将这种结构展现在文档里就可以了)
这种有结构的东西 swagger 也可以用 php 注释定义:

<?php

/**
 * @SWG\Definition(type="object", @SWG\Xml(name="Image"))
 */
class Image {

    /**
     * @SWG\Property()
     * @var string
     */
    public $url;
    
    /**
     * @SWG\Property(format="int32")
     * @var int
     */
    public $height;
    
    /**
     * @SWG\Property(format="int32")
     * @var int
     */
    public $width;

}

<?php

/**
 * @SWG\Definition(type="object", @SWG\Xml(name="Video"))
 */
class Video {

    /**
     * @SWG\Property()
     * @var string
     */
    public $url;

    /**
     * @SWG\Property()
     * @var string
     */
    public $thumb_url;

    /**
     * @SWG\Property(format="int32")
     * @var int
     */
    public $length;

    /**
     * @SWG\Property(format="int64")
     * @var int
     */
    public $size;

}

这样当这两个类也被 swagger-php/bin/swagger 扫描到后,其他地方就可以正确引用到 Image 和 Video 为名字的这两个结构体了.
这样做的好处是,在接口参数文档中,这个结构会被展示出来,这样客户端同学就知道该传什么结构了.

我的接口栗子里都没有写 response 规则,是因为我们用 json 作为返回载体,返回错误码也是包含在这个 json 结构体里. 并且多数接口返回的json格式都很复杂,用 swagger 的 response 规则基本没法描述.
swagger 的 response 编写规则是按照 http 的 response code 来的 (404, 401 等), 总之对我们的接口来说,这套描述规则不好用.
因此我就直接舍弃了 response 描述, 直接用 swagger 就地请求接口看看返回了什么就是. 再不行就把接口的返回信息在 description 里大体描述一下.

文档写完后,就可以调用 swagger-php/bin/swagger 命令生成 swagger.json, 再拷贝到 swagger-ui 中你指定的那个目录中,就可以访问文档了.

NOTE:
大家应该已经看出来了,其实接口的注释不一定要写在接口上,凭空写注释,一样能生成文档.所以不必纠结各个注释放在什么地方. 比如 swagger 整体定义, tag 定义等,写在任意可以被扫描到的 php 文件中就可以了.

常用字段简要说明:

这里只是自己理解加翻译的简要说明,更详细的字段说明,还是要去看文档.再次贴出文档:
http://bfanger.nl/swagger-explained/#/swaggerObject

接口描述 (@SWG\Get, @SWG\Post 等) 常用字段:

summary - string
接口的简要介绍,会显示在接口标头上,不能超过120个字符

description - string
接口的详细介绍

externalDocs - string
外部文档链接

operationId - string
全局唯一的接口标识

consumes - [string]
接口接收的MIME类型

produces - [string]
接口返回的MIME类型,如 application/json

schemes -   [string]
接口所支持的协议,取值仅限: "http", "https", "ws", "wss"

parameters -    [Parameter Object | Reference Object]
参数列表

参数描述 (@SWG\Parameter) 常用字段:

name - string
参数名. 通过路径传参(in 取值 "path")时有注意事项,没用到,懒得看了...

in - string
参数从何处来. 必填. 取值仅限: "query", "header", "path", "formData", "body"

description - string
参数描述. 最好别太长

type - string
参数类型. 取值仅限: "string", "number", "integer", "boolean", "array", "file"

required - boolean
参数是否必须. 通过路径传参(in 取值 "path")时必须为 true.

default - *
默认值. 在你打算把参数通过 path 传递时规矩挺多,我没用到.用到的同学自己看文档吧.

遇到的问题:

跨域问题:

swagger 牛X的地方就是它可以在文档上就地访问接口并展示输出,对于调试和对接口非常的方便.但如果不想将 swagger-ui 部署在接口项目下,那么在 swagger-ui 就地访问接口时,就会因跨域问题而请求不到结果. (Response Headers: no response from server; Response Body: no content).
这里不讲跨域问题怎么解决,只是给遇到上面的问题的各位一个思路,知道错误是由跨域产生的,就好解决了.

登录鉴权:

如果要将文档放在公网,直接暴露自己的接口可不太合适. 因此要给文档的访问地址做鉴权.
因为安全性要求不高,并且公司较小开发组人员不多,我就直接用了 nginx 提供的 http basic auth 做了登录鉴权.
老规矩,先贴官方文档:
https://www.nginx.com/resources/admin-guide/restricting-access-auth-basic/
这样做鉴权很简单,分分钟搞定. 不详述, 就两步:

1. 首先用 htpasswd 命令,为需要访问文档的同学生成帐号名和密码:

$ htpasswd -cb your/path/to/api_project_accounts.db admin password_for_admin
$ htpasswd -b your/path/to/api_project_accounts.db liuxu 123456
$ htpasswd your/path/to/api_project_accounts.db xiaoming

-c 选项表示如果账号文件 ( api_project_accounts.db ) 不存在,则新建之. 因此创建第一个账号时一定要加 -c, 之后创建则一定不要再加 -c.
-b 参数表示明文指定密码,就是上面第一条和第二条命令中最后一个输入 (password_for_admin, 123456) . 因此如果不想明文指定,可以不加 -b, 像上面的第三条命令,就会和sudo命令一样,让你输入一段看不见的密码.
上面命令创建了三个账号, admin, liuxu, xiaoming, 并将账号密码保存在 api_project_accounts.db 文件中.

2. 然后在 nginx 的项目配置中给自己的这个访问地址开启 http basic auth 就可以了.

location /dist {
    auth_basic              "my api project login";
    auth_basic_user_file    your/path/to/api_project_accounts.db;
}

记得改完了重启 nginx:

nginx -s reload

这样一个简单的登录鉴权就建立起来了.

NOTE:
如果系统里没有 htpass 这个命令, 可以安装 apache 的 httpd 服务器软件, htpass 这个命令就包含在其中:

yum install httpd

参考:

[1] swagger 官网
[2] swagger 项目地址
[3] swagger ui 项目地址
[4] swagger php 项目地址
[5] swagger 文档参考地址

来源：https://www.jianshu.com/p/1a1ef251301d

评论

发表评论

此博客中的热门博文

近期折腾 tailscale 的一些心得

发布于
一、我的需求 最近自己装了一台高配台式机，打算当作自己的主力机器使用，笔记本电脑就作为一个移动 UI，工作都远程连到家里台式机使用。 为了满足这个需求，就需要 NAT 穿透，正好最近 mesh vpn 的概念很火，又看到 tailscale 正好对个人用户免费，于是就想试试看了。 二、TailScale 是什么 VPN 是什么？ 虽然国人看到 VPN 第一反应应该是“翻墙”，但 VPN 最初应该也是最普遍的用途应该是用来做内网打通， 这也是其名字虚拟私有网络的用意，VPN 让你可以在公开的网络线路上建立一个私有的子网， 然后将所有接入的机器都分配一个私有的内网地址，让他们可以通过 VPN 的私有网络互联。 比如最常见的需求就是，公司有一个内网办公环境，当你外出办公时，也希望你的电脑能够接入办公网络。 因为外网的机器和内网的机器不能互联，所以一般会有一个中心服务器， 所有的子节点都和中心服务器相连，然后中心服务器转发所有的流量。 这样做的缺点显而易见，首先是中心服务器（hub）会成为瓶颈。 其次，某种极端情况下，如果节点 A 和 节点 B 距离非常近，但是都离 hub 很远， 这样就会导致非常高的延迟。 那么我们就会想，能不能让节点间直接互联呢？ 这就是 mesh VPN，其实现就是 wireguard。 wireguard 的每一个节点都会存储其他所有节点的信息，并且和其他所有的节点都建立 tls 连接。 如果涉及到内网穿透的话，那么你需要找到一台处于网关位置的节点（内外网都可达），将其设置为 coordinator， 扮演类似于 hub 的角色， 分发穿透内外网的流量。 wireguard 的缺点在于： 配置比较繁琐 维护也比较困难，增删节点都需要改动所有节点的配置 基于上述这些痛点，tailscale 做了一些改进： 在原有的 ICE、STUN 等 UDP 协议外，实现了 DERP TCP 协议来实现 NAT 穿透 基于公网的 coordinator 服务器下发 ACL 和配置，实现节点动态更新 通过第三方（如 Google） SSO 服务生成用户和私钥，实现身份认证 简而言之，我们可以认为 tailscale 是更为易用版的、功能封装更为完善的 wireguard。 三、TailScale 能做到什么 只要你的机器可以连到公网，tailscale 可以让所有的...
阅读全文

高可用用户中心设计

发布于
概述 我们公司现在的账户体系比较混乱，每个系统都有一套自己的账户体系，没有办法进行统一的账户管理，比如统计一个人在哪个系统有账号，这样操作是比较麻烦的，还有就是我们如何进行用户行为分析，最终综合用户的信息进行用户的画像。这些都是需要解决的问题。 常规的用户设计是统一账号和统一登录验证，统一注册等信息。但是结合我们公司的实际，发现这样的话我们的系统可能会出问题，我们无法屏蔽很多细节。我们的现状是： 系统需要向用户隐藏是同一个公司的这个事实。也就是说我们做了用户中心的设计，但是不能让用户感知这个系统的存在。也就是说多个系统之间的登录都是需要隔离的。离论上不能做统一账号的登录，但是可以做统一账号的验证。 同一个系统可能有多个马甲app，我想马甲app之间也需要登录隔离，虽然他们调用的是同一个后台系统，那么我们不得不面对一个问题，同一个用户同时下单的逻辑处理，需要后台做这种处理，否则就会出现严重的并发错误，而开发人员可能都没有注意到这个事实的存在，从而导致一些稀奇古怪的事情出现。 web端与app端应该是需要同时登录的，我们好像没有web的要求，但是好像有微信的web端的事情。假如我们有web端的登录，那么问题来了，我们要不要实现二维码登录web。目前看是可以先不实现的，但是作为设计考量我们不得不考虑这些。 第三方账户的登录，我们是通过手机号作为唯一标识，那么不太好实现第三方的登录注册。但是我们可以后期实现，如果实现第三方的登录注册，那么问题来了，我们的设计貌似不支持，需要改动，就是改掉手机作为唯一标识的问题，但是想想好像是不影响的，只要数据能插入问题就不大，因为没有手机号，这些用户是不能登录需要手机的app，但是有的系统可以做特殊处理，从而支持第三方账户的登录注册。但是这样做也有缺点，就是用户利用多种方式进行注册，也就是说我们不得不解决一个问题就是用户可能存在多个账户的可能性。加入用户有微信注册的账户，然后又用手机登录，绑定微信，这个时候我们可能需要去系统中用微信的unionId或者openId查找一下是否有用户，有就不能绑定，没有才能绑定。如果有我们可能也知道了这个人有重复号的可能性。这个可能需要在做的时候处理。 验证保密问题，公司居然都没有人提到这点。不过也对我们是通过手机号进行验证的。但是如果以后我们不在使用手机号，可能我们需要验证问题。还需要判断用户的活动记录...
阅读全文

群晖硬软件的的各种坑及解决方案

发布于
  适用对象：   白群晖用户，不愿意折腾，对数据敏感性较强（装了很多家庭照片，文件，宝贵的**姐们）； 不适用对象： 黑群用户，有些问题会涉及到硬件，由于黑群配置差异极大，很难找到原因；关于硬件推荐：本人与群晖无任何商业联系，因此不在此帖推荐任何硬件，只是以个人角度说一下使用过硬件的一些优缺点； 最后更新日期： 2021 年 9 月 2 日 （DSM 7.0 , 以群晖的牙膏性，这篇文章应该在未来2年都不会过时）； 不折腾玩转群晖NAS的通用建议： 用企业级硬盘： 多花点钱买企业级硬盘，现在10-16T的企业级硬盘价格真的不贵，耐心搜索本版帖子就能找到靠谱商家的合适价格（2021 年9月差不多120块钱1T）。既然是用白群了，那就要知道群晖的是根据盘位费卖硬件的，尽量不要用普通硬盘，尤其是淘汰下来的N 年旧硬盘做 NAS，问题多多，每月都有人求助群晖“存储空间损毁”的问题。另外，NAS 盘，除了对静音有极致要求，现在也不推荐，不仅价格贵，性能低、还吃了好多亏（SMR红盘坏了好几块）。 加内存是性价比最高的性能提升方式： 群晖有一篇非常冷门的 文章 ，提到了RAID/网络/内存对性能的影响，简单的总结就是，8G->16G内存，性能可以提升 30%以上，16G->32G内存，写性能还能提升 30%。当然这个测试都是基于“旗舰级”硬件测试的，但对于家用机，200多块钱的内存升级仍是最有效的性能提升方式，推荐大家无脑堆到支持内存的上限。 RAID不是数据保险箱： **姐有价，数据无价，如果真的想要保护数据，仅靠NAS是不够的，RAID而是用来保证某硬盘损坏时候依然能提供相关服务，而不是用来保证数据不丢的。为了数据安全，切记使用 “3-2-1”法则 保证数据安全。否则接收开盘数据恢复价格1T=1k； 群晖机器的性价比计算方式是价格/盘位： 群晖各阶机型CPU性能差异不太明显，但后期扩充盘位费极贵。因此简单计算性价比的方式就是价格/盘位，从而能比较出 2、4、5、6、8 盘位机器的性价比。注意只关注主机有多少个盘位，不要把扩展 DX517 这种算进去，大部分家庭用户很难再去买一个 DX517 用于扩容，所以不要想着买两盘位的720+，想着未来在买一个 DX517做成7盘位，应该直接买1621+直接上到 6盘位。...
阅读全文

打造一个可国内访问的Blogger（Blogspot）方法

发布于
  Blog‍‌‍‌​‌‌‌‌​‌​‍‌​‍‌‍‍​‌‌‍‌​‌‍​‍‌​​‍‌‌‌​‌‍‌‌​‍‍‍​‍‍‌​​‍‌‍‌​‍‌‍‍​‌‌‍‌​‌‍​‍‌​​‍​‍‍‍​‌‍‍‌ger,一个干爽、免费的博客发布平台，作为主流的发布，提供免费的托管，免去了Typecho&Wordpress高昂的服务器费用，避免了Hexo&Jekyll静态博客无后台的缺陷，与CSDN、简书相比，可以绑定域名，界面干净，无广告【当然可以自己放自己的广告】。 实际上，当今写博客的软件数不胜数，主要分为一下三类： 服务器部署：典型代表：Wordpress\Typecho 无服务器托管：典型代表：Hexo\Jekyll\Gidea\Hugo\Hola等等 集成型网站：Blogger、简书、CSDN、cnblog、wodemo等等 上面所有软件，优缺点都有，具体看个人选择 当然，个人认为Typecho适合做个人博客，Hexo可以作为要求不高的人。集成性网站最主要的是只要安安心心写文章，不用管后端乱七八糟的代码。当然，最有问题的是大多数都不支持绑定域名，而且经常往网站上塞广告，自定义范围也不够。 接下来，我们扯扯集成博客中的一股清流：Blogger Blogger.com是由Pyra Labs公司创立，是目前全球用户数量最多的个人网志服务提供商。Pyra Labs和Blogger.com均被Google公司收购，成为其旗下的一项服务内容。 Blogger提供免费主机Blogspot.com存放博客，用户不必写任何代码或者安装服务器软件或脚本，通过所见即所得界面轻松地创建、发布、维护和修改自己的网志。 Blogger允许有经验的用户自行设计博客界面，其模板支持使用HTML和CSS进行编辑 实际上，由于Blogger托管于谷歌，写作域名  www.blogger.com  和托管域名  *.blogspot.com  均被MainLand所Ban。但是接下来来，我会讲讲如何打造一个能在国内大陆访问的Blogger 1. 注册Blogger 众所周知，请善用技术上网。 用谷歌账号登录 ( https://www.blogger.com ) ，没有？不是⑧不是吧不是扒，都0202年了，还不会去注册一个谷歌账号？ 进入控制台，新建一个博客： 绑...
阅读全文

星际蜗牛安装黑裙（群晖）制作家用nas

发布于
说重点，群晖安装 选哪个型号哪个版本呢？ 之前用的5.2版本功能不够多，docker装上去运行个迅雷，隔一段时间就卡死了。download station里的rss订阅时间长了也更新不了。同时考虑到同步办公文件，这次得找个稳定的版本安装。 网上流传一个ds3617的二合一版本，正好可以安装到固态上。装完以后开机显示的画面有乱码 ，虽然乱码不影响使用，可总感觉不够稳定，再加上第一次插上硬盘以后重启了下，发现硬盘损毁，更不敢用了。（现在回过头来发现，应该是我插上去的那块硬盘是从别的nas上拆下来的，系统不识别造成的吧 ） nas论坛上走一遭发现还是乖乖用优盘引导安装吧。 网上最多的是918、916、3617、3615四种型号，群晖版本一般是6.1.7、6.2、6.2.1，选来选去选了6.1.7版本的3615，网友说这个版本稳定运行几年了。希望它稳定运行到天荒地老 小白注解 ： 群晖安装文件分两部分，引导文件和系统安装文件，黑群晖为啥黑就是引导文件是大神破解的。系统安装文件都是官方的，不用修改。 软件下载 逛坛子发现有两个好东西，一个是XPEnology多功能工具箱V1.2，软件长这样，首页就是引导文件 第二页是系统安装文件 需要用到的工具也都集成在里面了， 但是我从这里面下载下来的引导文件解压不了。于是找到了第二个神器——黑群晖工具获取器。 打开软件点下加载，然后依次选择型号，版本就全出来了。这里面也带了工具软件，不过我没用。用黑群晖工具获取器下引导文件挺快的，浏览器下载就行，但是系统安装文件就不行了，没速度 ，换迅雷就OK了。 我把引导文件、系统安装文件还有其他工具软件一起放网盘里，大家可以直接下载。 所有文件我都是上传的压缩包，解压以后使用 。 百度网盘链接 : 提取码:sle3 工具准备 一台电脑，一个独立的 显示器 、显示器与NAS的连接线，usb接口键盘。 上面的安装的时候需要，安装完就不用了。 找个闲置的64m优盘，没有的话大一点也可以，就是浪费容量而已。这个优盘以后一直要插nas上了 你们准备完了吗？ OK，正式开始折腾 制作引导优盘 大致流程是 先记录优盘VID和PID 删除原优盘分区， 往优盘上写引导文件 修改引导文件。 首先，拿出64m的优盘，插电脑上，打开XPEnology多功能工具箱，去制作工具栏里找到ChipGenius， 打开，我装了360，...
阅读全文

Cloudflare免费版设置说明

发布于
一：域名接入 Cloudflare 这一步其实能说的不是很多，因为我已经添加过域名了，也不好意思随便加别人的域名来测试，所以就只跟大家简单的说说吧。 注册账号之后先把自己想接入 CDN 的域名添加好，然后应该会有 Cloudflare 的提示，告诉你要把域名的 NS 记录改成 Cloudflare 的： NS 记录的修改需要到你的域名注册商那边改，这个根据各商家面板的不同可能设置上稍有差异，请自行查找。域名注册商那边改好之后，应该在 Cloudflare 这边刷新一下就能看到已经帮你添加好的各种记录了，默认支持 CDN 的也已经帮你开启了 CDN 功能，如果没有，就自己按照原来的记录重新添加一份，然后最重要的把 A AAAA 记录这种开启 CDN 功能。 此处提一下，不知道大家知不知道 NS 记录的用途？当我们改成 Cloudflare 的 NS 之后，其实以后我们就不需要到域名注册商那边去添加各种 A AAAA 记录了，全部都在 Cloudflare 这边完成，因为已经被接管了。 另外请注意，域名接入的说明是针对免费版 Cloudflare 来说的，用的合作伙伴那种接入方法的我这里就不说了，一般人家面板上会告诉你怎么操作（其实也就是绑定下域名到域名注册商那边改一下 A AAAA 记录之类的）。 二：后台概览页面介绍 在正式给大家说明各类设置项之前，我们先来看看 Cloudflare 的概览界面： 上面那一排排的按钮就是各种设置项了，第一项就是概览。 概览页面可以看到一些常规的 CDN 缓存数据大小还有命中率什么的，页面左边是一些功能的快捷开关，方便我们平时有需要时随时开随时关，翻译已给大家奉上。 概览按钮后面接的是 Analytics 功能，主要是用来展示一些详细的统计数据之类的，因为基本不含设置项，而且与本文标题不太相关，所以就不多介绍直接跳过了。 三：DNS 设置 防止有些人还找不到我说的是什么设置项，我就直接上图说了： 标的框框这里是让你快速添加各种主机记录用的，后面的图标亮着代表开启 CDN 功能，不想开就手动点一下关闭就是了。 关于 DNS 的设置部分，因为主要就是各种记录的添加，所以没什么好说的，只需要注意给你要开启 CDN 的域名添加正确的记录就是了，记录的设置和在原来域...
阅读全文

N1 PT下载小钢炮固件下载及安装说明

发布于
Nano Disk Manager (NanoDM) 公测版由于功能尚未最终稳定。因此，更新会比较频繁。 强烈建议使用0411之后的版本, 不要再去下载0909版本了... 0909版本的任何问题或bug都不予处理. FAQ 缓存问题 (此问题仅存在于0909及之前的老固件): 如果你进某个页面总是跳回登录页面,或者直接没有显示任何东西 ，浏览器返回的是该页无法显示。 chrome浏览器缓存问题。 ctrl + shift + i , 然后右击浏览器顶部地址栏的刷新按钮， 选择第三项：“清空缓存并硬性重新加载”， 即可。 更多FAQ见： https://gitee.com/8ox86/phicomm-n1-issue 下载地址： https://rom.nanodm.net/N1/ ==================================================================================== 从n1原版android系统刷机操作步骤 1.有一个N1,准备个U盘. 不要太大，U盘大于512M即可. usb 2.0的最佳。 闪迪（SanDisk）酷豆（CZ33）16GB 或 8GB的测试通过，表现良好。lexar 8GB USB2.0 U盘表现更佳。 经测试，上次撸的台电（Teclast）锋芒 U盘 64G USB3.0很大概率上识别会有问题。 下载 phicomm-n1-s905-linux-hacklog-20190327-0136.img.7z , 用 7z 或 winrar 解压后,再校验img文件的md5. 注意校验md5 phicomm-n1-s905-linux-hacklog-20190327-0136.md5sum.txt 将镜像文件 phicomm-n1-s905-linux-hacklog-20190327-0136.img 通过工具写入U盘 (windows下可用 USB Image Tool 或etcher[ https://etcher.io]， linux gnome3环境下可直接用Disks工具写入) 关于img写入 推荐使用 usb-image-tool 写入 其它工具没有测试过.不保证其工作正常. 如果你下载的是一个.xz的...
阅读全文

分析redis key大小的几种方法

发布于
当redis被用作缓存时，有时我们希望了解key的大小分布，或者想知道哪些key占的空间比较大。本文提供了几种方法。 一. bigKeys 这是redis-cli自带的一个命令。对整个redis进行扫描，寻找较大的key。例： redis-cli -h b.redis -p 1959 --bigkeys 输出： # Scanning the entire keyspace to find biggest keys as well as # average sizes per key type. You can use -i 0.1 to sleep 0.1 sec # per 100 SCAN commands (not usually needed). [00.00%] Biggest hash found so far 's_9329222' with 3 fields [00.00%] Biggest string found so far 'url_http://mini.eastday.com/mobile/170722090206890.html?qid=sgllq&ch=east_sogou_push&pushid=13' with 8 bytes [00.00%] Biggest string found so far 'foo' with 40 bytes [00.00%] Biggest hash found so far 's_9329084' with 4 fields [00.23%] Biggest zset found so far 'region_hot_菏泽地' with 625 members [00.23%] Biggest zset found so far 'region_hot_葫芦岛' with 914 members [00.47%] Biggest string found so far 'top_notice_list' with 135193 bytes [00.73%] ...
阅读全文

Windows7系统目录迁移:Users,Program Files,ProgramData

发布于
微软设计了比如：我的文档、我的OOXX，之类的东西，在WIN7下面更连游戏、下载等等目录都设计好了，我也很乖巧的把各种文件都分门别类的放进去了。 同时也很厉害的设计在了“%HOMEDRIVE%”里面，各种的资料，这种软件的配置就全给放进去了 在XP的时候对于C盘的要求还不是那么大，但是在win7下就显的捉襟见肘了 再格式化，重装系统就全没了，囧，就也是必须移动出来的第二个理由 以前只是自己挪挪地儿，小改一下注册表，今天无意中参考了几篇文章，那搞的才是个全面啊，在膜拜只后就全给做笔记了，忽忽，先上牛人原文的 传送门 首先，不管你要怎么挪，请记住挪坏了我不会负责。其次，确定系统是刚刚安装好的，这样比较不会出现意外，也更有效优化，确定是用Administrator 登录。 移动Program Files目录到非系统盘 第一步，复制 Program Files 目录 不能直接用 资源管理器 复制，我们需要保留此目录的所有权限设置，（以前我就是直接在资源管理器面弄到，现在严重怀疑，我的机器时不时的抽风是不是和这个有关）假设要从C 盘移动到 D 盘： xcopy "C:\Program Files" "D:\Program Files\" /E /H /K /X /Y/C 第二步，修改注册表 Windows Registry Editor Version 5.00 [ HKEY_LOCAL_MACHINE \SOFTWARE\Microsoft\Windows\CurrentVersion ] "ProgramFilesDir" = "D:\\ProgramFiles" "CommonFilesDir" = "D:\\ProgramFiles\\Common Files" 第三步，重启 注意不是注销，因为 Program Files 里有很多文件是被系统服务使用的，注销并不能重启服务。 第四步，关闭 iphlpsvc 服务 因为它...
阅读全文

个性化推荐从入门到精通

发布于
今天的分享将为大家解答以下几个问题：你的公司是否适合采用个性化推荐？如果需要个性化推荐，该如何做好？产品运营在参与到一个推荐系统的构建当中，有哪些常见的坑？有哪些可以避开这些坑的一些简单方法？以及如何修炼成一个优秀的推荐产品经理？ 一、“四个关键”为你揭开推荐系统的神秘面纱 个人认为，推荐系统是根据用户以及不同的场景差异，对信息进行合理的排序、过滤，解决信息过载问题的一套机制。这个定义中包含四个关键点，如下： 1.“根据用户以及不同的场景差异” 对于很多刚开始做推荐的人可能会忽略这一点，大部分人在思考推荐时想的更多的可能是基于用户来做，但其实我从众多实践中发现，很多时候推荐产生价值不仅仅只是说以用户进行区分，相关场景的差异会对于最后推荐效果产生巨大的影响。 2.“推荐的本质是对信息进行合理的排序、过滤” 很多人认为推荐是一个魔盒，非常神奇，其实究其本质是企业有成千上万甚至上亿的 item，不管这些 item 是文章、视频，还是电商里面的商品，然后现在有某个人在一个具体的场景里面，企业需要把这些 item 给他看，那应该把哪个放在第一个？这就是推荐系统背后的运作原理。 3. “推荐系统要解决信息过载的问题” 举个例子，如果你的企业只做爆款商品，整个公司只卖两个商品，这样用户一看就明白了，显然也不需要推荐，所以做推荐的一个前提条件是你公司本身提供的业务里面的信息太多了，对于一个正常的自然人来说，他处理不了那么多信息的时候，企业才需要去帮助用户解决信息过载的问题，从而为用户设计这样一套机制。 4.“一套机制” 这点很好理解，推荐系统是由不同的算法、规则等构成的一套机制。这四点是我从产品视角为你解读了什么是推荐系统，以及他的一些简单作用。 二、推荐系统、广告系统、搜索系统三者有何不同？ 事实上，解决我在前面提到的一系列问题，推荐系统并不是唯一的方法。 比如，前面所提到的排序、过滤，做技术的同学应该很容易联想到，搜索和广告系统也涉及排序、过滤，且搜索也一定程度上解决了信息过载。那么，这三个系统，它到底有什么区别呢？ 我从 5 个方面对其进行了对比，下面将一一讲述： 1. 用户获取信息的方式。 广告与推荐系统，用户都是被动的，但搜索不一样，用户是主动搜索的，他需要输入一些关键词，会加入一些自己的意见和重点。 2. 点击率要求。 这三个系统...
阅读全文