ChainlessChain 文档

主题

多租户 SaaS (tenant) ​

Headless 命令 — 不依赖桌面 GUI，直接使用核心包运行。适用于服务器、CI/CD、容器化等无桌面环境。

核心特性 ​

  • 租户管理: 创建、配置、软删除/硬删除租户，支持 slug 标识
  • 订阅计划: 内置 free/starter/pro/enterprise 四档计划，各含不同配额
  • 用量计量: 按周期 (YYYY-MM) 记录 API 调用、存储、AI 请求等指标
  • 配额检查: 实时检查租户用量是否超过计划配额
  • 订阅管理: 创建、取消订阅，支持过期和金额覆盖
  • 导入导出: 租户数据 JSON 快照的完整导入导出

概述 ​

ChainlessChain CLI 多租户 SaaS 模块 (Phase 97) 提供完整的多租户平台管理。create 创建租户（名称、slug、计划、所有者），configure 更新配置。subscribe 创建订阅（自动取消前一个活跃订阅），check-quota 检查用量配额。record 按周期记录用量指标，usage 聚合查看。stats 展示 SaaS 全局统计，export/import 支持租户快照迁移。

命令参考 ​

tenant plans — 订阅计划 ​

bash
chainlesschain tenant plans
chainlesschain tenant plans --json

列出可用计划 (free/starter/pro/enterprise)，显示月费和各项配额。

tenant metrics — 计量指标 ​

bash
chainlesschain tenant metrics --json

列出追踪的用量指标（api_calls、storage_bytes、ai_requests 等）。

tenant create — 创建租户 ​

bash
chainlesschain tenant create "Acme Corp" acme-corp
chainlesschain tenant create "Dev Team" dev-team -p pro -o user-001 -c '{"region":"cn"}' --json

创建租户。-p 计划 (默认 free)，-o 所有者 ID，-c 配置 JSON。

tenant configure — 更新租户 ​

bash
chainlesschain tenant configure <tenant-id> -p pro
chainlesschain tenant configure <tenant-id> -s suspended -n "New Name" -c '{"custom":true}' --json

更新计划、状态 (active|suspended)、名称、配置。

tenant list — 列出租户 ​

bash
chainlesschain tenant list
chainlesschain tenant list -s active -p pro -o alice --limit 20 --json

列出租户。可按状态、计划、所有者子串过滤。

tenant show — 查看租户详情 ​

bash
chainlesschain tenant show <tenant-id> --json

显示租户详情和当前活跃订阅。

tenant delete — 删除租户 ​

bash
chainlesschain tenant delete <tenant-id>
chainlesschain tenant delete <tenant-id> --hard

软删除（标记 deletedAt）或硬删除（级联移除所有数据）。

tenant record — 记录用量 ​

bash
chainlesschain tenant record <tenant-id> api_calls 150
chainlesschain tenant record <tenant-id> storage_bytes 1048576 -P 2026-04 --json

记录用量采样。-P 指定周期 (YYYY-MM, 默认当月)。

tenant usage — 查看用量 ​

bash
chainlesschain tenant usage <tenant-id>
chainlesschain tenant usage <tenant-id> -P 2026-04 -m api_calls --json

聚合查看租户用量。可按周期和指标过滤。

tenant subscribe — 创建订阅 ​

bash
chainlesschain tenant subscribe <tenant-id> -p pro
chainlesschain tenant subscribe <tenant-id> -p enterprise -a 999 -d 7776000000 --json

创建订阅（自动取消前一个活跃订阅）。-p 计划 (必填)，-a 覆盖金额，-d 持续时间 (ms, 默认 30 天)。

tenant subscription — 查看活跃订阅 ​

bash
chainlesschain tenant subscription <tenant-id> --json

查看租户当前活跃订阅。

tenant cancel — 取消订阅 ​

bash
chainlesschain tenant cancel <tenant-id>

取消当前活跃订阅。

tenant subscriptions — 列出订阅 ​

bash
chainlesschain tenant subscriptions
chainlesschain tenant subscriptions -t <tenant-id> -s active -p pro --limit 20 --json

列出订阅。可按租户、状态、计划过滤。

tenant check-quota — 配额检查 ​

bash
chainlesschain tenant check-quota <tenant-id> api_calls
chainlesschain tenant check-quota <tenant-id> ai_requests -P 2026-04 --json

