use-docker-deploy-npm-and-matrix-chat

本教程指导您从零开始，在一台 Linux 服务器上部署一个基于 Docker 的 Matrix Homeserver (Synapse)，并使用 Nginx Proxy Manager (NPM) 进行反向代理和 SSL 加密。

域名占位符: xxxx.com

部署目录: /root/data/docker_data/

阶段 0：先决条件准备 (安装 Docker)

本阶段适用于全新的 Linux 服务器（以 Ubuntu/Debian 为例）。

1. 安装 Docker Engine

运行以下命令，使用官方脚本快速安装 Docker：

Bash

# 卸载旧版本（如果存在）
for pkg in docker.io docker-doc docker-compose docker-ce docker-ce-cli containerd.io docker-compose-plugin docker-buildx-plugin; do sudo apt-get remove $pkg; done

# 安装依赖
sudo apt update
sudo apt install ca-certificates curl gnupg

# 添加 Docker 官方 GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 添加 Docker 仓库
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 最终安装 Docker
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io

# 检查 Docker 状态
sudo systemctl status docker

2. 安装 Docker Compose V2

Docker Compose V2 现在作为 Docker CLI 的插件提供。

Bash

# 安装 Docker Compose
sudo apt install docker-compose-plugin

# 检查版本
docker compose version

3. 创建目录并清理环境

Bash

# 创建父目录
mkdir -p /root/data/docker_data/

# 停止并删除所有容器 (如果有残留)
docker stop $(docker ps -aq)
docker rm $(docker ps -aq)

# 删除所有未使用的 Docker 数据 (慎重操作)
docker system prune -a --volumes -f

---

阶段 I：网络准备与 NPM 部署

4. 创建共享 Docker 网络

这是确保 NPM 和 Synapse 能够通过容器名称互相访问的关键步骤。

Bash

docker network create proxy-matrix-net

等待输出一串数字，成功！

5. 部署 Nginx Proxy Manager (NPM)

Bash

# 创建 NPM 目录并进入
mkdir -p /root/data/docker_data/npm
cd /root/data/docker_data/npm

# 创建 docker-compose.yml 文件
nano docker-compose.yml

docker-compose.yml 内容：

YAML

version: '3'
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    container_name: 'npm_proxy'
    restart: unless-stopped
    ports:
      - '80:80'
      - '443:443'
      - '81:81' # NPM 管理界面
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
    networks:
      - proxy-matrix-net # 🌟 加入共享网络
      
networks:
  proxy-matrix-net:
    external: true

启动 NPM：

Bash

docker compose up -d

6. 访问并初始化 NPM

通过浏览器访问 http://您的服务器公网IP地址:81，使用默认凭据登录：

• Email: admin@example.com
• Password: changeme请立即修改您的管理员邮箱和密码。

---

阶段 II：部署 Matrix Synapse Homeserver (Synapse)

7. 生成 Synapse 配置文件（关键）

新版镜像需要手动生成配置。

Bash

# 创建 Matrix 目录并进入
mkdir -p /root/data/docker_data/matrix
cd /root/data/docker_data/matrix

# 运行临时容器生成 homeserver.yaml
docker run --rm \
  -v /root/data/docker_data/matrix/data:/data \
  -e SYNAPSE_SERVER_NAME="xxxx.com" \
  -e SYNAPSE_REPORT_STATS="no" \
  matrixdotorg/synapse:latest generate

8. 修改 Synapse 配置 (homeserver.yaml)

打开生成的配置文件进行修改：

Bash

nano ./data/homeserver.yaml

查找并确保以下配置：

配置项	值	目的
federation_enabled:	false	禁用 Matrix 联邦，实现私有化。
enable_registration:	true	允许用户在 Element 客户端注册。

保存并退出文件。

9. 创建并启动 Synapse 容器

Bash

# 创建 docker-compose.yml 文件
nano docker-compose.yml

docker-compose.yml 内容：

YAML

version: "3.3"
services:
  synapse:
    image: "matrixdotorg/synapse:latest"
    container_name: "matrix_synapse" # 🌟 NPM 将通过此名称访问
    restart: unless-stopped
    volumes:
      - "./data:/data"
    networks:
      - proxy-matrix-net # 🌟 加入共享网络
      
networks:
  proxy-matrix-net:
    external: true

启动 Synapse 并检查状态：

Bash

docker compose up -d
docker compose ps
# 确认 matrix_synapse 状态为 Up (healthy)

---

阶段 III：配置 NPM 反向代理与 SSL

10. 在 NPM 中配置反向代理主机

登录 NPM Web 界面，点击 Hosts -> Proxy Hosts -> Add Proxy Host。

配置项	值	备注
Domain Names	xxxx.com	替换为您的实际域名
Scheme	http
Forward Hostname / IP	matrix_synapse	使用容器名称
Forward Port	8008
Block Common Exploits	取消勾选

11. 配置 SSL 证书和 Custom Locations（关键）

SSL 选项卡： 请求或选择证书，勾选 Force SSL 和 HTTP/2 Support。

Custom Locations (自定义位置) 选项卡： 必须添加以下三个转发规则：

Location (路径)	Scheme	Forward Hostname / IP	Forward Port
/	http	matrix_synapse	8008
/.well-known/	http	matrix_synapse	8008
/_matrix/	http	matrix_synapse	8008

---

阶段 IV：最终验证

12. 客户端登录与加密验证

1. 访问 Element 官方网页客户端：https://app.element.io/
2. 输入您的 Homeserver URL：https://xxxx.com
3. 注册或登录账户。
4. 创建一个新房间，并在创建时启用端到端加密，发送一条测试消息。