集群部署「k8s」

1. 适用场景

文档中台 K8s 集群部署适合正式上线、长期运行、需要高可用或后续扩容的场景。

推荐使用 3 master + N worker。最低准备 3 台服务器，3 台都作为 master，worker 可先复用 master 节点，后续再按规模增加 worker。

集群部署支持两种方式：

方式	适用情况
新建 K8s 集群	当前还没有可用 Kubernetes 环境
使用已有 K8s 集群	已有可用 Kubernetes 环境，并能提供集群访问凭据、namespace、存储路径

2. 部署前准备

2.1 先准备这些信息

信息	示例	说明
网络环境	在线 / 离线	支持公网访问选在线；内网或离线环境选离线
安装节点 IP	`<安装节点IP>`	选择 1 台作为安装节点，用来启动 Web 页面
业务节点 IP	`<节点1IP>`、`<节点2IP>`、`<节点3IP>`	新建 K8s 集群时至少 3 台服务器
执行用户	`root`	安装命令使用 `root` 执行
访问协议	HTTP / HTTPS	正式环境建议 HTTPS
访问域名	`<访问域名>`	访问文档中台 Demo 页和接口服务的地址
数据目录	`/data`	所有节点建议保持一致
安装工具	`mdp-installer`	石墨提供的安装器
产品安装包	文档中台安装包	以实际交付文件名为准
License 授权信息	以实际交付内容为准	安装或后台授权时使用
离线镜像包	`*.tar.gz`	仅离线安装需要
外部中间件	有 / 无	有外部中间件时，提前准备地址、端口、账号、密码

使用已有 K8s 集群时，还要准备：

集群访问凭据或 token。

namespace。

存储路径。

镜像仓库访问方式。

2.2 服务器最低要求

项目	要求
服务器数量	3 台及以上
推荐角色	`3 master + N worker`
每节点 CPU	16 Core 以上
每节点内存	32 GB 以上
系统盘	根 `/` 分区 100 GB 以上
数据盘	独立挂载 `/data`，可用空间 300 GB 以上
离线安装	安装节点数据盘建议额外预留 100 GB 以上

注意：

/root、/var、/tmp 建议放在根分区下统一管理。

数据目录统一放到 /data。

所有节点的时间必须同步。

安装节点需要能通过 SSH 访问其他节点。

可在每台服务器上执行：

在安装节点上确认能访问其他节点：

如登录未通过，先检查 SSH、密码、防火墙或安全组配置，再继续安装。

3. 上传安装工具和安装包

注意根据实际情况修改命令中的文件名称，例如安装器包名在x86架构环境为 mdp-installer-amd64。

根据实际场景选择适合的上传方式，本文以scp命令行说明，亦可使用其它图形化ssh工具上传。

在本地电脑执行下面命令，把安装器传到安装节点：

离线安装还要上传离线镜像包：

登录安装节点：

给安装器加执行权限：

启动安装器 Web 页面：

浏览器访问：

http://<安装节点IP>:18080

4. 通过 Web 页面安装

4.1 上传产品安装包

打开 http://<安装节点IP>:18080。

上传文档中台安装包。

上传完成后点击 继续。

4.2 配置访问域名

填写访问文档中台的方式：

配置项	怎么填
访问域名 / IP	`<访问域名>`

4.3 确认基础配置

配置项	怎么填
节点 IP	逐个填写 master / worker 节点 IP
SSH 端口	通常为 `22`
SSH 密码	`root` 用户密码
节点类型	`master`、`worker`、安装节点
数据目录	`/data`

操作步骤：

添加安装节点 IP。

添加各 master / worker 节点 IP。

为每台服务器分配节点角色。

测试安装节点到各节点的连通性。

填写数据目录和容器网段。

启用离线安装模式：
如果使用离线安装模式，需要上传离线包到服务器并浏览文件选择离线镜像文件

配置时重点确认：

访问协议和访问域名填写正确。

Pod CIDR、Service CIDR 与现网、办公网、VPN、IDC 网段不冲突。

数据目录使用 /data 或实际规划的数据盘目录。

在线 / 离线安装方式与当前网络环境一致。

离线安装需上传离线基础镜像包和应用镜像包，默认是在线安装，需要保证集群有可访问公网能力

4.4 初始化部署

配置完成后，点击初始化部署。页面会展示本次部署的概览信息，请重点检查：

产品包版本。

部署节点 IP。

SSH 用户和端口。

访问域名和协议。

数据目录。

在线或离线安装模式。

中间件选择。

确认无误后继续。

4.5 检查系统环境

安装器会自动检查服务器环境。

检查通过后继续部署。若出现失败项，请根据页面提示处理后重新检查。常见处理方向包括：

磁盘空间不足：清理空间或扩容数据盘。

端口不可用：释放端口或调整端口占用。

SSH 连接失败：检查账号、密码、私钥、端口和安全组。

时间同步异常：配置 NTP 或校准服务器时间。

基础命令缺失：按系统发行版安装缺失命令。

4.6 开始部署

环境检查通过后，点击开始部署。

部署过程中可以查看各组件执行日志。安装期间请保持：

