pikasTech-unidesk/.agents/skills/unidesk-ops/SKILL.md

---
name: unidesk-ops
description: UniDesk 手动运维 CLI — `server`、`gc`、YAML 声明的 `platform-db postgres` 与 host swap、platform-infra egress proxy 和 k3s dependency proxy benchmark 运维。覆盖主 server 启停、健康检查、swap、日志、Docker 镜像清理、磁盘 GC、服务重建/重启、host PostgreSQL、D601/D518 proxyserver 视角流量测速和 k3s 真实依赖拉取 benchmark。用户提到 server start、server status、server swap、host swap 扩容、server rebuild、server restart、gc、磁盘清理、platform-db、PostgreSQL、egress-proxy traffic、proxy 测速、k3s benchmark、apk/npm/go/git mirror 拉取测速时使用。
---

# UniDesk Ops

主 server、GC 和 PK01 PostgreSQL 的手动运维入口。常规操作走 `bun scripts/cli.ts server ...`、`gc ...`、`platform-db postgres ...`。

## 高频入口

```bash
bun scripts/cli.ts server status
bun scripts/cli.ts server start
bun scripts/cli.ts server stop
bun scripts/cli.ts server logs --tail-bytes 12000
bun scripts/cli.ts gc plan
bun scripts/cli.ts platform-db postgres status
bun scripts/cli.ts platform-db postgres swap plan --config config/platform-db/postgres-nc01.yaml
bun scripts/cli.ts platform-infra egress-proxy traffic --target D601 --sample-seconds 15
bun scripts/cli.ts platform-infra egress-proxy k3s-build-benchmark --targets D601,D518 --profile real-deps-500m --dry-run
```

启停、健康检查、节点资源指标、swap、日志、服务重建/重启见 [references/server.md](references/server.md)；Docker 镜像清理和磁盘 GC 见 [references/gc.md](references/gc.md)；PK01 PostgreSQL、YAML-first 运维、egress proxy 和 k3s benchmark 见 [references/platform-infra.md](references/platform-infra.md)。

## K3s Dependency Proxy Benchmark

用于验证 k3s CI/CD 构建出网性能时，必须用真实远程依赖，不用 Cloudflare synthetic。标准 profile 是 `real-deps-500m`：k3s 远程拉 `alpine:3.20`、`node:22-bookworm`、`golang:1.24-bookworm`，然后在 Pod 内跑 `apk add`、`npm install`、`go mod download`、`git clone --mirror` 和 `remote update --prune`；proxyserver 视角累计/窗口流量至少要能支撑 500MiB+ 验收。

```bash
# 计划预览：确认 D601/D518、镜像、pull policy、最小 proxy 流量和依赖集合。
bun scripts/cli.ts platform-infra egress-proxy k3s-build-benchmark \
  --targets D601,D518 --profile real-deps-500m --dry-run

# 启动 benchmark：fire-and-forget，同时启动 stage recorder 持久化阶段流量证据。
bun scripts/cli.ts platform-infra egress-proxy k3s-build-benchmark \
  --targets D601,D518 --profile real-deps-500m --confirm

# 状态表：看 APK/NPM/GO/GIT_MIRROR/REAL_DEPS、STAGE_PROXY、failure family 和可选即时采样。
bun scripts/cli.ts platform-infra egress-proxy k3s-build-benchmark status \
  --targets D601,D518 --profile real-deps-500m --traffic-sample-seconds 15

# 日志 drill-down：按 init container 展开 image pull、apk、npm、go、git mirror 阶段尾部。
bun scripts/cli.ts platform-infra egress-proxy k3s-build-benchmark logs \
  --targets D601,D518 --profile real-deps-500m --tail-lines 160

# 只看 proxyserver 视角实时/累计流量和 top client/destination。
bun scripts/cli.ts platform-infra egress-proxy traffic --target D601 --sample-seconds 15
bun scripts/cli.ts platform-infra egress-proxy traffic --target D518 --sample-seconds 15

# 清理测试 Job，避免慢速或失败样本继续占用 k3s 资源。
bun scripts/cli.ts platform-infra egress-proxy k3s-build-benchmark cleanup \
  --targets D601,D518 --profile real-deps-500m --confirm
```

D601/D518 结果必须分表记录：`STATE`、Job/run、duration、`APK/NPM/GO/GIT_MIRROR/REAL_DEPS`、`STAGE_PROXY`、`STAGE_PROXY_EVIDENCE`、`TRAFFIC_WINDOW`、`TRAFFIC_RATE`、`PROXY_CUM`、`TOP_CLIENT`、`TOP_DEST` 和 `FAILURE`。D518 通过不代表 D601 通过；D601 只证明 k3s/containerd 走到 proxy 也不等于性能达标。未完成 500MiB+ 的真实 k3s image pull + apk/npm/go/git mirror 测试前，不关闭对应 issue，不合并标记为等待运行面验收的 PR。

## Egress Proxy 运行面修复入口

