andre/kuboard-press
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

优化 Kuboard v3 的安装文档

Browse Source
This commit is contained in:
huanqing.shao
2021-01-09 23:24:25 +08:00
parent f7b4b4c03b
commit 8d30af5247
24 changed files with 77 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
install/v3-upgrade.md
View File

@ -23,10 +23,10 @@ meta:
sudo docker run -d \
--restart=unless-stopped \
--name=kuboard \
-p 80:80/tcp \
-p 10080:80/tcp \
-p 10081:10081/udp \
-p 10081:10081/tcp \
-e KUBOARD_ENDPOINT="http://kuboard.mycompany.com" \
-e KUBOARD_ENDPOINT="http://kuboard.this-is-a-sample.com:10080" \
-e KUBOARD_AGENT_SERVER_UDP_PORT="10081" \
-e KUBOARD_AGENT_SERVER_TCP_PORT="10081" \
-v /root/kuboard-data:/data \

BIN
install/v3/install-built-in.assets/image-20201110231839543.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 63 KiB

BIN
install/v3/install-built-in.assets/image-20201117194202143.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 184 KiB

BIN
install/v3/install-built-in.assets/image-20210109213231697.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 54 KiB

35
install/v3/install-built-in.md
View File

@ -14,19 +14,15 @@ meta:
在正式安装 kuboard v3 之前，需做好一个简单的部署计划的设计，在本例中，各组件之间的连接方式，如下图所示：
* 假设用户通过 http://kuboard.mycompany.com 访问 Kuboard v3；
* 假设用户通过 http://外网IP:10080 访问 Kuboard v3；
* 安装在 Kubernetes 中的 Kuboard Agent 通过 `kuboard.mycompany.com` 访问 Kuboard 的 Web 服务端口 80 / 443 和 Kuboard Agent Server 端口 10081。
::: tip 域名解析
* 必须能够通过 DNS 正确解析到该域名，如果直接在宿主机配置 `/etc/hosts` 文件，将不能正常运行；
* 如果不方便配置 DNS，也可以直接使用 IP 地址，例如 `http://192.168.32.21`。
:::
* 安装在 Kubernetes 中的 Kuboard Agent 通过 `内网IP` 访问 Kuboard 的 Web 服务端口 10080 和 Kuboard Agent Server 端口 10081。
<p>
<img src="./install-built-in.assets/image-20201117194202143.png" style="max-width: 600px; margin-left: 20px;"/>
<img src="./install-built-in.assets/image-20210109213231697.png" style="max-width: 600px; margin-left: 20px;"/>
</p>
安装 Kuboard 之前，假设：
* 您已经准备好了一个 Linux 服务器用于安装 Kuboard-V3，并且该机器上的 docker 版本不低于 19.03
@ -41,10 +37,11 @@ meta:
sudo docker run -d \
--restart=unless-stopped \
--name=kuboard \
-p 80:80/tcp \
-p 10080:80/tcp \
-p 10081:10081/udp \
-p 10081:10081/tcp \
-e KUBOARD_ENDPOINT="http://kuboard.mycompany.com" \
-e KUBOARD_ENDPOINT="http://内网IP:10080" \
# 内网 IP 不能是 127.0.0.1 或者 localhost \
-e KUBOARD_AGENT_SERVER_UDP_PORT="10081" \
-e KUBOARD_AGENT_SERVER_TCP_PORT="10081" \
-v /root/kuboard-data:/data \
@ -53,27 +50,23 @@ sudo docker run -d \
```
::: danger
kuboard.mycompany.com 是一个假想域名，请替换成您自己的域名（运行 Kuboard 的宿主机以及所有 Kubernetes 节点都可以解析该域名），或者使用 IP 地址；
* KUBOARD_ENDPOINT 参数的作用是，让部署到 Kubernetes 中的 `kuboard-agent` 知道如何访问 Kuboard Server；
* KUBOARD_ENDPOINT 中也可以使用外网 IP；
* 建议在 KUBOARD_ENDPOINT 中使用域名；
* 如果使用域名，必须能够通过 DNS 正确解析到该域名，如果直接在宿主机配置 `/etc/hosts` 文件，将不能正常运行；
:::
::: tip 参数解释
* 建议将此命令保存为一个 shell 脚本，例如 `start-kuboard.sh`，后续升级 Kuboard 或恢复 Kuboard 时，需要通过此命令了解到最初安装 Kuboard 时所使用的参数；
* 第 4 行，将 Kuboard Web 端口 80 映射到宿主机的 `80` 端口（您可以根据自己的情况选择宿主机的其他端口）；
* 第 4 行，将 Kuboard Web 端口 80 映射到宿主机的 `10080` 端口（您可以根据自己的情况选择宿主机的其他端口）；
* 第 5、6 行，将 Kuboard Agent Server 的端口 `10081/udp`、`10081/tcp` 映射到宿主机的 `10081` 端口（您可以根据自己的情况选择宿主机的其他端口）；
* 第 7 行，指定 KUBOARD_ENDPOINT 为 `http://kuboard.mycompany.com`，如果后续修改此参数，需要将已导入的 Kubernetes 集群从 Kuboard 中删除，再重新导入；
* 第 7 行，指定 KUBOARD_ENDPOINT 为 `http://内网IP`，如果后续修改此参数，需要将已导入的 Kubernetes 集群从 Kuboard 中删除，再重新导入；
* 第 8、9 行，指定 KUBOARD_AGENT_SERVER 的端口为 `10081`，此参数与第 5、6 行中的宿主机端口应保持一致，修改此参数不会改变容器内监听的端口 `10081`；
* 第 10 行，将持久化数据 `/data` 目录映射到宿主机的 `/root/kuboard-data` 路径，请根据您自己的情况调整宿主机路径；
:::
## 访问 Kuboard v3.0
在浏览器输入 `http://your-host-ip` 即可访问 Kuboard v3.0 的界面，登录方式：
在浏览器输入 `http://your-host-ip:10080` 即可访问 Kuboard v3.0 的界面，登录方式：
* 用户名： `admin`
* 密 码： `Kuboard123`
## 问题反馈
关于 Kuboard v3.0.0 版本的问题反馈，请加 QQ 群：656520037
<img style="padding: 10px; width: 200px; border: 1px solid #eee; border-radius: 5px;" src="https://kuboard.cn/images/kuboard_qq.png"/>

