企业官网建设流程全解析

• 后端
• 即时通讯

本指南以 Dendrite 官方安装文档（docs/installation 章节）为主线，系统讲解在自建部署一个 Dendrite Matrix 服务器时所需的全部关键环节：部署前的资源与依赖规划、域名与联邦委派（delegation）配置、TLS 证书与反向代理设置、手动源码编译与数据库准备、签名密钥生成、配置文件逐项解读，以及 Docker Compose 与 Kubernetes Helm 两种容器化安装方式。读完本文，你将具备从零到一完整部署一个可参与联邦的 Dendrite 实例的实操能力，并理解每项配置背后的源码级实现原理。

一、部署前的规划

数据库引擎选型：PostgreSQL 与 SQLite

Dendrite 支持 PostgreSQL 和 SQLite 两种存储后端，二者取舍差异巨大（详见 部署规划文档）：

• PostgreSQL：需要单独安装并独立运行于 Dendrite 之外，整体资源占用更高，但性能显著优于SQLite。PostgreSQL 具备更好的写入并发能力，允许 Dendrite 并行处理更多任务，这对参与联邦的部署来说几乎是必需的。
• SQLite：内建于 Dendrite，无需额外数据库引擎，搭建更省事，但多数场景下比 PostgreSQL 慢得多。SQLite 同一时刻只允许一个写入者，会严重限制 Dendrite 并行处理任务的能力。

官方目前对所有生产部署均推荐 PostgreSQL。

资源需求评估

Dendrite 可在 Linux、macOS 与 Windows Server 上运行，FreeBSD、OpenBSD 等 BSD 变体通常也能正常工作；AIX、Solaris、Plan 9 与 z/OS 未经测试（见 规划文档）。

CPU、内存与磁盘需求很难给出绝对值，主要取决于：

• 服务器上的用户数量；
• 服务器加入的房间数量——联邦房间通常比仅含本地用户的房间消耗更多资源；
• 房间的复杂度——成员频繁进出的房间复杂度通常高得多。

某些任务格外昂贵，例如通过联邦加入房间、执行状态解析（state resolution）、向包含大量远程用户的大型联邦房间发送消息。因此规划时要预留足够的资源余量，以承受远超空闲水平的 CPU/内存尖峰：

• 绝对下限：1GB RAM；
• 舒适日常部署（供若干本地用户参与联邦房间）：2–4 CPU 核心 + 8GB RAM，用户数增加时应相应加配。

若 PostgreSQL 与 Dendrite 同机运行，还需为数据库引擎额外预留 CPU 与内存余量，否则过载时进程可能被操作系统 OOM 杀掉。

依赖清单

• Go：当前 Dendrite 要求Go 1.21 或更高（见 规划文档）。通过包管理器安装 Go 后，务必先运行go version确认版本满足要求。
• PostgreSQL：若使用 PostgreSQL 后端，需PostgreSQL 12 或更高版本。
• NATS Server：Dendrite自带内建 NATS Server（基于 JetStream），无需手动安装。
• 反向代理：Caddy、NGINX、HAProxy 等反向代理对生产部署很有用。仓库提供了 Caddy 示例配置 与 NGINX 示例配置。
• Windows 构建：在 Windows 上编译需要gcc在 PATH 中，推荐通过 MinGW-w64 环境安装并构建。

二、域名与联邦委派配置

每个 Matrix 服务器都需要一个唯一标识自身的 server name。例如服务器名为example.com，则用户名为@user:example.com格式（见 域名设置文档）。联邦场景下该域名必须已注册并配置好相应的 DNS 记录。

联邦服务器发现机制

Matrix 服务器之间联邦互连时，按以下顺序发现对方：

1. 若example.com上存在 well-known 委派，则使用 well-known 文件中的域名与端口连接远程服务器；
2. 若存在 DNS SRV 委派，则使用 SRV 记录中的 IP 与端口连接；
3. 若两者均未配置，则尝试通过 HTTPS 直连example.com的 TCP/8448 端口。

TLS 证书要求

联邦要求域名上存在受信任 CA 签发的有效 TLS 证书。Let's Encrypt 是常见选择——证书受公开信任、免费且可通过 ACME 协议自动化。自签名证书不适合联邦，通常会被其他服务器拒绝。最佳实践是自动化证书续期，最省事的做法是让反向代理代劳：Caddy被官方推荐为 Dendrite 前端的生产级反向代理，只要域名先指向你的服务器，它就会默认自动获取并续期 TLS 证书。核心规则是把所有/_matrix路径反代到 Dendrite：

