feat(skill): 增加 UniDesk Temporal 运维能力
This commit is contained in:
Codex
@@ -0,0 +1,136 @@
|
||||
---
|
||||
name: unidesk-temporal
|
||||
description: UniDesk Temporal 基础设施与工作流运维技能，覆盖 YAML-first 受控部署、native PostgreSQL、Kubernetes/逻辑 namespace、共享 gRPC、Web 管理入口、统一管理员密码、状态验证，以及 native SDK worker/workflow smoke。用户提到 Temporal、workflow、activity、worker、task queue、temporal.hwpod.com、Temporal namespace、Temporal Web 或 Temporal smoke 时使用。
|
||||
---
|
||||
|
||||
# UniDesk Temporal
|
||||
|
||||
## 核心事实
|
||||
|
||||
- 配置真相位于 `config/platform-infra/temporal.yaml`。
|
||||
- 数据库真相位于 `config/platform-db/postgres-nc01.yaml`：
|
||||
- 使用 NC01 host native PostgreSQL；
|
||||
- 禁止在 Kubernetes 内创建 PostgreSQL workload 或 PVC。
|
||||
- Kubernetes namespace 固定为 `temporal`。
|
||||
- 默认业务逻辑 namespace 固定为 `unidesk`，保留期由 owning YAML 声明。
|
||||
- 集群内共享入口为 `temporal-frontend.temporal.svc.cluster.local:7233`。
|
||||
- Web 管理入口为 `https://temporal.hwpod.com`。
|
||||
- Web 用户名来自 owning YAML；密码只来自 `/root/.unidesk/.env/unified-admin-password.txt`，并通过 `unidesk-secret` 分发。
|
||||
|
||||
## 操作边界
|
||||
|
||||
- 基础设施变更必须加载 `$unidesk-ymalops`，只修改 owning YAML 和受控 CLI 渲染器。
|
||||
- 部署、状态和验证只使用 `bun scripts/cli.ts platform-infra temporal ...`。
|
||||
- 临时 smoke worker 可以在 NC01 host native 启动，并跳过 CI/CD；不得把临时 worker 固化为 Kubernetes workload。
|
||||
- 正式应用 worker 的交付仍遵循应用自身的 YAML/Git/CI/CD 流程。
|
||||
- 不得硬编码 Service ClusterIP；native client 每次从 Service 只读解析当前 ClusterIP。
|
||||
- 不得读取、打印或从 Kubernetes Secret、Pod env、数据库和日志反解密码。
|
||||
- 不得用原生 `kubectl apply/delete`、Helm 或 Compose 建立第二套 Temporal 部署入口。
|
||||
|
||||
## 部署顺序
|
||||
|
||||
1. 检查 native PostgreSQL 计划并受控收敛：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts platform-db postgres plan \
|
||||
--config config/platform-db/postgres-nc01.yaml
|
||||
bun scripts/cli.ts platform-db postgres apply \
|
||||
--config config/platform-db/postgres-nc01.yaml \
|
||||
--confirm
|
||||
```
|
||||
|
||||
2. 通过统一 Secret 配置同步 Web 管理密码：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts secrets plan \
|
||||
--config config/secrets-distribution.yaml \
|
||||
--scope temporal \
|
||||
--target temporal-nc01
|
||||
bun scripts/cli.ts secrets sync \
|
||||
--config config/secrets-distribution.yaml \
|
||||
--scope temporal \
|
||||
--target temporal-nc01 \
|
||||
--confirm
|
||||
```
|
||||
|
||||
3. 先 plan 和服务端 dry-run，再执行异步 apply：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts platform-infra temporal plan --target NC01
|
||||
bun scripts/cli.ts platform-infra temporal apply --target NC01 --dry-run
|
||||
bun scripts/cli.ts platform-infra temporal apply --target NC01 --confirm
|
||||
```
|
||||
|
||||
4. 按 apply 返回的 job ID 查询终态，再验证运行面：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts job status <job-id> --tail-bytes 12000
|
||||
bun scripts/cli.ts platform-infra temporal status --target NC01 --full
|
||||
bun scripts/cli.ts platform-infra temporal validate --target NC01
|
||||
```
|
||||
|
||||
5. 只在 Temporal ready 后收敛共享公网入口：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts platform-infra public-edge apply --target NC01 --confirm
|
||||
bun scripts/cli.ts platform-infra public-edge status --target NC01
|
||||
```
|
||||
|
||||
## 验收标准
|
||||
|
||||
- Temporal server 与 UI 的 `readyReplicas` 达到 YAML 声明值。
|
||||
- frontend/UI endpoint 均存在。
|
||||
- 数据库模式显示 `nc01-host-native-postgresql`，Secret 只披露 presence/fingerprint，且 `valuesPrinted=false`。
|
||||
- 逻辑 namespace `unidesk` 存在。
|
||||
- `https://temporal.hwpod.com/healthz` 返回 `200`。
|
||||
- 未认证访问 Web 根路径返回 `401`。
|
||||
- 管理登录仅使用 repo-owned typed `web-probe` 命令；缺少 Temporal typed login smoke 时记录工具缺口，不得临时读取统一密码或复制一次性浏览器脚本。
|
||||
- `public-edge status` 可能被其他站点的探针拉低；必须同时核对 Temporal 单站点证据，不能把无关站点故障归因给 Temporal。
|
||||
|
||||
## Native Workflow Smoke
|
||||
|
||||
- 使用 `$unidesk-trans` 的远程临时实验合同：
|
||||
- `route` 使用 `NC01`；
|
||||
- `work_dir` 使用唯一 `/tmp/<task-id>`；
|
||||
- worker、client、task queue 和 workflow ID 均为一次性；
|
||||
- 使用官方 Temporal SDK；
|
||||
- 输出只保留 namespace、task queue、workflow ID、预期结果和 worker stop 状态；
|
||||
- 成功或失败后幂等清理整个实验目录。
|
||||
- 先动态解析 native 连接地址：
|
||||
|
||||
```bash
|
||||
trans NC01:k3s kubectl -n temporal get service temporal-frontend \
|
||||
-o jsonpath={.spec.clusterIP}:{.spec.ports[0].port}
|
||||
```
|
||||
|
||||
- smoke 必须完成以下闭环：
|
||||
- native worker 连接当前 Service ClusterIP；
|
||||
- client 在 `unidesk` namespace 提交唯一 workflow；
|
||||
- workflow 调用至少一个 activity；
|
||||
- client 校验精确返回值；
|
||||
- worker 明确进入 `STOPPED`；
|
||||
- 删除临时依赖、脚本、日志和 PID 文件。
|
||||
- NC01 `/tmp` 是独立 tmpfs；遇到 `ENOSPC` 时加载 `$unidesk-gc`，先区分根盘与 `/tmp`，不得直接清理 k3s、containerd、PVC 或并行任务目录。
|
||||
|
||||
## 常见故障
|
||||
|
||||
- server 报 dynamic config 文件不存在：
|
||||
- 检查 YAML 的 `runtime.server.dynamicConfigFilePath`；
|
||||
- 路径必须指向当前 server 镜像内实际文件。
|
||||
- UI 把 `TEMPORAL_UI_PORT=tcp://...` 当整数解析：
|
||||
- 检查 server/UI Pod spec 的 `enableServiceLinks: false`；
|
||||
- 不在容器内覆盖 Kubernetes 自动环境变量。
|
||||
- `/healthz` 返回 `401`：
|
||||
- Caddy sidecar 必须用互斥 `handle /healthz` 与认证 `handle`；
|
||||
- 其他路径继续启用 Basic Auth。
|
||||
- native host 无法解析 `.svc.cluster.local`：
|
||||
- 只读解析当前 Service ClusterIP；
|
||||
- 不修改 `/etc/hosts`，不增加 NodePort 或公网 gRPC。
|
||||
|
||||
## 跟踪与配合
|
||||
|
||||
- 基础设施可靠性任务记录在 `docs/MDTODO/platform-infra-runtime-reliability.md`。
|
||||
- 详细方案、偏差与验收证据写入对应 GitHub issue，并使用 `$unidesk-gh` 受控入口。
|
||||
- 跨 host 调试与临时 native smoke 使用 `$unidesk-daddev` 和 `$unidesk-trans`。
|
||||
- Web 公网验收使用 `$unidesk-webdev`。
|
||||
- 统一管理员密码生命周期使用 `$unidesk-secret`。
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "UniDesk Temporal"
|
||||
short_description: "受控管理 UniDesk Temporal 基础设施、工作流与 smoke 验证"
|
||||
default_prompt: "使用 $unidesk-temporal 检查 Temporal 运行面并执行一次受控 workflow smoke。"
|
||||
Reference in New Issue
Block a user