feat(docs): improve README & Deploy

README.zh-CN.md

@@ -21,86 +21,64 @@
 
 # Apache APISIX Dashboard
 
-Apache APISIX Dashboard 项目的目标是为了让大家快速上手体验和学习 Apache APISIX，并不能直接用于生产环境。
+## 介绍
 
-它的功能永远都是 Apache APISIX 的子集，也可能会滞后于 Apache APISIX 的快速迭代。
+Apache APISIX Dashboard 旨在通过前端界面，让用户尽可能更方便地操作 [Apache APISIX](https://github.com/apache/apisix)。
 
-如果你需要把 Apache APISIX Dashboard 项目用于生产系统，需要对用户权限、通讯安全、高可用、高级功能等方面做增强。
+Dashboard 为控制平面，完成所有参数的校验；Apache APISIX 混合了数据平面与控制平面，会逐渐演进为纯粹的数据平面。
 
-## 安装
+本项目包含了 `manager-api` 与前端界面，前者将逐渐替代 Apache APISIX 中的 `admin-api`，我们正在积极地迁移相关逻辑。
 
-提供多种方式来安装 Apache APISIX Dashboard
+注意：目前 Dashboard 尚未完整覆盖 Apache APISIX 的功能，[访问此处](https://github.com/apache/apisix-dashboard/milestones)以查看里程碑。
 
-### Docker
+![architecture](./docs/images/architecture.png)
 
-通过下面的方法来启动一个可运行的版本
+## 目录结构
 
-- [使用 Docker 一键部署](./docs/deploy-with-docker.zh-CN.md)
-
-### 从源代码构建
-
-从源代码构建，首先先确认你的 `golang` 版本在 1.13 或者 更高的版本。
-
-同样你也需要提前安装好 `Node.js` 和 `yarn`。
-
-```sh
-$ git clone -b v2.0 https://github.com/apache/apisix-dashboard.git
-$ cd apisix-dashboard
-$ make build
 ```
-
-然后你可以在 `./output` 目录下找到运行 Apache APISIX Dashboard 需要的所有文件(配置文件、可执行文件、web静态资源)
-
-通过下面的命令启动
-
-```sh
-$ cd ./output
-$ exec ./manager-api
+.
+├── CHANGELOG.md
+├── CHANGELOG.zh-CN.md
+├── CODE_OF_CONDUCT.md
+├── CONTRIBUTING.md
+├── Dockerfile
+├── LICENSE
+├── Makefile
+├── NOTICE
+├── README.md
+├── README.zh-CN.md
+├── api
+├── docs
+├── licenses
+└── web
 ```
 
-`makefile` 提供以下几种命令
+1. `api` 目录用于存放 `manager-api` 源码，它用于管理 `etcd` 并为前端界面提供接口。
+2. `web` 目录用于存放前端源码。
 
-```text
-Makefile rules:
+## 构建并启动
 
-    help:		    Show Makefile rules
-    build:		    Build Apache APISIX Dashboard, it contains web and manager-api
-    api-test:		Run the tests of manager-api
-    api-run:		Run the manager-api
-    api-stop:		stop manager-api
-    go-lint:	    Lint Go source code
-    license-check:	Check Apache APISIX Dashboard Source Codes for Apache License
-```
-
-更详细的构建步骤参见这里 - [从源代码构建](./docs/deploy.zh-CN.md)
+支持以下方式：
 
-### 对于开发者
+- [源码](./docs/deploy.zh-CN.md)
+- [Docker](./docs/deploy-with-docker.zh-CN.md)
 
-Apache APISIX Dashboard 为 [Apache APISIX](https://github.com/apache/apisix) 提供管理界面，需要先[安装 APISIX](https://github.com/apache/apisix#configure-and-installation).
+## 本地开发
 
-然后请参考这里分别启动 `manager-api` 和 `web`
-
-- [开发 Apache APISIX Dashboard](./docs/develop.zh-CN.md)
+请参考[开发指南](./docs/develop.zh-CN.md)
 
 ## 使用指南
 
-请参考 [用户指南](./docs/USER_GUIDE.zh-CN.md)
+请参考[用户指南](./docs/USER_GUIDE.zh-CN.md)
 
-## 里程碑
+## 参与贡献
 
-- [2.0](https://github.com/apache/apisix-dashboard/milestone/4)
-- [2.1](https://github.com/apache/apisix-dashboard/milestone/5)
+请参考[贡献指南](./CONTRIBUTING.md)以获取更详细的流程
 
-## 贡献
+## FAQ
 
-请参考[贡献指南](./CONTRIBUTING.md)以获取更详细的流程。
+请参考 [FAQ 汇总](./docs/FAQ.zh-CN.md)以查看更多已知问题
 
 ## License
 
-Apache License 2.0, [LICENSE](https://github.com/apache/apisix-dashboard/blob/master/LICENSE)
-
-## FAQ
-
-1. 如果你需要 Vue.js 构建的 Apache APISIX Dashboard 1.0，请使用 [master-vue 分支](https://github.com/apache/apisix-dashboard/tree/master-vue)。
-2. 2.0 版本的控制台移除了[1.5 版本](https://github.com/apache/apisix-dashboard/tree/backup-1.5-latest)中的 MySQL，将直接操作 etcd。
-3. 如果你使用 v2.0 以下版本的 Apache APISIX，需要注意 etcd v2 API 的数据与 v3 API 的数据是[不互通的](https://etcd.io/docs/v3.4.0/op-guide/v2-migration/)。Apache APISIX Dashboard v2.0 及以上版本使用 etcd v3 API，apisix 1.5 及以下版本使用 etcd v2 API。
+[Apache License 2.0](./LICENSE)

api/conf/conf.yaml

@@ -17,23 +17,25 @@
 
 conf:
   listen:
-    host: 127.0.0.1          # `manager api` listening ip or host name
-    port: 8080               # `manager api` listening port
+    host: 127.0.0.1 # `manager api` listening ip or host name
+    port: 8080 # `manager api` listening port
   etcd:
-    endpoints:               # supports defining multiple etcd host addresses for an etcd cluster
+    endpoints: # supports defining multiple etcd host addresses for an etcd cluster
       - 127.0.0.1:2379
   log:
     error_log:
-      level: warn                  # supports levels, lower to higher: debug, info, warn, error, panic, fatal
-      file_path: logs/error.log    # supports relative path, absolute path, standard output
-                                   # such as: logs/error.log, /tmp/logs/error.log, /dev/stdout, /dev/stderr
+      level: warn # supports levels, lower to higher: debug, info, warn, error, panic, fatal
+      file_path:
+        logs/error.log # supports relative path, absolute path, standard output
+        # such as: logs/error.log, /tmp/logs/error.log, /dev/stdout, /dev/stderr
 authentication:
-  secret: secret             # secret for jwt token generation.
-                             # *NOTE*: Highly recommended to modify this value to protect `manager api`.
-                             # if it's default value, when `manager api` start , it will generate a random string to replace it.
-  expire_time: 3600          # jwt token expire time, in second
+  secret:
+    secret # secret for jwt token generation.
+    # NOTE: Highly recommended to modify this value to protect `manager api`.
+    # if it's default value, when `manager api` start , it will generate a random string to replace it.
+  expire_time: 3600 # jwt token expire time, in second
   users:
-    - username: admin        # username and password for login `manager api`
+    - username: admin # username and password for login `manager api`
       password: admin
     - username: user
       password: user

api/test/shell/cli_test.sh

@@ -46,7 +46,7 @@ fi
 
 #change level and path
 
-sed -i 's/file_path: logs\/error.log/file_path: .\/error.log/' conf/conf.yaml
+sed -i 's/logs\/error.log/.\/error.log/' conf/conf.yaml
 sed -i 's/warn/info/' conf/conf.yaml
 
 ./manager-api &

docs/examples/docker-conf-example.yaml → docs/FAQ.md

@@ -1,3 +1,4 @@
+<!--
 #
 # Licensed to the Apache Software Foundation (ASF) under one or more
 # contributor license agreements.  See the NOTICE file distributed with
@@ -14,23 +15,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-# PLEASE DO NOT UPDATE THIS FILE!
-# If you want to set the specified configuration value, you can set the new
-# value in the conf/config.yaml file.
-#
+-->
+
+# FAQ
 
-conf:
-  listen:
-    host: 0.0.0.0
-    port: 8080
-  etcd:
-    endpoints:
-      - 127.0.0.1:2379
-authentication:
-  secret: secret
-  expire_time: 3600
-  users:
-    - username: admin
-      password: admin
-    - username: user
-      password: user
+TODO

docs/FAQ.zh-CN.md

@@ -0,0 +1,56 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+# FAQ
+
+### 1. Vue.js 版本的 Dashboard
+
+若您需要 Vue.js 构建的 Apache APISIX Dashboard 1.0，请使用 [master-vue 分支](https://github.com/apache/apisix-dashboard/tree/master-vue)。
+
+### 2. Dashboard 2.0 版本与 1.5 版本有什么差异？
+
+2.0 版本的控制台移除了[1.5 版本](https://github.com/apache/apisix-dashboard/tree/backup-1.5-latest)中的 MySQL，将直接操作 etcd。
+
+### 3. etcd 兼容性问题
+
+若您使用 v2.0 以下版本的 Apache APISIX，需要注意 etcd v2 API 的数据与 v3 API 的数据是[不互通的](https://etcd.io/docs/v3.4.0/op-guide/v2-migration/)。Apache APISIX Dashboard v2.0 及以上版本使用 etcd v3 API，apisix 1.5 及以下版本使用 etcd v2 API。
+
+### 4. 在 Apache APISIX 中修改插件 schema 或创建自定义插件后，为什么在控制台找不到？
+
+由于 Dashboard 缓存了 Apache APISIX 中插件的 jsonschema 数据，因此您在 Apache APISIX 中创建自定义插件后，需要同步 Dashboard 中的数据，当前**仅支持手动操作**，该问题会在后续版本得到优化。如下为操作步骤：
+
+1. 安装 [Lua](https://www.lua.org/download.html) 与 `zip`。
+
+2. 执行如下命令：
+
+```sh
+# `$version` 为 `master` 或者 Apache APISIX 的版本号，如 2.0。
+$ api/build-tools/schema-sync.sh $version
+```
+
+若您有自定义插件，请确保该插件在 `apisix` 目录中，并使用如下命令：
+
+```sh
+$ api/build-tools/schema-sync.sh /path/to/apisix
+
+# 示例：
+$ api/build-tools/schema-sync.sh /usr/local/apisix
+```
+
+命令执行完成后，若您使用的是已经完成构建的二进制 `manager-api`，那么需要手动将 `api/conf/schema.json` 拷贝到 Dashboard **工作目录**下的 `conf` 目录中。其中，**工作目录**是指根据该[文档](./deploy.zh-CN.md)构建完成后，在根目录下生成的 `output` 目录或修改名称后的目录。

docs/deploy-with-docker.zh-CN.md

@@ -17,44 +17,65 @@
 #
 -->
 
-# 使用 Docker 部署
+# 使用 Docker 构建并启动
 
-1. 构建镜像
+使用 Docker 构建 Dashboard，您只需下载**根目录**中的 `Dockerfile` 文件到您的设备（无需下载源码），并根据本指南操作即可。
+
+本构建指南产物中，将包含 `manager-api` 与 `web`。
+
+## 环境准备
+
+在使用 Docker 构建镜像、启动容器前，请确认您的环境中，已安装并运行如下依赖：
+
+1. [Docker](https://docs.docker.com/engine/install/)
+2. [etcd](https://etcd.io/docs/v3.4.0/dl-build/) 3.4.0+
+
+## 构建
 
 ```sh
-# 注意：需手动指定 $tag
-$ docker build -t apisix-dashboard:{$tag} .
+# 在 Dockerfile 所在目录下（默认为项目根目录）执行构建命令，请手动指定 tag。
+$ docker build -t apisix-dashboard:$tag .
+
+# 对于中国大陆的用户，可启用 `ENABLE_PROXY` 参数加快模块下载速度。
+$ docker build -t apisix-dashboard:$tag . --build-arg ENABLE_PROXY=true
 ```
 
-2. 准备配置文件
+## 启动
 
-在启动容器前，需要在**宿主主机**内准备配置文件 `conf.yaml`，以便覆盖容器内部默认的配置文件。请参考[示例配置文件](./examples/docker-conf-example.yaml)。
+1. 准备配置文件
 
-示例配置说明：
+在启动容器前，需要在**宿主主机**内准备配置文件 `conf.yaml`，以便覆盖容器内部默认的[配置文件](../api/conf/conf.yaml)。
 
-- `conf.listen.host` 为容器内监听 IP，必须为 `0.0.0.0`，这样宿主才能访问容器内网络。
-- `conf.listen.port` 为容器内监听端口，默认为 `8080`。如需修改，请同步修改 [Dockerfile](../Dockerfile)。
-- `conf.etcd.endpoints` 为 ETCD 主机列表，支持多个节点，请确保容器可以访问到这些主机，例如：示例配置中 `conf.etcd.endpoints` 为 `host.docker.internal` 旨在允许容器访问宿主主机上的网络。
+配置文件有如下注意事项：
 
-3. 启动容器
+- `conf.listen.host` 为 `0.0.0.0` 时，才能使外部网络访问到容器内的服务。
+- `conf.etcd.endpoints` 必须能够在容器内访问 `etcd` 服务。例如：使用 `host.docker.internal:2379` 以便容器能够访问宿主机网络中的 `etcd`。
+
+2. 启动 Dashboard
 
 ```sh
-$ docker run -d -p 80:8080 -v /path/to/conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml --name apisix-dashboard apisix-dashboard:{$tag}
+# /path/to/conf.yaml 需使用 绝对路径 指向上述提到的配置文件
+$ docker run -d -p 80:8080 -v /path/to/conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml --name apisix-dashboard apisix-dashboard:$tag
 ```
 
-现在你可以在浏览器中通过 `http://127.0.0.1` 使用 Dashboard。
+3. 检查容器是否启动成功
 
-## 注意
+```sh
+$ docker ps -a
+```
 
-1. 构建镜像后，如需修改配置文件，可通过使用 `docker -v /local-path-to-conf-file:/conf/conf.yaml` 参数指定 `manager-api` 所需要的配置文件，以便启动容器时动态加载配置文件。
-2. 中国用户可使用 `ENABLE_PROXY` 指令以加速所需依赖的下载。
+若容器 `apisix-dashboard` 状态正常，访问 `http://127.0.0.1:8080` 以使用有前端界面的控制台，默认用户密码均为 `admin`。
+
+4. 停止 Dashboard
 
 ```sh
-$ docker build -t apisix-dashboard:{$tag} . --build-arg ENABLE_PROXY=true
+$ docker stop apisix-dashboard
 ```
 
-3. 如果不是第一次构建，建议不要使用缓存。
+## 其它
+
+1. 多次构建镜像时，不建议使用缓存。
 
 ```sh
-$ docker build -t apisix-dashboard:{$tag} . --build-arg ENABLE_PROXY=true --no-cache=true
+$ docker build -t apisix-dashboard:$tag . --no-cache=true
 ```