reverse_proxy /_matrix/* localhost:8008

反向代理可以监听标准 HTTPS 端口 TCP/443，前提是域名的委派配置指向 TCP/443。

委派（Delegation）的两种方式

委派让你可以指定 Dendrite 实例实际可达的服务器名与端口，或将 Dendrite 托管在与被委派域名不同的服务器名上。例如实例实际位于matrix.example.com:8448，可通过委派让用户获得@user:example.com而非@user:matrix.example.com的用户名：

• Well-known 委派（推荐）：在目标域名上通过 HTTPS 提供 well-known 文本文件，指向matrix.example.com:8448；
• DNS SRV 委派（不推荐）：见下文说明。

若使用反向代理转发/_matrix，well-known 或委派内容必须指向反向代理监听的域名与端口。

Well-known 委派配置

使用 well-known 委派要求在example.com上运行一个监听标准 HTTPS 端口 TCP/443 的 Web 服务器。假设 Dendrite 在matrix.example.com:8448上监听 HTTPS 连接，委派文件须在https://example.com/.well-known/matrix/server提供，内容如下：

{ "m.server": "matrix.example.com:8448" }

Caddy 配置示例：

handle /.well-known/matrix/server { header Content-Type application/json header Access-Control-Allow-Origin * respond `{"m.server": "matrix.example.com:8448"}` } handle /.well-known/matrix/client { header Content-Type application/json header Access-Control-Allow-Origin * respond `{"m.homeserver": {"base_url": "https://matrix.example.com:8448"}}` }

仓库还提供了完整的 Caddyfile 示例（含.well-known响应与/_matrix反代两个站点块）和 NGINX 示例。

让 Dendrite 自己提供 well-known：如果 Dendrite 直接暴露在example.com:443，不想为.well-known单独架设 Web 服务器，可在配置中设置well_known_server_name，Dendrite 会代为提供m.server值：

global: ... well_known_server_name: "example.com:443"

该选项在 dendrite-sample.yaml 的global段有对应注释说明（well_known_server_name用于委派 server-server 通信，另有well_known_client_name用于委派 client-server 通信）。

DNS SRV 委派（不推荐）

SRV 记录行为相当反直觉：它只会改变其他服务器连接的 IP 与端口，不会影响域名本身。即联邦请求的Host头与 TLS SNI 仍是example.com，即使 SRV 指向matrix.example.com。这意味着服务器必须为example.com而非matrix.example.com配置有效 TLS 证书；若有反向代理，代理配置也必须按example.com书写，因为它永远不会在入站请求中看到matrix.example.com。若两个域名指向同一 IP，SRV 记录基本没有意义（仅可改变端口）。如确要用 SRV，服务名为_matrix，协议为_tcp。

三、手动源码构建与安装

构建全部命令

Dendrite 除服务器本体外还有多个实用命令。在源码仓库根目录执行（见 构建文档）：

go build -o bin/ ./cmd/...

构建产物将输出到bin子目录。

安装 dendrite 二进制

用go install将 Dendrite 二进制安装到$GOPATH/bin：

go install ./cmd/dendrite

或用go build指定自定义输出路径：

go build -o /usr/local/bin/ ./cmd/dendrite

cmd/目录下包含dendrite（服务器主程序）、generate-keys（生成签名密钥）、generate-config（生成配置）等工具。从 cmd/dendrite/main.go 的源码看，monolith 模式会把 appservice、federationapi、roomserver、userapi 等全部内部 API 组合进单一进程，并通过AddAllPublicRoutes暴露 Matrix API。

四、数据库存储准备

PostgreSQL：手动建库

Dendrite 能自动创建数据库表、索引与序列，但不能自己创建数据库，必须手动建库，且数据库必须使用 UTF-8 编码，否则部署会出问题（见 数据库文档）。

推荐做法：

1. 配置一个供 Dendrite 连接数据库的角色（含用户名与密码）；
2. 创建数据库，并确保该角色拥有足够权限——因为表、索引、序列均由 Dendrite 自行创建与管理。

连接字符串格式：Dendrite 仅支持 PostgreSQL libpq 的 "Connection URIs" 格式，不支持"Keyword/Value" 格式。例如：

• postgresql://user:pass@hostname/database?options=...
• postgres://user:pass@hostname/database?options=...

需要禁用数据库连接的 SSL/TLS 时，在连接串末尾追加?sslmode=disable。

创建角色（macOS 上可省略sudo -u postgres）：

sudo -u postgres createuser -P dendrite

创建单一数据库（使用上面的dendrite角色）：

sudo -u postgres createdb -O dendrite -E UTF-8 dendrite

SQLite：无需建库但有严格限制

警告：SQLite 后端更慢、可靠性更低，不推荐用于生产，应改用 PostgreSQL；官方表示使用 SQLite 后端遇到问题可能无法提供支持。

SQLite 部署无需手动建库，只需在配置文件中指定数据库文件名，Dendrite 启动时自动创建并填充。

关键限制：Dendrite不能跨组件共享同一个 SQLite 数据库文件。每个组件必须配置自己的 SQLite 文件名——即必须删除global.database段，改为在每个组件各自的配置段中分别配置。

SQLite 连接字符串形式：

• 当前工作目录路径：file:dendrite_component.db
• 完整指定路径：file:///path/to/dendrite_component.db

这一行为与 cmd/generate-config/main.go 的源码逻辑一致：当-db参数为空或为 SQLite URI 时，会为federationapi、keyserver、mscs、mediaapi、roomserver、syncapi、userapi、relayapi各自生成独立的dendrite_<component>.db文件；只有传入 PostgreSQL URI 时才写入global.database连接池。

五、生成服务器签名密钥

所有 Matrix 服务器都需要一个签名私钥，用于对联邦请求与事件进行认证（见 签名密钥文档）。

生成新密钥

使用generate-keys工具（构建后位于bin目录）：

./bin/generate-keys --private-key matrix_key.pem

生成的matrix_key.pem即为新签名密钥。从 cmd/generate-keys/main.go 源码可见，该工具还支持-tls-cert/-tls-key生成 TLS 证书、-server指定域名、-keysize指定 RSA 密钥位数等可选参数，其中签名密钥由test.NewMatrixKey生成 Ed25519 私钥。

重要警告

• 该密钥高度敏感，绝不可分享给任何人——任何人都不应索要此密钥，即使是为了排查 Dendrite 故障；
• 务必做好安全备份：未来在同一域名上重装 Dendrite 或其他 Matrix 服务器时很可能需要它；丢失密钥可能导致加入联邦房间困难。

旧密钥复用与格式

• 同一域名下旧 Dendrite 实例的密钥可直接原样复用，无需额外配置；
• 曾标记为过期的密钥不可再用；
• 旧 Synapse 实例的密钥可转换为 Dendrite 的 PEM 格式并配置为old_private_keys。

Dendrite 的 PEM 格式结构：

-----BEGIN MATRIX PRIVATE KEY----- Key-ID: ed25519:<Key ID> <Base64 Encoded Key Data> -----END MATRIX PRIVATE KEY-----

转换 Synapse 密钥

Synapse 密钥格式为ed25519 <Key ID> <Base64 Encoded Key Data>。转换为 PEM 时，Key ID 必须原样复制，Base64 数据末尾的等号（=）必须保留（若原密钥没有需补上），因为密钥数据必须补齐到恰好 32 字节：

-----BEGIN MATRIX PRIVATE KEY----- Key-ID: ed25519:<Key ID> <Base64 Encoded Key Data>= -----END MATRIX PRIVATE KEY-----

六、Dendrite 配置文件详解

Dendrite 使用 YAML 配置文件，仓库根目录提供样例 dendrite-sample.yaml。你需要复制该样例并命名为dendrite.yaml，再按自身部署调整（见 配置文档）。配置文件采用version: 2格式，分为global段与各组件段（app_service_api、client_api、federation_api、media_api、mscs、sync_api、user_api、relay_api等）。

server_name

server_name必须与你在域名委派配置中选择的域名一致：

global: # ... server_name: example.com

服务器签名密钥路径

在global段设置private_key指向签名密钥文件：

global: # ... private_key: /path/to/matrix_key.pem

JetStream 配置

Dendrite 部署可使用内建 NATS Server，也可对接独立 NATS Server。

使用内建 NATS Server：jetstream段下不配置任何服务器地址，并设置storage_path指向文件系统上的持久化目录：

global: # ... jetstream: storage_path: /path/to/storage/folder topic_prefix: Dendrite

使用独立 NATS Server：配置addresses指向 NATS Server 监听端口：

global: # ... jetstream: addresses: - localhost:4222 topic_prefix: Dendrite

使用独立 NATS 时无需配置storage_path；连接多节点 NATS 集群时可在addresses中配置多个地址。从 config_jetstream.go 源码可见该配置项对应结构：Addresses（默认空，空时在 monolith 模式下自动启动内建 NATS）、StoragePath（默认./）、TopicPrefix（默认Dendrite）、InMemory等，流名由TopicPrefix拼接而成。

全局数据库连接池

若要使用单一连接池连接单个 PostgreSQL 数据库，取消注释并配置global.database段：

global: # ... database: connection_string: postgres://user:pass@hostname/database?sslmode=disable max_open_conns: 90 max_idle_conns: 5 conn_max_lifetime: -1

然后必须删除或注释掉配置文件中其他区域的database段（如app_service_api、federation_api、key_server、media_api、mscs、relay_api、room_server、sync_api、user_api块下），否则它们会覆盖全局数据库配置。dendrite-sample.yaml中的注释也明确指出：该段仅适用于 PostgreSQL monolith 部署；SQLite monolith 部署必须在各组件段分别配置database。

全文检索（Full-text search）

Dendrite 使用 Bleve 支持全文索引，在sync_api段配置。根据服务器上最可能使用的语言调整language，以确保检索结果符合预期：

sync_api: # ... search: enabled: false index_path: "./searchindex" language: "en"

从 internal/fulltext/bleve.go 源码可见，Bleve 分析器通过 side-effect import 支持 ar、cjk、ckb、da、de、en、es、fa、fi、fr、hi、hr、hu、it、nl、no、pt、ro、ru、sv、tr 等语言分析包；dendrite-sample.yaml 中注明完整语言列表见 Bleve 的analysis/lang目录。

其他值得关注的配置段

完整配置远不止上述几项，建议通读 dendrite-sample.yaml 全部选项，重点包括：

• global.key_validity_period：远程服务器缓存我方签名密钥的时长（默认168h0m0s）；
• global.old_private_keys：旧密钥列表（含expired_at时间戳，毫秒精度），用于验证旧事件；
• global.cache：内存缓存上限（max_size_estimated）与条目寿命（max_age）；
• global.well_known_client_name：client-server 通信委派的 base URL；
• global.disable_federation：禁用联邦（无法与其他服务器通信，联邦 API 不暴露）；
• global.presence：控制 presence 事件的入站/出站处理；
• global.report_stats：phone-home 统计数据上报；
• global.server_notices：服务器通知机器人配置；
• global.metrics：Prometheus 指标采集（含 basic_auth）；
• global.dns_cache：可选 DNS 缓存（cache_size与cache_lifetime）；
• client_api：注册开关（registration_disabled、guests_disabled、registration_shared_secret）、reCAPTCHA、TURN、限流（rate_limiting）；
• federation_api：发送重试次数（send_max_retries）、密钥透视服务器（key_perspectives）、prefer_direct_fetch等——若要从实例联邦进入公共房间，配置key_perspectives（如样例中的matrix.org）能显著提升可靠性，因为可从存活的服务器获取已下线服务器的公钥；
• media_api：媒体存储路径base_path、上传大小上限max_file_size_bytes、缩略图尺寸列表；
• mscs：启用实验性 MSC；
• sync_api.real_ip_header：反向代理后识别真实客户端 IP 的请求头；
• user_api：bcrypt 哈希成本bcrypt_cost（默认 10，范围 4–31）、auto_join_rooms等；
• logging：日志类型（std/file）与级别（debug/info/warn/error）。

用 generate-config 生成配置

也可用generate-config工具快速生成一份基于默认值的配置。其命令行参数（见 cmd/generate-config/main.go）：-server指定域名、-db指定数据库 URI（PostgreSQL 走全局连接池，SQLite/空则按组件拆分）、-dir指定各类路径的根目录、-ci生成 CI 适用的默认配置、-normalise为已有配置补充缺失项与默认值。

七、启动 Dendrite

完成上述全部准备后，执行dendrite二进制即可启动（见 启动文档）：

./dendrite -config /path/to/dendrite.yaml

-config参数来自 setup/flags.go 的configPath标志，默认值为dendrite.yaml；启动时若配置文件非法，会打印错误并log.Fatal。

默认情况下 Dendrite 在 HTTP 8008 端口监听。可通过-http-bind-address与-https-bind-address更改监听地址与端口（默认分别为:8008与:8448，见 cmd/dendrite/main.go）：

./dendrite -config /path/to/dendrite.yaml \ -http-bind-address 1.2.3.4:12345 \ -https-bind-address 1.2.3.4:54321

补充说明（来自 cmd/dendrite/main.go 源码）：

• HTTPS 监听仅在同时提供-tls-cert与-tls-key时才启用；
• 另有实验性-unix-socket选项，启用 unix socket 后会禁用 http/https 绑定地址功能；
• 启动时会执行cfg.Verify校验配置，任何配置错误都会导致启动失败；
• 还支持-version标志（立即打印版本并退出）与-really-enable-open-registration标志（不推荐，显著增加被用于垃圾邮件或攻击的风险）。

八、Docker Compose 安装

Dendrite 官方提供示例 Docker Compose 文件（见 Docker 安装文档）。注意该 compose 文件仅依赖 Postgres，且仍需自行配置 反向代理。

生成私钥

用dendrite-monolith镜像的generate-keys入口生成密钥到./config（只需执行一次，重复执行会覆盖密钥）：

mkdir -p ./config docker run --rm --entrypoint="/usr/bin/generate-keys" \ -v $(pwd)/config:/mnt \ matrixdotorg/dendrite-monolith:latest \ -private-key /mnt/matrix_key.pem # Windows 等效命令: docker run --rm --entrypoint="/usr/bin/generate-keys" -v %cd%/config:/mnt matrixdotorg/dendrite-monolith:latest -private-key /mnt/matrix_key.pem

生成配置

用镜像中的generate-config生成配置，把server换成你的域名、db按 docker-compose 中services.postgres.environment的修改调整：

mkdir -p ./config docker run --rm --entrypoint="/bin/sh" \ -v $(pwd)/config:/mnt \ matrixdotorg/dendrite-monolith:latest \ -c "/usr/bin/generate-config \ -dir /var/dendrite/ \ -db postgres://dendrite:itsasecret@postgres/dendrite?sslmode=disable \ -server YourDomainHere > /mnt/dendrite.yaml" # Windows 等效命令: docker run --rm --entrypoint="/bin/sh" -v %cd%/config:/mnt matrixdotorg/dendrite-monolith:latest -c "/usr/bin/generate-config -dir /var/dendrite/ -db postgres://dendrite:itsasecret@postgres/dendrite?sslmode=disable -server YourDomainHere > /mnt/dendrite.yaml"

之后可按需修改config/dendrite.yaml。

启动

docker-compose -f docker-compose.yml up

九、Kubernetes Helm 安装

添加仓库

helm repo add dendrite https://matrix-org.github.io/dendrite/ helm repo update

创建 values.yaml

所有可配置项见 helm/dendrite/values.yaml，但至少必须配置server_name，否则 chart 会报错（见 Helm 安装文档）：

dendrite_config: global: server_name: "localhost"

若使用已有的 Postgres 数据库，还需配置连接：

dendrite_config: global: database: connection_string: "postgresql://PostgresUser:PostgresPassword@PostgresHostName/DendriteDatabaseName" max_open_conns: 90 max_idle_conns: 5 conn_max_lifetime: -1

随 chart 一并安装 PostgreSQL

chart 内置 Postgres 依赖，可在values.yaml中启用随 Dendrite 一并安装（此时database.connection_string会自动为你设置好）：

postgresql: enabled: true # 安装 Postgres primary: persistence: size: 1Gi # 定义 $PGDATA 的大小 dendrite_config: global: server_name: "localhost"

十、安装方式总结与选型建议

无论采用哪种方式，完整的生产部署都离不开三件事：签名密钥（生成方法）、数据库准备（PostgreSQL/SQLite 说明）与域名/委派/TLS 配置（域名设置）。配置文件是这一切的汇聚点，建议以 dendrite-sample.yaml 为起点逐段核对，再配合 配置文档 理解每个字段的语义，最终通过dendrite -config dendrite.yaml启动并验证。

• 后端
• 即时通讯