支持地域：上海

微搭私有部署 Kubernetes 集群版部署指南

本文档将指导您在 Kubernetes 集群环境中部署微搭私有化平台，实现高可用、可扩展的企业级部署。

适用范围

K8s 集群版仅适用于微搭私有化企业版以上套餐

部署概述

微搭 Kubernetes 集群版提供了高可用、可扩展的部署方案，适用于生产环境和大规模应用场景。

部署架构

部署流程图

1. 环境准备

1.1 集群要求

运维能力要求

部署前请确保具备 Kubernetes 集群运维能力，K8s 底层相关运维不在维保范围内

硬件配置要求

组件类型	节点数量	配置要求	用途说明
微搭核心服务	3 个节点	8 核 vCPU + 16GB 内存	部署底座平台服务（多副本、高可用、支持滚动更新）
CI/CD 服务	1 个节点	4 核 vCPU + 8GB 内存	可选：内置自动部署或单独部署

软件环境要求

软件组件	版本要求	说明
Kubernetes	v1.22.0 以上	集群版本
kubectl	与集群版本兼容	安装指南
helm	3.x 版本	安装指南
Ingress Controller	任意兼容版本	配置指南

存储中间件要求

中间件依赖

以下中间件为必需组件，如无法提供请参考中间件部署指南

中间件类型	版本要求	配置指南
MySQL 数据库	8.x 版本	MySQL 配置指南
对象存储	S3 兼容协议	S3 对象存储配置指南

系统工具要求

确保部署环境已安装以下工具：

wget：用于下载部署脚本
unzip：用于解压安装包

1.2 网络配置要求

外网访问白名单

部署过程中需要访问以下外网地址，请确保网络策略允许：

地址	端口	用途
`weda-private.tencentcloudcr.com`	443	镜像仓库访问
`https://license.tcloudbasegateway.com`	443	证书激活/获取最新版本
`https://weda-private.tencentcloudcr.com`	443	镜像拉取
`https://tcr-9r3x9jec-1302110647.cos.ap-guangzhou.myqcloud.com`	443	镜像拉取

2. 部署配置

2.1 获取部署工具

根据服务器架构选择对应的部署工具：

x86_64 架构

# 创建部署目录
mkdir -p k8s_weda && cd k8s_weda

# 下载部署工具
wget -L -O wedaCli https://software-1302110647.cos.ap-guangzhou.myqcloud.com/rc/k8s/x86_64/lastest/wedaCli && chmod +x wedaCli

aarch64 架构

# 创建部署目录
mkdir -p k8s_weda && cd k8s_weda

# 下载部署工具
wget -L -O wedaCli https://software-1302110647.cos.ap-guangzhou.myqcloud.com/rc/k8s/arm64/lastest/wedaCli && chmod +x wedaCli

初始化配置

# 初始化配置文件
./wedaCli init

2.2 配置参数说明

编辑生成的 config.yml 文件，该文件用于生成 Helm values.yaml。主要配置参数说明：

微搭核心配置

配置项	说明	示例值
`weda.ns`	微搭部署的 K8s 命名空间	`weda-software`
`weda.ingressClass`	Ingress Controller 类名	使用 `kubectl get ingressClass` 获取
`weda.nodeSelector`	Pod 节点选择器	可选，用于指定部署节点
`weda.replicaCount`	服务副本数	默认：1
`weda.disableRollingUpdate`	是否禁用滚动更新	`false`（默认滚动更新）/ `true`（停服更新）

域名和访问配置

配置项	说明	示例值
`weda.domain`	微搭服务域名	`weda.example.com`（不含协议）
`weda.domainProtocol`	访问协议	`http` 或 `https`
`weda.tlsSecretName`	TLS 证书 Secret 名称	可选，HTTPS 访问时需要
`weda.license`	微搭许可证书	从控制台获取的 License

MySQL 数据库配置

配置项	说明	示例值
`middleware.mysql.host`	数据库主机地址	`mysql.example.com`
`middleware.mysql.port`	数据库端口	`3306`
`middleware.mysql.username`	数据库用户名	`weda_user`
`middleware.mysql.password`	数据库密码	`your_password`
`middleware.mysql.dbname`	设计态数据库名	`lowcode`
`middleware.mysql.dbRuntimeName`	运行态数据库名	`lcruntime`

数据库创建语句

-- 创建设计态数据库
CREATE DATABASE `lowcode` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建运行态数据库
CREATE DATABASE `lcruntime` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

S3 对象存储配置

