VisibleBase
参考

AdminClient

可信环境如何管理 product、签发 user_token，并维护 Runtime env。

AdminClient 只应该运行在可信环境里。

典型场景：

  • 你自己的产品后端
  • 本地管理脚本
  • 内网管理工具
  • CI 或运维脚本

不要把 admin_secret_key 放到浏览器、公开前端或不受控客户端。

最小示例

import { AdminClient } from "@visiblebase/client";

const admin = new AdminClient({
  base_url: "https://base.example.com",
  admin_secret_key: process.env.VISIBLEBASE_ADMIN_SECRET_KEY,
});

如果没有显式传 admin_secret_key，SDK 会尝试从 process.env.VISIBLEBASE_ADMIN_SECRET_KEY 读取。

典型调用链

可信后端完成登录、鉴权和业务判断。
AdminClient调用 /api/admin/products、/api/admin/tokens/apply、/api/admin/env。
VisibleBase校验 admin_secret_key 后，再执行 product、token 和 env 管理动作。

products

list()

const items = await admin.products.list();

create()

const product = await admin.products.create({
  name: "Chrome Extension",
});

返回值包含：

  • product_id
  • name
  • status
  • created_at
  • updated_at

pause() / activate()

await admin.products.pause({
  product_id: product.product_id,
});

await admin.products.activate({
  product_id: product.product_id,
});

适合：

  • 暂停某个产品的所有用户调用
  • 临时下线某个产品
  • 重新开放一个 product

remove()

await admin.products.remove({
  product_id: product.product_id,
});

当前语义就是删除 product 记录。调用前要先确认这是否符合你的业务预期。

tokens.apply()

这是最常用的管理端能力：为某个用户在某个 product 下申请 user_token。

const issued = await admin.tokens.apply({
  product_id: product.product_id,
  user_id: "user_123",
  metadata: {
    plan: "pro",
    org_id: "org_001",
  },
  ttl: "7d",
});

返回值包含：

  • user_token
  • product_id
  • user_id
  • expires_at

ttl 支持：

  • 30m
  • 1h
  • 7d
  • 秒数

推荐登录链路

router.post("/login", async (c) => {
  const user_id = await login(c);

  const issued = await admin.tokens.apply({
    product_id: "prod_xxx",
    user_id,
    ttl: "7d",
  });

  return c.json({
    product_id: "prod_xxx",
    user_token: issued.user_token,
  });
});

也就是：

  1. 你的业务后端先完成用户登录
  2. 再由可信后端向 Base 申请 user_token
  3. 把 product_id + user_token 返回给前端
  4. 前端再用 UserClient 调 Base

env

admin.env 负责 Runtime .env 管理。

list()

const envs = await admin.env.list();

upsert()

await admin.env.upsert({
  key: "OPENAI_API_KEY",
  value: "sk-xxx",
});

remove()

await admin.env.remove("OPENAI_API_KEY");

import()

await admin.env.import(`
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.openai.com/v1
`);

这些修改会写回 Base 当前使用的 .env 文件。

错误处理

AdminClient 收到非 2xx HTTP 响应时会抛出 Error。这个错误会带两个额外字段：

  • status：HTTP 状态码。
  • body：Base 返回的原始响应文本，通常是 {"error":"..."}。
try {
  await admin.tokens.apply({
    product_id: "prod_xxx",
    user_id: "user_123",
  });
} catch (error) {
  const status = error instanceof Error && "status" in error ? error.status : undefined;
  const body = error instanceof Error && "body" in error ? error.body : undefined;

  console.log(status, body);
}

常见状态码：

  • 401：admin_secret_key 缺失或错误。
  • 403：目标 product 已暂停，不能继续签发 token。
  • 404：目标 product 不存在。
  • 500：Base 缺少必要配置，或管理动作内部执行失败。

当前不归 AdminClient 管的事情

这几件事当前不走 AdminClient：

  • 模型配置
  • 直接修改 models 表
  • 注册 service handler

它们分别属于：

  • 数据库层
  • Base 运行时层

UserClient

产品侧如何读取模型目录，并调用 text、stream、image、tts 等 service。

HTTP API

/v1/* 与 /api/admin/* 路由的鉴权边界、请求方式和返回形态。

目录

最小示例典型调用链productslist()create()pause() / activate()remove()tokens.apply()推荐登录链路envlist()upsert()remove()import()错误处理当前不归 AdminClient 管的事情