BIN
install/v3/install-github.assets/image-20201114140336932.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 277 KiB

BIN
install/v3/install-github.assets/image-20201115230700829.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 101 KiB

BIN
install/v3/install-github.assets/image-20210109221355583.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 416 KiB

BIN
install/v3/install-github.assets/image-20210109224747134.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 166 KiB

39
install/v3/install-github.md
View File

@ -32,18 +32,13 @@ Kuboard 支持多种认证方式：
* 用户通过 https://github.com 访问 github.com；
* 用户通过 http://kuboard.mycompany.com 访问 Kuboard v3；
* 用户通过 `http://外网IP:10080` 访问 Kuboard v3；
* Kuboard 通过 https://github.com 访问 GitHub API；
* 安装在 Kubernetes 中的 Kuboard Agent 通过 `kuboard.mycompany.com` 访问 Kuboard 的 Web 服务端口 80 / 443 和 Kuboard Agent Server 端口 10081。
* 安装在 Kubernetes 中的 Kuboard Agent 通过 `内网IP:10080` 访问 Kuboard 的 Web 服务端口 80 / 443 和 Kuboard Agent Server 端口 10081。
::: tip 域名解析
* 必须能够通过 DNS 正确解析到该域名，如果直接在宿主机配置 `/etc/hosts` 文件，将不能正常运行；
* 如果不方便配置 DNS，也可以直接使用 IP 地址，例如 `http://192.168.32.21`。
:::
![image-20201115230700829](./install-github.assets/image-20201115230700829.png)
![image-20210109224747134](./install-github.assets/image-20210109224747134.png)
本例子中，假设：
@ -68,11 +63,11 @@ Kuboard 支持多种认证方式：
| 字段名称 | 字段取值 | 字段描述 |
| -------------------------- | ----------------------------------------- | ------------------------------------------------------------ |
| Application name | kuboard-v3 | 标识用，填写任意名称即可 |
| Homepage URL | http://kuboard.mycompany.com | 根据 [部署计划](#部署计划)，此处应该填写 http://kuboard.mycompany.com |
| Homepage URL | http://外网IP:10080 | 根据 [部署计划](#部署计划)，此处应该填写 http://外网IP:10080 |
| 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 路径 |
| Authorization callback URL | http://外网IP:10080/sso/callback | 根据 [部署计划](#部署计划)，此处应该填写 http://外网IP:10080/sso/callback，`/sso/callback` 为 Kuboard 中处理 OAuth 回调的 URL 路径 |
![image-20201114154856032](./install-github.assets/image-20201114154856032.png)
![image-20210109221355583](./install-github.assets/image-20210109221355583.png)
* 在上图中点击 ***Register application*** 按钮之后，将进入新创建的 OAuth application 的详情页面，在该页面可以获得 ***Client ID*** 和 ***Client Secret*** 两个字段，如下图所示：
@ -87,12 +82,13 @@ Kuboard 支持多种认证方式：
sudo docker run -d \
--restart=unless-stopped \
--name=kuboard \
-p 80:80/tcp \
-p 10080: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_ENDPOINT="http://内网IP:10080" \
# 内网 IP 不能是 127.0.0.1 或者 localhost \
-e KUBOARD_AGENT_SERVER_UDP_PORT="10081" \
-e KUBOARD_AGENT_SERVER_TCP_PORT="10081" \
-e KUBOARD_ROOT_USER="shaohq" \
@ -103,16 +99,19 @@ sudo docker run -d \
```
::: danger
kuboard.mycompany.com 是一个假想域名，请替换成您自己的域名（运行 Kuboard 的宿主机以及所有 Kubernetes 节点都可以解析该域名），或者使用 IP 地址；
* KUBOARD_ENDPOINT 参数的作用是，让部署到 Kubernetes 中的 `kuboard-agent` 知道如何访问 Kuboard Server；
* KUBOARD_ENDPOINT 中也可以使用外网 IP；
* 建议在 KUBOARD_ENDPOINT 中使用域名；
* 如果使用域名，必须能够通过 DNS 正确解析到该域名，如果直接在宿主机配置 `/etc/hosts` 文件，将不能正常运行；
:::
::: tip 参数说明
* 建议将此命令保存为一个 shell 脚本，例如 `start-kuboard.sh`，后续升级 Kuboard 或恢复 Kuboard 时，需要通过此命令了解到最初安装 Kuboard 时所使用的参数；
* 第 4 行，Kuboard v3.0 需要暴露 `80` 端口，如安装指令的第三行所示，默认映射到了宿主机的 `80` 端口，您可以根据自己的情况选择宿主机的其他端口；
* 第 4 行，Kuboard v3.0 需要暴露 `80` 端口，如安装指令的第三行所示，默认映射到了宿主机的 `10080` 端口，您可以根据自己的情况选择宿主机的其他端口；
* 第 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）；此参数不能以 `/` 结尾；
* 第 9 行，必须指定 `KUBOARD_ENDPOINT` 环境变量为访问 Kuboard 界面的 URL；（如 [部署计划](#部署计划) 中所描述，本例子中，使用 `http://内网IP:10080` 作为通过执行此命令启动的 Kuboard 的访问 URL）；此参数不能以 `/` 结尾；
* 第 10、11 行，指定 KUBOARD_AGENT_SERVER 的端口为 `10081`，此参数与第 5、6 行中的宿主机端口应保持一致，修改此参数不会改变容器内监听的端口 `10081`；
* 第 12 行，必须指定 `KUBOARD_ROOT_USER`，使用该 GitHub 用户登录到 Kuboard 以后，该用户具备 Kuboard 的所有权限；
* 第 13 行，必须指定 `GITHUB_CLIENT_ID`，该参数来自于 [准备 GitHub](#准备-github) 步骤中创建的 GitHub OAuth Application 的 `Client ID` 字段
@ -123,7 +122,7 @@ kuboard.mycompany.com 是一个假想域名，请替换成您自己的域名（
上面的命令行可以用于和 github.com 集成，如果您使用 GitHub Enterprise，需要在命令行中增加如下两个参数：
* `GITHUB_HOSTNAME`，GitHub Enterprise 的 hostname，如
```sh
-e GITHUB_HOSTNAME="github.mycompany.com"
-e GITHUB_HOSTNAME="github.this-is-a-sample.com"
```
* `GITHUB_ROOT_CA`，如果您的 GitHub Enterprise 使用了自签名证书，则需要指定 GITHUB_ROOT_CA，否则，可以忽略此参数，如：
```sh
@ -135,10 +134,10 @@ kuboard.mycompany.com 是一个假想域名，请替换成您自己的域名（
## 访问 Kuboard 界面
* 在浏览器中输入 `http://kuboard.mycompany.com`，您将被重定向到 GitLab 登录界面；
* 在 GitLab 登录界面使用 docker run 命令中 `KUBOARD_ROOT_USER` 参数指定的用户完成登录后，GitLab 将提示您是否授权访问 Kuboard，如下图所示：
* 在浏览器中输入 `http://外网IP:10080`，您将被重定向到 GitHub 登录界面；
* 在 GitHub 登录界面使用 docker run 命令中 `KUBOARD_ROOT_USER` 参数指定的用户完成登录后，GitHub 将提示您是否授权访问 Kuboard，如下图所示：
![image-20201113215827177](./install-gitlab.assets/image-20201113215827177.png)
![image-20201114164729229](./install-github.assets/image-20201114164729229.png)
* 点击上图中的 ***Authorize*** 按钮后，您将成功登录 Kuboard 界面。

BIN
install/v3/install-gitlab.assets/image-20201112232710461.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 161 KiB

BIN
install/v3/install-gitlab.assets/image-20201113212028264.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 649 KiB

After

Width:  |  Height:  |  Size: 652 KiB

BIN
install/v3/install-gitlab.assets/image-20201113220547459.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 65 KiB

BIN
install/v3/install-gitlab.assets/image-20201115223736418.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 102 KiB

BIN
install/v3/install-gitlab.assets/image-20201115230226328.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 62 KiB

BIN
install/v3/install-gitlab.assets/image-20201115230236714.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 62 KiB

BIN
install/v3/install-gitlab.assets/image-20210109224438846.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 174 KiB

38
install/v3/install-gitlab.md
View File

@ -29,25 +29,21 @@ Kuboard 支持多种认证方式：
在正式安装 kuboard v3 之前，需做好一个简单的部署计划的设计，在本例中，各组件之间的连接方式，如下图所示：
* 用户通过 http://gitlab.mycompany.com 访问 gitlab；
* 用户通过 http://gitlab.this-is-a-sample.com 访问 gitlab；
* 用户通过 http://kuboard.mycompany.com 访问 Kuboard v3；
* 用户通过 http://外网IP:10080 访问 Kuboard v3；
* Kuboard 通过 http://gitlab.mycompany.com 访问 GitLab API；
* Kuboard 通过 http://gitlab.this-is-a-sample.com 访问 GitLab API；
* 安装在 Kubernetes 中的 Kuboard Agent 通过 `kuboard.mycompany.com` 访问 Kuboard 的 Web 服务端口 80 / 443 和 Kuboard Agent Server 端口 10081。
* 安装在 Kubernetes 中的 Kuboard Agent 通过 `内网IP:10080` 访问 Kuboard 的 Web 服务端口 10080 和 Kuboard Agent Server 端口 10081。
::: tip 域名解析
* 必须能够通过 DNS 正确解析到该域名，如果直接在宿主机配置 `/etc/hosts` 文件，将不能正常运行；
* 如果不方便配置 DNS，也可以直接使用 IP 地址，例如 `http://192.168.32.21`。
:::
![image-20201115223736418](./install-gitlab.assets/image-20201115223736418.png)
![image-20210109224438846](./install-gitlab.assets/image-20210109224438846.png)
本例子中，假设：
* 您已经准备好了一个 Linux 服务器用于安装 Kuboard-V3
* 您的 gitlab 已经完成安装且版本不低于 11，并且可以从用户的浏览器以及用于安装 Kuboard-V3 的服务器访问到（使用 URL http://gitlab.mycompany.com）
* 您的 gitlab 已经完成安装且版本不低于 11，并且可以从用户的浏览器以及用于安装 Kuboard-V3 的服务器访问到（使用 URL http://gitlab.this-is-a-sample.com）
* 本例子支持 gitlab-ce / gitlab-ee，也支持 gitlab.com
@ -61,7 +57,7 @@ Kuboard 支持多种认证方式：
| 字段名称 | 字段取值 | 字段说明 |
| ------------ | ------------------------------------------ | ------------------------------------------------------------ |
| Name | kuboad-v3 | 应用程序在 GitLab 中的标识，例如，此处填写了 kuboard-v3 |
| Redirect URI | http://kuboard.my-company.com/sso/callback | 登录成功后的回调 URL，必须填写绝对路径，且必须指定到 kuboard 的 `/sso/callback` 路径 |
| Redirect URI | http://外网IP:10080/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)
@ -79,16 +75,17 @@ Kuboard 支持多种认证方式：
sudo docker run -d \
--restart=unless-stopped \
--name=kuboard \
-p 80:80/tcp \
-p 10080: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_ENDPOINT="http://内网IP:10080" \
# 内网 IP 不能是 127.0.0.1 或者 localhost \
-e KUBOARD_AGENT_SERVER_UDP_PORT="10081" \
-e KUBOARD_AGENT_SERVER_TCP_PORT="10081" \
-e KUBOARD_ROOT_USER="shaohq" \
-e GITLAB_BASE_URL="http://gitlab.mycompany.com" \
-e GITLAB_BASE_URL="http://gitlab.this-is-a-sample.com" \
-e GITLAB_APPLICATION_ID="7c10882aa46810a0402d17c66103894ac5e43d6130b81c17f7f2d8ae182040b5" \
-e GITLAB_CLIENT_SECRET="77c149bd3a4b6870bffa1a1afaf37cba28a1817f4cf518699065f5a8fe958889" \
eipwork/kuboard:v3
@ -96,26 +93,29 @@ sudo docker run -d \
```
::: danger
kuboard.mycompany.com 是一个假想域名，请替换成您自己的域名（运行 Kuboard 的宿主机以及所有 Kubernetes 节点都可以解析该域名），或者使用 IP 地址；
* KUBOARD_ENDPOINT 参数的作用是，让部署到 Kubernetes 中的 `kuboard-agent` 知道如何访问 Kuboard Server；
* KUBOARD_ENDPOINT 中也可以使用外网 IP；
* 建议在 KUBOARD_ENDPOINT 中使用域名；
* 如果使用域名，必须能够通过 DNS 正确解析到该域名，如果直接在宿主机配置 `/etc/hosts` 文件，将不能正常运行；
:::
::: tip 参数说明
* 建议将此命令保存为一个 shell 脚本，例如 `start-kuboard.sh`，后续升级 Kuboard 或恢复 Kuboard 时，需要通过此命令了解到最初安装 Kuboard 时所使用的参数；
* 第 4 行，Kuboard v3.0 需要暴露 `80` 端口，如安装指令的第三行所示，默认映射到了宿主机的 `80` 端口，您可以根据自己的情况选择宿主机的其他端口；
* 第 4 行，Kuboard v3.0 需要暴露 `80` 端口，如安装指令的第三行所示，默认映射到了宿主机的 `10080` 端口，您可以根据自己的情况选择宿主机的其他端口；
* 第 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）；此参数不能以 `/` 结尾；
* 第 9 行，必须指定 `KUBOARD_ENDPOINT` 环境变量为访问 Kuboard 界面的 URL；（如 [部署计划](#部署计划) 中所描述，本例子中，使用 `http://内网IP:10080` 作为通过执行此命令启动的 Kuboard 的访问 URL）；此参数不能以 `/` 结尾；
* 第 10、11 行，指定 KUBOARD_AGENT_SERVER 的端口为 `10081`，此参数与第 5、6 行中的宿主机端口应保持一致，修改此参数不会改变容器内监听的端口 `10081`；
* 第 12 行，必须指定 `KUBOARD_ROOT_USER`，使用该 GitLab 用户登录到 Kuboard 以后，该用户具备 Kuboard 的所有权限；
* 第 13 行，指定 `GIBLAB_BASE_URL`，（如 [部署计划](#部署计划) 中所描述，本例子中，使用 `http://gitlab.mycompany.com` 作为通过作为 GitLab 的访问 URL，并假设 GitLab 已经事先准备就绪，如果不指定，该参数默认值为 `https://gitlab.com`）；此参数不能以 `/` 结尾；
* 第 13 行，指定 `GIBLAB_BASE_URL`，（如 [部署计划](#部署计划) 中所描述，本例子中，使用 `http://gitlab.this-is-a-sample.com` 作为通过作为 GitLab 的访问 URL，并假设 GitLab 已经事先准备就绪，如果不指定，该参数默认值为 `https://gitlab.com`）；此参数不能以 `/` 结尾；
* 第 14 行，必须指定 `GITLAB_APPLICATION_ID`，该参数来自于 [准备 GitLab](#准备-gitlab) 步骤中创建的 GitLab Application 的 `Application ID` 字段
* 第 15 行，必须指定 `GITLAB_CLIENT_SECRET`，该参数来自于 [准备 GitLab](#准备-gitlab) 步骤中创建的 GitLab Application 的 `Secret` 字段
:::
## 访问 Kuboard 界面
* 在浏览器中输入 `http://kuboard.mycompany.com`，您将被重定向到 GitLab 登录界面；
* 在浏览器中输入 `http://外网IP:10080`，您将被重定向到 GitLab 登录界面；
* 在 GitLab 登录界面使用 docker run 命令中 `KUBOARD_ROOT_USER` 参数指定的用户完成登录后，GitLab 将提示您是否授权访问 Kuboard，如下图所示：
![image-20201113215827177](./install-gitlab.assets/image-20201113215827177.png)

BIN
install/v3/install-ldap.assets/image-20201114170038294.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 109 KiB

BIN
install/v3/install-ldap.assets/image-20201115230620704.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 98 KiB

BIN
install/v3/install-ldap.assets/image-20210109231936944.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 155 KiB

35
install/v3/install-ldap.md
View File

@ -30,18 +30,14 @@ Kuboard 支持多种认证方式：
在正式安装 kuboard v3 之前，需做好一个简单的部署计划的设计，在本例中，各组件之间的连接方式，如下图所示：
* 用户通过 http://kuboard.mycompany.com 访问 Kuboard v3；
* 用户通过 http://外网IP:10080 访问 Kuboard v3；
* Kuboard 通过 `localhost:389` 和 `localhost:636` 访问 LDAP；
* 安装在 Kubernetes 中的 Kuboard Agent 通过 `kuboard.mycompany.com` 访问 Kuboard 的 Web 服务端口 80 / 443 和 Kuboard Agent Server 端口 10081。
* 安装在 Kubernetes 中的 Kuboard Agent 通过 `内网IP:10080` 访问 Kuboard 的 Web 服务端口 10080 和 Kuboard Agent Server 端口 10081。
::: tip 域名解析
* 必须能够通过 DNS 正确解析到该域名，如果直接在宿主机配置 `/etc/hosts` 文件，将不能正常运行；
* 如果不方便配置 DNS，也可以直接使用 IP 地址，例如 `http://192.168.32.21`。
:::
![image-20201115230620704](./install-ldap.assets/image-20201115230620704.png)
![image-20210109231936944](./install-ldap.assets/image-20210109231936944.png)
本例子中，假设：
@ -68,7 +64,7 @@ Kuboard 支持多种认证方式：
* 登录 phpLDAPadmin
在浏览器输入 `https://kuboard.mycompany.com:6443` ，按下图所示步骤登录 phpLDAPadmin：
在浏览器输入 `https://内网IP:10080:6443` ，按下图所示步骤登录 phpLDAPadmin：
| 字段名称 | 字段值 | 字段描述 |
| -------- | -------------------------- | -------------- |
@ -137,12 +133,13 @@ Kuboard 支持多种认证方式：
sudo docker run -d \
--restart=unless-stopped \
--name=kuboard \
-p 80:80/tcp \
-p 10080: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_ENDPOINT="http://内网IP:10080" \
# 内网 IP 不能是 127.0.0.1 或者 localhost \
-e KUBOARD_AGENT_SERVER_UDP_PORT="10081" \
-e KUBOARD_AGENT_SERVER_TCP_PORT="10081" \
-e KUBOARD_ROOT_USER="shaohq" \
@ -165,16 +162,19 @@ sudo docker run -d \
```
::: danger
kuboard.mycompany.com 是一个假想域名，请替换成您自己的域名（运行 Kuboard 的宿主机以及所有 Kubernetes 节点都可以解析该域名），或者使用 IP 地址；
* KUBOARD_ENDPOINT 参数的作用是，让部署到 Kubernetes 中的 `kuboard-agent` 知道如何访问 Kuboard Server；
* KUBOARD_ENDPOINT 中也可以使用外网 IP；
* 建议在 KUBOARD_ENDPOINT 中使用域名；
* 如果使用域名，必须能够通过 DNS 正确解析到该域名，如果直接在宿主机配置 `/etc/hosts` 文件，将不能正常运行；
:::
::: tip 参数说明
* 建议将此命令保存为一个 shell 脚本，例如 `start-kuboard.sh`，后续升级 Kuboard 或恢复 Kuboard 时，需要通过此命令了解到最初安装 Kuboard 时所使用的参数；
* 第 4 行，Kuboard v3.0 需要暴露 `80` 端口，如安装指令的第三行所示，默认映射到了宿主机的 `80` 端口，您可以根据自己的情况选择宿主机的其他端口；
* 第 4 行，Kuboard v3.0 需要暴露 `80` 端口，如安装指令的第三行所示，默认映射到了宿主机的 `10080` 端口，您可以根据自己的情况选择宿主机的其他端口；
* 第 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）；此参数不能以 `/` 结尾；
* 第 9 行，必须指定 `KUBOARD_ENDPOINT` 环境变量为访问 Kuboard 界面的 URL；（如 [部署计划](#部署计划) 中所描述，本例子中，使用 `http://内网IP:10080` 作为通过执行此命令启动的 Kuboard 的访问 URL）；此参数不能以 `/` 结尾；
* 第 10、11 行，指定 KUBOARD_AGENT_SERVER 的端口为 `10081`，此参数与第 5、6 行中的宿主机端口应保持一致，修改此参数不会改变容器内监听的端口 `10081`；
* 第 12 行，必须指定 `KUBOARD_ROOT_USER`，使用该 GitLab 用户登录到 Kuboard 以后，该用户具备 Kuboard 的所有权限；
:::
@ -206,13 +206,8 @@ LDAP 相关的参数相对复杂，本章节以 Kuboard 集成 LDAP 时，对 LD
## 访问 Kuboard 界面
* 在浏览器中输入 `http://kuboard.mycompany.com`，您将被重定向到 GitLab 登录界面；
* 在 GitLab 登录界面使用 docker run 命令中 `KUBOARD_ROOT_USER` 参数指定的用户完成登录后，GitLab 将提示您是否授权访问 Kuboard，如下图所示：
![image-20201113215827177](./install-gitlab.assets/image-20201113215827177.png)
* 点击上图中的 ***Authorize*** 按钮后，您将成功登录 Kuboard 界面。
* 在浏览器中输入 `http://外网IP:10080`，将进入登录界面；
* 在登录界面中输入您在 LDAP 中的用户名、密码，并点击登录按钮，您将可以成功登录 Kuboard。
## 授权用户访问 Kuboard
默认情况下，只有 `KUBOARD_ROOT_USER` 参数指定的用户可以执行 Kuboard 中的所有操作，其他用户通过单点登录进入 Kuboard 系统后，除了退出系统，几乎什么事情也做不了。为了让单点登录的用户获得合适的权限，您需要在 Kuboard 中为对应的用户/用户组授权。请参考 [为单点登录的用户/用户组授权](./auth-user-sso.html)

4
install/v3/proxy.md
View File

@ -16,7 +16,7 @@ meta:
在为 Kuboard 配置反向代理时，需要注意：
* WebContextRoot
* Kuboard 需要使用根路径进行访问，即 https://kuboard.mycompany.com/，而不能是 https://mycompany.com/kuboard/ 这样的二级路径；
* Kuboard 需要使用根路径进行访问，即 https://kuboard.this-is-a-sample.com/，而不能是 https://this-is-a-sample.com/kuboard/ 这样的二级路径；
* 启用 WebSocket
* Kuboard 中终端和日志的功能需要用到 WebSocket，需要在您的反向代理中配置 WebSocket，才能正常使用 Kuboard 的终端和日志功能；
@ -42,7 +42,7 @@ http {
server {
listen 80;
server_name kuboard.mycompany.com; # 替换成你的域名，应该与 KUBOARD_ENDPOINT 中的域名部分保持一致
server_name kuboard.this-is-a-sample.com; # 替换成你的域名
location / {
proxy_pass http://192.168.32.205:10080/; # 替换成你的 Kuboard IP 地址和端口，应该是 IP 地址，而不是 KUBOARD_ENDPOINT 参数的值

12
install/v3/tls.md
View File

@ -39,11 +39,11 @@ sudo docker run -d \
-v /hostpath/to/your/server.key:/etc/certs/my.company.com/server.key \
-e KUBOARD_TLS_CERT=/etc/certs/my.company.com/server.crt \
-e KUBOARD_TLS_KEY=/etc/certs/my.company.com/server.key \
-p 80:80/tcp \
-p 10080:80/tcp \
-p 443:443/tcp \
-p 10081:10081/tcp \
-p 10081:10081/udp \
-e KUBOARD_ENDPOINT="http://kuboard.mycompany.com" \
-e KUBOARD_ENDPOINT="http://kuboard.this-is-a-sample.com:10080" \
-e KUBOARD_AGENT_SERVER_UDP_PORT="10081" \
-e KUBOARD_AGENT_SERVER_TCP_PORT="10081" \
-v /root/kuboard-data:/data \
@ -65,13 +65,13 @@ Lets Encrypt 是一个开源免费的证书颁发机构，如果您直接在公
```sh {4,7,8}
sudo docker run -d \
--restart=unless-stopped \
-p 80:80/tcp \
-p 10080:80/tcp \
-p 443:443/tcp \
-p 10081:10081/tcp \
-p 10081:10081/udp \
-e KUBOARD_TLS_AUTOCERT=true \
-e KUBOARD_TLS_DOMAIN=kuboard.mycompany.com \
-e KUBOARD_ENDPOINT="http://kuboard.mycompany.com" \
-e KUBOARD_TLS_DOMAIN=kuboard.this-is-a-sample.com \
-e KUBOARD_ENDPOINT="http://kuboard.this-is-a-sample.com:10080" \
-e KUBOARD_AGENT_SERVER_UDP_PORT="10081" \
-e KUBOARD_AGENT_SERVER_TCP_PORT="10081" \
-v /root/kuboard-data:/data \
@ -83,4 +83,4 @@ sudo docker run -d \
* 第 7 行激活 Kuboard 中的 Lets Encrypt 客户端；
* 第 8 行指定 Lets Encrypt 颁发证书时对应的域名；
> 使用 Lets Encrypt 时，请将 `kuboard.mycompany.com` 域名指向您的 Kuboard 所在宿主机的公网 IP，并且确保 80, 443 端口开放。Kuboard 启动后，在您第一次访问 `https://kuboard.mycompany.com` 时，Lets Encrypt 将自动申请证书（浏览器上显示第一次访问将失败）。等候 1-5 分钟时间，再次访问 `https://kuboard.mycompany.com` 时，您将能够成功访问，证书也已经颁发并且自动配置好；通常免费证书有效期是一年时间，证书到期前一个月，系统会自动为您更新证书，无需您额外做任何操作。
> 使用 Lets Encrypt 时，请将 `kuboard.this-is-a-sample.com` 域名指向您的 Kuboard 所在宿主机的公网 IP，并且确保 80, 443 端口开放。Kuboard 启动后，在您第一次访问 `https://kuboard.this-is-a-sample.com` 时，Lets Encrypt 将自动申请证书（浏览器上显示第一次访问将失败）。等候 1-5 分钟时间，再次访问 `https://kuboard.this-is-a-sample.com` 时，您将能够成功访问，证书也已经颁发并且自动配置好；通常免费证书有效期是一年时间，证书到期前一个月，系统会自动为您更新证书，无需您额外做任何操作。