企业官网建设流程全解析

• 后端
• 即时通讯

本篇指南围绕 Dendrite（用 Go 编写的第二代 Matrix 联邦式聊天服务器）的安装规划文档展开，帮助你在动手安装前完成三项关键决策：选择 PostgreSQL 还是 SQLite 作为存储后端、估算服务器所需的 CPU/内存/磁盘资源、确认 Go、数据库、NATS 与反向代理等前置依赖。读完本文，你将能依据部署规模做出有依据的选型与容量规划，并为后续构建、配置与启动铺平道路。

一、为什么安装前必须先做规划

Dendrite 是一个由多个内部组件（roomserver、federationapi、syncapi、userapi 等）组成的 Matrix homeserver，数据全部持久化在 SQL 数据库中，组件之间则通过 NATS JetStream 进行消息传递。这意味着部署形态在启动之前就已由配置文件确定——尤其是数据库引擎的选择，它决定了后续所有建表、连接池与并发写入的行为，难以在运行中途随意切换。因此，规划阶段需要同时考虑三点：

1. 存储后端：单库全局连接池还是多库、PostgreSQL 还是 SQLite；
2. 硬件容量：用户数、房间数与房间复杂度直接决定资源水位；
3. 依赖链：编译工具链（Go）、数据库服务、消息总线与反向代理是否齐备。

以下各节逐一展开。

二、数据库选型：PostgreSQL 与 SQLite 的取舍

原文档明确指出，Dendrite 同时支持 PostgreSQL 与 SQLite 两种后端，但两者存在显著的权衡，官方推荐所有生产环境部署使用 PostgreSQL。

从代码结构也可以印证这种设计取向：setup/config/config_global.go中的DatabaseOptions专门为"全局连接池"提供了max_open_conns、max_idle_conns、conn_max_lifetime三个调优参数，并且默认将最大打开连接数设为 90——这是面向 PostgreSQL 这类可承载大量并发连接的服务端数据库设计的（参见 DatabaseOptions 定义）。而 SQLite 的典型形态则是"一组件一文件"，无法像 PostgreSQL 那样由所有组件共享同一个全局连接池，配置方式也因此不同（详见数据库准备文档）。

需要特别提醒的是：

• 原文档对 SQLite 的定位是"内置、易上手、但大多数情况下明显慢于 PostgreSQL"；
• 官方在数据库准备文档中进一步强调：SQLite 后端更慢、可靠性更低，不推荐用于生产，且不能跨多个组件共享同一个 SQLite 数据库文件——每个组件必须配置各自的数据库文件名，这意味着需要移除global.database段并为每个组件单独配置；
• 如果选择 SQLite，连接串形如file:dendrite_component.db（当前工作目录）或file:///path/to/dendrite_component.db（完整路径）。

三、硬件与资源需求规划

3.1 影响资源消耗的核心因素

Dendrite 无法给出一个"标准答案"式的 CPU/内存/磁盘配置，因为实际需求高度依赖以下三个因素：

1. 用户数量：注册用户越多，认证、同步、事件写入等负载越大；
2. 加入的房间数量：尤其是联邦房间——涉及远程服务器的房间通常比只有本地用户的房间消耗更多资源；
3. 房间复杂度：成员频繁进出（加入/离开）的房间，其状态与状态解析（state resolution）开销显著更高。

3.2 高负载任务与资源尖峰

有些任务的成本远高于日常请求，规划时必须为其预留余量：

• 通过联邦加入远程房间：需要拉取并处理远程历史事件与状态；
• 运行状态解析：房间状态发生分歧时，Dendrite 需要计算合并后的正确状态；
• 向拥有大量远程用户的大型联邦房间发送消息：事件需要广播给众多远程服务器并逐一确认。

这些任务会造成远超空闲水平的 CPU 与内存尖峰，因此资源规划不能只按平均负载来定，而应确保在尖峰时段依然有足够的余量，避免进程被操作系统 OOM 杀掉。

3.3 官方给出的参考基准

原文档给出的量化参考如下：

同时，若 PostgreSQL 与 Dendrite 运行在同一台机器上，必须为数据库引擎额外预留 CPU 与内存余量。在同一台机器上运行过多重型服务可能导致资源饥饿，进程可能因内存耗尽而被操作系统强制终止。

3.4 运行平台支持

Dendrite 可在以下平台运行：

• 官方支持：Linux、macOS、Windows Server；
• 预计可运行：FreeBSD、OpenBSD 等 BSD 变体；
• 未测试：AIX、Solaris、Plan 9、z/OS——在这些平台上运行效果"因环境而异"（your mileage may vary）。

四、依赖清单与版本要求

安装 Dendrite 前需确认以下依赖均已满足。

4.1 Go 工具链

• Dendrite 要求Go 1.21 或更高版本，不支持使用更老的 Go 版本构建；
• 若通过包管理器安装 Go，构建前请先运行go version确认版本符合要求；
• 仓库根目录的 go.mod 声明了模块github.com/matrix-org/dendrite，其依赖列表（如gomatrixserverlib、nats-server、bleve等）反映了当前版本的实际构建需求。

4.2 PostgreSQL（仅在使用 PostgreSQL 后端时需要）