检查租户指定指标的配额使用情况。返回已用量、限额、剩余量、是否超额。

tenant stats — 全局统计 ​

bash
chainlesschain tenant stats --json

SaaS 全局统计：租户数、订阅数、活跃订阅、按状态/计划分布、总用量。

tenant export — 导出租户 ​

bash
chainlesschain tenant export <tenant-id>
chainlesschain tenant export <tenant-id> tenant-backup.json

导出租户快照 (租户 + 订阅 + 用量) 为 JSON。

tenant import — 导入租户 ​

bash
chainlesschain tenant import tenant-backup.json

从 JSON 快照导入租户。返回导入和跳过的订阅/用量数。

数据库表 ​

表名说明
tenants租户（名称、slug、计划、状态、所有者、配置、删除时间）
tenant_subscriptions订阅（租户 ID、计划、状态、金额、开始/过期时间）
tenant_usage用量记录（租户 ID、指标、值、周期）

系统架构 ​

用户命令 → tenant.js (Commander) → tenant-saas.js
                                         │
         ┌──────────────────────────────┼──────────────────────┐
         ▼                              ▼                       ▼
     租户管理                      订阅 & 配额               用量 & 统计
 (create/configure/             (subscribe/cancel/        (record/usage/
  list/show/delete)              subscription/check-quota)  stats)
         ▼                              ▼                       ▼
       tenants              tenant_subscriptions          tenant_usage

配置参考 ​

bash
# tenant create
<name> <slug>                  # 名称和 slug（必填）
-p, --plan <plan>              # free|starter|pro|enterprise (默认 free)
-o, --owner <id>               # 所有者 ID
-c, --config <json>            # 配置 JSON

# tenant subscribe
<tenant-id>                    # 租户 ID（必填）
-p, --plan <plan>              # 计划 (必填)
-a, --amount <n>               # 覆盖金额
-d, --duration-ms <ms>         # 持续时间 (默认 30 天)

# tenant check-quota
<tenant-id> <metric>           # 租户 ID 和指标（必填）
-P, --period <period>          # 周期 YYYY-MM

性能指标 ​

操作目标实际状态
create 创建租户< 200ms~100msOK
subscribe 创建订阅< 200ms~120msOK
check-quota 配额检查< 200ms~80msOK
record 记录用量< 150ms~60msOK
stats 全局统计< 500ms~250msOK
export 导出< 1s~400msOK

关键文件 ​

文件职责
packages/cli/src/commands/tenant.jstenant 命令主入口 (Phase 97)
packages/cli/src/lib/tenant-saas.js租户 CRUD、订阅管理、用量计量、配额检查、统计核心实现

测试覆盖率 ​

__tests__/unit/tenant-saas.test.js — 135 tests

覆盖：多租户 CRUD、订阅计划与续费、用量计量写入、配额检查（周期 / 硬上限 / 软上限）、统计聚合、导入导出。

安全考虑 ​

  1. 数据隔离：所有表带 tenant_id 索引，查询必须带 tenant 过滤
  2. API 密钥隔离：租户密钥独立派生，不共享主密钥
  3. 配额硬限：check-quota 支持 strict 模式，超限直接拒写
  4. 订阅续费：过期未续费自动转 suspended，避免超售
  5. 审计：订阅/用量事件全量进 tenant_audit，便于对账

故障排查 ​

症状可能原因解决方案
create 重名slug 冲突改 slug 或 --force
subscribe 拒tenant 未 activetenant activate
check-quota 越界period 参数错使用 YYYY-MM 格式
export 空tenant 无数据stats 先验证

使用示例 ​

bash
# 1. 创建租户
tid=$(cc tenant create acme -o did:key:owner --slug acme --json | jq -r .id)

# 2. 订阅 Pro 计划（30 天）
cc tenant subscribe $tid -p pro -a 99.0 -d 2592000000

# 3. 记录用量 & 配额检查
cc tenant record $tid llm_tokens 120000 -P 2026-04
cc tenant check-quota $tid llm_tokens -P 2026-04

# 4. 统计 & 导出
cc tenant stats --json
cc tenant export tenants.json

相关文档 ​

基于 MIT 许可发布

Copyright © 2024-2026 ChainlessChain Team