gxthrj commented on a change in pull request #785: URL: https://github.com/apache/apisix-dashboard/pull/785#discussion_r521491221
########## File path: docs/develop.zh-CN.md ########## @@ -17,99 +17,52 @@ # --> -# Apache APISIX Dashboard 开发 +# 开发指南 -## 前置条件 +Dashboard 包含了 `manager-api` 与 `web` 两部分，因此需要分别启动开发环境。 -```sh -$ git clone -b v2.0 https://github.com/apache/apisix-dashboard.git -$ cd apisix-dashboard -``` - -## 前端开发 +## 环境准备 -1. 确保你的设备已经安装了 `Node.js(version version 10.0.0+)`。 +在开发前，请参考该[指南](./deploy.zh-CN.md#环境准备)以安装依赖。 -2. 安装 [yarn](https://yarnpkg.com/)。 - -3. 安装依赖: +## 克隆项目 ```sh -$ yarn install -``` - -4. 若需要修改 manager-api 地址，请访问 `config/proxy.ts` 文件。 - -5. 启动 (开发模式) - -```sh -$ yarn start +$ git clone -b v2.0 https://github.com/apache/apisix-dashboard.git ``` -### 编写 E2E 测试案例 +## 开始开发 -请参考 [E2E 文档](../web/src/e2e/README.zh-CN.md)。 +### manager-api -## 开发 manager-api +1. 请在 `api/conf/conf.yaml` 中修改配置信息。 -### 启动 - -1. 修改配置文件 目录: `api/conf/conf.yaml` - -```yaml -conf: - listen: - host: 127.0.0.1 - port: 8080 - etcd: - endpoints: - - 127.0.0.1:2379 -authentication: - secret: secret - expire_time: 3600 - users: - - username: admin - password: admin - - username: user - password: user -``` - -2. 启动 (开发模式) +2. 启动开发模式 ```sh $ make api-run ``` -3. 关闭 (开发模式) +3. 关闭开发模式 ```sh $ make api-stop ``` -### 同步 jsonschema - -从 Apache APISIX 同步 jsonschema ，需要预安装 `Lua` 5.1+ 和 `zip` ，并执行命令 +4. 关于增加自定义插件或修改插件 schema 后在控制台显示异常的问题，请查阅 [FAQ 汇总](./FAQ.zh-CN.md)关于该问题的描述。 -```sh -$ api/build-tools/schema-sync.sh $version -``` +### web -注意：`$version` 为 `master` 或者 Apache APISIX 的版本号。 +1. 请在 `config/proxy.ts` 文件中修改 `manager-api` 地址。 -示例： +2. 启动开发模式 ```sh -# 使用 "master" -$ api/build-tools/schema-sync.sh master - -# 使用 Apache APISIX 的版本号 -$ api/build-tools/schema-sync.sh 2.0 -``` +$ cd /web Review comment: here shoud be a relation path ########## File path: 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 Review comment: There will be noisy data with `-a`, which will list the closed but not deleted containers. ########## File path: docs/deploy.zh-CN.md ########## @@ -17,118 +17,80 @@ # --> -# 从源文件打包部署 +# 源码构建并启动 -## 克隆项目 - -```sh -$ git clone -b v2.0 https://github.com/apache/apisix-dashboard.git - -$ cd apisix-dashboard -``` +Dashboard 包含了 `manager-api` 与 `web` 两部分，其中 `web` 是*可选*的。 ## 构建 -### Manager-api 检查项 +本构建指南将包含 `web` 控制台。 -`manager-api` 用于为控制台提供接口，就像 Apache APISIX 和控制台之间的桥梁。下面是手动构建步骤： +### 环境准备 -1. 需要预先安装 `Go` 1.13+ +在构建之前，请确认您的环境中，已安装如下依赖： -注意：如果使用插件编排，需要同时预先安装 `Lua` 5.1+ ，后续版本会对此进行优化，取消对 `Lua` 的依赖。 +#### manager-api -2. 检查环境变量 - -- 对于大多数中国用户，我们可以使用 [Goproxy](https://goproxy.cn/) 加快模块下载速度。 +1. [Golang](https://golang.org/dl/) 1.13+：对于中国大陆的用户，可使用如下命令加快模块下载速度。 ```sh $ go env -w GOPROXY=https://goproxy.cn,direct ``` -### 前端 检查项 +2. [Lua](https://www.lua.org/download.html) 5.1+：仅在使用**插件编排**功能时，需要安装本依赖。在后续版本中，会对该部分进行优化以取消对其依赖。 -该项目使用 [Ant Design Pro](https://pro.ant.design) 初始化。以下是一些使用方法的快速指南。 +#### web -1. 确保你的设备已经安装了 `Node.js(版本 10.0.0+)`。 +1. [Node.js](https://nodejs.org/en/download/) 10.23.0+ +2. [Yarn](https://yarnpkg.com/getting-started/install) -2. 安装 [yarn](https://yarnpkg.com/)。 +### 克隆项目 -### 开始构建 +```sh +$ git clone -b v2.0 https://github.com/apache/apisix-dashboard.git +``` +### 开始构建 ```sh +$ cd apisix-dashboard $ make build ``` -构建完成后的文件在根目录 `output` 下。 +构建完成后，构建结果将存放在根目录下 `output` 目录中。 + +注意：`make build` 将会构建 `manger-api` 与 `web`，使用 `make help` 命令以查看更多指令。 ## 启动 -1. 根据您的部署环境，检查并修改 `output/conf/conf.yaml` 中的配置。 - -例如： - -```yaml -conf: - listen: - host: 127.0.0.1 - port: 8080 - etcd: - endpoints: - - 127.0.0.1:2379 -authentication: - secret: secret - expire_time: 3600 - users: - - username: admin - password: admin - - username: user - password: user -``` +1. 根据您的部署环境，检查并修改 `output/conf/conf.yaml` 中的配置信息。 -2. 启动 Apache APISIX Dashboard +2. 启动 Dashboard ```sh $ cd ./output Review comment: `make api-run` is used for dev mode ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
