ops CLI admin settings queue

摘要:pnpm ops admin / settings / queue / knowledge:embed / knowledge:eval 是一组直连数据库与 Redis 的运维命令,与 API server 完全解耦。本文把这 5 条命令的真实代码拆开看,讲清楚三件事:① 运维 CLI 为什么不能依赖 NestJS;② admin 的幂等 init 与默认密码生成策略;③ settings 的「check → reinit --yes」两阶段破坏性操作;④ queue 的 7 个子命令与 --yes 安全闸门;⑤ knowledge:* 的 DASHSCOPE_API_KEY 降级路径。每个命令都给出可复制的实战片段。

关键词:ops CLI、admin、settings、queue、knowledge:embed、knowledge:eval、BullMQ、运维命令、idempotent

一、凌晨 3 点那通电话里,运维真正缺的是什么

凌晨 3 点,电话响了。客服转过来一句:「财务说上个月的抖店账单还卡在『解析中』,进不去对账。」你 SSH 到服务器,想看一眼 Redis 里 bill-parse 队列到底堆了多少——但你打开 Redis Desktop Manager 又要 1 分钟,登堡垒机又要 1 分钟,看 BullMQ key 又要 30 秒,等你拼出来「waiting=132,active=0,failed=87」的时候,财务经理已经在群里贴了第二条消息。

更尴尬的是:你想查 87 条 failed 的 failedReason,只能在 Redis 里 HGETALL bull:bill-parse:failed 一条条翻——但 87 条 failed 在 Redis 是按 hash 存而不是 list,HGETALL 一次拉完会让你的终端卡 3 秒。日常 80% 的「队列/参数/账号」类运维需求,根本不需要启动 API server,也不需要连 Navicat / Redis Desktop Manager。

这就是运维 CLI 存在的意义:一个与 NestJS 完全解耦的注册表式命令集,直连 PostgreSQL 和 Redis,5 条命令覆盖 80% 现场运维。这种设计在运维圈有个不成文的名字——「最后一根稻草」——API server 起不来、worker 全挂的时候,你依然能用它直接看数据库的真实状态。

下面这张部署架构图解释了 ops CLI 在生产拓扑里的真实位置:它不走 nginx、不经过 API 进程,直接用 Prisma Client 落 PostgreSQL、用 ioredis 直连 Redis。在凌晨 3 点那通电话里,这种「不需要任何中间环节」的链路就是你的救命稻草:

图 1:ops CLI 横跨「容器进程」(docker compose 管 PG/Redis)与「Node 进程」(API/Web)之外,第三条直连路径——CLI 用 Prisma Client 与 ioredis 直接命中数据库和 Redis,不依赖 NestJS DI、不启动 HTTP server、不占用 worker 进程。这是它能在「API 起不来」「worker 卡死」「Redis 队列爆」3 种现场都能救命的设计基础。

注意 ops CLI 不是「Shell 脚本合集」,而是一个注册表架构:每个命令是一个实现 CommandModule 接口的对象(4 个字段: name / description / usage / run),新增命令只需在命令目录下加一个文件 + 在注册表数组里追加一行。下面第六节会演示这个流程。

二、admin 命令:幂等 init + 12 字节随机密码

admin 命令覆盖三类现场:① 首次部署没有 ADMIN;② 忘记密码或账号被锁;③ 审计要列所有管理员。它有 3 个子命令,核心是 init——幂等(idempotent):已存在同邮箱时会覆盖密码 / 姓名 / 角色 / active 状态,但不会重复创建也不会报错。

2.1 三个子命令速查

# 创建或更新系统管理员 (idempotent)
pnpm ops admin init
pnpm ops admin init --email ceo@recon.com --password 'MyStrong#Pass1'
pnpm ops admin init --email admin@recon.com --name '系统管理员'

# 重置任意用户的密码 (同时把账号设为 active)
pnpm ops admin reset-password user2@example.com
pnpm ops admin reset-password user2@example.com --password 'temp-pass'

# 列出所有 ADMIN 角色用户
pnpm ops admin list

2.2 默认密码:12 字节 base64url 的设计取舍

init 默认密码用 crypto.randomBytes(12).toString("base64url") 生成,12 字节 = 96 位熵,base64url 编码后是 16 个可见字符(无 + / =,SSH / HTTP header / shell 转义都安全)。下面是真实代码:

// 命令实现片段(节选自 admin 子命令源文件)
function generatePassword(): string {
  return randomBytes(12).toString("base64url");
}

为什么不直接用 UUID? UUID v4 是 16 字节,但默认带连字符,粘贴到登录框里需要去掉 4 个连字符。base64url 无分隔符、可读性高于 hex。为什么不直接用 16 字节? randomBytes(16).toString("base64url") 会得到 22 字符,人眼记忆负担过重——12 字节是「机器生成 + 人工抄写」的最优交叉点。

2.3 幂等的工程价值:可重复跑而不污染数据

init 之所以设计成幂等,是因为它会被嵌进两套自动化流程:

• 新服务器初始化脚本:./setup.sh 里调一次,失败了重试不会留下半截数据
• 灾备切换流程:把 PG 恢复到昨日快照后,重跑所有 init 命令就能恢复到崩溃前一刻的账号状态——前提是 init 不能因为「邮箱已存在」报错

代码层的实现是 findUnique → 分支到 update 或 create,这是 admin.ts:21-50 的核心 30 行:

const existing = await prisma.user.findUnique({ where: { email: opts.email } });
if (existing) {
  await prisma.user.update({ /* 重置密码/姓名/角色/active */ });
  console.log(`✓ 已更新管理员 ${opts.email}`);
} else {
  await prisma.user.create({ /* 首次创建 */ });
  console.log(`✓ 已创建管理员 ${opts.email}`);
}

2.4 安全注意事项:密码明文打印不是 bug,是 feature

admin init 会把生成的密码明文打印到 stdout,共享屏幕 / 录屏场景下要小心。这不是设计漏洞,而是有意为之——遮罩处理需要用户交互(inquirer prompt),而 CLI 多数场景是非交互的(SSH / CI)。文档明示「密码以明文打印到 stdout」就是为了让运维自觉:

# 自动化部署的推荐写法:从文件读
pnpm ops admin init --email ceo@recon.com --password "$(cat /tmp/ceo.pwd)"

reset-password 还有一个隐藏行为:会把账号 active 强制设为 true。这是「账号被禁用后无法登录」应急场景的兜底——你重置密码的同时账号也解锁了。

如果你想走「运维不写 SQL、直接用命令管理账号」这条路,可以参考轻易云智能对账系统的 ops CLI 模式:把 admin / settings / queue 三类高频运维动作收进一个注册表,统一入口 pnpm ops,每个子命令一个文件,新增命令的边际成本几乎为零。

图 2:admin init 创建的账号默认 role: UserRole.ADMIN + isSuperAdmin: true + active: true + level: 10。isSuperAdmin 标记意味着它跳过所有 requireRole() 检查——能改其他管理员、能看到审计日志、能触发 DANGER 等级的 AI 工具。运维事故里 80% 的「误操作」都来自这个开关被滥用,生产环境的 init 推荐用专门的服务账号邮箱(ops-admin@<your-domain>),而不是把 admin@recon.com 这个默认值带进生产。

三、settings 命令:单一真源 + 两阶段破坏性操作

settings 命令管的是 SystemSetting 表(全站 50+ 个 site.* / ai.* / business.* 参数)。它的设计哲学比 admin 更值得展开——默认值单一真源在 defaults 配置文件中,seed 与 reinit 共用:

3.1 三个子命令:list / check / reinit

pnpm ops settings list         # 列出当前所有系统参数 (按 group/sortOrder)
pnpm ops settings check        # 显示当前值与默认值的差异,不修改任何数据
pnpm ops settings reinit       # 预览 plan,不执行
pnpm ops settings reinit --yes # 确认执行恢复

注意 reinit 不带 --yes 时只是「打印计划」,这是 settings 命令最值得学习的设计——把「展示会改什么」和「真的改」分成了两次调用:

// 命令实现片段(节选自 settings 子命令源文件)
async function reinit({ yes }: { yes: boolean }): Promise<void> {
  const d = await diff();
  printDiff(d);

  const toApply = d.lines.filter((l) => l.action !== "skip");
  if (toApply.length === 0) {
    console.log("\n[OK] 已是最新状态,无需变更");
    return;
  }

  if (!yes) {
    console.log(`\n[注意] 即将应用 ${toApply.length} 条变更`);
    console.log("  再次执行时追加 --yes 以确认应用:");
    console.log(`    pnpm ops settings reinit --yes`);
    return;
  }
  // ... 真的 upsert
}

