后端即时通讯【免费下载链接】dendriteDendrite is a second-generation Matrix homeserver written in Go!项目地址https://gitcode.com/gh_mirrors/de/dendrite点击查看免费下载本指南系统讲解 Matrix 第二代家庭服务器homeserverDendrite 所支持的管理端点Admin API涵盖管理员权限的授予方式、各端点房间疏散、用户疏散、密码重置、全文检索重建、设备刷新、房间清理、服务器通知、用户信息查询的请求格式、参数含义与底层实现原理。读完本文你将能够通过curl直接调用这些端点完成日常运维并在出现 E2EE端到端加密解密失败、房间数据残留等问题时快速定位可用的管理手段。说明本文内容以仓库文档 docs/administration/4_adminapi.md 为主体骨架并结合 clientapi/routing/admin.go、clientapi/routing/routing.go、roomserver/internal/perform/perform_admin.go 等源码文件进行印证与扩充。一、使用管理 API 的前提条件Dendrite 目前支持的管理端点数量有限且官方文档明确提示这些端点目前不提供 API 稳定性保证其形态可能在无预警的情况下变化字段名、返回值、路径均可能调整后续会陆续新增更多端点。因此在实际部署中建议先核对所使用版本对应的源码路由见 clientapi/routing/routing.go。1.1 通过 curl 调用所有端点都要求携带有效的访问令牌access token通用调用形式如下curl --header Authorization: Bearer access_token -X POST|GET|PUT Endpoint URI -d Request Body Contents其中access_token访问令牌Bearer 方式放入请求头POST|GET|PUT按端点要求选择 HTTP 方法Endpoint URI端点路径见下文各节-d Request Body ContentsJSON 请求体GET 类端点通常不需要。访问令牌可以从大多数基于 Element 的 Matrix 客户端中获取进入Settings设置→Help About帮助与关于→Advanced高级→Access Token访问令牌。注意拥有 access token 即可以对应用户身份执行操作必须严格保密切勿泄露或提交到代码仓库。1.2 管理员身份校验机制从源码看Dendrite 的所有/_dendrite/admin/*端点均通过httputil.MakeAdminAPI包装该包装器在鉴权通过后还会强制校验device.AccountType ! userapi.AccountTypeAdmin否则直接返回403 Forbidden见 internal/httputil/httpapi.go。账户类型的枚举定义在 userapi/api/api.go枚举值含义AccountTypeUser 1普通用户账户AccountTypeGuest 2访客账户AccountTypeAdmin 3管理员账户AccountTypeAppService 4应用服务AppService账户即只有userapi_accounts表中account_type为3的用户才能调用管理端点。1.3 将已有账户提升为管理员官方文档给出的方法是在数据库中直接更新userapi_accounts表UPDATE userapi_accounts SET account_type 3 WHERE localpart $localpart;其中$localpart仅指用户名部分例如alice不含和域名。userapi_accounts表在 PostgreSQL 与 SQLite3 两种后端下均存在见 userapi/storage/postgres/accounts_table.go 与 userapi/storage/sqlite3/accounts_table.go表中注释也明确标注了account_type的取值user 1, guest 2, admin 3, appservice 4。提示该字段由迁移脚本deltas/2022021013023800_add_account_type.goPostgreSQL和deltas/2022021012490600_add_account_type.goSQLite3引入升级旧版本数据库时该列会自动补齐默认值为1普通用户。如果希望更规范地创建管理员也可以在注册流程之外直接以AccountTypeAdmin调用存储层CreateAccount参见测试用例 userapi/storage/storage_test.go。二、房间与用户疏散evacuateRoom与evacuateUser2.1 POST/_dendrite/admin/evacuateRoom/{roomID}该端点指示 Dendrite 让所有本地用户退出 URL 中指定的roomID房间。处理可能需要一定时间完成后返回 JSON 体包含所有受影响用户的用户 IDaffected数组。路由注册与响应格式见 clientapi/routing/routing.go 与 clientapi/routing/admin.go{ affected: [alice:example.com, bob:example.com, ...] }注意事项如果房间设置了别名例如房间已发布URL 中可能看不到房间 ID此时可在 Element Web 的Settings设置→Advanced高级中查看该房间的 internal ID内部 ID。从 roomserver/internal/perform/perform_admin.go 的实现看该操作会先通过RoomInfo校验房间存在且非 stub 状态然后查询房间内所有成员事件将成员状态改写为leave并依次构造、签名、提交m.room.member事件KindNew、非异步。若房间不存在路由层会返回404 Not Found。由于事件是逐个构建并提交的每个事件以PrevEvents链式衔接房间越大耗时越长属于预期行为。2.2 POST/_dendrite/admin/evacuateUser/{userID}该端点指示 Dendrite 让指定的本地userID退出其当前已加入的所有房间。返回 JSON 体包含所有受影响的房间 IDaffected数组。路由注册与响应格式见 clientapi/routing/routing.go 与 clientapi/routing/admin.go{ affected: [!room1:example.com, !room2:example.com, ...] }实现细节见 roomserver/internal/perform/perform_admin.go该端点只允许疏散本地用户若userID的域名不是本服务器IsLocalServerName校验不通过直接返回错误。实现会查询用户当前处于join与invite状态的房间列表逐个调用PerformLeave生成离开事件并通过OutputProducer.ProduceRoomEvents将输出事件广播给其他组件如 sync API。因此该操作同样可能耗时较长。三、重置用户密码resetPassword3.1 POST/_dendrite/admin/resetPassword/{userID}重置本地用户的密码。userID为完整用户 ID例如alice:example.com。请求体格式{ password: new_password_here, logout_devices: false }字段类型说明passwordstring新密码必填且不能为空字符串logout_devicesbool是否注销该用户的所有设备。若为true所有 access_token 将被作废可能导致加密消息无法解密潜在丢失实现细节见 clientapi/routing/admin.go路由层首先通过cfg.Matrix.SplitLocalID拆分userID得到 localpart 与服务器名并调用QueryAccountAvailability确认用户存在若可用则说明用户不存在返回404。随后校验密码非空并调用internal.ValidatePassword检查密码强度再通过PerformPasswordUpdate携带LogoutDevices标志写入新密码哈希。成功时返回{ password_updated: true }调用后用户即可用新密码登录若logout_devices为true旧设备全部失效用户需重新登录。四、全文检索重建索引fulltext/reindex4.1 GET/_dendrite/admin/fulltext/reindex该端点指示 Dendrite 对所有可搜索事件重建全文索引可搜索事件类型包括m.room.message消息正文body、m.room.topic主题topic和m.room.name房间名name。请求立即返回一个空 JSON 体{}实际索引在后台执行索引过程中服务器日志会每 1000 条或不足 1000 条时事件打印一次进度重建完成后调试日志中会出现类似Indexed 69586 events in 53.68223182s的汇总行可用于确认耗时与总量。前置条件全文检索必须在配置中启用。配置文件dendrite-sample.yaml中对应片段如下sync_api: # Configuration for the full-text search engine. search: # Whether or not search is enabled. enabled: true # The path where the search index will be created in. index_path: ./searchindex # The language most likely to be used on the server - used when indexing, to # ensure the returned results match expectations. language: en配置结构定义见 setup/config/config_syncapi.goindex_path默认值为./searchindex校验器要求该路径非空。底层原理结合源码该端点通过 NATS JetStream 发布InputFulltextReindex主题消息见 setup/jetstream/streams.go由消费端在后台触发全量重建路由层以 10 秒超时等待 NATS 应答见 clientapi/routing/admin.go。索引存储基于 BleveopenIndex打开或创建index_path下的索引文件Index方法通过批量写入batch将元素按事件 ID 索引见 internal/fulltext/bleve.go。增量索引发生在 sync API 的 roomserver 消费端writeFTS仅对m.room.message、m.room.name、m.room.topic三类事件提取对应字段body/name/topic写入索引m.room.redaction事件则从索引中删除被撤回的事件对于编辑m.replace关联的消息会删除原消息条目以避免搜索结果重复见 syncapi/consumers/roomserver.go。仓库自带的索引测试覆盖了索引写入、搜索与高亮提取等场景见 internal/fulltext/bleve_test.go。适用场景升级索引语言配置、索引文件损坏或早期版本索引不完整时可通过此端点强制重建而无需删除index_path目录后重启。五、刷新远端用户设备refreshDevices5.1 POST/_dendrite/admin/refreshDevices/{userID}该端点指示 Dendrite立即向联邦服务器查询/devices/{userID}以更新本地存储的该用户设备列表与设备密钥。成功时返回空 JSON 体{}。适用场景解决 E2EE 相关问题——例如远端用户更换设备或重置密钥后本地仍持有过期的设备信息导致远端用户无法解密消息。触发该端点可强制拉取最新设备与密钥重建设备列表的 stale过期状态。实现细节见 clientapi/routing/admin.go 与 userapi/internal/key_api.go路由层使用gomatrixserverlib.SplitID(, userID)解析域名若该用户是本服务器用户IsLocalServerName则拒绝执行本地设备列表不能通过此端点标记为 stale返回400。对远端用户调用PerformMarkAsStaleIfNeeded若本地已存在该设备的密钥记录则直接返回否则调用Updater.ManualUpdate将设备列表标记为需要从远端重新获取。之后用户设备的 key 查询流程会在同步时触发对远端/devices/{userID}的请求从而更新本地设备/密钥缓存。六、清理房间数据purgeRoom6.1 POST/_dendrite/admin/purgeRoom/{roomID}该端点指示 Dendrite 从数据库中移除指定房间的全部痕迹。返回空 JSON 体{}。重要限制不会删除媒体文件media API 中的图片、文件等仍会保留根据房间大小清理可能耗时较长路由层返回空 JSON 是在已通知其他组件删除该房间之后不代表所有组件的删除均已完成。实现细节见 roomserver/internal/perform/perform_admin.go首先用gomatrixserverlib.SplitID(!, roomID)校验传入的是合法的房间 ID以!开头而非别名或任意字符串然后调用r.DB.PurgeRoom(ctx, roomID)从 roomserver 数据库删除房间日志记录Purging room from roomserver最后通过OutputProducer.ProduceRoomEvents广播一条OutputTypePurgeRoom输出事件通知 sync API 等其他组件同步清理见 syncapi/consumers/roomserver.go 中onPurgeRoom对 sync API 库表的清理逻辑。注意_dendrite/admin/purgeRoom与疏散evacuate不同疏散是让用户离开房间而 purge 是从数据库删除房间本身两者面向不同的运维场景。七、发送服务器通知/_synapse/admin/v1/send_server_notice7.1 端点与配置前提该端点兼容 Synapse 的管理 API 风格用于向指定用户发送服务器通知Server Notice。它仅在配置中启用了server_notices时才会挂载见 clientapi/routing/routing.go挂载时日志会输出Enabling server notices at /_synapse/admin/v1/send_server_notice。请求体格式{ user_id: target_user:server_name, content: { msgtype: m.text, body: This is my message } }字段说明user_id接收通知的目标用户完整 IDcontent.msgtype消息类型通常为m.textcontent.body通知正文成功发送后返回{ event_id: event_id }关于服务器通知行为的更多细节可参考 Matrix 规范中的 Server Notices 章节Client-Server API。7.2 配置片段服务器通知在 dendrite-sample.yaml 中的配置如下# Server notices allows server admins to send messages to all users on the server. server_notices: enabled: false # The local part, display name and avatar URL (as a mxc:// URL) for the user that # will send the server notices. These are visible to all users on the deployment. local_part: _server display_name: Server Alerts avatar_url: # The room name to be used when sending server notices. This room name will # appear in user clients. room_name: Server Alerts配置结构定义见 setup/config/config_global.goenabled为总开关local_part是发送通知的机器人账号 localpart默认_serverdisplay_name与avatar_url是其显示名称与头像mxc://URLroom_name是服务器通知房间的名称默认 Server Alerts。7.3 底层行为结合 clientapi/routing/server_notices.go 的实现该端点的工作流程如下鉴权仅允许AccountTypeAdmin调用否则返回403事务去重若请求带{txnID}路径参数对应PUT方法会先查询事务缓存命中则直接返回缓存响应POST不带txnID时跳过——因此官方路由同时注册了PUT /admin/v1/send_server_notice/{txnID}与POST /admin/v1/send_server_notice两种形式且两者都会经过客户端限流rate limit校验请求user_id、content.msgtype、content.body任一缺失都返回400 Bad Request寻找/创建房间查询发送者_server账号与目标用户的共同房间若无共同房间则以m.federate: false禁止联邦、Visibility: private、PresetPrivateChat创建新房间并邀请目标用户同时在目标用户的账户数据中打上m.server_notice标签Order 1.0便于客户端识别若共同房间数大于 1 则报错发送消息以发送者设备在房间内构造m.room.message事件并提交给 roomserver返回event_id。发送者账号由getSenderDevice自动创建不存在时并配置头像与显示名见 clientapi/routing/server_notices.go。八、共享密钥注册/_synapse/admin/v1/registerGET /_synapse/admin/v1/register为共享密钥shared secret注册端点用于在启用注册令牌/共享密钥的场景下创建用户。该端点的配置与使用方式详见仓库文档 docs/administration/1_createusers.md用户创建指南。相关服务端校验逻辑可在 clientapi/routing/register_secret.go 中查看。九、查询用户信息/_matrix/client/v3/admin/whois/{userId}该端点遵循 Matrix 规范Client-Server API 中的GET /_matrix/client/v3/admin/whois/{userId}用于获取特定用户的信息。userId为完整用户 ID例如alice:domain.com。鉴权差异与/_dendrite/admin/*不同该端点允许两类调用者服务器管理员AccountTypeAdmin被查询用户本人userID device.UserID。若两者都不满足返回403 Forbidden见 clientapi/routing/admin_whois.go。响应结构见 clientapi/routing/admin_whois.go包含user_id与按设备 ID 组织的devices映射{ user_id: alice:domain.com, devices: { DEVICEID1: { sessions: [ { connections: [ { ip: 203.0.113.1, last_seen: 1700000000000, user_agent: Element/1.11.0 } ] } ] } } }其中ip为该设备最近一次会话的来源 IPlast_seen为最近活动时间戳毫秒user_agent为客户端标识。数据来源于 user API 的设备会话记录QueryDevices查询见 clientapi/routing/admin_whois.go。十、端点速查表端点方法作用响应/_dendrite/admin/evacuateRoom/{roomID}POST让所有本地用户退出指定房间{affected: [userID...]}/_dendrite/admin/evacuateUser/{userID}POST让指定本地用户退出其全部房间{affected: [roomID...]}/_dendrite/admin/resetPassword/{userID}POST重置本地用户密码{password_updated: true}/_dendrite/admin/fulltext/reindexGET后台重建全部可搜索事件索引{}/_dendrite/admin/refreshDevices/{userID}POST强制刷新远端用户设备/密钥{}/_dendrite/admin/purgeRoom/{roomID}POST从数据库移除房间不含媒体{}/_synapse/admin/v1/send_server_noticePOST或PUT /{txnID}向指定用户发送服务器通知{event_id: ...}/_synapse/admin/v1/registerGET共享密钥注册见 docs/administration/1_createusers.md/_matrix/client/v3/admin/whois/{userId}GET查询用户设备与连接信息见上文响应结构十一、运维注意事项与最佳实践令牌安全所有管理端点依赖access_token且管理令牌具有高权限务必妥善保管logout_devices: true的密码重置会使目标用户所有设备失效执行前应确认影响范围。端点的非稳定性官方文档明确表示这些端点当前无稳定性承诺升级 Dendrite 版本前应重新核对路由clientapi/routing/routing.go中的路径与请求/响应字段。耗时操作evacuateRoom、evacuateUser、purgeRoom均可能因房间/用户规模而耗时较长建议在低峰期执行fulltext/reindex在后台执行可通过 debug 日志中的Indexed N events in T汇总确认完成。联邦与本地边界refreshDevices仅面向远端用户本地用户会返回400evacuateUser仅支持本地用户purgeRoom只接受以!开头的房间 ID。配置联动send_server_notice依赖server_notices.enabledfulltext/reindex依赖sync_api.search.enabled与index_path。配置改动后需重启对应组件或整个 Dendrite 实例方可生效。以上管理能力覆盖了 Dendrite 运维中最常见的用户、房间、检索、设备与通知管理诉求结合仓库内 docs/administration 目录下的其他管理文档如 用户创建、注册配置、管理 API 使用前提可以形成一套完整的日常运维方案。赞分享后端即时通讯【免费下载链接】dendriteDendrite is a second-generation Matrix homeserver written in Go!项目地址https://gitcode.com/gh_mirrors/de/dendrite点击查看免费下载相关推荐Authentik用户管理指南从创建到权限控制的完整操作手册Authentik用户管理指南从创建到权限控制的完整操作手册 还在为复杂的用户身份管理而烦恼面对多应用系统的用户同步、权限分配和安全认证传统方案往往力不从后端认证鉴权单点登录Dendrite房间管理完全指南创建、邀请、权限全掌握Dendrite房间管理完全指南创建、邀请、权限全掌握 Dendrite作为第二代Matrix家庭服务器提供了强大而灵活的房间管理功能。无论你是新手还是经验后端即时通讯Dendrite用户管理终极指南从账户创建到设备管理的完整流程Dendrite用户管理终极指南从账户创建到设备管理的完整流程 Dendrite作为第二代Matrix家庭服务器提供了强大而灵活的用户管理功能。无论你是系统后端即时通讯上一篇electron-vue 常见问题排查指南空白窗口、文件资源管理器与主进程调试全解析下一篇DeepSeek Harness 会话事件折叠将 trace-only 事件并入承载事件的事件建模重构创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考