- 多主机 k3s worker 的 bootstrap proxy：
  - 集群 owning YAML 通过 `hostProxyConfigRef` 组合 `config/platform-infra/host-proxy.yaml`。
  - 部署和验收统一走 `platform-infra k3s-cluster apply|status`。
  - 集群入口经 Windows 宿主内网 SSH 分发静态客户端到 guest。
  - Windows staging 工件按 YAML URL 获取并校验 SHA-256，Provider/trans 不搬运大二进制。
  - 启动 `k3s-agent` 前必须验证外网 probe。
  - WireGuard 只承载集群三层网络；NAT 或链路不稳定的 worker proxy 消费 `vpn-server` 输出的 Hysteria2 client YAML。
  - containerd 直接通过 host proxy 访问上游 registry，不使用公共镜像站。

`sub2api-egress-proxy` 的持久化配置从 `config/platform-infra/sub2api.yaml` 渲染，运行面变更必须通过受控 CLI 落地。不要把一次性 `kubectl patch` 留作最终状态。

```bash
bun scripts/cli.ts platform-infra sub2api apply --target D601 --dry-run
bun scripts/cli.ts platform-infra sub2api apply --target D601 --confirm --wait
bun scripts/cli.ts platform-infra sub2api status --target D601 --full
```

D601 若需要让 `sub2api-egress-proxy` 绕开 pod overlay，可在 YAML 中显式配置 egress proxy `hostNetwork: true`，manifest 必须同时使用 `dnsPolicy: ClusterFirstWithHostNet`，并用 `maxSurge=0/maxUnavailable=1` 避免 hostNetwork 端口冲突导致 rollout 残留 Pending pod。D518 当前保持 `hostNetwork: false`，不要把 D601 的运行面实验自动泛化到其它 node。

常见判读：
- `TOP_CLIENT=10.42.0.1` 且 `TOP_DEST=registry-1.docker.io:443`：k3s/containerd image pull 已从 proxyserver 视角可见。
- `TOP_DEST=dl-cdn.alpinelinux.org:443`：Pod 内 `apk` 阶段已走 proxy。
- `registry.npmjs.org:443`、`proxy.golang.org:443`、`github.com:443`：分别对应 `npm install`、Go module 拉取和 Git mirror clone/sync。
- `STAGE_PROXY_EVIDENCE` 是 Job annotation 中持久化的阶段证据；最终 `succeeded` 后仍应保留 apk/npm/go/git-mirror 各阶段 top destination、window bytes、max rate 和 proxy cumulative。`TRAFFIC_*` 列只是 status 命令即时采样。
- `image-pull` failure 表示还卡在 kubelet/containerd 拉镜像；`apk-download`、`npm-download`、`go-download`、`git-mirror` 分别表示 Pod 内依赖阶段失败。
- proxy 窗口 `0 B/s` 但 active cumulative 增长很慢时，按性能不达标处理；先清理 Job，再继续查上游，不要让慢速 benchmark 长时间占用资源。

## P0 边界

- PK01 默认只允许只读诊断：
  - 只有用户在当前请求中明确要求修改 PK01，才允许改变服务版本、YAML/Compose/systemd、数据库配置、容器、网络、Secret 绑定或其他运行面状态；
  - “修复”“恢复”“部署”“清理”或跨系统故障处理不自动扩大为 PK01 mutation 授权。
- backend-core 运行面恢复 healthy 后，除非用户明确要求，不主动 rebuild/restart/替换 backend-core。
- Master server 不作为通用构建机；Docker/Rust/Go/前端高 CPU 构建必须走批准的 CI/运行面。
- GC 默认 plan 只读，真实删除必须显式 `run --confirm` 并遵循 allowlist/retention。
- 已启用的远端 host swap 扩容使用 `platform-db postgres swap plan|apply --confirm|status`：
  - 总容量、主文件、扩展文件、`swappiness` 和 sysctl 文件只来自目标 YAML 的 `node.swap`；
  - 只新增缺失容量，不 `swapoff` 既有区域，不操作业务进程；
  - `apply --confirm` 只提交远端异步 job，随后用返回的 `--job-id` 查询；
  - swap 始终不计入 WebProbe 的真实 `MemAvailable` 门槛。
- Secret、database URL 和 API key 不打印完整值。
- k3s proxy benchmark 是运行面验收，不是源码层测试；长任务必须 start/status/logs/traffic 短轮询，结束或不达标时必须 cleanup。

## 何时读取 reference

- 需要服务 rebuild/restart、日志、swap 或 health 判定：读 [references/server.md](references/server.md)。
- 需要磁盘/镜像/trace GC：读 [references/gc.md](references/gc.md)。
- 需要 PK01 PostgreSQL 或 YAML-first 运维：读 [references/platform-infra.md](references/platform-infra.md)。
- 需要 k3s proxy benchmark 或 D601/D518 egress proxy 流量测速时，优先使用本 SKILL 的高频入口；涉及 CI/CD rollout 再加载 `$unidesk-cicd`。
- 需要 profile smoke、Moon Bridge 或 session recovery：读 [references/server.md](references/server.md)。