配置项	说明	示例值
`middleware.s3.endpoint`	S3 服务地址	`s3.example.com`（不含协议）
`middleware.s3.port`	S3 服务端口	`9000`
`middleware.s3.scheme`	S3 访问协议	`http` 或 `https`
`middleware.s3.accessKey`	S3 访问密钥	`your_access_key`
`middleware.s3.secretKey`	S3 秘密密钥	`your_secret_key`
`middleware.s3.region`	S3 区域	`us-east-1`
`middleware.s3.pathStyle`	是否支持路径风格	`true` 或 `false`
`middleware.s3.insecureSkipVerify`	跳过证书验证	`false`（默认）

S3 存储桶配置

配置项	权限要求	用途说明
`middleware.s3.defaultBucket`	公有读私有写	默认存储桶
`middleware.s3.cloudStorageBucket`	私有读私有写	云存储桶
`middleware.s3.ciSource`	私有读私有写	CI/CD 源码桶

存储桶命名

上述三个存储桶不能同名，详细配置请参考：S3 对象存储配置指南

CI/CD 服务配置

外部 CI/CD 服务

配置项	说明	示例值
`middleware.build.enabled`	启用外部 CI/CD 服务	`true` 或 `false`
`middleware.build.wedaInternalHost`	内网 Host 配置	`"10.0.0.1 weda.example.com"`
`middleware.build.gitness.host`	Gitness 访问地址	`gitness.example.com`
`middleware.build.gitness.proxy`	微搭访问域名	`weda.example.com`

内置 CI/CD 服务

配置项	说明	示例值
`middleware.internalBuild.enabled`	启用内置 CI/CD 服务	`true` 或 `false`
`middleware.internalBuild.hostPath`	数据存放目录	`/data/cicd`
`middleware.internalBuild.nodeSelector`	节点选择器	可选配置

CI/CD 服务优先级

当 middleware.build.enabled 和 middleware.internalBuild.enabled 都为 true 时，系统将优先使用内置 CI/CD 服务

3. 部署执行

3.1 执行安装

完成配置后，执行安装命令：

./wedaCli install

3.2 验证部署状态

检查 Pod 状态

kubectl -n weda-software get po

预期输出示例：

NAME                                  READY   STATUS    RESTARTS   AGE
allin-one-design-b8f855787-58zsj      1/1     Running   0          44m
allin-one-runtime-66cf7b5658-pjw8c    1/1     Running   0          43m
gateway-7c7c786495-vprl6              1/1     Running   0          48m
idaasserver-b6bf65cfc-5dvvg           1/1     Running   0          48m
lcap-service-55dcb9fd-vcpxw           1/1     Running   0          48m
lowcode-5d45ffd9cc-zckxd              1/1     Running   1          48m
proxy-7bf84f8c48-bszw7                1/1     Running   0          48m
weda-plugin-adaptor-dd67659b5-4vcn8   1/1     Running   0          48m

所有 Pod 状态应为 Running，READY 列显示 1/1。

4. 访问配置

4.1 服务暴露配置

微搭集群版使用 Ingress 将服务暴露给外部访问。根据 Ingress Controller 的部署方式，配置方法有所不同：

NodePort 方式

访问方式：使用各节点的外部 IP 访问
负载均衡：需要外接 LB（负载均衡器）
适用场景：测试环境或有外部负载均衡器的环境

LoadBalancer 方式

访问方式：通过 LoadBalancer 的 EXTERNAL-IP 访问
配置步骤：
1. 查看 Ingress Controller 的 EXTERNAL-IP
2. 将 EXTERNAL-IP 与域名进行绑定

查看 Ingress Controller 状态：

# 查看 Ingress Controller 服务
kubectl -n ingress-nginx get svc

# 示例输出
NAME                      TYPE           CLUSTER-IP     EXTERNAL-IP    PORT(S)                      AGE
ingress-nginx-controller  LoadBalancer   10.0.134.188   192.168.2.40   80:30252/TCP,443:31414/TCP   52d

查看 Ingress 配置：

# 查看微搭 Ingress 配置
kubectl get ing -n weda-software

# 示例输出
NAME    CLASS   HOSTS                 ADDRESS        PORTS   AGE
proxy   nginx   weda-test-cloud.com   192.168.2.40   80      6d20h

4.2 DNS 配置

将集群外可访问的 IP 与配置的域名（weda.domain）进行映射：

生产环境

通过 DNS 服务配置域名解析
将域名指向 LoadBalancer 的 EXTERNAL-IP 或外部负载均衡器 IP

测试环境

在本地配置 hosts 文件进行解析
格式：<IP地址> <域名>

4.3 访问微搭平台

完成 DNS 配置后，可通过以下地址访问微搭平台：

开发平台地址：http://<weda.domain>/dev
默认登录信息：
- 用户名：admin
- 密码：Weda@123456
入门开发指南：
- 入门开发指南