安装器进程持续运行。

浏览器与安装节点网络连通。

服务器不要重启。

不要移动或删除安装包、离线镜像包和数据目录。

4.7 等待安装完成

安装过程需要等待一段时间，具体时间取决于服务器性能、网络环境和镜像拉取速度。

当页面显示所有任务执行成功，且没有失败组件时，表示部署完成。

4.8 确认安装结果

安装完成后，安装器会展示部署完成页面和访问入口信息。请先确认页面中没有失败任务，再继续访问业务系统和 MDP 运维平台。

文档中台业务对接域名：

http://<访问域名>

文档中台业务demo地址：

http://<访问域名>/sdk/demo

如果安装时配置了 HTTPS，请访问：

https://<访问域名>/sdk/demo

访问文档中台demo页面：
注：demo页面仅作演示测试使用！

访问 MDP 运维平台：

<安装完成页展示的 MDP URL>

如需修改 MDP 管理员密码，可在部署节点执行以下命令可修改重置密码。
请按实际安全要求将{password}替换为新的复杂强密码。

5. 安装后验收

5.1 检查 K8s 节点状态

在部署节点执行：

节点状态应为 Ready。

继续检查服务：

正常状态通常为：

Running：服务正在运行。

Completed：任务执行完成。

如出现 CrashLoopBackOff、ImagePullBackOff、Error、Pending 等状态，请先查看对应 Pod 日志并处理。

5.2 检查管理后台和 License

确认以下项目：

管理后台可以访问。

管理员可以登录。

License 页面可以打开。

机器信息可以查看。

可按授权流程申请或更新 License。

5.3 检查业务功能

使用测试账号或管理员创建的账号登录后，至少验证：

可以创建文档、表格、幻灯片。

文档可以编辑、保存、刷新后内容仍然存在。

多人协作编辑可用。

文件导入导出正常。

首次使用默认测试账号登录后，请立即修改密码。

账号：test@shimo.im
密码：Sm123456

5.4 停止安装器进程

部署完成并验收通过后，可停止安装器 Web 服务
安装web页面停止：

命令停止安装器：

如果安装器使用 nohup 后台启动，也可以查看日志：

6. 常见问题处理

6.1 浏览器无法打开安装器页面

检查方向：

安装器进程是否仍在运行。

18080 端口是否被防火墙或安全组拦截。

浏览器访问的 IP 是否为安装节点 IP。

可在服务器上执行：

6.2 环境检查不通过

根据页面提示逐项处理。处理完成后，返回安装器页面重新执行环境检查。

优先检查：

CPU、内存、磁盘是否满足要求。

/data 是否为独立数据盘。

服务器时间是否同步。

SSH 用户是否具备部署权限。

6.3 离线安装镜像拉取失败

检查方向：

离线镜像包是否已上传到部署节点。

基础离线镜像包和产品离线镜像包是否完整。

镜像包版本是否与产品安装包匹配。

私有镜像仓库地址、账号、密码是否填写正确。

6.4 Pod 长时间处于异常状态

先查看异常 Pod：

再查看日志：

根据日志处理镜像、配置、资源或依赖连接问题。

7. 安装后保留资料

部署完成后，建议保留以下资料，便于后续运维、升级和问题排查：

安装节点 IP、访问域名和访问协议。

安装器文件名和版本。

产品安装包文件名和版本。

离线镜像包文件名和版本。

Web 页面关键配置截图。

kubectl get node 检查结果。

kubectl get pod -A 检查结果。

License 授权记录。

业务功能验收记录。

部署过程中出现过的问题和处理结果。

1. 适用场景#

2. 部署前准备#

2.1 先准备这些信息#

2.2 服务器最低要求#

3. 上传安装工具和安装包#

4. 通过 Web 页面安装#

4.1 上传产品安装包#

4.2 配置访问域名#

4.3 确认基础配置#

4.4 初始化部署#

4.5 检查系统环境#

4.6 开始部署#

4.7 等待安装完成#

4.8 确认安装结果#

5. 安装后验收#

5.1 检查 K8s 节点状态#

5.2 检查管理后台和 License#

5.3 检查业务功能#

5.4 停止安装器进程#

6. 常见问题处理#

6.1 浏览器无法打开安装器页面#

6.2 环境检查不通过#

6.3 离线安装镜像拉取失败#

6.4 Pod 长时间处于异常状态#

7. 安装后保留资料#

1. 适用场景

2. 部署前准备

2.1 先准备这些信息

2.2 服务器最低要求

3. 上传安装工具和安装包

4. 通过 Web 页面安装

4.1 上传产品安装包

4.2 配置访问域名

4.3 确认基础配置

4.4 初始化部署

4.5 检查系统环境

4.6 开始部署

4.7 等待安装完成

4.8 确认安装结果

5. 安装后验收

5.1 检查 K8s 节点状态

5.2 检查管理后台和 License

5.3 检查业务功能

5.4 停止安装器进程

6. 常见问题处理

6.1 浏览器无法打开安装器页面

6.2 环境检查不通过

6.3 离线安装镜像拉取失败

6.4 Pod 长时间处于异常状态

7. 安装后保留资料