feat(docs): improve README & Deploy (#785)

* feat(doc): update README & deploy * feat(docs): added FAQ * fix: linkx * feat(docs): update deploy with docker * feat(docs): update FAQ * feat: update README * feat: update README * feta: update README * fix: link * feat: update deploy with docker * feat(docs): added tip for some users * feat(doc): improve deploy with docker * feat(docs): improve deploy with docker * feat(doc): update run with docker * feat(doc): improve deploy * feat(doc): added more info * feat(doc): added more info * feat(doc): remove extra info * feat: added more detailed * fix: CI fail according `api/conf/conf.yaml ` is changed. * fix: revert changed * feat(docs): improve English version * feat(docs): use frontend instead, just like backend * feat(docs): remove extra statements * feat(docs): update typo * feat(docs): remove startup with message * feat: update CI's name Co-authored-by: nic-chen <johz@163.com>
apache · Nov 13, 2020 · 6dae80b · 6dae80b
1 parent a539f48
commit 6dae80b
Show file tree

Hide file tree

Showing 16 changed files with 399 additions and 479 deletions.
diff --git a/.github/workflows/frontend-e2e-test.yml b/.github/workflows/frontend-e2e-test.yml
@@ -1,4 +1,4 @@
-name: Front-end e2e test
+name: Frontend e2e test
 
 on:
   push:
@@ -14,7 +14,7 @@ defaults:
 
 jobs:
   web-e2e:
-    name: Front-end e2e test
+    name: Frontend e2e test
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -36,5 +36,5 @@ jobs:
         if: steps.node_modules_cache_id.outputs.cache-hit != 'true'
         run: yarn install
 
-      - name: Start Front-end then test
+      - name: Start frontend then test
         run: yarn test:e2e
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -29,18 +29,18 @@ This is a release candidate.
 
 # Core
 
-- Refactor front-end with Admin-API.
+- Refactor frontend with Admin-API.
 - Manager-API removes dependency on MySQL.
 - Support plugin orchestration.
-- Setting standards for front-end internationalization.
+- Setting standards for frontend internationalization.
 - New deployment pattern.
 - Add more test cases.
 - Document Enhancement.
 - Add back-end E2E test examples.
 - Improve CI testing.
 - Support log save to local file.
 - Optimize the deployment process.
-- Add E2E test examples to the front-end. [#619](https://github.com/apache/apisix-dashboard/pull/619)
+- Add E2E test examples to the frontend. [#619](https://github.com/apache/apisix-dashboard/pull/619)
 - Fix the Promethues plugin updating incorrect values when updating routes. [#666](https://github.com/apache/apisix-dashboard/pull/666)
 - Fix page display exceptions when the Redirect option is selected as Enable HTTPS in the Route page. [#692](https://github.com/apache/apisix-dashboard/pull/692)
 

diff --git a/README.md b/README.md
@@ -21,90 +21,64 @@ English | [简体中文](./README.zh-CN.md)
 
 # Apache APISIX Dashboard
 
-Apache APISIX Dashboard for [Apache APISIX](https://github.com/apache/apisix)
+## What's Apache APISIX Dashboard
 
-The goal of Apache APISIX Dashboard project is to let users to quickly experience and learn Apache APISIX, but it still cannot be used directly in a production environment. 
+The Apache APISIX Dashboard is designed to make it as easy as possible for users to operate [Apache APISIX](https://github.com/apache/apisix) through a frontend interface.
 
-Its function is always a subset of Apache APISIX, and may lag behind the rapid iteration of Apache APISIX.
+The Dashboard is the control plane and performs all parameter checks; Apache APISIX mixes data and control planes and will evolve to a pure data plane.
 
-If you need to use the Apache APISIX Dashboard project in a production system, you need to enhance user permissions, communication security, high availability and other advanced features.
+This project includes `manager-api`, which will gradually replace `admin-api` in Apache APISIX.
 
-## Installation
+Note: Currently the Dashboard does not have complete coverage of Apache APISIX features, [visit here](https://github.com/apache/apisix-dashboard/milestones) to view the milestones.
 
-Support multiple ways to install Apache APISIX Dashboard
+![architecture](./docs/images/architecture.png)
 
-### Docker
+## Project structure
 
-Start a runnable version by the following method
-
-- [Deploy With Docker](./docs/deploy-with-docker.md)
-
-### Build from Source Code
-
-To build Apache APISIX Dashboard from source code, first make sure that your `golang` version is 1.13 or greater.
-
-Also you need to make sure that `Node.js` and `yarn` are installed.
-
-```sh
-$ git clone -b v2.0 https://github.com/apache/apisix-dashboard.git
-$ cd apisix-dashboard
-$ make build
 ```
-
-Then you can find all files (configuration files, executable files, web static resources) needed to run Apache APISIX Dashboard in the `./output` directory.
-
-Start by the following commands.
-
-```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` provides the following commands.
+1. The `api` directory is used to store the `manager-api` source codes, which is used to manage `etcd` and provide APIs to the frontend interface.
+2. The `web` directory is used to store the frontend source codes.
 
-```text
-Makefile rules:
+## Build then launch
 
-    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
-```
+Support the following ways currently.
 
-For more detailed construction steps, see -  [Build from Source Codes](./docs/deploy.md)
+- [Source Codes](./docs/deploy.md)
+- [Docker](./docs/deploy-with-docker.md)
 
-### For developer
+## Development
 
-Apache APISIX Dashboard provides a management interface for [Apache APISIX](https://github.com/apache/apisix), you need to [install APISIX first](https://github.com/apache/apisix#configure-and-installation).
+Please refer to the [Development Guide](./docs/develop.md).
 
-Please refer to here to start `manager-api` and `web`respectively.
+## User Guide
 
-- [Develop Apache APISIX Dashboard](./docs/develop.md)
-
-## User guide
-
-Please refer to [User Guide](./docs/USER_GUIDE.md)
-
-## Milestones
-
-- [2.0](https://github.com/apache/apisix-dashboard/milestone/4)
-- [2.1](https://github.com/apache/apisix-dashboard/milestone/5)
+Please refer to the [User Guide](./docs/USER_GUIDE.md).
 
 ## Contributing
 
-See [CONTRIBUTING](./CONTRIBUTING.md) for details on submitting patches and the contribution workflow.
-
-## License
-
-Apache License 2.0, [LICENSE](https://github.com/apache/apisix-dashboard/blob/master/LICENSE)
+Please refer to the [Contribution Guide](./CONTRIBUTING.md) for a more detailed infomation.
 
 ## FAQ
 
-1. If you need the Apache APISIX Dashboard 1.0 which is built with Vue.js, please refer to [master-vue](https://github.com/apache/apisix-dashboard/tree/master-vue).
+Please refer to the [FAQ](./docs/FAQ.md) for more known issues.
 
-2. The Apache APISIX Dashboard 2.0 removes MySQL which [Apache APISIX Dashboard 1.5](https://github.com/apache/apisix-dashboard/tree/backup-1.5-latest) is relied on.
+## License
 
-3. If you are using APISIX 1.5 or below, kindly note that the v2 api store and v3 api store are [separate and isolated](https://etcd.io/docs/v3.4.0/op-guide/v2-migration/). Apache APISIX Dashboard v2.0 and above use the etcd v3 api, APISIX 1.5 and below use the etcd v2 api.
+[Apache License 2.0](./LICENSE)
diff --git a/README.zh-CN.md b/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)
diff --git a/api/conf/conf.yaml b/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
diff --git a/docs/FAQ.md b/docs/FAQ.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 version of the Dashboard
+
+If you need a Vue.js build of the Apache APISIX Dashboard 1.0, use the [master-vue branch](https://github.com/apache/apisix-dashboard/tree/master-vue).
+
+### What are the differences between Dashboard version 2.0 and version 1.5?
+
+The 2.0 version of the dashboard removed MySQL from [version 1.5](https://github.com/apache/apisix-dashboard/tree/backup-1.5-latest) and will operate directly on etcd.
+
+### 3. Etcd compatibility issues
+
+If you are using Apache APISIX below v2.0, be aware that the data from the etcd v2 API is [not compatible](https://etcd.io/docs/v3.4.0/op-guide/v2-migration/) with the data from the v3 API. Apache APISIX Dashboard v2.0 and above uses the etcd v3 API, and apisix 1.5 and below uses the etcd v2 API.
+
+### 4. After modifying the plugin schema or creating a custom plugin in Apache APISIX, why can't I find it on the dashboard?
+
+Since the Dashboard caches the jsonschema data of the plugins in Apache APISIX, you need to synchronize the data in the Dashboard after you create your custom plugins in Apache APISIX, which currently **only supports manual operation**, this issue will be optimized in the following versions. Please follow the following guide.
+
+1. Install [Lua](https://www.lua.org/download.html) and `zip`.
+
+2. Execute the following commands.
+
+```sh
+# `$version` is the version number of Apache APISIX, e.g. master or 2.0.
+$ api/build-tools/schema-sync.sh $version
+```
+
+If you have a custom plugin, make sure it is in the `apisix` directory and use the following command.
+
+```sh
+$ api/build-tools/schema-sync.sh /path/to/apisix
+
+# e.g
+$ api/build-tools/schema-sync.sh /usr/local/apisix
+```
+
+After the command finishes executing, if you are using a binary `manager-api` that has already been built, you will need to manually copy `api/conf/schema.json` to the `conf` directory under the Dashboard **working directory**. where **working directory** refers to the `conf` directory under this [document](./deploy.md) is the `output` directory, or the directory with the modified name, that is generated in the root directory after the build is complete.