v3.0.0-alpha.3

.vuepress/config-sidebar.js

@@ -60,6 +60,7 @@ let sidebar = {
           title: '配置 Kuboard v3',
           collapsable: true,
           children: [
+            'v3/auth-user-sso',
             'v3/proxy',
             'v3/tls',
             'v3-upgrade',

install/v3/auth-user-sso.md

@@ -0,0 +1,39 @@
+
+
+# 为单点登录的用户/用户组授权
+
+当您配置 Kuboard 与 gitlab / github / ldap 实现单点登录以后，Kuboard 并不管理用户基本信息、用户组信息、用户与用户组之间的映射信息，这些信息需要您在 gitlab / github/ ldap 中管理和配置。
+
+默认情况下，只有 `KUBOARD_ROOT_USER` 参数指定的用户可以执行 Kuboard 中的所有操作，其他用户通过单点登录进入 Kuboard 系统后，除了退出系统，几乎什么事情也做不了。为了让单点登录的用户获得合适的权限，您需要在 Kuboard 中为对应的用户/用户组授权。下面描述了为指定用户授权的操作步骤：
+
+* 为用户添加角色绑定
+
+  如下图所示，导航到 ***用户*** 列表菜单，点击 ***为用户添加角色绑定*** 按钮
+
+  ![Kuboard-V3-用户授权](./auth-user-sso.assets/image-20201114095004698.png)
+
+  在图中的弹出对话框输入单点登录用户系统中的用户名，点击确定。
+
+* 切换到 ***角色绑定（全局）***
+
+  点击上图中的确定之后，将进入用户的授权界面，如下图所示，此时请切换到 ***角色绑定（全局）*** 标签页，点击 ***创建角色绑定*** 按钮。
+
+  ![Kuboard-V3-用户授权](./auth-user-sso.assets/image-20201114095804049.png)
+
+
+
+* 创建角色绑定
+
+  选择角色，点击确定后，用户将具备该角色指定的权限。
+
+  ![Kuboard-V3-用户授权](./auth-user-sso.assets/image-20201114100349010.png)
+
+
+
+::: tip 注意
+
+* 全局角色绑定，用户可以在所有 Kubernetes 集群范围内执行该角色授予的权限；
+* 集群角色绑定，用户只能在指定的 Kubernetes 集群范围内执行该角色授予的权限；
+* 通常，以为用户组授权比为单个用户授权更为灵活和方便。
+
+:::

install/v3/install-github.md

@@ -10,6 +10,7 @@ meta:
 
 <AdSenseTitle/>
 
+
 Kuboard 支持多种认证方式：
 
 * 内建用户库
@@ -17,6 +18,134 @@ Kuboard 支持多种认证方式：
 * GitHub Enterprise / github.com
 * LDAP
 
-本文将要描述如何使用 GitHub 用户登录 Kuboard。
+本文描述了如何配置 Kuboard v3 使其与 github.com / github ee 实现单点登录。
 
-预计在 kuboard v3.0.0-alpha.5 支持此认证方式。
+## 前提条件
+
+* 用于安装 Kuboard v3.0 的机器已经安装了 docker，并且版本不低于 docker 19.03
+* 您已经有自己的 Kubernetes 集群，并且版本不低于 Kubernetes v1.13
+* 您已经安装好了 github ee 或者您打算直接使用 github.com 中的账号
+
+## 部署计划
+
+在正式安装 kuboard v3 之前，需做好一个简单的部署计划的设计，在本例中，各组件之间的连接方式，如下图所示：
+
+* 用户通过 https://github.com 访问 github.com；
+
+* 用户通过 http://kuboard.mycompany.com 访问 Kuboard v3；
+
+* Kuboard 通过 https://github.com 访问 GitHub API；
+
+* 安装在 Kubernetes 中的 Kuboard Agent 通过 `kuboard.mycompany.com` 访问 Kuboard 的 Web 服务端口 80 / 443 和 Kuboard Agent Server 端口 10081。
+
+
+![image-20201115230700829](install-github.assets/image-20201115230700829.png)
+
+本例子中，假设：
+
+* 您已经准备好了一个 Linux 服务器用于安装 Kuboard-V3
+* 您将要配置 Kuboard 使用 github.com 实现单点登录
+  * 也可以支持自己本地安装的 GitHub Enterprise Edition
+
+
+
+## 准备 GitHub
+
+* 在 github.com （或者 github ee）中导航到 ***Settings / Developer settings*** 菜单，如下图所示：
+
+  ![image-20201114153558542](./install-github.assets/image-20201114153558542.png)
+
+* 在 ***Settings / Developer settings*** 菜单中导航到 ***OAuth Apps*** 菜单，如下图所示：
+
+  ![image-20201114154213721](./install-github.assets/image-20201114154213721.png)
+
+* 在上图中点击 ***New OAuth App***，并填写如下表单：
+
+  | 字段名称                   | 字段取值                                  | 字段描述                                                     |
+  | -------------------------- | ----------------------------------------- | ------------------------------------------------------------ |
+  | Application name           | kuboard-v3                                | 标识用，填写任意名称即可                                     |
+  | Homepage URL               | http://kuboard.mycompany.com              | 根据 [部署计划](#部署计划)，此处应该填写 http://kuboard.mycompany.com |
+  | Application description    | Kuboard v3.0.0                            | 描述，可以为空                                               |
+  | Authorization callback URL | http://kuboard.mycompany.com/sso/callback | 根据 [部署计划](#部署计划)，此处应该填写 http://kuboard.mycompany.com/sso/callback，`/sso/callback` 为 Kuboard 中处理 OAuth 回调的 URL 路径 |
+
+  ![image-20201114154856032](./install-github.assets/image-20201114154856032.png)
+
+* 在上图中点击 ***Register application*** 按钮之后，将进入新创建的 OAuth application 的详情页面，在该页面可以获得 ***Client ID*** 和 ***Client Secret*** 两个字段，如下图所示：
+
+  ![image-20201114155605975](./install-github.assets/image-20201114155605975.png)
+
+
+
+## 启动 Kuboard 
+
+使用如下命令启动 Kuboard v3：
+``` sh
+sudo docker run -d \
+  --restart=unless-stopped \
+  --name=kuboard \
+  -p 80:80/tcp \
+  -p 10081:10081/udp \
+  -p 10081:10081/tcp \
+  -v /root/kuboard-data:/data \
+  -e KUBOARD_LOGIN_TYPE="github" \
+  -e KUBOARD_ENDPOINT="http://kuboard.mycompany.com" \
+  -e KUBOARD_ROOT_USER="shaohq" \
+  -e GITHUB_CLIENT_ID="17577d45e4de7dad88e0" \
+  -e GITHUB_CLIENT_SECRET="ff738553a8c7e9ad39569c8d02c1d85ec19115a7" \
+  eipwork/kuboard:v3-alpha
+```
+
+::: tip 参数说明
+* 建议将此命令保存为一个 shell 脚本，例如 `start-kuboard.sh`，后续升级 Kuboard 或恢复 Kuboard 时，需要通过此命令了解到最初安装 Kuboard 时所使用的参数；
+* 第 4 行，Kuboard v3.0 需要暴露 `80` 端口，如安装指令的第三行所示，默认映射到了宿主机的 `80` 端口，您可以根据自己的情况选择宿主机的其他端口；
+* 第 5、6 行，Kuboard v3.0 需要暴露 `10081` 端口 TCP / UDP，默认映射到了宿主机的 `10081` 端口，您可以根据自己的情况选择宿主机的其他端口；
+* 第 7 行，Kuboard v3.0 的持久化数据存储在 `/data` 目录，默认映射到了宿主机的 `/root/kuboard-data` 路径，请根据您自己的情况进行调整；
+* 第 8 行，将 Kuboard v3.0 与 GitHub 进行单点登录集成时，必须指定环境变量 `KUBOARD_LOGIN_TYPE` 为 `github` （适用于 github.com / github-ee）；
+* 第 9 行，必须指定 `KUBOARD_ENDPOINT` 环境变量为访问 Kuboard 界面的 URL；（如 [部署计划](#部署计划) 中所描述，本例子中，使用 `http://kuboard.mycompany.com` 作为通过执行此命令启动的 Kuboard 的访问 URL）；此参数不能以 `/` 结尾；
+* 第 10 行，必须指定 `KUBOARD_ROOT_USER`，使用该 GitHub 用户登录到 Kuboard 以后，该用户具备 Kuboard 的所有权限；
+* 第 11 行，必须指定 `GITHUB_CLIENT_ID`，该参数来自于 [准备 GitHub](#准备-github) 步骤中创建的 GitHub OAuth Application 的 `Client ID` 字段
+* 第 12 行，必须指定 `GITHUB_CLIENT_SECRET`，该参数来自于 [准备 GitHub](#准备-github) 步骤中创建的 GitHub OAuth Application 的 `Client Secret` 字段
+:::
+
+::: tip GitHub EE
+上面的命令行可以用于和 github.com 集成，如果您使用 GitHub Enterprise，需要在命令行中增加如下两个参数：
+* `GITHUB_HOSTNAME`，GitHub Enterprise 的 hostname，如
+  ```sh
+  -e GITHUB_HOSTNAME="github.mycompany.com"
+  ```
+* `GITHUB_ROOT_CA`，如果您的 GitHub Enterprise 使用了自签名证书，则需要指定 GITHUB_ROOT_CA，否则，可以忽略此参数，如：
+  ```sh
+  -v /path/to/your/rootca.crt:/github-root-ca.crt
+  -e GITHUB_ROOT_CA="/github-root-ca.crt"
+  ```
+:::
+
+
+## 访问 Kuboard 界面
+
+* 在浏览器中输入 `http://kuboard.mycompany.com`，您将被重定向到 GitLab 登录界面；
+* 在 GitLab 登录界面使用 docker run 命令中 `KUBOARD_ROOT_USER` 参数指定的用户完成登录后，GitLab 将提示您是否授权访问 Kuboard，如下图所示：
+
+  ![image-20201113215827177](./install-gitlab.assets/image-20201113215827177.png)
+
+* 点击上图中的 ***Authorize*** 按钮后，您将成功登录 Kuboard 界面，第一次登录时，界面显示如下所示：
+
+  根据 [部署计划](#部署计划) 的设想，如下表单的填写内容为：
+
+  | 参数名称                                             | 参数值                                                       | 参数说明                                                     |
+  | ---------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
+  | <div style="width: 170px;">Kuboard UI 访问地址</div> | <div style="width: 130px;">http://kuboard.mycompany.com</div> | 根据 [部署计划](#部署计划) ，安装在 Kubernetes 中的 Kuboard Agent 通过 http://kuboard.mycompany.com 这个 URL 访问 Kuboard Web 界面，此处为 Kubernetes 集群和 Kuboard 浏览器端用户设定了不同的访问域名（在 docker run 命令的 `KUBOARD_ENDPOINT` 参数指定）。 |
+  | Agent Server Host                                    | kuboard.mycompany.com                                        | 根据 [部署计划](#部署计划) ，安装在 Kubernetes 中的 Kuboard Agent 通过 kuboard.mycompany.com 解析到 Kuboard 所在宿主机的 IP 地址 |
+  | Agent Server UDP 端口                                | 10081                                                        | 此端口必须与 docker run 命令中映射的 10081/udp 端口一致      |
+  | Agent Server TCP 端口                                | 10081                                                        | 此端口必须与 docker run 命令中映射的 10081/tcp 端口一致      |
+  
+  
+  ![image-20201115230236714](install-gitlab.assets/image-20201115230236714.png)
+  
+* 点击上图中的 ***保存*** 按钮，您将进入 Kuboard 集群列表页，此时，您可以向 Kuboard 添加 Kubernetes 集群，如下图所示：
+
+  ![image-20201113221543277](./install-gitlab.assets/image-20201113221543277.png)
+
+## 授权用户访问 Kuboard
+
+默认情况下，只有 `KUBOARD_ROOT_USER` 参数指定的用户可以执行 Kuboard 中的所有操作，其他用户通过单点登录进入 Kuboard 系统后，除了退出系统，几乎什么事情也做不了。为了让单点登录的用户获得合适的权限，您需要在 Kuboard 中为对应的用户/用户组授权。请参考 [为单点登录的用户/用户组授权](./auth-user-sso.html)

install/v3/install-gitlab.md

@@ -17,6 +17,115 @@ Kuboard 支持多种认证方式：
 * GitHub Enterprise / github.com
 * LDAP
 
-本文将要描述如何使用 GitLab 用户登录 Kuboard。
+本文描述了如何配置 Kuboard v3 使其与 gitlab.com / gitlab ee / gitlab ce 实现单点登录。
 
-预计在 kuboard v3.0.0-alpha.3 支持此认证方式。
+## 前提条件
+
+* 用于安装 Kuboard v3.0 的机器已经安装了 docker，并且版本不低于 docker 19.03
+* 您已经有自己的 Kubernetes 集群，并且版本不低于 Kubernetes v1.13
+* 您已经安装好了 gitlab-ce 或者 gitlab-ee，又或者您打算直接使用 gitlab.com 中的账号
+
+## 部署计划
+
+在正式安装 kuboard v3 之前，需做好一个简单的部署计划的设计，在本例中，各组件之间的连接方式，如下图所示：
+
+* 用户通过 http://gitlab.mycompany.com 访问 gitlab；
+
+* 用户通过 http://kuboard.mycompany.com 访问 Kuboard v3；
+
+* Kuboard 通过 http://gitlab.mycompany.com 访问 GitLab API；
+
+* 安装在 Kubernetes 中的 Kuboard Agent 通过 `kuboard.mycompany.com` 访问 Kuboard 的 Web 服务端口 80 / 443 和 Kuboard Agent Server 端口 10081。
+
+
+![image-20201115223736418](install-gitlab.assets/image-20201115223736418.png)
+
+本例子中，假设：
+
+* 您已经准备好了一个 Linux 服务器用于安装 Kuboard-V3
+* 您的 gitlab 已经完成安装且版本不低于 11，并且可以从用户的浏览器以及用于安装 Kuboard-V3 的服务器访问到（使用 URL http://gitlab.mycompany.com）
+  * 本例子支持 gitlab-ce / gitlab-ee，也支持 gitlab.com
+
+
+
+## 准备 GitLab
+
+在 gitlab.com （或者 gitlab ee / gitlab ce）创建 Application，如下图所示：
+
+表单填写说明：
+
+| 字段名称     | 字段取值                                   | 字段说明                                                     |
+| ------------ | ------------------------------------------ | ------------------------------------------------------------ |
+| Name         | kuboad-v3                                  | 应用程序在 GitLab 中的标识，例如，此处填写了 kuboard-v3      |
+| Redirect URI | http://kuboard.my-company.com/sso/callback | 登录成功后的回调 URL，必须填写绝对路径，且必须指定到 kuboard 的 `/sso/callback` 路径 |
+| Scopes       | read_user / openid / profile / email       | 应用程序可以访问的 GitLab 接口范围，对于 Kuboard 而言，必须勾选如下几个选项： read_user / openid / profile / email |
+
+![image-20201113212028264](./install-gitlab.assets/image-20201113212028264.png)
+
+
+
+完成创建后，您将获得 `Application ID` 以及 `Secret` 两个字段的值，如下图所示：
+
+![image-20201112230944049](./install-gitlab.assets/image-20201112230944049.png)
+
+## 启动 Kuboard
+
+使用如下命令启动 Kuboard v3：
+``` sh
+sudo docker run -d \
+  --restart=unless-stopped \
+  --name=kuboard \
+  -p 80:80/tcp \
+  -p 10081:10081/udp \
+  -p 10081:10081/tcp \
+  -v /root/kuboard-data:/data \
+  -e KUBOARD_LOGIN_TYPE="gitlab" \
+  -e KUBOARD_ENDPOINT="http://kuboard.mycompany.com" \
+  -e KUBOARD_ROOT_USER="shaohq" \
+  -e GITLAB_BASE_URL="http://gitlab.mycompany.com" \
+  -e GITLAB_APPLICATION_ID="7c10882aa46810a0402d17c66103894ac5e43d6130b81c17f7f2d8ae182040b5" \
+  -e GITLAB_CLIENT_SECRET="77c149bd3a4b6870bffa1a1afaf37cba28a1817f4cf518699065f5a8fe958889" \
+  eipwork/kuboard:v3-alpha
+```
+
+::: tip 参数说明
+* 建议将此命令保存为一个 shell 脚本，例如 `start-kuboard.sh`，后续升级 Kuboard 或恢复 Kuboard 时，需要通过此命令了解到最初安装 Kuboard 时所使用的参数；
+* 第 4 行，Kuboard v3.0 需要暴露 `80` 端口，如安装指令的第三行所示，默认映射到了宿主机的 `80` 端口，您可以根据自己的情况选择宿主机的其他端口；
+* 第 5、6 行，Kuboard v3.0 需要暴露 `10081` 端口 TCP / UDP，默认映射到了宿主机的 `10081` 端口，您可以根据自己的情况选择宿主机的其他端口；
+* 第 7 行，Kuboard v3.0 的持久化数据存储在 `/data` 目录，默认映射到了宿主机的 `/root/kuboard-data` 路径，请根据您自己的情况进行调整；
+* 第 8 行，将 Kuboard v3.0 与 GitLab 进行单点登录集成时，必须指定环境变量 `KUBOARD_LOGIN_TYPE` 为 `gitlab` （适用于 gitlab.com / gitlab-ee / gitlab-ce）；
+* 第 9 行，必须指定 `KUBOARD_ENDPOINT` 环境变量为访问 Kuboard 界面的 URL；（如 [部署计划](#部署计划) 中所描述，本例子中，使用 `http://kuboard.mycompany.com` 作为通过执行此命令启动的 Kuboard 的访问 URL）；此参数不能以 `/` 结尾；
+* 第 10 行，必须指定 `KUBOARD_ROOT_USER`，使用该 GitLab 用户登录到 Kuboard 以后，该用户具备 Kuboard 的所有权限；
+* 第 11 行，指定 `GIBLAB_BASE_URL`，（如 [部署计划](#部署计划) 中所描述，本例子中，使用 `http://gitlab.mycompany.com` 作为通过作为 GitLab 的访问 URL，并假设 GitLab 已经事先准备就绪，如果不指定，该参数默认值为 `https://gitlab.com`）；此参数不能以 `/` 结尾；
+* 第 12 行，必须指定 `GITLAB_APPLICATION_ID`，该参数来自于 [准备 GitLab](#准备-gitlab) 步骤中创建的 GitLab  Application 的 `Application ID` 字段
+* 第 13 行，必须指定 `GITLAB_CLIENT_SECRET`，该参数来自于 [准备 GitLab](#准备-gitlab) 步骤中创建的 GitLab  Application 的 `Secret` 字段
+:::
+
+## 访问 Kuboard 界面
+
+* 在浏览器中输入 `http://kuboard.mycompany.com`，您将被重定向到 GitLab 登录界面；
+* 在 GitLab 登录界面使用 docker run 命令中 `KUBOARD_ROOT_USER` 参数指定的用户完成登录后，GitLab 将提示您是否授权访问 Kuboard，如下图所示：
+
+  ![image-20201113215827177](./install-gitlab.assets/image-20201113215827177.png)
+
+* 点击上图中的 ***Authorize*** 按钮后，您将成功登录 Kuboard 界面，第一次登录时，界面显示如下所示：
+
+  根据 [部署计划](#部署计划) 的设想，如下表单的填写内容为：
+
+  | 参数名称                                             | 参数值                                                       | 参数说明                                                     |
+  | ---------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
+  | <div style="width: 170px;">Kuboard UI 访问地址</div> | <div style="width: 130px;">http://kuboard.mycompany.com</div> | 根据 [部署计划](#部署计划) ，安装在 Kubernetes 中的 Kuboard Agent 通过 http://kuboard.mycompany.com 这个 URL 访问 Kuboard Web 界面，此处为 Kubernetes 集群和 Kuboard 浏览器端用户设定了不同的访问域名（在 docker run 命令的 `KUBOARD_ENDPOINT` 参数指定）。 |
+  | Agent Server Host                                    | kuboard.mycompany.com                                        | 根据 [部署计划](#部署计划) ，安装在 Kubernetes 中的 Kuboard Agent 通过 kuboard.mycompany.com 解析到 Kuboard 所在宿主机的 IP 地址 |
+  | Agent Server UDP 端口                                | 10081                                                        | 此端口必须与 docker run 命令中映射的 10081/udp 端口一致      |
+  | Agent Server TCP 端口                                | 10081                                                        | 此端口必须与 docker run 命令中映射的 10081/tcp 端口一致      |
+  
+  
+  ![image-20201115230236714](install-gitlab.assets/image-20201115230236714.png)
+  
+* 点击上图中的 ***保存*** 按钮，您将进入 Kuboard 集群列表页，此时，您可以向 Kuboard 添加 Kubernetes 集群，如下图所示：
+
+  ![image-20201113221543277](./install-gitlab.assets/image-20201113221543277.png)
+
+## 授权用户访问 Kuboard
+
+默认情况下，只有 `KUBOARD_ROOT_USER` 参数指定的用户可以执行 Kuboard 中的所有操作，其他用户通过单点登录进入 Kuboard 系统后，除了退出系统，几乎什么事情也做不了。为了让单点登录的用户获得合适的权限，您需要在 Kuboard 中为对应的用户/用户组授权。请参考 [为单点登录的用户/用户组授权](./auth-user-sso.html)

install/v3/install-ldap.md

@@ -10,6 +10,7 @@ meta:
 
 <AdSenseTitle/>
 
+
 Kuboard 支持多种认证方式：
 
 * 内建用户库
@@ -17,6 +18,184 @@ Kuboard 支持多种认证方式：
 * GitHub Enterprise / github.com
 * LDAP
 
-本文将要描述如何使用 LDAP 用户登录 Kuboard。
+本文描述了如何配置 Kuboard v3 使用 LDAP 实现用户登录。
 
-预计在 kuboard v3.0.0-alpha.4 支持此认证方式。
+## 前提条件
+
+* 用于安装 Kuboard v3.0 的机器已经安装了 docker，并且版本不低于 docker 19.03
+* 您已经有自己的 Kubernetes 集群，并且版本不低于 Kubernetes v1.13
+
+## 部署计划
+
+在正式安装 kuboard v3 之前，需做好一个简单的部署计划的设计，在本例中，各组件之间的连接方式，如下图所示：
+
+
+* 用户通过 http://kuboard.mycompany.com 访问 Kuboard v3；
+
+* Kuboard 通过 `localhost:389` 和 `localhost:636` 访问 LDAP；
+
+* 安装在 Kubernetes 中的 Kuboard Agent 通过 `kuboard.mycompany.com` 访问 Kuboard 的 Web 服务端口 80 / 443 和 Kuboard Agent Server 端口 10081。
+
+
+![image-20201115230620704](install-ldap.assets/image-20201115230620704.png)
+
+本例子中，假设：
+
+* 您已经准备好了一个 Linux 服务器用于安装 Kuboard-V3
+
+## 准备 LDAP
+
+> 本章节将引导您搭建一个测试用的 LDAP，如果您使用已经有的 LDAP，可跳过本章节。
+
+* 启动 Open LDAP
+
+  > 下面启动 Open LDAP 的脚本仅用于测试，未考虑如何持久化，如何设置 TLS 等，更多信息请参考该脚本中所用容器的 [帮助文档](https://github.com/osixia/docker-openldap)
+  ``` sh
+  docker run -p 389:389 -p 636:636 --name my-openldap-container --detach osixia/openldap:1.4.0
+  ```
+  
+* 启动 phpLDAPadmin
+
+  ```sh
+  docker run -p 6443:443 \
+    --env PHPLDAPADMIN_LDAP_HOSTS=host.docker.internal \
+    --detach osixia/phpldapadmin:0.9.0
+  ```
+  
+* 登录 phpLDAPadmin
+  
+  在浏览器输入 `https://kuboard.mycompany.com:6443` ，按下图所示步骤登录 phpLDAPadmin：
+  
+  | 字段名称 | 字段值                     | 字段描述       |
+  | -------- | -------------------------- | -------------- |
+  | Login DN | cn=admin,dc=example,dc=org | 默认管理员用户 |
+  | Password | admin                      | 管理员密码     |
+  
+  ![image-20201114175421773](./install-ldap.assets/image-20201114175421773.png)
+
+* 添加用户组
+
+  登录成功后，按照下图所示步骤，进入添加分组的表单：
+
+  ![image-20201114180239080](./install-ldap.assets/image-20201114180239080.png)
+
+  在表单中填写 `mygroup` 然后点击 ***Create Object*** 按钮，创建 `mygroup` 用户组，如下图所示：
+
+  ![image-20201114182400836](./install-ldap.assets/image-20201114182400836.png)
+
+  > 点击 ***Create Object*** 之后的界面中再次点击 ***Commit*** 按钮，才能完成对象的创建。
+
+* 添加用户
+
+  按照下图所示步骤，进入添加用户的表单：
+
+  ![image-20201114182716704](./install-ldap.assets/image-20201114182716704.png)
+
+  表单各字段填写说明：
+
+  | 字段名称       | 字段值             |
+  | -------------- | ------------------ |
+  | First name     | Huanqing           |
+  | Last name      | Shao               |
+  | Common Name    | Huanqing Shao      |
+  | User ID        | shaohq             |
+  | Password       | 123456             |
+  | GID Number     | mygroup            |
+  | Home Directory | /home/users/shaohq |
+
+  表单界面如下所示：
+
+  ![image-20201114183112103](./install-ldap.assets/image-20201114183112103.png)
+
+  点击上图中的 ***Create Object*** 按钮，然后再点击 ***Commit*** 按钮，将成功创建用户，并进入如下界面。按照如下步骤在该界面中为用户添加邮箱地址字段：
+
+  * 点击 Add new attribute
+  * 选择 Email 字段类型
+  * 填写电子邮箱地址
+  * 点击 Update Object 按钮
+
+  ![image-20201114183716496](./install-ldap.assets/image-20201114183716496.png)
+
+::: tip LDAP Demo
+
+此时我们已经准备好了用于演示的 LDAP 环境：
+
+* 快速安装了一个 LDAP 服务实例
+* 创建了一个用户组 `mygroup`
+* 创建了一个用户 `shaohq`，该用户归属于用户组 `mygroup`，其密码为 `123456`
+
+:::
+
+## 启动 Kuboard
+
+使用如下命令启动 Kuboard v3：
+``` sh
+sudo docker run -d \
+  --restart=unless-stopped \
+  --name=kuboard \
+  -p 80:80/tcp \
+  -p 10081:10081/udp \
+  -p 10081:10081/tcp \
+  -v /Users/shaohuanqing/temp/kuboard-data:/data \
+  -e KUBOARD_LOGIN_TYPE="ldap" \
+  -e KUBOARD_ENDPOINT="http://kuboard.mycompany.com" \
+  -e KUBOARD_ROOT_USER="shaohq" \
+  -e LDAP_HOST="host.docker.internal:389" \
+  -e LDAP_BIND_DN="cn=admin,dc=example,dc=org" \
+  -e LDAP_BIND_PASSWORD="admin" \
+  -e LDAP_BASE_DN="dc=example,dc=org" \
+  -e LDAP_FILTER="(objectClass=posixAccount)" \
+  -e LDAP_USER_NAME="uid" \
+  -e LDAP_ID_ATTRIBUTE="uid" \
+  -e LDAP_EMAIL_ATTRIBUTE="mail" \
+  -e LDAP_DISPLAY_NAME_ATTRIBUTE="cn" \
+  -e LDAP_GROUP_SEARCH_BASE_DN="dc=example,dc=org" \
+  -e LDAP_GROUP_SEARCH_FILTER="(objectClass=posixGroup)" \
+  -e LDAP_USER_MACHER_USER_ATTRIBUTE="gidNumber" \
+  -e LDAP_USER_MACHER_GROUP_ATTRIBUTE="gidNumber" \
+  -e LDAP_GROUP_NAME_ATTRIBUTE="cn" \
+  eipwork/kuboard:v3-alpha
+```
+
+
+::: tip 参数说明
+* 建议将此命令保存为一个 shell 脚本，例如 `start-kuboard.sh`，后续升级 Kuboard 或恢复 Kuboard 时，需要通过此命令了解到最初安装 Kuboard 时所使用的参数；
+* 第 4 行，Kuboard v3.0 需要暴露 `80` 端口，如安装指令的第三行所示，默认映射到了宿主机的 `80` 端口，您可以根据自己的情况选择宿主机的其他端口；
+* 第 5、6 行，Kuboard v3.0 需要暴露 `10081` 端口 TCP / UDP，默认映射到了宿主机的 `10081` 端口，您可以根据自己的情况选择宿主机的其他端口；
+* 第 7 行，Kuboard v3.0 的持久化数据存储在 `/data` 目录，默认映射到了宿主机的 `/root/kuboard-data` 路径，请根据您自己的情况进行调整；
+* 第 8 行，将 Kuboard v3.0 与 GitLab 进行单点登录集成时，必须指定环境变量 `KUBOARD_LOGIN_TYPE` 为 `gitlab` （适用于 gitlab.com / gitlab-ee / gitlab-ce）；
+* 第 9 行，必须指定 `KUBOARD_ENDPOINT` 环境变量为访问 Kuboard 界面的 URL；（如 [部署计划](#部署计划) 中所描述，本例子中，使用 `http://kuboard.mycompany.com` 作为通过执行此命令启动的 Kuboard 的访问 URL）；此参数不能以 `/` 结尾；
+* 第 10 行，必须指定 `KUBOARD_ROOT_USER`，使用该 GitLab 用户登录到 Kuboard 以后，该用户具备 Kuboard 的所有权限；
+* 第 11 行，指定 `GIBLAB_BASE_URL`，（如 [部署计划](#部署计划) 中所描述，本例子中，使用 `http://gitlab.mycompany.com` 作为通过作为 GitLab 的访问 URL，并假设 GitLab 已经事先准备就绪，如果不指定，该参数默认值为 `https://gitlab.com`）；此参数不能以 `/` 结尾；
+* 第 12 行，必须指定 `GITLAB_APPLICATION_ID`，该参数来自于 [准备 GitLab](#准备-gitlab) 步骤中创建的 GitLab  Application 的 `Application ID` 字段
+* 第 13 行，必须指定 `GITLAB_CLIENT_SECRET`，该参数来自于 [准备 GitLab](#准备-gitlab) 步骤中创建的 GitLab  Application 的 `Secret` 字段
+:::
+
+## 访问 Kuboard 界面
+
+* 在浏览器中输入 `http://kuboard.mycompany.com`，您将被重定向到 GitLab 登录界面；
+* 在 GitLab 登录界面使用 docker run 命令中 `KUBOARD_ROOT_USER` 参数指定的用户完成登录后，GitLab 将提示您是否授权访问 Kuboard，如下图所示：
+
+  ![image-20201113215827177](./install-gitlab.assets/image-20201113215827177.png)
+
+* 点击上图中的 ***Authorize*** 按钮后，您将成功登录 Kuboard 界面，第一次登录时，界面显示如下所示：
+
+  根据 [部署计划](#部署计划) 的设想，如下表单的填写内容为：
+
+  | 参数名称                                             | 参数值                                                       | 参数说明                                                     |
+  | ---------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
+  | <div style="width: 170px;">Kuboard UI 访问地址</div> | <div style="width: 130px;">http://kuboard.mycompany.com</div> | 根据 [部署计划](#部署计划) ，安装在 Kubernetes 中的 Kuboard Agent 通过 http://kuboard.mycompany.com 这个 URL 访问 Kuboard Web 界面，此处为 Kubernetes 集群和 Kuboard 浏览器端用户设定了不同的访问域名（在 docker run 命令的 `KUBOARD_ENDPOINT` 参数指定）。 |
+  | Agent Server Host                                    | kuboard.mycompany.com                                        | 根据 [部署计划](#部署计划) ，安装在 Kubernetes 中的 Kuboard Agent 通过 kuboard.mycompany.com 解析到 Kuboard 所在宿主机的 IP 地址 |
+  | Agent Server UDP 端口                                | 10081                                                        | 此端口必须与 docker run 命令中映射的 10081/udp 端口一致      |
+  | Agent Server TCP 端口                                | 10081                                                        | 此端口必须与 docker run 命令中映射的 10081/tcp 端口一致      |
+  
+  
+  ![image-20201115230236714](install-gitlab.assets/image-20201115230236714.png)
+  
+* 点击上图中的 ***保存*** 按钮，您将进入 Kuboard 集群列表页，此时，您可以向 Kuboard 添加 Kubernetes 集群，如下图所示：
+
+  ![image-20201113221543277](./install-gitlab.assets/image-20201113221543277.png)
+
+## 授权用户访问 Kuboard
+
+默认情况下，只有 `KUBOARD_ROOT_USER` 参数指定的用户可以执行 Kuboard 中的所有操作，其他用户通过单点登录进入 Kuboard 系统后，除了退出系统，几乎什么事情也做不了。为了让单点登录的用户获得合适的权限，您需要在 Kuboard 中为对应的用户/用户组授权。请参考 [为单点登录的用户/用户组授权](./auth-user-sso.html)

support/change-log/v3.0.x.md

@@ -13,6 +13,25 @@ description: 本文描述了Kuboard_v3.0.x的版本变更说明
 
 Kuboard v3.0.x 的更新说明
 
+## v3.0.0-alpha.3
+
+**发布日期**
+
+2020年11月15日
+
+**新特性**
+
+* Kuboard 与上游系统实现单点认证登录
+  * GitLab 单点认证登录
+  * GitHub 单点认证登录
+  * LDAP 单点认证登录
+* 单点登录模式下的用户授权
+
+**BUG修正**
+
+* 通用设置 --> 修改页脚文字时，输入框默认不应该为空
+* 集群概览页 --> StorageClass 列表、PV 列表 的链接错误
+
 
 ## v3.0.0-alpha.2