# dify-cce-gitops

**Repository Path**: yangdechao_admin/dify-cce-gitops

## Basic Information

- **Project Name**: dify-cce-gitops
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Dify CCE-Turbo 多环境GitOps部署仓库
## 一、仓库概述
本仓库基于ArgoCD+华为CodeHub实现Dify开发/生产环境统一管理，所有配置代码化、版本化，一套仓库维护两套隔离环境。
### 环境资源清单
| 环境 | 命名空间 | 访问域名                 | 中间件集群 | 镜像策略 | mTLS模式 |
|------|---------|----------------------|------------|----------|----------|
| prod | dify | dify.prod.XXXXXX.com | 商用高可用RDS/DCS/CSS/OBS-Prod | IfNotPresent | STRICT强制加密 |
| dev | dify-dev | dify.dev.XXXXX.com   | 轻量开发中间件集群/OBS-Dev | Always拉取最新 | PERMISSIVE兼容调试Pod |

## 二、目录说明
1. `argocd/`：ArgoCD Application CRD，分别对应dev、prod两套部署流水线
2. `env/prod/`：生产环境全套Helm values、Istio网格、网络策略、Secret模板
3. `env/dev/`：开发环境全套轻量化配置，资源规格减半，开启调试日志与HPA
4. `docs/`：部署操作文档、环境差异对比

## 三、前置依赖及其部署规范
### 前置依赖
1. 华为云CCE-Turbo集群，已安装ASM应用服务网格
2. 集群内部署ArgoCD，配置CodeHub仓库访问凭证
3. 华为云托管中间件：RDS PG17、DCS Redis7.x、CSS OpenSearch2.XX、OBS桶（分dev/prod）
4. 域名SSL证书托管至CCE Secret

### 部署规范
1. Secret仅保留模板文件，真实密码、AK/SK本地填充后通过kubectl注入集群，禁止提交Git
2. 环境变更流程：修改对应env下yaml → MR评审合并 → ArgoCD自动同步集群
3. 升级Dify版本：统一修改两个ArgoCD Application中的`targetRevision`Chart版本

## 四、环境切换操作
### 1. 初始化命名空间与Sidecar注入
```bash
# 生产环境
kubectl create ns dify
kubectl label ns dify istio-injection=enabled
# 开发环境
kubectl create ns dify-dev
kubectl label ns dify-dev istio-injection=enabled

# 生产校验
kubectl get ns dify --show-labels
# 开发校验
kubectl get ns dify-dev --show-labels
# 预期输出包含 istio-injection=enabled
```

### 2. 注入秘钥 （本地执行，不上传 Git）
```bash
# 生产密钥
kubectl apply -f env/prod/secrets/secret-template-prod.yaml -n dify
# 开发密钥
kubectl apply -f env/dev/secrets/secret-template-dev.yaml -n dify-dev
```


## 五、部署ArgoCD Application，启动GitOps同步

### 5.1 下发两套环境ArgoCD资源

```
# 生产环境ArgoCD应用
kubectl apply -f argocd/app-dify-prod.yaml -n argocd
# 开发环境ArgoCD应用
kubectl apply -f argocd/app-dify-dev.yaml -n argocd

# 校验ArgoCD应用创建完成
kubectl get application -n argocd
# 预期输出 dify-prod、dify-dev 两条记录
```

### 5.2 ArgoCD 手动触发首次同步

1. 方式1：命令行触发同步

```
# 生产同步
argocd app sync dify-prod
# 开发同步
argocd app sync dify-dev
```

2. 方式2：ArgoCD UI控制台，选中应用点击Sync同步按钮

### 5.3 同步状态观测

同步完成标准：应用状态为 `Synced` + `Healthy`
查看应用详细同步日志：

```
argocd app logs dify-prod
argocd app logs dify-dev
```

## 六、环境部署后完整校验流程

### 6.1 资源Pod数量校验

#### 生产环境（dify命名空间）

常驻业务Pod合计11个：frontend(2) + api(3) + worker(4) + sandbox(2)，外加一次性init-job迁移Pod

```
kubectl get pods -n dify
# 过滤运行中业务Pod，排除已完成init-job
kubectl get pods -n dify --field-selector=status.phase=Running | grep -v init
```