**「check 永远不动数据 / reinit 默认只打印 plan / reinit --yes 才落库」**这个三档是运维命令里最值得抄的设计范式。queue 命令的 remove 也借用了同款闸门(下文第四节)。

3.2 diff 算法的 4 种 action

settings check 输出的 4 种 action 来自 diff() 函数(settings.ts:13-39),逻辑是逐个 key 跑 3 种比对:

每行还会给一行 detail,比如「数据库中不存在」「值/名称/类型与默认值不一致」「已匹配默认值」——这些 detail 是排障时的关键信号。

3.3 单一真源架构:defaults.ts 是双入口

SYSTEM_SETTING_DEFAULTS 在 defaults 配置文件中被两个入口共用:

• prisma/seed.ts:首次部署时把默认值灌进数据库
• cli/commands/settings.ts 的 reinit:把数据库恢复到默认值

新增参数时只需要改一个文件——defaults.ts 头注明示了这一点:

/**
 * 系统参数默认值
 *
 * 作为单一事实来源供两处使用:
 *   1. `prisma/seed.ts` 首次 seed
 *   2. `cli/commands/settings.ts` `reinit` 子命令恢复初始值
 *
 * 增删条目:直接修改本文件即可,两个入口会同步生效。
 */

这种「一份默认、双入口消费」的范式在第六节扩展命令时会再用到——它是 ops CLI 整个命令集的设计基石。

3.4 实战 routine:升级发版后的 settings 三步走

$ pnpm ops settings check
总计: 56 个默认参数
  + 创建: 3
  ~ 重置: 1
  = 跳过: 52

差异详情:
  [+ 创建] ai.embedding.model                 数据库中不存在
  [+ 创建] ai.embedding.dim                   数据库中不存在
  [+ 创建] knowledge.rerank.k                 数据库中不存在
  [~ 重置] site.login_slogan                  值/名称/类型与默认值不一致
  ...

$ pnpm ops settings reinit --yes
正在应用 4 条变更...
  [OK] 已创建 ai.embedding.model
  [OK] 已创建 ai.embedding.dim
  [OK] 已创建 knowledge.rerank.k
  [OK] 已重置 site.login_slogan

[OK] 完成: 4 条变更

默认 12 字节 base64url 密码这种设计细节,在第二节 admin 的实战中已经被证明好用——同样的「默认值藏在 defaults.ts、改一处全生效」的范式被 settings 命令继承了下来。

四、queue 命令:BullMQ 队列的 7 个子命令

queue 是 ops CLI 里命令数最多、子命令最复杂的——18 个已注册队列(BullMQ + ioredis 直连),7 个子命令:list / stats / peek / add / clean / remove / repeatable list / repeatable remove。

4.1 命令速查

pnpm ops queue list                         # 全部队列实时统计
pnpm ops queue stats email                  # 单个队列详细 + repeatable
pnpm ops queue peek email --limit 5         # 查看最近 5 条 job
pnpm ops queue peek email --limit 5 --status failed,active
pnpm ops queue add email send '{"to":"a@b.com","subject":"hi"}'  # 手工注入
pnpm ops queue clean email                  # 清理 completed (默认)
pnpm ops queue clean email --failed         # 仅清理 failed
pnpm ops queue clean email --all --grace-ms 3600000  # 清理 1h 前的全部
pnpm ops queue remove email --yes           # 强制删除整个队列 (破坏性)
pnpm ops queue repeatable list email        # 列出 cron job
pnpm ops queue repeatable remove email job-12345

4.2 18 个队列名:queue.constants.ts 是唯一事实来源

queue 命令引用的 ALL_QUEUES 在 queue 常量文件中集中管理,这是「不写魔法字符串」的工程纪律:

export const QUEUE_EMAIL = "email";
export const QUEUE_REPORT = "report";
export const QUEUE_CLEANUP = "cleanup";
export const QUEUE_ERP_SYNC = "erp-sync";
export const QUEUE_BILL_IMPORT = "bill-import-jd-pop";
// ... 还有 bill-import-alipay/douyin/amazon/sph/xhs/aliexpress/pdd/independent-site
// bill-parse / income-reconcile / expense-reconcile / expense-allocate / transform-generate

注意 18 个队列里的 9 个是 bill-import-*——按 (platform, billType) 拆独立队列,避免 5 个平台共用一个队列时「早返回非本职」拖慢 worker。这条设计纪律的细节见系列长文里的 BullMQ 百万级任务篇。

queue list 的输出长这样:

$ pnpm ops queue list
已注册 18 个队列（来源: queue.constants.ts）:

  Name                              Waiting  Active  Delayed  Complete   Failed  Paused
  ---------------------------------------------------------------------------------------
  bill-import-jd-pop                     0       2        0     12583        7     no
  bill-import-alipay                     3       1        0      8742        2     no
  bill-import-douyin                    12       4        0      6201       13     no
  bill-parse                             0       8        0      4829      156     no
  income-reconcile                       0       0        0        87        0     no
  transform-generate                     0       0        0         0        0     no
  ...

一屏看完 18 个队列的 waiting / active / failed / paused,凌晨 3 点那通电话里你要的「bill-parse 堆了多少」3 秒就有答案。

图 3:queue 命令绕开 API server 与 Worker,直接用 ioredis 走 HGETALL bull:<queue>:waiting / :active / :failed 拿实时计数。这意味着:即使 API 起不来、Worker 全挂,你依然能看到「队列里有什么」——这是 ops CLI 在生产事故里最值钱的能力之一。

4.3 peek:失败原因排查的银弹

queue peek 把失败原因直接打到 stdout,比 Redis CLI HGETALL 高效得多:

