后端即时通讯【免费下载链接】synapseSynapse: Matrix homeserver written in Python/Twisted.项目地址https://gitcode.com/gh_mirrors/sy/synapse点击查看免费下载本文基于 SynapseMatrix homeserverPython/Twisted 实现官方管理接口文档系统讲解/_synapse/admin/v1/event_reports系列三个端点举报列表分页查询、单条举报详情查看、以及举报记录删除。读者读完将掌握如何用access_token调用 Admin API 审计与处置用户举报理解每个 URL 参数、返回字段的语义与默认值并能结合源码理解其分页与过滤实现原理。背景什么是 Event Report在 Matrix 生态中客户端可以通过m.report消息对应的服务端接口为POST /_matrix/client/v3/rooms/{roomId}/report/{eventId}对房间内的某条事件进行举报附带一个reason举报理由与一个score严重程度评分-100 表示“最具冒犯性”0 表示“无害”。这些举报记录会被持久化到 Synapse 数据库的event_reports表中供服务器管理员通过管理 API 审计和处理。从数据库 schema 可以看到该表的原始结构synapse/storage/schema/main/delta/32/reports.sqlCREATE TABLE event_reports( id BIGINT NOT NULL PRIMARY KEY, received_ts BIGINT NOT NULL, room_id TEXT NOT NULL, event_id TEXT NOT NULL, user_id TEXT NOT NULL, reason TEXT, content TEXT );其中content字段以 JSON 形式保存了举报请求中的score与reason等附加内容reason单独成列用于索引与过滤。管理员 API 返回结果时会将该 JSON 反序列化拆出score与reason两个字段返回。权限与认证前提使用本节全部接口都必须提供服务器管理员账号的access_token通过Authorization: Bearer token请求头携带否则请求会被拒绝。关于 Admin API 的认证方式与管理员账号配置参见 Admin API 使用说明。从源码实现synapse/rest/admin/event_reports.py看每个处理器在业务逻辑前都会调用await assert_requester_is_admin(self._auth, request)测试用例也验证了两种失败场景tests/rest/admin/test_event_reports.py未携带 token 调用GET /_synapse/admin/v1/event_reports返回401errcode为MISSING_TOKENtest_no_auth普通非管理员用户调用返回403errcode为FORBIDDENtest_requester_is_no_admin。一、列出事件举报GET /_synapse/admin/v1/event_reports该接口返回本服务器已知的所有事件举报记录支持分页、排序方向与按用户/房间过滤。请求GET /_synapse/admin/v1/event_reports?from0limit10URL 参数参数类型必填默认值说明limitinteger否100本次调用返回的最大条数用于分页frominteger否0结果偏移量。应视为不透明值只应使用上一次调用返回的next_token不应手工指定其他值dirstring否b举报记录的排序方向bbackwards为最新的在前fforwards为最旧的在前user_idstring否无过滤条件只返回user_id举报人包含该值的记录room_idstring否无过滤条件只返回room_id包含该值的记录源码synapse/rest/admin/event_reports.py中对参数的解析与校验如下start parse_integer(request, from, default0) limit parse_integer(request, limit, default100) direction parse_enum(request, dir, Direction, Direction.BACKWARDS) user_id parse_string(request, user_id) room_id parse_string(request, room_id) if start 0: raise SynapseError(HTTPStatus.BAD_REQUEST, The start parameter must be a positive integer., errcodeCodes.INVALID_PARAM) if limit 0: raise SynapseError(HTTPStatus.BAD_REQUEST, The limit parameter must be a positive integer., errcodeCodes.INVALID_PARAM)因此若传入负数的from或limit接口会返回400与M_INVALID_PARAM。响应示例{ event_reports: [ { event_id: $bNUFCwGzWca1meCGkjp-zwslF-GfVcXukvRLI1_FaVY, id: 2, reason: foo, score: -100, received_ts: 1570897107409, canonical_alias: #alias1:matrix.org, room_id: !ERAgBpSOcCCuTJqQPk:matrix.org, name: Matrix HQ, sender: foobar:matrix.org, user_id: foo:matrix.org }, { event_id: $3IcdZsDaN_En-S1DF4EMCy3v4gNRKeOJs8W5qTOKj4I, id: 3, reason: bar, score: -100, received_ts: 1598889612059, canonical_alias: #alias2:matrix.org, room_id: !eGvUQuTCkHGVwNMOjv:matrix.org, name: Your room name here, sender: foobar:matrix.org, user_id: bar:matrix.org } ], next_token: 2, total: 4 }响应字段字段类型说明idinteger举报记录的 IDreceived_tsinteger举报提交时间Unix 时间戳毫秒room_idstring被举报事件所在房间的 IDnamestring房间名称event_idstring被举报事件的 IDuser_idstring举报人撰写举报理由的用户的用户 IDreasonstring举报人填写的理由可能为空字符串或nullscoreinteger举报严重程度评分-100 为“最具冒犯性”0 为“无害”可能为nullsenderstring被举报原始事件发送者的用户 IDcanonical_aliasstring房间的规范别名未设置时为nullnext_tokeninteger分页游标见下文分页说明totalinteger与查询条件user_id、room_id匹配的举报总数分页机制判断响应中是否含next_token若存在next_token将from设为该值再次调用本端点即可取得下一页数据若响应中没有next_token说明没有更多举报可翻页了。从源码可见next_token的生成规则synapse/rest/admin/event_reports.pyret {event_reports: event_reports, total: total} if (start limit) total: ret[next_token] start len(event_reports)即当from limit仍小于总数total时next_token from 本次实际返回条数否则不返回该字段。过滤与排序的底层实现分页与过滤最终由存储层 synapse/storage/databases/main/room.py 的get_event_reports_paginate完成其 SQL 行为值得注意user_id与room_id过滤采用LIKE % || 参数 || %子串匹配如er.user_id LIKE ?、er.room_id LIKE ?所以传部分 ID 也能命中dirb时按received_ts DESC排序最新在前dirf时按received_ts ASC排序最旧在前使用LIMIT ? OFFSET ?实现分页查询会对event_reports别名erLEFT JOIN events获取发送者sender并JOIN room_stats_state获取房间name与canonical_alias。源码注释特别说明即使不使用room_stats_state的列也必须 JOIN 它因为 JOIN 会影响返回的行数例如房间状态缺失、房间可能已被删除的情况从而保证“总数统计查询”与“结果查询”一致content字段经db_to_json反序列化后取出score与reason若某行 JSON 解析失败会记录错误日志并跳过该行Unable to parse json from event_reports。二、查看单条举报详情GET /_synapse/admin/v1/event_reports/report_id该接口返回指定举报记录的完整信息包括被举报事件的原始 JSON。请求GET /_synapse/admin/v1/event_reports/report_idURL 参数参数类型说明report_idstring事件举报记录的 ID数据库主键源码中对report_id的校验逻辑synapse/rest/admin/event_reports.py必须是能解析为非负整数的字符串否则返回400M_INVALID_PARAM若数据库中没有该 ID则返回404NotFoundError(Event report not found)。响应示例{ event_id: $bNUFCwGzWca1meCGkjp-zwslF-GfVcXukvRLI1_FaVY, event_json: { auth_events: [ $YK4arsKKcc0LRoe700pS8DSjOvUT4NDv0HfInlMFw2M, $oggsNXxzPFRE3y53SUNd7nsj69-QzKv03a1RucHu-ws ], content: { body: matrix.org: This Week in Matrix, format: org.matrix.custom.html, formatted_body: strongmatrix.org/strong:bra href\https://matrix.org/blog/\strongThis Week in Matrix/strong/a, msgtype: m.notice }, depth: 546, hashes: { sha256: xK1//xnmvHJIOvbgXlkI8eEqdvoMmihVDJ9J4SNlsAw }, origin: matrix.org, origin_server_ts: 1592291711430, prev_events: [ $YK4arsKKcc0LRoe700pS8DSjOvUT4NDv0HfInlMFw2M ], prev_state: [], room_id: !ERAgBpSOcCCuTJqQPk:matrix.org, sender: foobar:matrix.org, signatures: { matrix.org: { ed25519:a_JaEG: csOUKW/iHx5pEidbWxh0UiNNHwe46Ai9LwNzAh16aWDNszVIe2gaAcVZfvNsBhakQTew51tlKmL2kspXk/Dg } }, type: m.room.message, unsigned: { age_ts: 1592291711430 } }, id: report_id, reason: foo, score: -100, received_ts: 1570897107409, canonical_alias: #alias1:matrix.org, room_id: !ERAgBpSOcCCuTJqQPk:matrix.org, name: Matrix HQ, sender: foobar:matrix.org, user_id: foo:matrix.org }响应字段与列表接口相比单条详情返回了额外的event_json字段字段类型说明idinteger举报记录 IDreceived_tsinteger举报提交时间Unix 毫秒时间戳room_idstring被举报事件所在房间 IDnamestring房间名称event_idstring被举报事件 IDuser_idstring举报人用户 IDreasonstring举报理由可能为空scoreinteger举报评分-100 最严重0 无害senderstring被举报事件发送者用户 IDcanonical_aliasstring房间规范别名未设置时为nullevent_jsonobject被举报原始事件的完整 JSON含content、type、sender、origin_server_ts、signatures、hashes、auth_events、prev_events等事件原始字段event_json的作用是让管理员无需另查事件详情即可直接看到被举报内容的原始内容如消息正文、格式化后的 HTML、消息类型等便于判断举报是否成立。存储层实现synapse/storage/databases/main/room.py 的get_event_report中该接口额外JOIN event_json ON event_json.event_id er.event_id并把事件原始 JSON 以event_json键返回。三、删除单条举报记录DELETE /_synapse/admin/v1/event_reports/report_id该接口用于删除指定举报记录。删除成功后响应体为空 JSON 对象{}。请求DELETE /_synapse/admin/v1/event_reports/report_idURL 参数参数类型说明report_idstring要删除的事件举报记录 ID成功响应请求成功后返回 HTTP200响应体为{}失败场景report_id无法解析为非负整数返回400M_INVALID_PARAMreport_id不存在返回404NotFoundError(Event report not found)。存储层delete_event_reportsynapse/storage/databases/main/room.py通过simple_delete_one从event_reports表删除对应id的行当记录不存在时捕获StoreError返回False由 REST 层转换为404。实战示例用 curl 完成一次举报审计以下是结合上述三个端点的完整 curl 调用示例$TOKEN为管理员access_token# 1. 列出前 10 条举报最新的在前 curl -H Authorization: Bearer $TOKEN \ https://your-server.example/_synapse/admin/v1/event_reports?from0limit10 # 2. 按举报人过滤 curl -H Authorization: Bearer $TOKEN \ https://your-server.example/_synapse/admin/v1/event_reports?user_idfoo:matrix.org # 3. 按房间过滤并按最旧在前排序 curl -H Authorization: Bearer $TOKEN \ https://your-server.example/_synapse/admin/v1/event_reports?room_id!ERAgBpSOcCCuTJqQPk:matrix.orgdirf # 4. 查看单条举报详情含被举报事件原始 JSON curl -H Authorization: Bearer $TOKEN \ https://your-server.example/_synapse/admin/v1/event_reports/2 # 5. 删除某条举报记录 curl -X DELETE -H Authorization: Bearer $TOKEN \ https://your-server.example/_synapse/admin/v1/event_reports/2相关实现文件索引REST 接口实现synapse/rest/admin/event_reports.py存储层查询与删除逻辑synapse/storage/databases/main/room.pyget_event_report、get_event_reports_paginate、delete_event_report数据库表结构synapse/storage/schema/main/delta/32/reports.sql测试用例tests/rest/admin/test_event_reports.py客户端侧举报接口产生举报数据的来源synapse/rest/client/report_event.py赞分享后端即时通讯【免费下载链接】synapseSynapse: Matrix homeserver written in Python/Twisted.项目地址https://gitcode.com/gh_mirrors/sy/synapse点击查看免费下载相关推荐Synapse 媒体管理 Admin API 完全指南查询、隔离与删除本地/远端媒体Synapse 媒体管理 Admin API 完全指南查询、隔离与删除本地/远端媒体 SynapseMatrix 协议的 Python/Twisted 实现后端即时通讯如何提升 Windows 游戏帧率AtlasOS 显卡优化实操教程如何提升 Windows 游戏帧率AtlasOS 显卡优化实操教程 打开大型游戏帧数忽高忽低、画面偶尔卡一下、按键响应慢半拍——这往往不是显卡不行而是 W后端即时通讯Use-After-Free、双重释放一网打尽Matrix MemGuard 基于 GWP-Asan 的堆内存检测实现Use After Free、双重释放一网打尽Matrix MemGuard 基于 GWP Asan 的堆内存检测实现 在 Android 的 Native可观测性性能剖析移动开发上一篇Spring AI终极指南如何用Java构建智能AI应用的完整教程下一篇UVR 5.6 安装指南从 0 到跑通第一首歌创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考