功能与套餐开通对照表

本项目是自托管产品，“套餐”体现为三层控制：① 服务开通项（8 个 service.activation 开关）决定相关 Open API 是否返回 1021；② 配额（4 项）在协议上限内进一步收紧；③ 控制台功能开关（6 项）写穿到前两层。没有计费、购买与到期，因此本页只对照“能力 ↔ 开通项 ↔ 接口 ↔ SDK ↔ Demo ↔ 控制台”，并标注哪些是代码强制、哪些只是记录。

概念​

当前契约表（Rust contract::dump_tables() 导出的机器产物 contract-tables.json）共 230 个 Open API 操作，其中 91 个声明了服务开通项；其余操作不校验开通状态。

前置条件​

• 服务端已启动；已创建应用（POST /api/admin/apps）。
• 持有 Admin Secret（IM_ADMIN_SECRET，默认 dev-admin）。
• 若要验证 1021，需要一个可签名的 Open API 调用（AppKey + AppSecret + 签名），见OpenAPI 与 Postman 调试。

步骤​

1. 查看当前开通项与配额

   curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/services" \ -H 'X-Admin-Secret: dev-admin'

2. 关闭一个服务并验证 1021

   curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/services" \ -H 'X-Admin-Secret: dev-admin' \ -H 'content-type: application/json' \ -d '{"services":{"private_chat":false},"quotas":{"maxGroupMembers":100,"maxSuperGroupMembers":1000,"maxChatroomMembers":200,"messageRatePerMinute":60}}'

   随后用 Open API 调 message.private.publish，应返回 403 / code=1021；调 user.get 仍成功（该操作无 service 声明）。

3. 验证配额生效

   把 maxGroupMembers 设为 3 后创建群并加第 4 个成员，应返回 1015（成员数量超出上限）；普通群上限默认取 protocol.limits.groupMaxMembers。

   配额只收紧、不放宽：即使配置值大于协议上限，实际仍以协议上限为准。

4. 用控制台功能开关联动

   curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/features" \ -H 'X-Admin-Secret: dev-admin' \ -H 'content-type: application/json' \ -d '{"features":{"friend":false,"group":false,"chatroom":false,"push":false,"sensitiveWord":false,"messageCallbacks":false}}'

   该接口把开关写穿到 services.private_chat/group/chatroom/sensitive_words/callbacks 与 app.pushEnabled。

5. 恢复默认

   curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/services" \ -H 'X-Admin-Secret: dev-admin' \ -H 'content-type: application/json' \ -d '{"services":{"private_chat":true,"group":true,"supergroup":true,"chatroom":true,"system_notification":true,"callbacks":true,"sensitive_words":true,"message_routing":true},"quotas":{"maxGroupMembers":0,"maxSuperGroupMembers":0,"maxChatroomMembers":0,"messageRatePerMinute":0}}'

参数表​

功能闭环表​

8 个服务开通项的强制点​

计数由构建时解析服务端契约声明中的 service 字段得到；若解析失败则显示 0，页面仍可生成。

配额（services.quotas）​

控制台功能开关 → 数据源​

示例​

查询 → 关闭 → 断言 1021 → 恢复（Node.js）​

// service-gate.mjs — 验证服务开通项对 Open API 的强制效果
import { createHash, randomBytes } from 'node:crypto';

const HOST = process.env.IM_HOST || 'http://127.0.0.1:8080';
const ADMIN_SECRET = process.env.IM_ADMIN_SECRET || 'dev-admin';
const APPKEY = process.env.IM_APPKEY || 'demo';
const APP_SECRET = process.env.APP_SECRET || 'YOUR_APP_SECRET'; // 变量：应用 AppSecret

async function admin(method, path, body) {
  const res = await fetch(HOST + path, {
    method,
    headers: { 'X-Admin-Secret': ADMIN_SECRET, 'content-type': 'application/json' },
    body: body ? JSON.stringify(body) : undefined,
  });
  return (await res.json()).data;
}

async function openapi(path, body) {
  const nonce = randomBytes(8).toString('hex');
  const timestamp = String(Date.now());
  const signature = createHash('sha1').update(APP_SECRET + nonce + timestamp).digest('hex');
  const res = await fetch(HOST + '/im/v2' + path, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'App-Key': APPKEY,
      Nonce: nonce, Timestamp: timestamp, Signature: signature,
    },
    body: JSON.stringify(body),
  });
  return { status: res.status, body: await res.json() };
}

const before = await admin('GET', '/api/admin/apps/' + APPKEY + '/services');
console.log('当前 private_chat =', before.services.private_chat);

await admin('POST', '/api/admin/apps/' + APPKEY + '/services', { services: { private_chat: false } });
const blocked = await openapi('/message/private/publish', {
  fromUserId: 'alice', toUserId: 'bob', content: { type: 'text', text: 'hi' },
});
console.log('关闭后发布单聊:', blocked.status, blocked.body.code); // 期望 403 / 1021

await admin('POST', '/api/admin/apps/' + APPKEY + '/services', { services: { private_chat: true } });
const ok = await openapi('/message/private/publish', {
  fromUserId: 'alice', toUserId: 'bob', content: { type: 'text', text: 'hi' },
});
console.log('恢复后发布单聊:', ok.status, ok.body.code); // 期望 200 / 0

恢复全部开通（curl）​

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/services" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"services":{"private_chat":true,"group":true,"supergroup":true,"chatroom":true,"system_notification":true,"callbacks":true,"sensitive_words":true,"message_routing":true},"quotas":{"maxGroupMembers":0,"maxSuperGroupMembers":0,"maxChatroomMembers":0,"messageRatePerMinute":0}}'

常见问题​

关闭 service 后客户端还能发消息？​

能。客户端 WS send 帧不校验服务开通项；关闭只影响 Open API（以及客户端 REST 建聊天室）。若要做客户端级管控，请同时下发 features 快照到客户端，由客户端隐藏入口。

配额设得比协议上限大，会放宽吗？​

不会。生效值取 min(协议上限, 配额)；配额只能收紧。

message_routing 开关有用吗？​

当前没有。它只出现在开通项列表中，代码没有读取点；全量消息路由由 callbacks 与订阅事件决定。

messageRatePerMinute 能限流吗？​

不能。该字段只回显；真正的接口限流是 ratelimit 的按 operation QPS（超限 1008 + Retry-After: 1）。

为什么 features 里点「好友」关掉，单聊也不能发了？​

friend 开关映射到 services.private_chat，因此 message.private.publish 会返回 1021。

如何判断某个 Open API 是否受开通项约束？​

看本页「功能闭环表」；或查 API 文档中该接口说明，1021 出现在错误码列表即表示有 service 声明。

相关链接​

• 查询服务开通项 / 设置服务开通项
• 限频、配额与容量限制
• 状态码与错误码：1021 / 1015 / 1008
• 问题排查手册：1021 与限流排查
• OpenAPI 与 Postman 调试：构造可签名调用验证 1021
• 消息计数、存储与推送策略