docs: move unidesk skills into repo
This commit is contained in:
Codex
@@ -0,0 +1,185 @@
|
||||
---
|
||||
name: unidesk-ops
|
||||
description: UniDesk 手动运维 CLI — `server` 和 `gc` 子命令，覆盖主 server 启停、健康检查、swap、日志、Docker 镜像清理、磁盘 GC 和服务重建。用户提到 server start、server status、server swap、server rebuild、gc、磁盘清理、运维时使用。
|
||||
---
|
||||
|
||||
# UniDesk 手动运维 CLI
|
||||
|
||||
主 server 运维入口，通过 `bun scripts/cli.ts server ...` 和 `bun scripts/cli.ts gc ...` 操作。
|
||||
|
||||
**固定入口前缀**: `cd /root/unidesk && bun scripts/cli.ts ...`
|
||||
|
||||
---
|
||||
|
||||
## 启停
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts server start
|
||||
bun scripts/cli.ts server stop
|
||||
```
|
||||
|
||||
异步 job 模式，返回 `job.id`、日志路径。`start` 执行 Docker 构建+启动，`stop` 停止 Compose project 全部服务。
|
||||
|
||||
---
|
||||
|
||||
## 健康检查
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts server status
|
||||
```
|
||||
|
||||
返回公开端口、受限宿主端口、内部端口、swap 摘要、Compose 容器状态、各服务健康检查和访问 URL。
|
||||
|
||||
低内存时 `swap.warning` 非空，先执行 `server swap ensure`。
|
||||
|
||||
---
|
||||
|
||||
## Swap 管理
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts server swap status
|
||||
bun scripts/cli.ts server swap ensure [--path /swapfile] [--size 2GiB] [--dry-run]
|
||||
```
|
||||
|
||||
`ensure` 在无 active swap 时创建 swapfile（`chmod 600`、`mkswap`、`swapon`、写 `/etc/fstab`）。已有 swap 时 no-op。fstab 写入失败返回 `degraded`。
|
||||
|
||||
---
|
||||
|
||||
## 日志
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts server logs
|
||||
```
|
||||
|
||||
返回文件日志和 Docker 容器日志尾部，默认限制输出大小。
|
||||
|
||||
---
|
||||
|
||||
## Docker 镜像清理
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts server cleanup plan [--min-age-hours 24] [--limit N]
|
||||
```
|
||||
|
||||
只生成 dry-run 计划，不执行删除。保守白名单：保留 running/stopped 容器镜像、deploy.json/CI.json commit-pinned artifact、Compose stable image。禁止 `docker system prune`、`docker volume rm`、`docker compose down -v`。
|
||||
|
||||
---
|
||||
|
||||
## 磁盘 GC
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gc plan
|
||||
bun scripts/cli.ts gc run --confirm
|
||||
bun scripts/cli.ts gc db-trace
|
||||
bun scripts/cli.ts gc policy
|
||||
bun scripts/cli.ts gc remote <providerId> [--target-use-percent N] [--dry-run|--confirm]
|
||||
```
|
||||
|
||||
主 server 和 provider 磁盘高水位缓解。`plan` 只读输出候选、风险、估算收益和保护对象。`run` 必须 `--confirm`。`remote` 通过 SSH 透传执行远端 GC。
|
||||
|
||||
---
|
||||
|
||||
## 服务重建
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts server rebuild <service>
|
||||
```
|
||||
|
||||
service 可选：`backend-core` | `frontend` | `dev-frontend-proxy` | `provider-gateway` | `todo-note` | `code-queue-mgr` | `project-manager` | `baidu-netdisk` | `oa-event-flow`
|
||||
|
||||
异步 job：构建镜像 → `.state/locks/server-compose.lock` 串行保护 → `--no-deps --force-recreate` 替换容器 → 等待 `healthy/running`。
|
||||
|
||||
启动后必须轮询 job，不要把提交 job 当成已经完成：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts server rebuild backend-core
|
||||
bun scripts/cli.ts job status <jobId> --tail-bytes 12000
|
||||
```
|
||||
|
||||
backend-core 重建完成后再做运行面验证：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts server status
|
||||
docker exec unidesk-backend-core sh -lc 'backend-core --fetch-json http://127.0.0.1:8080/health --require-ok'
|
||||
```
|
||||
|
||||
**禁止事项**：
|
||||
- backend-core 常规迭代不得在 master server 编译；只有已提交修复需要上线主 server Compose runtime 时，才用 `server rebuild backend-core` 受控异步 job
|
||||
- D601 Code Queue 执行面不由 `server rebuild` 管理
|
||||
- 不重建/删除 database 命名卷
|
||||
|
||||
---
|
||||
|
||||
## Moon Bridge 管理
|
||||
|
||||
Moon Bridge 是 Codex ↔ 上游 provider 的桥接服务，通过 profile 级 wrapper 管理：
|
||||
|
||||
```bash
|
||||
# DeepSeek profile
|
||||
dscx bridge-start
|
||||
dscx bridge-status
|
||||
dscx bridge-smoke dscx-bridge-ok
|
||||
dscx bridge-stop
|
||||
|
||||
# MiniMax profile
|
||||
mxcx bridge-start
|
||||
mxcx bridge-status
|
||||
mxcx bridge-smoke mxcx-bridge-ok
|
||||
mxcx bridge-stop
|
||||
```
|
||||
|
||||
- `dscx` → `127.0.0.1:38440`（Codex custom provider `deepseek`，DeepSeek V4 Pro）
|
||||
- `mxcx` → `127.0.0.1:38441`（Codex custom provider `minimax`，MiniMax-M3）
|
||||
- 启动用 `setsid` + profile-local PID file，进程不随 CLI 退出
|
||||
- 日志在 `<CODEX_HOME>/logs/moonbridge/`
|
||||
|
||||
---
|
||||
|
||||
## Codex Profile Smoke
|
||||
|
||||
```bash
|
||||
# DeepSeek
|
||||
dscx doctor
|
||||
dscx bridge-smoke dscx-bridge-ok
|
||||
dscx exec --skip-git-repo-check 'Reply exactly: dscx-codex-ok'
|
||||
|
||||
# MiniMax
|
||||
mxcx doctor
|
||||
mxcx bridge-smoke mxcx-bridge-ok
|
||||
mxcx exec --skip-git-repo-check 'Reply exactly: mxcx-codex-ok'
|
||||
```
|
||||
|
||||
`bridge-smoke` 验证 Moon Bridge → provider 链路。`exec` 验证完整 Codex CLI → bridge → provider 全链路。
|
||||
|
||||
---
|
||||
|
||||
## MiniMax Session Recovery
|
||||
|
||||
MiniMax 会话因无效 tool-call arguments 导致 `resume` 反复失败时的恢复流程：
|
||||
|
||||
```bash
|
||||
# 1. 清理无效 tool arguments
|
||||
mxcx session-clean <session-id-or-jsonl>
|
||||
|
||||
# 2. 确认幂等（应返回 changed=false）
|
||||
mxcx session-clean <session-id-or-jsonl>
|
||||
|
||||
# 3. 注入 guard 防止复发
|
||||
mxcx session-guard <session-id-or-jsonl>
|
||||
|
||||
# 4. 非交互 smoke 验证恢复
|
||||
mxcx exec resume <session-id> 'Reply exactly: recovered-ok'
|
||||
|
||||
# 5. apply-patch smoke（如涉及远端编辑）
|
||||
# 验证使用 trans <route> apply-patch，非 download/upload/sed
|
||||
```
|
||||
|
||||
`mxcx resume <session-id>` 自动执行 `session-clean` + `session-guard` 后再调用 Codex。修复最小化：只修无效 `function_call.arguments`，不压缩/截断/重排 transcript。
|
||||
|
||||
---
|
||||
|
||||
## 参考文档
|
||||
|
||||
- **主 server 架构与行为规范**: `/root/docs/reference/master-server-ops.md`（Execution Boundary、Codex Provider Profile 架构、Moon Bridge 内部规则、MiniMax session-clean 行为约束、apply-patch 策略）
|
||||
- **磁盘 GC 长期规则**: `docs/reference/gc.md`
|
||||
- **部署边界**: `docs/reference/deployment.md`
|
||||
Reference in New Issue
Block a user