内容审核
这是什么 / 何时用
Moderation 在写入链路上对内容做前置审核:对象是数据表文本与存储桶图片。它与 rowSecurity 互补——rowSecurity 管谁能读写数据,Moderation 管写入的内容是否允许保存。
2.6.0 状态:表文本审核可用;桶图片审核暂不可用(配置接口与代码链路已预留,待图片签名 URL 与审核服务链路就绪后再启用)——不要在生产开启或依赖图片审核。
2.9.0 新增:createConfig 支持 **mode: 'post' | 'hybrid'**(异步后置审核;平台 Admin 开启二期后生效,未开启等同 pre)与 **requireManualReviewOnViolation**(违规转人工复核,默认开启;关闭时违规文档为 private_hold 而非隔离)。文档读取返回 moderationStatus(checking / pending / published / quarantined / private_hold / action_error)与 moderationJobId;未发布文档对非创建者隐藏。
前置
- API Key scopes:
moderation.config.write(增删改配置)、moderation.config.read(查配置)、moderation.log.read(查日志)。自动化配置放 Node Server SDK / 受控后端 / Function;API Key 不进浏览器代码。 - 项目级审核开关与审核服务已就绪(写入报审核错误时先检查这两项)。
- Console SDK 不需要也不能
new Moderation()(控制台页面直接配置);Web SDK 只负责登录后正常写入/上传/读取,不配置审核规则。
使用骨架
- 创建表文本审核配置(仅首次;对已有配置重复 create 会失败):
moderation.createConfig({
resourceType: ResourceType.Collections, // 或 'collections'
resourceId: '<tableId>',
databaseId: '<databaseId>', // collections 必填
mode: 'pre', // 2.9.0 起可选 'post' | 'hybrid'(需平台开启审核二期,未开启等同 pre)
requireManualReviewOnViolation: true, // 2.9.0:违规转人工复核(默认 true;false 时违规文档 private_hold)
contentTypes: ['text'], // 首次 createConfig 必填
enabled: true
})- 之后继续普通的 TablesDB 写入(
createRow/updateRow等):审核自动在写入链路执行——没有moderate()之类的显式方法。通过 → 写入成功;阻断 → 写入返回错误。 - 查配置 / 调整 / 删除:
getConfig/updateConfig(改enabled或审核参数;仅切enabled可省略contentTypes,原有配置保留)/deleteConfig。 - 排查:
listLogs({ queries: [Query.equal('result', 'block')], total: true })按 resourceType / resourceId / databaseId / result / timestamp / userId / contentType 筛选审核日志;getLog({ logId })查单条。
关键参数与返回
resourceType:collections(表)或buckets(桶);mode:pre/post/hybrid(post / hybrid 需平台开启审核二期,未开启时等同pre;hybrid按平台文本长度阈值分流同步 / 异步路径)。requireManualReviewOnViolation默认true(违规 → quarantined 隔离);false时违规文档进入 private_hold(仅创建者可见)。- 列筛选语义:审核范围按表 schema 自动确定——审查
string/varchar/text/mediumtext/longtext(含这些类型的数组列);integer / float / boolean / 日期时间 / 关系等类型不审;Email / URL / IP / Enum 底层是 string,因此也审。contentTypes: ['text']不是"只审名为 text 的列",也不是列名列表,而是"本次写入数据中所有符合条件的文本列"。 - 图片审核的预留形态为
resourceType: 'buckets'+contentTypes: ['image']——当前禁止创建这类生产配置。
错误与边界
- 写入被阻断:TablesDB 写入返回审核错误 → 先
listLogs查阻断原因,再检查项目级审核开关与审核服务配置。 - 已有图片审核配置的实例:用
updateConfig({ resourceType: 'buckets', resourceId, enabled: false })显式关闭,不要依赖它。 - 不要把图片审核当作
Storage.createFile的既有保证,也不要把本地路径或任意外部图片 URL 传给createConfig。
SDK 类别差异
- Server SDK(server-sdk/nodejs.md):
Moderation服务全集(配置 CRUD + 日志)。 - 客户端 SDK(client-sdk/web.md):无 Moderation 服务;浏览器只感知写入成功/失败。
- Console SDK(console-sdk/nodejs.md):JS Console SDK 无 Moderation 服务(控制台页面配置);Java Console SDK 有
Moderation服务。
示例指引
- JavaScript(Node 配置审核与查日志):examples/javascript.md
- Java:examples/java.md
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
创建表文本审核配置
审核配置是服务端管理面:Web SDK 无 Moderation 服务(浏览器只感知写入成功/失败),JS Console SDK 亦无(控制台页面直接配置)。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
import { Client, Moderation, ResourceType } from 'agentbase-node-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // 必须包含 /v1
.setProject(process.env.APPBASE_PROJECT_ID!)
.setKey(process.env.APPBASE_API_KEY!); // moderation.config.write
const moderation = new Moderation(client);
await moderation.createConfig({
resourceType: ResourceType.Collections, // 或 'collections'
resourceId: 'tasks',
databaseId: 'app-db', // collections 必填
mode: 'pre', // v1 仅支持前置审核
contentTypes: ['text'], // 首次 createConfig 必填
enabled: true
});
// 仅首次:对已有配置重复 create 会失败;之后继续普通 TablesDB 写入即可import io.agentbase.services.Moderation;
Moderation moderation = new Moderation(client); // client 初始化见 server-sdk/java.md
moderation.createConfig(ResourceType.COLLECTIONS, "tasks", Mode.PRE,
List.of("text"), "app-db", true);
// 仅首次:重复 create 会失败;之后继续普通 TablesDB 写入即可from agentbase.services.moderation import Moderation
moderation = Moderation(client) # 方法面与 Node SDK 同构,snake_case 入参
moderation.create_config(
resource_type='collections', resource_id='tasks',
database_id='app-db', mode='pre',
content_types=['text'], enabled=True) # 仅首次;之后继续普通 TablesDB 写入mod := agentbase.NewModeration(cl) // facade 构造器;cl 为已装载 API Key 的 Client
mod.CreateConfig("collections", "tasks", "pre", []string{"text"},
mod.WithCreateConfigDatabaseId("app-db"),
mod.WithCreateConfigEnabled(true))
// 仅首次:重复 create 会失败;之后继续普通 TablesDB 写入即可curl -sS -X POST "$APPBASE_ENDPOINT/moderation-configs" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"resourceType":"collections","resourceId":"tasks","databaseId":"app-db","mode":"pre","contentTypes":["text"],"enabled":true}'
# 查/改/删:GET | PATCH | DELETE /moderation-configs/{resourceType}/{resourceId}(仅切 enabled 可省略 contentTypes)
# 图片审核(resourceType=buckets + contentTypes=image)当前不可用,禁止创建这类生产配置写入数据并触发审核
没有显式 moderate() 方法:配置生效后由普通 TablesDB 写入(createRow / updateRow)在链路上自动执行——通过则写入成功,阻断则写入返回审核错误。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
import { TablesDB, ID } from 'agentbase-node-sdk';
const tablesDB = new TablesDB(client); // client 同「创建表文本审核配置」卡
await tablesDB.createRow('app-db', 'tasks', ID.unique(), { title: '待审核的文本' });
// 通过:写入成功;阻断:写入报错 → 到「排查审核日志」卡定位原因import { TablesDB, ID } from 'agentbase-web-sdk'; // 前提:用户已登录
const tablesDB = new TablesDB(client);
await tablesDB.createRow({
databaseId: 'app-db',
tableId: 'tasks',
rowId: ID.unique(),
data: { title: '待审核的文本' } // 受表/行权限约束;审核同样在写入链路执行
});import io.agentbase.services.TablesDB;
TablesDB tables = new TablesDB(client); // client 初始化见 server-sdk/java.md
tables.createRow("app-db", "tasks", ID.unique(),
Map.of("title", "待审核的文本"), null, null); // 通过:写入成功;阻断:写入报错from agentbase.services.tables_db import TablesDB
tables_db = TablesDB(client) # 方法面与 Node SDK 同构,snake_case 入参
tables_db.create_row(
database_id='app-db', table_id='tasks', row_id=ID.unique(),
data={'title': '待审核的文本'})tables := agentbase.NewTablesDB(cl) // facade 构造器;cl 为已装载 API Key 的 Client
tables.CreateRow("app-db", "tasks", "<rowId>",
map[string]interface{}{"title": "待审核的文本"}) // 通过:写入成功;阻断:写入报错curl -sS -X POST "$APPBASE_ENDPOINT/tablesdb/app-db/tables/tasks/rows" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"rowId":"task-1","data":{"title":"待审核的文本"}}'
# 通过:201 写入成功;阻断:moderation_rejected → 到「排查审核日志」卡定位原因查配置、调整与删除
已有配置不要重复 createConfig(重复创建会失败):查 getConfig、调整/启停 updateConfig(仅切 enabled 时可省略 contentTypes,原有配置保留)、删除 deleteConfig。Web SDK 无 Moderation 服务。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const tableResource = {
resourceType: ResourceType.Collections, // 或 'collections'
resourceId: 'tasks',
databaseId: 'app-db'
};
const current = await moderation.getConfig(tableResource);
await moderation.updateConfig({ ...tableResource, enabled: false }); // 关闭但保留配置
await moderation.updateConfig({ ...tableResource, enabled: true }); // 重新开启
await moderation.deleteConfig(tableResource);Object current = moderation.getConfig(ResourceType.COLLECTIONS, "tasks", "app-db");
moderation.updateConfig(ResourceType.COLLECTIONS, "tasks", "app-db",
null, null, false); // 关闭但保留配置;仅切 enabled 时可省略 contentTypes
moderation.updateConfig(ResourceType.COLLECTIONS, "tasks", "app-db",
null, null, true); // 重新开启
moderation.deleteConfig(ResourceType.COLLECTIONS, "tasks", "app-db");table_resource = dict(resource_type='collections', resource_id='tasks', database_id='app-db')
current = moderation.get_config(**table_resource)
moderation.update_config(**table_resource, enabled=False) # 关闭但保留配置;仅切 enabled 时可省略 content_types
moderation.update_config(**table_resource, enabled=True) # 重新开启
moderation.delete_config(**table_resource)mod.GetConfig("collections", "tasks", mod.WithGetConfigDatabaseId("app-db"))
mod.UpdateConfig("collections", "tasks",
mod.WithUpdateConfigDatabaseId("app-db"),
mod.WithUpdateConfigEnabled(false)) // 关闭但保留配置;仅切 enabled 时可省略 ContentTypes
mod.UpdateConfig("collections", "tasks",
mod.WithUpdateConfigDatabaseId("app-db"),
mod.WithUpdateConfigEnabled(true)) // 重新开启
mod.DeleteConfig("collections", "tasks", mod.WithDeleteConfigDatabaseId("app-db"))# 查询:databaseId 走 query
curl -sS "$APPBASE_ENDPOINT/moderation-configs/collections/tasks?databaseId=app-db" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 调整/启停:仅切 enabled 时省略 contentTypes,原有配置保留(databaseId 走 body)
curl -sS -X PATCH "$APPBASE_ENDPOINT/moderation-configs/collections/tasks" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"enabled":false,"databaseId":"app-db"}'
# 删除(databaseId 走 body)
curl -sS -X DELETE "$APPBASE_ENDPOINT/moderation-configs/collections/tasks" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"databaseId":"app-db"}'排查审核日志
写入被阻断(TablesDB 写入返回审核错误)时,先查日志定位原因,再检查项目级审核开关与审核服务配置。Web SDK 无 Moderation 服务(浏览器只感知写入成功/失败)。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
import { Query } from 'agentbase-node-sdk';
const blocked = await moderation.listLogs({
queries: [Query.equal('result', 'block')],
total: true
}); // 可按 resourceType / resourceId / databaseId / result / timestamp / userId / contentType 筛选
const one = await moderation.getLog({ logId: '<logId>' });import io.agentbase.Query;
io.agentbase.models.ModerationLogList blocked = moderation.listLogs(
List.of(Query.equal("result", "block")), true); // 可按 resourceType / resourceId / databaseId / result / timestamp / userId / contentType 筛选
io.agentbase.models.ModerationLog one = moderation.getLog("<logId>");from agentbase.query import Query
blocked = moderation.list_logs(queries=[Query.equal('result', 'block')], total=True)
# 可按 resource_type / resource_id / database_id / result / timestamp / user_id / content_type 筛选
one = moderation.get_log(log_id='<logId>')import "agentbase-go-sdk/query"
blocked, _ := mod.ListLogs(
mod.WithListLogsQueries([]string{query.Equal("result", "block")}),
mod.WithListLogsTotal(true)) // 可按 resourceType / resourceId / databaseId / result / timestamp / userId / contentType 筛选
_ = blocked
one, _ := mod.GetLog("<logId>")
_ = onecurl -sS "$APPBASE_ENDPOINT/moderation-logs?queries[]=equal(\"result\",\"block\")&total=true" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 单条:GET /moderation-logs/{logId}事实源
skills/ob-agentbase/references/content-moderation.md- appbase v2.9.0(tag v2.9.0,peeled
ebae9540…;审核二期docs/features/moderation/README.md) - agentbase-sdks v2.9.0 specs(
packages/sdks/server-nodejs/src/services/moderation.ts方法面:createConfig mode/requireManualReviewOnViolation)