配置 Hocuspocus 服务器

介绍

目前只需传入少量设置。大多数功能通过 hooks 控制。

设置

设置	描述	默认值
`name`	用于日志记录的实例名称。
`port`	服务器应监听的端口。	`80`
`address`	服务器应绑定的主机/接口，例如 `127.0.0.1`。如果未设置，服务器将监听所有接口。
`timeout`	连接健康检查间隔，单位为毫秒。在 v4 中从 30 秒增加到 60 秒。	`60000 (= 60s)`
`debounce`	在指定的毫秒数内对 onStoreDocument hook 的调用进行防抖。否则每次更新都会被持久化。	`2000 (= 2s)`
`maxDebounce`	确保至少在指定的时间（毫秒）内调用一次 onStoreDocument。	`10000 (= 10s)`
`quiet`	默认情况下，服务器会显示启动界面。如果传入 false，服务器将以静默方式启动。	`false`
`websocketOptions`	传递给底层 WebSocket 服务器的选项（例如 `{ maxPayload: 1024 * 1024 }`）。在 v4 中移入配置对象内部。	`{}`
`maxUnauthenticatedQueueSize`	单个连接在尚未完成身份验证期间可缓冲的最大字节数（跨所有文档）。超过此限制时将关闭连接。请参阅预身份验证资源限制。	`5242880 (= 5 MiB)`
`maxUnauthenticatedQueueMessages`	单个连接在尚未完成身份验证期间可缓冲的最大消息数（跨所有文档）。超过此限制时将关闭连接。	`1000`
`maxPendingDocuments`	单个连接在其中任何文档完成身份验证之前可以打开的不同文档的最大数量。超过此限制时将关闭连接。	`100`

使用示例

import { Server } from '@hocuspocus/server'

const server = new Server({
  name: 'hocuspocus-fra1-01',
  port: 1234,
  timeout: 60000,
  debounce: 5000,
  maxDebounce: 30000,
  quiet: true,
  websocketOptions: { maxPayload: 1024 * 1024 },
})

server.listen()

通用 Context 类型

从 v4 开始，服务器接受一个通用的 Context 类型参数，以便在所有 hooks 中实现端到端的类型安全：

import { Server } from '@hocuspocus/server'

interface MyContext {
  userId: string
  permissions: string[]
}

const server = new Server<MyContext>({
  async onAuthenticate({ token }) {
    // 返回值的类型为 MyContext
    return { userId: '123', permissions: ['read', 'write'] }
  },
  async onChange({ context }) {
    // context.userId 的类型为 string
    console.log(context.userId)
  },
})

该泛型的默认值为 any，因此未显式指定类型的现有代码仍可继续正常工作。

认证前资源限制

在认证完成之前收到的消息会按连接缓存在内存中。若没有上限，未认证客户端可能会耗尽服务器内存（参见 GHSA-xwhh-v746-pj9m）。以下三个设置用于限制这种缓存，一旦超过任一限制，连接就会立即关闭：

maxUnauthenticatedQueueSize（默认 5 MiB）— 每个连接缓冲的总字节数。
maxUnauthenticatedQueueMessages（默认 1000）— 每个连接缓冲的总消息数。
maxPendingDocuments（默认 100）— 单个连接在任一时刻可打开的、尚未通过认证的不同文档数量。每个待处理文档都有自己的队列和 hook 负载，因此这可以阻止客户端在保持每连接队列限制之内的同时，向多个文档名分散连接。

此外，空闲 timeout 会在认证前被强制作为一个绝对的认证截止时间（从连接建立时开始计算，不会因入站流量而刷新），直到连接对其首个文档完成认证。首次认证成功后，timeout 会恢复为该 socket 在其余生命周期中的正常空闲行为。

import { Server } from '@hocuspocus/server'

const server = new Server({
  maxUnauthenticatedQueueSize: 5 * 1024 * 1024, // 5 MiB
  maxUnauthenticatedQueueMessages: 1000,
  maxPendingDocuments: 100,
})

server.listen()

Previously示例

Next up钩子