• 若采用 PostgreSQL 数据库引擎，需要安装PostgreSQL 12 或更高版本；
• 数据库必须以UTF-8 编码创建，否则部署可能遇到问题；
• 详细建库步骤（角色创建、建库命令）参见数据库准备文档。

4.3 NATS Server（无需手动安装）

Dendrite 内置了 NATS Server，因此不需要单独安装。这一结论在源码中有直接证据：

• setup/jetstream/nats.go 中的Prepare方法会检查配置中的addresses：如果为空，就在进程内启动一个内嵌的 NATS Server（natsserver.Options{JetStream: true, StoreDir: ...}），并通过InProcessServer建立连接；
• setup/config/config_jetstream.go 中JetStream结构体的Addresses注释写明："如果不指定任何地址，monolith 模式下将自动启动一个内部 NATS server"。

这意味着两种可选的 JetStream 形态：

• 内置 NATS：global.jetstream.addresses留空，仅配置持久化目录storage_path；
• 独立 NATS：配置addresses（如localhost:4222），多节点集群可配置多个地址；此时无需配置storage_path。

4.4 反向代理（强烈建议）

Caddy、NGINX、HAProxy 等反向代理对生产部署非常有用。原文档不在此处展开代理配置，但仓库中提供了现成的示例：

• Caddy 示例配置：将/_matrix路径反代到 Dendrite，例如reverse_proxy /_matrix/* localhost:8008，并可同时处理.well-known/matrix/*的响应；
• NGINX 示例配置：监听 443 端口并使用proxy_pass http://monolith转发。

4.5 Windows 构建环境

• 若要在Windows上构建 Dendrite，需要将gcc加入 PATH；
• 官方推荐的途径是使用MinGW-w64环境进行安装与构建。仓库 go.mod 中mattn/go-sqlite3（依赖 cgo）等依赖的存在，正是 Windows 下需要 C 编译器的原因。

五、规划之后：一次安装的完整链路

完成上述规划后，安装流程通常按以下顺序展开（各环节均有独立文档）：

1. 域名与联邦规划：Dendrite 的 server_name 必须是可被互联网解析的域名，用户 ID 形如@user:example.com。联邦发现依次尝试 well-known 委派、DNS SRV 委派、直连 8448 端口，细节与委派配置参见域名设置文档；
2. 构建二进制：在源码根目录执行go build -o bin/ ./cmd/...，产物位于bin子目录，详见构建文档；
3. 生成签名密钥：运行./bin/generate-keys --private-key matrix_key.pem生成 PEM 格式的服务器签名私钥，该密钥必须严格保密并妥善备份，详见签名密钥文档；
4. 准备数据库：PostgreSQL 场景需手动创建 UTF-8 编码的数据库与角色；SQLite 场景则只需在配置中指定文件名，详见数据库准备文档；
5. 编写配置文件：复制仓库根目录的 dendrite-sample.yaml 为dendrite.yaml，至少填写global.server_name、global.private_key与 JetStream/数据库配置，详见配置文档；
6. 启动服务：执行./dendrite -config /path/to/dendrite.yaml，默认监听 HTTP 8008 端口；可用-http-bind-address与-https-bind-address调整监听地址（源码见 cmd/dendrite/main.go），详见启动文档。

六、与规划直接相关的配置项速查

以下配置项在规划阶段就应确定，并最终落到配置文件中（示例取自 dendrite-sample.yaml）：

global: # 域名即 server_name，决定了用户 ID 与联邦身份 server_name: example.com # 签名私钥路径（由 generate-keys 生成） private_key: matrix_key.pem # PostgreSQL 全局连接池（monolith + PostgreSQL 场景） database: connection_string: postgresql://username:password@hostname/dendrite?sslmode=disable max_open_conns: 90 max_idle_conns: 5 conn_max_lifetime: -1 # JetStream：addresses 留空则使用内置 NATS Server jetstream: # addresses: # - localhost:4222 storage_path: ./ topic_prefix: Dendrite

要点说明：

• max_open_conns: 90的默认值来自 config_global.go 的DatabaseOptions.Defaults，是面向 PostgreSQL 并发写能力的典型配置；
• 若使用 SQLite，则必须删除global.database段，并为各组件（app_service_api、federation_api、key_server、media_api、mscs、relay_api、room_server、sync_api、user_api）分别配置database.connection_string；
• topic_prefix用于在同一 NATS 部署上运行多个 Dendrite 时隔离流名称（源码见 config_jetstream.go）。

七、结论

规划阶段的核心结论可以浓缩为三条：

1. 生产环境一律选择 PostgreSQL，并预留额外的数据库进程资源；SQLite 仅适合测试、小规模或极简部署；
2. 资源按尖峰而非均值规划：最低 1GB RAM 起步，面向联邦参与的舒适部署建议 2-4 核 + 8GB RAM，并随用户数增长而扩容；
3. 依赖在编译前确认：Go ≥ 1.21、PostgreSQL ≥ 12（如使用）、无需单独安装 NATS（内置）、生产部署准备反向代理（参考 Caddy 与 NGINX 示例）、Windows 下准备 gcc/MinGW-w64。

完成这些决策后，即可按安装手册的步骤进入实际部署阶段。

• 后端
• 即时通讯