微搭私有部署内置 CI/CD 服务配置指南

本文档将指导您在微搭私有部署集群版中配置和启用内置 CI/CD 服务。

功能概述

微搭私有部署提供了内置的 CI/CD 服务，支持应用的自动构建、测试和部署流程。

版本支持

• v1.4.10 及以上版本：CI/CD 服务支持自动安装，无需单独部署
• v1.4.10 以下版本：需要先获取新版本的升级包或命令行工具 wedaCli 进行手动安装

服务类型说明

微搭提供两种 CI/CD 部署方式：

• 内置 CI/CD（internalBuild）：部署在 Kubernetes 集群内部（存储路径占用磁盘空间要求至少: 100G）
• 外部 CI/CD（build）：部署在集群外部的独立服务器上

两种方式必须至少启用一种，同时启用时优先使用内置 CI/CD 服务。

前置条件和要求

节点规划

为确保 CI/CD 服务的稳定运行，建议：

1. 专用节点部署：为 CI/CD 服务分配专用的 Kubernetes 节点
2. 资源隔离：避免与其他微搭服务部署在同一节点上
3. 数据持久化：配置专用的数据存储目录

关键配置要求

重要提示

以下配置必须正确设置，否则将导致数据丢失：

• **节点选择器（nodeSelector）和数据目录（hostPath）**必须在同一个节点上
• 如果不设置节点选择器和数据目录，CI/CD 数据无法持久化，构建历史记录将丢失
• 数据目录建议使用独立的大容量磁盘，避免系统盘空间不足

配置步骤

步骤 1：设置节点标签

首先需要为专用的 CI/CD 节点设置标签，用于节点选择器识别。

kubectl label nodes <node-name> weda-gitness=service

参数说明：

• <node-name>：替换为实际的 Kubernetes 节点名称
• weda-gitness=service：CI/CD 服务的节点选择器标签

查看节点名称：

kubectl get nodes

步骤 2：创建数据持久化目录

在设置了标签的节点上创建 CI/CD 数据存储目录：

mkdir -p /data1/gitness

目录规划建议：

生产环境注意事项

• 示例目录 /data1/gitness 可根据实际情况调整
• 强烈建议将数据目录放在独立的大容量磁盘上（至少100G）
• 避免使用系统盘，防止磁盘空间不足导致服务异常
• 确保目录具有适当的读写权限

推荐的目录结构：

# 生产环境推荐配置
/data/cicd/gitness          # 使用独立数据盘
/opt/weda/cicd/data         # 或使用专用分区（存储路径占用磁盘空间要求至少: 100G）

步骤 3：配置 CI/CD 服务

在微搭的配置文件中添加以下 CI/CD 服务配置：

internalBuild:
  # 启用内置 CI/CD 服务
  # true: 开启并自动部署内置 CI/CD 服务
  # false: 不开启内置 CI/CD 服务
  enabled: true
  
  # 节点选择器配置
  # 指定 CI/CD 服务部署的目标节点
  nodeSelector:
    weda-gitness: service
  
  # 数据持久化目录
  # 必须与 nodeSelector 指定的节点上的实际目录路径一致
  hostPath: "/data1/gitness"

配置参数详解

配置项	类型	必填	说明	示例值
enabled	boolean	是	是否启用内置 CI/CD 服务	true / false
nodeSelector	object	推荐	节点选择器标签，用于指定部署节点	weda-gitness: service
hostPath	string	推荐	数据持久化目录的绝对路径	/data1/gitness

配置策略说明

部署策略

必须启用的服务：

• internalBuild（内置 CI/CD）和 build（外部 CI/CD）必须至少启用一个
• 同时启用时，系统优先使用内置 CI/CD 服务

节点选择器策略：

• 设置 nodeSelector：CI/CD 服务将部署到指定标签的节点
• 不设置 nodeSelector：系统根据资源情况自动选择合适的节点

数据持久化策略：

• 设置 hostPath：CI/CD 数据将持久化保存，可查看构建历史
• 不设置 hostPath：数据不持久化，重启后构建历史丢失

部署和启动

步骤 4：应用配置并启动服务

完成上述配置后，执行以下操作启动 CI/CD 服务：

1. 保存配置文件：确保所有配置项已正确填写
2. 应用配置：按照 安装或重启服务 文档执行部署操作

验证部署结果

部署完成后，可以通过以下命令验证 CI/CD 服务状态：

# 查看 CI/CD 相关 Pod 状态
kubectl get pods -n software | grep gitness

# 查看服务日志
kubectl logs -f <gitness-pod-name> -n software -c gitness

# 验证数据目录
ls -la /data1/gitness

常见问题排查

服务无法启动

可能原因：

1. 节点标签设置错误
2. 数据目录权限不足
3. 磁盘空间不足

排查步骤：

# 1. 检查节点标签
kubectl get nodes --show-labels | grep weda-gitness

# 2. 检查目录权限
ls -ld /data1/gitness

# 3. 检查磁盘空间
df -h /data1

数据无法持久化

可能原因：

1. nodeSelector 和 hostPath 不在同一节点
2. 目录路径配置错误

解决方案：

1. 确认节点标签和数据目录在同一节点
2. 验证 hostPath 配置的路径是否正确

最佳实践建议

生产环境建议

1. 资源规划：为 CI/CD 服务分配足够的 CPU 和内存资源
2. 存储规划：使用高性能 SSD 磁盘作为数据存储
3. 备份策略：定期备份 CI/CD 数据目录
4. 监控告警：配置服务状态和资源使用监控
5. 安全配置：限制 CI/CD 服务的网络访问权限

总结

通过以上步骤，您已经成功：

1. ✅ 了解了内置 CI/CD 服务的功能和版本要求
2. ✅ 完成了节点标签和数据目录的配置
3. ✅ 掌握了 CI/CD 服务的配置参数和部署方法
4. ✅ 学会了常见问题的排查和解决方法

现在您可以在微搭私有部署环境中充分利用内置 CI/CD 服务的强大功能，实现应用的自动化构建和部署。