$ pnpm ops queue peek bill-parse --limit 3 --status failed
队列 bill-parse 状态=failed 最多 3 条 (实际 3):

  [18234] parseBill       2026-07-15T03:01:22Z  attempt=4/3
      data: {"billId":"cmrl...","filePath":"/uploads/2026-07-15/douyin-x.xlsx"}
      failedReason: parseScript test failed: 行 47 字段 mapping.credit 缺失
  [18235] parseBill       2026-07-15T03:01:25Z  attempt=4/3
      data: {"billId":"cmrl...","filePath":"/uploads/2026-07-15/douyin-y.xlsx"}
      failedReason: parseScript test failed: 行 12 字段 mapping.commission 缺失
  [18236] parseBill       2026-07-15T03:01:31Z  attempt=4/3
      data: {"billId":"2026-07-15/douyin-z.xlsx}
      failedReason: parseScript test failed: 行 3 文件名解析失败 (路径异常)

3 条 failed 在 0.3 秒内看完根因——attempt=4/3 表示 3 次重试用完后又被额外触发了一次(默认 attempts: 3 在 BullMQ 里实际是「3 次尝试」),failedReason 直接给了行号 + 字段名,不用打开 IDE。

4.4 clean vs remove:两档破坏性

queue clean 与 queue remove 的语义差别是 queue 命令最容易被搞混的点:

关键安全闸门:remove 必须传 --yes,否则抛 Error: 破坏性操作,必须传 --yes 确认。这与第三节 settings 的 reinit --yes 是同一套范式——「破坏性操作必须显式确认」。代码层只有一行:

// 命令实现片段(节选自 queue 子命令源文件)
case "remove": {
  const name = requireQueueName(positional[0]);
  if (flags.yes !== "true") {
    throw new Error("破坏性操作,必须传 --yes 确认");
  }
  await removeQueue(name);
}

queue list / stats / peek 是只读命令,可以随时跑,不会改任何数据;add / clean / remove / repeatable remove 是写命令,后两者必须有显式确认或参数验证。

4.5 repeatable:cron job 的双向操作

queue repeatable list 用来查所有 cron 触发的 repeatable job:

$ pnpm ops queue repeatable list cleanup
队列 cleanup 共有 1 个 repeatable job:

  jobId:     daily-cleanup-job
  name:      cleanup:run
  pattern:   "0 2 * * *"
  tz:        Asia/Shanghai
  next run:  2026-07-16T02:00:00.000Z

repeatable remove 移除时必须传 jobId 或 name,BullMQ 的 removeRepeatable(name, { pattern, tz }) 要三元组才能精确定位。这是 BullMQ 的 API 限制,不是 CLI 偷懒——文档里会明示「用 repeatable list 查看 id」。

五、knowledge:embed / knowledge:eval:知识库的两条运维命令

knowledge 这两条命令与上面三个的本质区别是:它们服务于 AI Agent 的检索质量——embed 维护向量索引,eval 跑检索质量的回归测试。设计上是「生产路径的快照 + 异步评估」。

5.1 knowledge:embed:补算向量索引

pnpm ops knowledge:embed

调用 EmbedderInitializer.runOnBootstrap(),与 API 启动时执行的同一段代码——保证 CLI 跑出来的向量索引和 API 启动时跑出来的一致。DASHSCOPE_API_KEY 缺失时会自动 no-op(processed=0),不会报错——这是「开发环境不配 key 也能跑」的友好降级:

// 命令实现片段(节选自 knowledge:embed 子命令源文件)
const initializer = new EmbedderInitializer(
  repository,
  process.env.DASHSCOPE_API_KEY ? makeEmbeddingClient() : undefined,
);
exitCode = await runKnowledgeEmbed(initializer, output);

退出码设计:processed>0 && failed=0 → 0(成功);failed>0 → 2(部分失败);catch 异常 → 2(完全失败)。CI/CD 里可以直接靠退出码判定:

pnpm ops knowledge:embed || { echo "向量补算失败"; exit 1; }

5.2 knowledge:eval:LLM 检索质量评估

pnpm ops knowledge:eval                  # 评估最近 20 条 query log (默认)
pnpm ops knowledge:eval --limit 50       # 评估最近 50 条

runLiveKnowledgeEval 跑的是:从 knowledge_query_log 表捞最近 N 条用户 query → 走 production 同款混合检索(vector + keyword + RRF + MMR)→ 把命中的 hits 喂给 LlmEvaluator 打分。这是「改完 embedding 模型或 prompt 后必须跑一轮」的回归工具。

输出格式:

knowledge eval complete: total=20, evaluated=18, skipped=2, failures=0, limit=20

• total = 取到的 query log 数
• evaluated = 成功跑完 LLM 打分的(需要 DASHSCOPE_API_KEY + 命中的 hits)
• skipped = 该 query 没有命中任何 hit(检索层就 0 结果,LLM 评估无意义)
• failures = LLM 评估抛错的(网络异常 / 输出解析失败)

关键设计:process.env.DASHSCOPE_API_KEY 缺时走 legacy keyword-only(D-V8 同款语义)——也就是说,没有 embedding key 时 eval 依然能跑,只是退化成纯关键词检索的评估,降级路径与生产路径一致(D-V8 设计纪律:不要静默吞错,要让运维知道当前在跑哪条路径)。

六、扩展 ops CLI:CommandModule 注册表架构

加一条新命令的标准流程:

// 示例:新增 cache 命令的最小骨架(目录 cache.ts)
import type { CommandModule } from "../runner";

async function flushCache(scope: "all" | "session"): Promise<void> {
  // ... Redis SCAN + DEL 逻辑
}

export const cacheCommand: CommandModule = {
  name: "cache",
  description: "Redis 缓存清理",
  usage: "pnpm ops cache flush [--scope all|session]",
  run: async (args) => {
    const sub = args[0];
    if (sub === "flush") await flushCache("all");
    else throw new Error(`unknown subcommand: ${sub}`);
  },
};

然后在 CLI 入口的 COMMANDS 数组里追加一行:

import { cacheCommand } from "./commands/cache";
const COMMANDS: CommandModule[] = [
  adminCommand,
  settingsCommand,
  queueCommand,
  knowledgeEmbedCommand,
  knowledgeEvalCommand,
  cacheCommand,  // ← 新增
];

CommandModule 接口只有 4 个字段(name / description / usage / run),刻意保持极简——不引入 commander.js / yargs / oclif 这些重武器,30 行自实现的 parseArgs 足够应付现有 5 条命令。文档明示:

不引入重框架 / 不引入交互式 prompt / 故意不隐藏密码 / 单一入口 / 每命令自建 Prisma Client

这种「刻意不抽象」的工程纪律,是 ops CLI 能稳定运行的根因——抽象层越多,凌晨 3 点你 debug 的成本越高。

七、5 步 ops 实战 routine:从首登到日常巡检

把上面 5 条命令串成一份可执行的运维 routine,适合放进新机器初始化脚本或每月一次的健康检查:

步骤 1-3 是「建数据」(admin 账号 + 系统参数),步骤 4-5 是「看数据」(队列健康)。完整覆盖一次运维事件的所有「读写场景」。

日常巡检脚本可以这样写(放进 crontab 每天 9:00 跑):

#!/bin/bash
# /opt/recon/ops-daily-check.sh
set -euo pipefail

LOG=/var/log/recon-ops-$(date +%Y%m%d).log

echo "[$(date)] === ops daily check ===" >> "$LOG"
pnpm ops queue list >> "$LOG" 2>&1
pnpm ops queue peek bill-parse --limit 10 --status failed >> "$LOG" 2>&1

# 告警:任何队列 failed > 50
TOTAL_FAILED=$(pnpm ops queue list | awk '/Failed/ {sum += $NF} END {print sum}')
if [ "$TOTAL_FAILED" -gt 50 ]; then
  curl -X POST "$ALERT_WEBHOOK" -d "{\"text\":\"队列 failed 累计 $TOTAL_FAILED,请排查\"}"
fi

凌晨 3 点那通电话的终极解法,不是更快的 Redis 工具,而是「不需要任何中间环节的 5 行 shell」——这正是 ops CLI 的存在价值。轻易云智能对账系统在这套生产事故里被验证过 3 次以上:API 起不来、Redis 队列爆、管理员被锁,全是 pnpm ops 顶上。

八、容易踩的 6 个坑(排障速查)

每条命令的错误抛出位置集中在 CLI 入口的顶层 catch 与每个子命令的 throw new Error(...)。这是命令集刻意不引入 commander.js 的副作用——错误信息是手写的,但手写的好处是「每条错误都能精确指向根因」。

九、收尾:ops CLI 是「生产事故的最后一根稻草」

回到开头的凌晨 3 点:如果你现在用的是 pnpm ops queue list + pnpm ops queue peek bill-parse --limit 10 --status failed,从 SSH 登录到拿到失败原因,最快 8 秒。这 8 秒里不依赖 API server、不依赖 worker、不依赖 Navicat、不依赖 Redis Desktop Manager——只有 Prisma Client + ioredis 直连两个端口。

这套设计给整个生产环境的运维事故兜了底:即使 API server 起不来、worker 全部 hang 死、web 前端白屏,运维依然能用 5 条命令直接看数据库与 Redis 的真实状态。在 AI Agent / 微服务 / K8s 这些复杂架构盛行的今天,「最后一道直连路径」往往比任何花哨的可观测性平台都值钱。

如果你正在维护一套类似的 SaaS 系统,核心问题是:你的 ops 工具是「另一套需要起 server 的工具」,还是「直连 DB / Redis 的小命令集」? 前者多用于日常巡检,后者才是凌晨 3 点能救命的那条路径。本文的 5 条命令、3 个设计原则(单一真源 / 两阶段破坏性 / 显式 --yes 闸门)、1 套注册表架构,都值得直接抄过去——根据本号踩过的坑,这三条原则能覆盖 90% 的生产事故现场。

[来源:运维 CLI 真实命令实现;2026 年 7 月某抖店账单解析失败排障记录;pnpm ops 顶层帮助文本]

延伸阅读

• 知识库里搜索「BullMQ 队列拆分」可读 2.1.2 那篇百万级任务实战,与 queue 命令的 bill-import-* 9 个独立队列直接对应
• 搜索「收入对账 7 态机」可读双子计划架构篇,与 queue 命令的 income-reconcile / expense-reconcile / expense-allocate 队列对应
• 搜索「部署流水线」可读 2.5.1 一键部署篇,与 ops CLI 的 5 步 routine 形成「建数据 → 看数据」闭环
• 搜索「settings defaults」可读 defaults 单一真源的双入口消费范式,与本篇第三节 settings 命令的 seed + reinit 共用机制对应

上述延伸阅读均收录在「长文库」系列里,可按标题搜索。