#### 开发环境（dify-dev命名空间）

常驻业务Pod合计4个：frontend(1) + api(1) + worker(1) + sandbox(1)

```
kubectl get pods -n dify-dev --field-selector=status.phase=Running | grep -v init
```

### 6.2 数据库迁移初始化校验

查看init-job执行日志，确认数据库表迁移无报错，输出`migrate success`

```
# 生产迁移日志
kubectl logs -l job-name=dify-init -n dify
# 开发迁移日志
kubectl logs -l job-name=dify-init -n dify-dev
```

### 6.3 ASM网格资源校验

校验网关、路由、mTLS策略全部正常同步

```
# 生产网格资源
kubectl get gateway,vs,dr,peerauth -n dify
# 开发网格资源
kubectl get gateway,vs,dr,peerauth -n dify-dev
```

### 6.4 业务访问验证

1. 本地配置域名DNS解析指向ELB公网IP
2. 浏览器访问对应域名
    - 生产：[https://dify.prod.XXXXXX.com](https://dify.prod.XXXXXX.com)
    - 开发：[https://dify.dev.XXXXXX.com](https://dify.dev.XXXXXX.com)
3. 验证功能：注册/登录、知识库上传、对话问答、文件上传OBS存储、向量检索正常

## 七、日常运维操作规范

### 7.1 Dify Chart版本升级流程

1. 修改`argocd/app-dify-prod.yaml`、`argocd/app-dify-dev.yaml`中`targetRevision`为目标Chart版本（如0.31.0）
2. 本地校验values文件与新版本Chart兼容，执行dry-run校验

```
# 生产dry-run校验
helm template dify https://langgenius.github.io/dify-helm/dify-0.31.0.tgz -f env/prod/helm/values-prod.yaml -n dify --dry-run
# 开发dry-run校验
helm template dify https://langgenius.github.io/dify-helm/dify-0.31.0.tgz -f env/dev/helm/values-dev.yaml -n dify-dev --dry-run
```

3. 提交代码MR至CodeHub，评审合并main分支
4. ArgoCD自动检测配置变更，执行滚动升级；也可手动sync加速发布
5. 升级完成后校验Pod重启、业务功能无异常

### 7.2 配置变更流程（资源/域名/中间件参数调整）

1. 修改对应环境下values.yaml或istio资源yaml
2. 本地执行helm dry-run校验语法无错误
3. 提交MR，评审人核对dev/prod差异
4. 合并main分支，ArgoCD自动同步集群生效

### 7.3 环境销毁操作（清理测试环境）

```
# 销毁开发环境所有资源
argocd app delete dify-dev
kubectl delete ns dify-dev
# 如需销毁生产环境（谨慎操作）
argocd app delete dify-prod
kubectl delete ns dify
```

## 八、常见故障排查手册

### 8.1 ArgoCD同步失败

1. 查看同步事件详情：`kubectl describe app dify-prod -n argocd`
2. 常见根因：CodeHub仓库地址错误、values文件yaml语法错误、Chart版本不存在、集群权限不足
3. 修复后重新提交代码，手动执行`argocd app sync`

### 8.2 Pod启动失败，无法连接中间件

1. 查看Pod日志：`kubectl logs <pod-name> -n dify`
2. 排查方向：Secret密钥填写错误、中间件内网地址变更、安全组未放行CCE网段、PG未安装pgvector扩展

### 8.3 域名访问404/502

1. 校验Gateway、VirtualService域名匹配是否正确
2. 查看istio-ingressgateway访问日志：`kubectl logs -n istio-system deploy/asm-ingressgateway`
3. 校验后端service端口与路由配置端口一致

### 8.4 mTLS流量不通（生产环境）

1. 检查PeerAuthentication模式是否为STRICT
2. 确认Pod已成功注入istio-proxy sidecar容器
3. 临时调试：切换为PERMISSIVE模式测试连通性，恢复后切回STRICT

### 8.5 知识库文件上传失败（OBS报错）

1. 核对Secret内OBS AK/SK、桶名称、区域endpoint是否匹配
2. 校验OBS桶策略，允许CCE集群内网访问写入