0%

Windows Azure部署Web应用:以docsify为例

前言

由于工作的需要,也为了紧跟技术发展的趋势(其实已经落后不少 😢 ),这几天在研究云部署、容器、Web服务一类的东西。刚好试着用docsify管理技术文档,就想着可以部署到Azure上去。整个过程回过头来看并不复杂,但是由于这两个东西都是刚刚上手,遇到了一些坑,记录一下折腾的过程。

Microsoft Azure介绍

何为云计算

云计算从概念到尝试再到大规模应用差不多有20年的时间,当然真正突飞猛进也就是最近10年的事情。云计算的介绍,参见各大云计算平台的网站,有兴趣的可以看一下这个视频。

云计算,就是用云来提供各种资源:存储、计算、分析等等各类应用服务……

所以,云就是哆啦A梦的口袋,Azure就是其中一朵。

Azure介绍

Microsoft Azure 是微软的公用云端服务平台,是微软在线服务 (Microsoft Online Services) 的一部分,于2010年2月份正式推出,目前已经成为全球第二大云计算平台。2014年Azure借由世纪互联运营进入中国,不过在国内还是阿里云等国内厂商优势更加明显。

Azure功能十分丰富,感兴趣的可以注册账号,免费试用12个月。接下来,我要介绍的就是其中的Azure应用服务

Azure应用服务介绍

Azure应用服务,是用于托管 Web 应用程序、REST API 和移动后端的服务 。 可以使用 .NET、NET Core、Java、Ruby、Node.js、PHP 或 Python 等偏好的语言进行开发。

应用服务不仅可将 Microsoft Azure 的强大功能(例如安全性、负载均衡、自动缩放和自动管理)添加到应用程序。 还可以利用其 DevOps 功能,例如包管理、过渡环境、自定义域和 SSL 证书。

个人初步体验下来,感觉试用Azure服务的好处是自己不需要开发提供支持的外围服务,从而节约开发和运营成本。

所以,我就将自己用*docsify搭建的技术文档网站部署到了Azure应用服务中。

docsify介绍

docsify 是一个采用markdown + vue 动态生成文档网站的工具。网上提供类似服务的工具/框架有很多,比如Gitbook、Hexo(我的博客用的就是Hexo),但是docsify在功能够用的同时更加方便简洁。简单总结docsify的三个特点如下。

动态解析

这可能是docsify最大的特点,即它不会将 .md 转成 .html 文件,所有转换工作都是在运行时进行,所以维护起来很清爽。(作为对比,Hexo需要我每次写好文章以后,先编译生成静态的html文件)

静态站点

虽然docsify对于markdown的解析是动态的,但是这个解析过程却是在浏览器端完成的,而在服务器端并没有任何动态生成的内容,因此基于docsify构建的文档网站实际上是一个静态站点。

单页应用

从docsify的架构可以看到只有一个HTML页面(index.html),浏览器一开始会加载必需的HTML、CSS和JavaScript,所有的操作都在这张页面上完成,都由JavaScript来控制(包括请求和解析文档内容),因此是一个单页面应用(SinglePage Web Application,SPA)。

一开始没有注意这个特点,结果就折腾了好久。

docsify部署到Azure 应用服务

docsify目录结构

假设我们按照docsify的官方指导初始化并预览网站,主要包括以下步骤:

  1. 安装docsify工具,方便构建及本地预览

    1
    npm i docsify-cli -g
  2. 在项目的./docs目录下初始化项目

    1
    docsify init ./docs

    在初始化之口,可以在./docs下看到如下内容:

    1
    2
    3
    4
    docs/
    ├── .nojekyll
    ├── README.md
    └── index.html

    后续都在./docs下编辑markdown文件。

  3. 本地预览,我们只要起一个Web服务可以访问./docs目录下的资源即可:

    1
    2
    3
    4
    # 法1:使用docsify-cli在docs的父目录运行
    docsify serve docs
    # 法2:在docs目录使用python启动
    cd docs && python -m SimpleHTTPServer 3000

