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

发表于 2020-02-07 分类于闭门造车阅读次数： Disqus：

前言

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

Microsoft Azure介绍

何为云计算

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

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

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

cotton-cloud

Azure介绍

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

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

azure-introduction

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的官方指导初始化并预览网站，主要包括以下步骤：

安装docsify工具，方便构建及本地预览
1
npm i docsify-cli -g
在项目的./docs目录下初始化项目
1
docsify init ./docs
在初始化之口，可以在./docs下看到如下内容：
1
2
3
4
docs/
├── .nojekyll
├── README.md
└── index.html
后续都在./docs下编辑markdown文件。

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

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

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

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

docsify-structure

Azure部署docsify文档站点

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

准备工作：
- 准备一个Azure的试用账户或者订阅；
- 将docsify的项目同步到Git服务器上。
启动Azure CLI工具，看到一个命令行界面，我们可以把这个理解为云端某个服务器的界面。
在命令行界面中用git命令把docsify项目克隆到当前目录：
1
git clone https://github.com/Azure-Samples/<你的docsify项目>

创建Web应用

高能预警第一弹：

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

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

然后运行：

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

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

{
  "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. >
}

浏览应用

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

高能预警第2弹

404--a-game

所以不禁要问404算怎么回事？！

添加web.config配置文件

问题出在了这里（已经有人趟过的坑）：

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

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

<configuration>
  <system.webServer>
    <staticContent>
      <remove fileExtension=".md" />
      <mimeMap fileExtension=".md" mimeType="text/markdown" />
    </staticContent>
  </system.webServer>
</configuration>