---
name: temporal-ops
description: >
  当用户需要清理 Temporal 工作流、重置开发环境的 Temporal、
  或排查 workflow 卡住/worker 连接失败等问题时使用。
  触发短语：Temporal 清理、workflow 卡住、worker 连不上、
  重置 Temporal、temporal reset、清理工作流。
---

# Temporal 运维技能

## 关键约束

> **生产环境绝对禁止全量重置和 namespace 删除。只能逐个终止 workflow。**

| 操作 | 开发环境 | 生产环境 |
|------|---------|---------|
| 全量重置（删 volume/DB） | ✅ 允许 | ❌ 禁止 |
| 删除 namespace | ✅ 允许 | ❌ 禁止 |
| 终止指定 workflow | ✅ 允许 | ✅ 允许 |
| 检查 task queue | ✅ 允许 | ✅ 允许 |

## 常见场景

### 场景 1：开发环境全量重置

当 Schema 迁移后 workflow 定义不兼容时：

**Docker Compose 方式**：
```bash
bash scripts/dev/dev.sh down
docker volume rm <temporal_data_volume> <temporal_es_volume>
bash scripts/dev/dev.sh up
# 等待 10 秒
npm run start:temporal
```

**Temporal CLI 方式**（本地开发）：
```bash
pkill -f "temporal server start-dev"
rm -rf ~/.temporal/development.db ~/.temporal/history
temporal server start-dev
npm run start:temporal
```

### 场景 2：生产环境清理 stale workflow

```bash
# 列出运行中的 workflow
temporal workflow list --query "ExecutionStatus='Running'"

# 终止指定 workflow
temporal workflow terminate --workflow-id <id> --reason "Schema migration cleanup"

# 批量终止旧 workflow
temporal workflow terminate --query "ExecutionStatus='Running' AND StartTime < '2026-03-01'"
```

### 场景 3：Worker 启动失败

常见原因和修复：
1. **Namespace 不存在** → 重建：`temporal operator namespace create --namespace default`
2. **Task queue 缓存过期** → 清理并重启：`rm -rf node_modules/.cache && npm run build && npm run start:temporal`
3. **版本不兼容** → 全量重置（仅开发环境）

### 验证

```bash
temporal operator namespace describe --namespace default  # namespace 存在
temporal workflow list --limit 5                          # 能查询 workflow
# 启动 worker 观察日志，应看到 "registered workflows" 和 "registered activities"
npm run start:temporal
# 提交一个测试审批，确认 workflow 能正常创建和执行
```