到此为止,这个静态站点就算是建立起来了,只需要部署到Azure即可。

之所以提到这个目录结构,是因为我后面因为不理解静态站点所以绕了弯路。

Azure部署docsify文档站点

既然docsify生成的是一个静态站点,那就应该按照静态HTML站点的方式部署,主要包括以下几个步骤:

  1. 准备工作:

    • 准备一个Azure的试用账户或者订阅;
    • 将docsify的项目同步到Git服务器上。
  2. 启动Azure CLI工具,看到一个命令行界面,我们可以把这个理解为云端某个服务器的界面。

  3. 在命令行界面中用git命令把docsify项目克隆到当前目录:

    1
    git clone https://github.com/Azure-Samples/<你的docsify项目>
  4. 创建Web应用

    高能预警第一弹:

    切换到docsify项目的**./docs**目录而非根目录下!

    p.s. 如果不这么做,可能需要重定向到自定义目录

    然后运行:

    1
    az webapp up --location chinaeast --name <app_name> --html

    这样之后,Azure就自动开始部署并运行这个应用,并会返回类似的json:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    {
    "app_url": "https://<app_name>.chinacloudsites.cn",
    "location": "China East",
    "name": "<app_name>",
    "os": "Windows",
    "resourcegroup": "appsvc_rg_Windows_chinaeast",
    "serverfarm": "appsvc_asp_Windows_chinaeast",
    "sku": "FREE",
    "src_path": "/home/<username>/<docsify项目根目录>/docs ",
    < JSON data removed for brevity. >
    }
  5. 浏览应用

    在浏览器中转到应用 URL:http://.chinacloudsites.cn。然而,你会看到的是:

    高能预警第2弹

所以不禁要问404算怎么回事?!

添加web.config配置文件

问题出在了这里(已经有人趟过的坑):

类似前面我们用docsify-cli或者python启动Web服务,Azure使用自家的IIS提供Web服务,而IIS默认是不会返回markdown文件的。

解决的方法其实很简单,./docs目录下添加IIS所需要的Web.Config,具体内容如下:

1
2
3
4
5
6
7
8
<configuration>
<system.webServer>
<staticContent>
<remove fileExtension=".md" />
<mimeMap fileExtension=".md" mimeType="text/markdown" />
</staticContent>
</system.webServer>
</configuration>

这个时候,才算是成功运行。

Tips:可以用还在预览阶段的“医用服务编辑器”直接在云端进行编辑,然后同步到Git库中,就不用回到本地修改了,再推到Azure了。

添加用户身份验证

docsify构建的站点非常简单,并没有提供身份验证等功能。好在Azure提供了相关的配置,根据微软Azure的技术文档,我们可以比着葫芦画瓢也为docsify的站点添加身份验证。

具体的过程,我就不多说了,因为实在是有点麻烦,而且会出现配置改变后无法保存也没有提示的情况,多试几次熟悉然后习惯就好。

当我们以为大功告成的时候,结果高能预警第3弹来了:

刚刚可以查看的文档,现在无权查看了?摔!

根据错误的log,在网上搜了一下,不是很懂大概的原因是:

我们的站点是一个SPA,也没有后端组件,需要在OAuth 2.0 Implict Flow中使用id-token验证,但是平台默认的身份验证并不提供。

解决的办法就是在“应用注册”里勾选“隐式授权”的ID令牌

具体参见这里:How to fix esponse_type ‘id_token’ is not enabled for the application” error

只有到这里,我们的任务——在Azure上部署docsify文档站点——才算告一段落。

小结

这篇文章主要介绍了如何将docsify生成的静态站点部署到Azure 应用服务,遇到的几个坑分别是:

  • 静态站点实际的根目录
  • Azure IIS的Web.config文件
  • SPA身份验证的ID令牌

作为在云上部署服务的初步尝试,终于还是成功了,虽然有些折腾!

张da统帅 wechat
扫码订阅我的微信公众号
走过路过,切莫错过!