add git guide

docs/deployment-guide.md

@@ -0,0 +1,118 @@
+# 部署操作手册
+
+> 本文档说明如何将代码推送到测试环境和生产环境。
+> 日常开发在 `dev` 分支，生产发布通过合并到 `master` 分支触发。
+
+---
+
+## 环境说明
+
+| 环境 | 触发分支 | 镜像仓库 | K3s 集群 | 域名 |
+|------|---------|---------|---------|------|
+| 测试（development） | `dev` | `cr.volces.com/zyc/...` | `192.168.0.129:6443` | `airflow-studio.test.airlabs.art` |
+| 生产（production） | `master` | `gitea-prod-cn-shanghai.cr.volces.com/prod/...` | `192.168.0.130:6443` | `airflow-studio.airlabs.art` |
+
+---
+
+## 推送到测试环境
+
+只需要把代码推到 `dev` 分支，CI/CD 自动触发。
+
+```bash
+# 确认当前在 dev 分支
+git checkout dev
+
+# 提交代码
+git add .
+git commit -m "feat: 你的改动描述"
+
+# 推送触发构建
+git push origin dev
+```
+
+构建完成后在 Gitea Actions 查看进度：
+- Build and Push Backend ✅
+- Build and Push Web ✅
+- Setup Kubectl ✅
+- Deploy to K3s ✅
+
+---
+
+## 推送到生产环境
+
+> ⚠️ **注意**：操作完成后必须切回 `dev` 分支，不要在 `master` 上继续开发。
+
+### 完整流程
+
+```bash
+# 1. 确保 dev 分支代码是最新的
+git checkout dev
+git pull origin dev
+
+# 2. 切换到 master 分支
+git checkout master
+
+# 3. 合并 dev 的代码
+git merge dev
+
+# 4. 推送到远程，触发生产构建
+git push origin master
+
+# 5. ⚠️ 立刻切回 dev，不要停留在 master
+git checkout dev
+```
+
+### 如果有合并冲突
+
+```bash
+# 解决冲突后
+git add .
+git commit -m "merge: dev into master"
+git push origin master
+git checkout dev
+```
+
+---
+
+## 构建失败排查
+
+### Build and Push 失败（docker pull 超时）
+Docker 镜像拉取超时，CI 会自动重试 3 次。如仍失败，检查构建机网络。
+
+### Setup Kubectl 失败（command not found）
+kubectl 未安装或下载失败，CI 会自动从 daocloud 镜像安装。
+
+### Deploy to K3s 失败（i/o timeout）
+K3s API Server 连接超时，CI 会自动重试 3 次（每次间隔 10 秒）。
+- 若持续失败，检查 K3s 节点状态：`kubectl get nodes`
+- 确认 kubeconfig secret（`VOLCANO_TEST_KUBE_CONFIG` / `VOLCANO_PROD_KUBE_CONFIG`）有值
+
+---
+
+## 快速检查部署状态
+
+```bash
+# 测试环境
+ssh root@14.103.63.199
+kubectl get pods -n default
+
+# 生产环境
+ssh root@118.196.0.100
+kubectl get pods -n default
+```
+
+---
+
+## Celery Worker 监控
+
+Celery worker 负责轮询火山 API 的视频生成状态。
+
+```bash
+# 查看 worker 日志（测试环境）
+kubectl logs -f deployment/celery-worker -n default
+
+# 查看队列积压（测试环境 Redis）
+redis-cli -h redis-shzlsczo52dft8mia.redis.ivolces.com -p 6379 -a Zyc188208 llen celery
+```
+
+`recover_stuck_tasks` 定时任务每 3 分钟自动扫描卡住的任务并重新入队，无需手动干预。