docs: move sub2api skill into unidesk
This commit is contained in:
Codex
@@ -0,0 +1,140 @@
|
||||
---
|
||||
name: unidesk-sub2api
|
||||
description: UniDesk Sub2API 平台运维技能。用户提到 Sub2API、sub2api、platform-infra sub2api、Codex pool、统一 API key、Sub2API FRP 暴露、Sub2API 管理 UI、配置 master ~/.codex 走 Sub2API、添加/删除 Codex 上游账号、校验 Sub2API /v1/models 时使用。
|
||||
---
|
||||
|
||||
# UniDesk Sub2API
|
||||
|
||||
UniDesk 在 G14 k3s `platform-infra` namespace 运维 Sub2API。日常操作统一使用 UniDesk CLI，不直接写 Kubernetes 资源或手工调用 Sub2API 管理 API。
|
||||
|
||||
**固定入口**: `cd /root/unidesk && bun scripts/cli.ts platform-infra sub2api ...`
|
||||
|
||||
## 先读边界
|
||||
|
||||
- 仓库长期开发边界见 `docs/reference/platform-infra.md`，本 skill 承担日常操作手册。
|
||||
- 配置真相是 YAML：`config/platform-infra/sub2api.yaml` 和 `config/platform-infra/sub2api-codex-pool.yaml`。
|
||||
- Runtime 在 `G14:k3s` 的 `platform-infra` namespace；master server 只是控制端和消费者，不部署 Sub2API/PostgreSQL/Redis。
|
||||
- Secret、`~/.codex/config.toml*`、`~/.codex/auth.json*` 是运行时输入或本地状态，不提交。
|
||||
- 输出只能包含 Secret 路径、长度、preview/fingerprint；禁止打印完整 API key、admin password、JWT secret、TOTP key。
|
||||
|
||||
## 部署与状态
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts platform-infra sub2api plan
|
||||
bun scripts/cli.ts platform-infra sub2api apply --dry-run
|
||||
bun scripts/cli.ts platform-infra sub2api apply --confirm
|
||||
bun scripts/cli.ts platform-infra sub2api status
|
||||
bun scripts/cli.ts platform-infra sub2api validate
|
||||
```
|
||||
|
||||
- `plan` 读取 `config/platform-infra/sub2api.yaml`，渲染 `src/components/platform-infra/sub2api/sub2api.k8s.yaml`，检查 no Ingress/NodePort/LoadBalancer/hostPort/hostNetwork/resource limits。
|
||||
- `apply --confirm` 默认创建异步 job；按返回的 `job status` 命令轮询，再跑 `status` 和 `validate`。
|
||||
- `status --full|--raw` 只在需要展开远端 stdout/stderr 或原始 JSON 时使用。
|
||||
- `validate` 是按需验收，不是连续可用性探针。
|
||||
|
||||
## 镜像升级
|
||||
|
||||
1. 修改 `config/platform-infra/sub2api.yaml` 的 `image.repository`、`image.tag` 或 `pullPolicy`。
|
||||
2. 执行 `sub2api plan`，确认策略检查通过。
|
||||
3. 执行 `sub2api apply --confirm`，轮询 job 完成。
|
||||
4. 执行 `sub2api status`，确认运行镜像等于 YAML 声明。
|
||||
5. 执行 `sub2api validate` 或 `codex-pool validate` 做入口验收。
|
||||
|
||||
不要把镜像版本写进脚本常量、JSON 或 manifest 模板。
|
||||
|
||||
## Codex Pool
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts platform-infra sub2api codex-pool plan
|
||||
bun scripts/cli.ts platform-infra sub2api codex-pool sync --confirm
|
||||
bun scripts/cli.ts platform-infra sub2api codex-pool validate
|
||||
```
|
||||
|
||||
`config/platform-infra/sub2api-codex-pool.yaml` 控制：
|
||||
|
||||
- `pool.groupName`: Sub2API group 名称。
|
||||
- `pool.apiKeySecretName` / `pool.apiKeySecretKey`: 统一消费 API key 的 k3s Secret 位置，默认 `platform-infra/sub2api-codex-pool-api-key.API_KEY`。
|
||||
- `pool.minOwnerBalanceUsd`: pool key owner 最低余额，sync/validate 会补齐。
|
||||
- `profiles.entries`: 从 master `~/.codex/` 选择上游 profile 并映射到 Sub2API account。
|
||||
- `profiles.entries[].openaiResponsesWebSocketsV2Mode`: 需要 Responses WebSocket v2 的上游才设置，值为 `off`、`ctx_pool` 或 `passthrough`。
|
||||
- `profiles.entries[].upstreamUserAgent`: 少数要求 Codex CLI User-Agent 的上游才设置，不能含换行。
|
||||
|
||||
`sync --confirm` 会登录 Sub2API admin、创建/更新 group、创建/更新 YAML 中的 `unidesk-codex-*` accounts、创建/复用统一 API key Secret，并删除 YAML 中已移除且 `extra.unidesk_managed=true` 的 `unidesk-codex-*` account。
|
||||
|
||||
## 添加上游
|
||||
|
||||
1. 在 master `~/.codex/` 准备 profile 文件，例如 `config.toml.<profile>` 和 `auth.json.<profile>`。
|
||||
2. 在 `config/platform-infra/sub2api-codex-pool.yaml` 添加 `profiles.entries` 项，指定 `profile`、`accountName`、`configFile`、`authFile`。
|
||||
3. 如需要，给该项加 `priority`、`openaiResponsesWebSocketsV2Mode` 或 `upstreamUserAgent`。
|
||||
4. 跑 `codex-pool plan`，确认 profile 可读、`base_url` 和 API key 来源有效，且 stdout 未泄露完整 key。
|
||||
5. 跑 `codex-pool sync --confirm`。
|
||||
6. 跑 `codex-pool validate`。
|
||||
|
||||
普通新增上游是 YAML 操作，不走 CI/CD，不改代码。只有需要新增可复用 schema 能力时才修改 `scripts/src/platform-infra-sub2api-codex.ts`。
|
||||
|
||||
## 删除上游
|
||||
|
||||
1. 从 `config/platform-infra/sub2api-codex-pool.yaml` 删除对应 `profiles.entries` 项。
|
||||
2. 跑 `codex-pool plan` 检查 desired 列表。
|
||||
3. 跑 `codex-pool sync --confirm`。
|
||||
4. 确认输出 `accounts.pruned` 只包含期望删除项。
|
||||
5. 跑 `codex-pool validate`。
|
||||
|
||||
CLI 只会 prune `name` 以 `unidesk-codex-` 开头且 `extra.unidesk_managed=true` 的缺席账号。
|
||||
|
||||
## FRP 暴露
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts platform-infra sub2api codex-pool expose
|
||||
bun scripts/cli.ts platform-infra sub2api codex-pool expose --confirm
|
||||
```
|
||||
|
||||
- 由 `publicExposure` YAML 控制。默认公共端是 `publicBaseUrl`，master 本地消费端是 `masterBaseUrl`。
|
||||
- `expose --confirm` 只为 YAML 指定的 `remotePort` 补 master `frps` allow port，并在 G14 创建/更新 `sub2api-frpc`。
|
||||
- 同一个 FRP TCP 入口同时暴露 OpenAI-compatible API 和 Sub2API 管理 UI `/login`。不要另开第二个管理端口，除非 YAML 明确声明新的暴露决策。
|
||||
- Sub2API Kubernetes Service 继续保持 ClusterIP。
|
||||
|
||||
## 配置 master Codex 消费端
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts platform-infra sub2api codex-pool configure-local
|
||||
bun scripts/cli.ts platform-infra sub2api codex-pool configure-local --confirm
|
||||
```
|
||||
|
||||
`configure-local --confirm` 会：
|
||||
|
||||
- 从 `platform-infra/<apiKeySecretName>.<apiKeySecretKey>` 读取统一 API key。
|
||||
- 把当前 `~/.codex/config.toml` 和 `~/.codex/auth.json` 备份为 `.<backupSuffix>`，默认 `.pre-sub2api`。
|
||||
- 重写默认 `~/.codex` 消费端，指向 `publicExposure.masterBaseUrl`，provider 名称和 wire API 来自 `localCodex`。
|
||||
- 用统一 key 做一次 gateway 验证。
|
||||
|
||||
防递归规则：`profiles.entries` 中 default 上游应指向 `config.toml.pre-sub2api` / `auth.json.pre-sub2api`，不要把已经改成 Sub2API consumer 的默认文件再导回上游池。
|
||||
|
||||
## 验收口径
|
||||
|
||||
部署 closeout 至少包含：
|
||||
|
||||
- `sub2api status`：Deployment/StatefulSet/Service/Secret 可见，运行镜像与 YAML 一致。
|
||||
- `sub2api validate`：app、PostgreSQL、Redis 和 service proxy 基础检查通过。
|
||||
- `codex-pool validate`：统一 key 的 `GET /v1/models` 成功，owner balance 已满足 YAML 最小值。
|
||||
- 若 `publicExposure.enabled=true`，确认 FRP path 可用；`expose --confirm` 会用未带 key 的 public `/v1/models` 401 作为网关可达性探针。
|
||||
|
||||
如果要证明真实模型请求可用，使用最小 `/v1/responses` 或等价 Codex smoke。不要把 group-level `/v1/models` 成功解释成每个上游 account 都健康。
|
||||
|
||||
## 排障
|
||||
|
||||
- profile invalid：先修 `~/.codex/config.toml.<profile>` 的 `base_url`、`wire_api`、`model` 或 `auth.json.<profile>` 的 API key；不要在 YAML 中写密钥。
|
||||
- pool key 401：跑 `codex-pool sync --confirm` 重建 Sub2API key 与 k3s Secret 绑定，再跑 `codex-pool validate`。
|
||||
- FRP 不通：先看 `codex-pool expose --confirm` 输出的 `masterFrps`、`sub2api-frpc` 和 public 401 probe；需要低层证据时只用 `trans G14:k3s` 做 bounded 查询。
|
||||
- default profile 递归：检查 YAML default entry 是否使用 `*.pre-sub2api` 备份文件；必要时恢复备份后重新 `configure-local --confirm`。
|
||||
- 上游需要 WebSocket v2：只给该 profile 配 `openaiResponsesWebSocketsV2Mode: ctx_pool|passthrough`，跑 `sync --confirm`。
|
||||
- 上游要求 Codex User-Agent：只给该 profile 配 `upstreamUserAgent`，跑 `sync --confirm`。
|
||||
|
||||
## 禁止事项
|
||||
|
||||
- 不用原生 `kubectl apply/delete/patch` 作为正式操作入口。
|
||||
- 不在 master server 部署或运行 Sub2API/PostgreSQL/Redis。
|
||||
- 不新增 Ingress、NodePort、LoadBalancer、hostPort、hostNetwork 或宽 FRP 端口段。
|
||||
- 不给 Sub2API manifest 添加 CPU/memory limits，除非有新的 YAML 化明确决策。
|
||||
- 不打印完整 API key、admin password 或 Secret 明文。
|
||||
- 不把普通上游增删做成代码变更、CI/CD、feature flag 或兼容双路径。
|
||||
@@ -0,0 +1,7 @@
|
||||
interface:
|
||||
display_name: "UniDesk Sub2API"
|
||||
short_description: "Operate UniDesk Sub2API and Codex pool"
|
||||
default_prompt: "Use $unidesk-sub2api to operate the UniDesk Sub2API Codex pool safely."
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: true
|
||||
Reference in New Issue
Block a user