域名说明

<weda.domain> 为步骤 2.2 中配置的域名

4.4 HTTPS 配置（可选）

如需通过 HTTPS 访问微搭服务，可在 Ingress 上配置 TLS 证书。

配置步骤

准备 TLS 证书文件
- 证书文件（.crt 或 .pem）
- 私钥文件（.key）
创建 TLS Secret
```
# 创建 TLS Secret
kubectl create secret tls weda-tls \
  --cert=path/to/cert/file \
  --key=path/to/key/file \
  -n weda-software
```
参数说明：
- tls：指定创建 TLS 类型的 Secret
- weda-tls：Secret 的名称，可自定义
- --cert：指定 TLS 证书文件的路径
- --key：指定 TLS 私钥文件的路径
- -n weda-software：指定命名空间

更新配置文件

在 config.yml 中添加 TLS 配置：

weda:
  domainProtocol: https
  tlsSecretName: weda-tls

重新部署
```
./wedaCli install
```

5. 运维管理

5.1 服务更新

当需要更新微搭服务时，按以下步骤操作：

切换到部署目录
```
cd k8s_weda
```
更新配置（可选）

根据需要修改 config.yaml 文件

更新部署工具

# 删除旧版本工具
rm wedaCli

# 下载新版本工具（参考 2.1 节）
wget -L -O wedaCli https://software-1302110647.cos.ap-guangzhou.myqcloud.com/rc/k8s/x86_64/lastest/wedaCli && chmod +x wedaCli

执行更新
```
./wedaCli install
```

5.2 License 续期

当 License 即将过期时，按以下步骤进行续期：

获取新的 License

从微搭控制台获取新的 License
备份环境文件
```
cd k8s_weda
mv env env-bak
```
更新配置文件

在 config.yaml 中替换 license 的值
执行续期
```
./wedaCli install
```

5.3 服务卸载

卸载警告

卸载操作将删除所有微搭服务，请确保已备份重要数据

卸载步骤

查询已部署的服务
```
helm list -n weda-software
```
卸载微搭服务
```
helm delete wedabaas -n weda-software
```
清理命名空间（可选）

重要警告
删除命名空间后，License 将无法继续使用，需要重新申请和配置。请谨慎操作！
```
kubectl delete namespace weda-software
```

6. 故障排查

6.1 常见问题

Pod 无法启动

检查节点资源是否充足
验证镜像拉取是否正常
查看 Pod 日志：kubectl logs <pod-name> -n weda-software

无法访问服务

检查 Ingress Controller 状态
验证 DNS 配置是否正确
确认防火墙和安全组配置

数据库连接失败

验证数据库配置参数
检查网络连通性
确认数据库权限设置

6.2 日志查看

# 查看特定 Pod 日志
kubectl logs <pod-name> -n weda-software

# 查看 Pod 详细信息
kubectl describe pod <pod-name> -n weda-software

# 查看 Ingress 状态
kubectl describe ingress -n weda-software

总结

通过本指南，您已经完成了微搭私有部署 Kubernetes 集群版的部署：

✅ 准备了符合要求的 K8s 集群环境
✅ 配置了必要的中间件服务
✅ 完成了微搭服务的部署和配置
✅ 设置了访问域名和 HTTPS（可选）
✅ 掌握了基本的运维管理操作

现在您可以开始使用微搭低代码平台进行企业级应用开发了。如遇到问题，请参考故障排查章节或联系技术支持。

部署概述​

部署架构​

1. 环境准备​

1.1 集群要求​

硬件配置要求​

软件环境要求​

存储中间件要求​

系统工具要求​

1.2 网络配置要求​

外网访问白名单​

2. 部署配置​

2.1 获取部署工具​

x86_64 架构​

aarch64 架构​

初始化配置​

2.2 配置参数说明​

微搭核心配置​

域名和访问配置​

MySQL 数据库配置​

S3 对象存储配置​

S3 存储桶配置​

CI/CD 服务配置​

外部 CI/CD 服务​

内置 CI/CD 服务​

3. 部署执行​

3.1 执行安装​

3.2 验证部署状态​

检查 Pod 状态​

4. 访问配置​

4.1 服务暴露配置​

NodePort 方式​

LoadBalancer 方式​

4.2 DNS 配置​

生产环境​

测试环境​

4.3 访问微搭平台​

4.4 HTTPS 配置（可选）​

配置步骤​

5. 运维管理​

5.1 服务更新​

5.2 License 续期​

5.3 服务卸载​

卸载步骤​

6. 故障排查​

6.1 常见问题​

Pod 无法启动​

无法访问服务​

数据库连接失败​

6.2 日志查看​

总结​