自部署去中心聊天项目 Matrix 服务器Debian12+宝塔面板+Docker安装Matrix免费开源聊天项目

一、项目需求说明

为了安全、高效和团队沟通交流，在网络上寻找、对比了多个免费、开源、安全、高效的文字、图片、语音的聊天工具项目，对比之后选择了使用Matrix这个项目

安装环境说明

计划使用域名 https://m.xqbn.com ，服务器使用Debian 12系统 + 宝塔面板 V11 + 宝塔的Docker进行部署

1、项目访问网址使用 https://m.xqbn.com
2、项目主路径 /www/dk_project/dk_app/m.xqbn.com
3、需要开启用户注册功能
4、数据库使用 PostgreSQL 数据库名称、用户名为 mxqbn_com 密码为 R4PhkSD*QPNho6788
5、做好安装、配置、以及每周定时备份的教程

二、Matrix安装、配置说明

下面我为你整理一份在Debian 12系统上，使用宝塔面板和Docker重新部署Matrix Synapse的详细教程。这个教程会完全按照你的要求进行配置，包括使用PostgreSQL数据库、开启用户注册功能，以及设置每周定时备份。

🗑️ 完全清理旧配置

首先彻底清理之前的安装：

# 停止并删除容器
cd /www/dk_project/dk_app/m.xqbn.com
docker-compose down

# 删除所有容器和镜像
docker rm -f matrix_postgres matrix_synapse 2>/dev/null || true
docker rmi matrixdotorg/synapse:latest postgres:13 2>/dev/null || true

# 彻底清理数据（⚠️ 注意：这会删除所有现有数据！）
rm -rf /www/dk_project/dk_app/m.xqbn.com/*

# 重新创建目录结构
mkdir -p /www/dk_project/dk_app/m.xqbn.com/{postgres_data,synapse_data,backups,scripts}

完全清理旧配置重新创建目录结构

🗄️ 配置PostgreSQL数据库

根据你的要求，我们先设置PostgreSQL数据库：

# 创建数据库初始化脚本
cat > /www/dk_project/dk_app/m.xqbn.com/scripts/init-db.sql << 'EOF'
CREATE USER mxqbn_com_sql WITH PASSWORD 'yR4PhkSD*QPNho8899';
CREATE DATABASE mxqbn_com_sql OWNER mxqbn_com_sql;
GRANT ALL PRIVILEGES ON DATABASE mxqbn_com_sql TO mxqbn_com_sql;
\c mxqbn_com_sql;
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
EOF

配置PostgreSQL数据库

🐳 创建Docker Compose配置

创建主配置文件 docker-compose.yml：

services:
  postgres:
    image: postgres:13
    container_name: matrix_postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: mxqbn_com_sql
      POSTGRES_PASSWORD: R4PhkSD*QPNho6788
      POSTGRES_DB: mxqbn_com_sql
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --lc-collate=C --lc-ctype=C"
    volumes:
      - ./postgres_data:/var/lib/postgresql/data
      - ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init-db.sql:ro
    command: >
      postgres 
      -c shared_preload_libraries=pg_stat_statements
      -c pg_stat_statements.track=all
      -c max_connections=200
      -c shared_buffers=256MB
      -c effective_cache_size=1GB
    networks:
      - matrix_net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U mxqbn_com_sql"]
      interval: 10s
      timeout: 5s
      retries: 5

  synapse:
    image: matrixdotorg/synapse:latest
    container_name: matrix_synapse
    restart: unless-stopped
    ports:
      - "127.0.0.1:8008:8008"
    environment:
      SYNAPSE_CONFIG_PATH: /data/homeserver.yaml
    volumes:
      - ./synapse_data:/data
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - matrix_net
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8008/health"]
      interval: 30s
      timeout: 10s
      retries: 3

networks:
  matrix_net:
    driver: bridge

将此文件保存为：/www/dk_project/dk_app/m.xqbn.com/docker-compose.yml

⚙️ 生成并配置Synapse

现在生成Synapse配置：

cd /www/dk_project/dk_app/m.xqbn.com

# 生成初始配置
docker run -it --rm \
  -v /www/dk_project/dk_app/m.xqbn.com/synapse_data:/data \
  -e SYNAPSE_SERVER_NAME=m.xqbn.com \
  -e SYNAPSE_REPORT_STATS=yes \
  matrixdotorg/synapse:latest generate

生成并配置Synapse

修改生成的配置文件 synapse_data/homeserver.yaml：

# 编辑配置文件
nano /www/dk_project/dk_app/m.xqbn.com/synapse_data/homeserver.yaml

以下是默认生成的信息：【我们需要保留 registration_shared_secret、macaroon_secret_key、form_secret、signing_key_path这些参数对应的信息】

需要修改的关键配置部分：【数据库信息需要修改为对应的，registration_shared_secret、macaroon_secret_key、form_secret、signing_key_path这些参数需要使用对应的信息】

server_name: "m.xqbn.com"
public_baseurl: "https://m.xqbn.com/"
pid_file: /data/homeserver.pid

listeners:
  - port: 8008
    tls: false
    type: http
    x_forwarded: true
    resources:
      - names: [client, federation]
        compress: false

# 数据库配置 - 使用你指定的PostgreSQL
database:
  name: psycopg2
  args:
    user: mxqbn_com_sql
    password: "R4PhkSD*QPNho6788"
    database: mxqbn_com_sql
    host: postgres
    port: 5432
    cp_min: 5
    cp_max: 10
    keepalives_idle: 30
    keepalives_interval: 10
    keepalives_count: 3

# 启用用户注册
enable_registration: true
enable_registration_without_verification: true

# 媒体存储路径
media_store_path: /data/media_store
uploads_path: /data/uploads

# 其他保持生成的默认值
log_config: "/data/m.xqbn.com.log.config"
registration_shared_secret: "p&[email protected]=SurgM6mt_HcowqU7o^D#af-zhr"
report_stats: true
macaroon_secret_key: "4i#0thVQ1AGhUBSaybp-:L;cXR52gqt_9Zek3~qK;*&jpAP5#8"
form_secret: "1s2#nz~yCbwP+;a^PloX@An+mA#BGjzF;_25qo2q7_b-LoRx:U"
signing_key_path: "/data/m.xqbn.com.signing.key"
trusted_key_servers:
  - server_name: "matrix.org"

# 取消密钥服务器警告（可选）
suppress_key_server_warning: true

🔧 设置权限并启动服务

# 设置正确的权限
chown -R 991:991 /www/dk_project/dk_app/m.xqbn.com/synapse_data
chown -R 999:999 /www/dk_project/dk_app/m.xqbn.com/postgres_data

# 启动服务
cd /www/dk_project/dk_app/m.xqbn.com
docker-compose up -d

# 检查服务状态
docker-compose ps
docker-compose logs -f

设置权限并启动服务

🌐 配置宝塔面板反向代理

在宝塔面板中配置反向代理：

创建新网站，域名填写：m.xqbn.com
在网站设置中找到"反向代理"，添加代理：
- 代理名称：matrix
- 目标URL：http://127.0.0.1:8008

👤 创建管理员用户

等待服务完全启动后（约2-3分钟），创建管理员用户：

cd /www/dk_project/dk_app/m.xqbn.com
docker-compose exec synapse register_new_matrix_user http://localhost:8008 -c /data/homeserver.yaml -a -u admin -p Google@168168

打开网站首页，看到这个界面就表示安装成功

💾 配置自动备份系统

创建备份脚本 scripts/backup.sh：

#!/bin/bash

# 备份配置
BACKUP_DIR="/www/dk_project/dk_app/m.xqbn.com/backups"
DATE=$(date +%Y%m%d_%H%M%S)
RETENTION_DAYS=28

# 创建备份目录
mkdir -p ${BACKUP_DIR}/${DATE}

echo "$(date) 开始Matrix数据备份..."

# 备份PostgreSQL数据库
echo "备份数据库..."
docker-compose exec -T postgres pg_dump -U mxqbn_com_sql mxqbn_com_sql > ${BACKUP_DIR}/${DATE}/matrix_db.sql

# 备份Synapse配置文件和数据
echo "备份Synapse配置..."
tar -czf ${BACKUP_DIR}/${DATE}/synapse_config.tar.gz -C /www/dk_project/dk_app/m.xqbn.com/synapse_data .

# 备份Docker配置
echo "备份Docker配置..."
cp /www/dk_project/dk_app/m.xqbn.com/docker-compose.yml ${BACKUP_DIR}/${DATE}/
cp -r /www/dk_project/dk_app/m.xqbn.com/scripts ${BACKUP_DIR}/${DATE}/

# 打包备份文件
echo "打包备份文件..."
tar -czf ${BACKUP_DIR}/matrix_backup_${DATE}.tar.gz -C ${BACKUP_DIR} ${DATE}

# 清理临时文件
rm -rf ${BACKUP_DIR}/${DATE}

# 清理旧备份
find ${BACKUP_DIR} -name "matrix_backup_*.tar.gz" -mtime +${RETENTION_DAYS} -delete

echo "$(date) 备份完成！备份文件: ${BACKUP_DIR}/matrix_backup_${DATE}.tar.gz"

设置脚本权限并测试：

chmod +x /www/dk_project/dk_app/m.xqbn.com/scripts/backup.sh

# 测试备份
/www/dk_project/dk_app/m.xqbn.com/scripts/backup.sh

⏰ 设置定时备份

使用crontab设置每周备份：

# 编辑crontab
crontab -e

# 添加以下行（每周日凌晨3点执行备份）
0 3 * * 0 /www/dk_project/dk_app/m.xqbn.com/scripts/backup.sh >> /www/dk_project/dk_app/m.xqbn.com/backups/backup.log 2>&1

或者在宝塔面板中添加计划任务：

任务类型：Shell脚本
执行周期：每周
脚本内容：/www/dk_project/dk_app/m.xqbn.com/scripts/backup.sh

🧪 验证部署

检查服务状态：

# 检查容器状态
docker-compose ps

# 检查日志
docker-compose logs --tail=50 synapse

# 测试健康检查
curl http://localhost:8008/health

# 测试 federation
curl https://m.xqbn.com/.well-known/matrix/server

访问 https://m.xqbn.com 应该能看到Matrix的欢迎页面。你可以在 https://app.element.io/ 使用你的服务器地址 https://m.xqbn.com 注册新用户或登录。

1、打开登录、注册页面 https://app.element.io/ 点击 Edit 更换登录的服务器

打开登录、注册页面 https://app.element.io/ 点击 Edit 更换登录的服务器

2、更换登录服务器为 https://m.xqbn.com 点击继续 Continue

更换登录服务器为 m.xqbn.com 点击继续 Continue

3、可以在注册窗口左下侧的按钮更换语言，支持中文。注册的时候，只需要填写用户名和密码，密码需要填写两次；用户名只能使用小写字母；

可以在注册窗口左下侧的按钮更换语言，支持中文。注册的时候，只需要填写用户名和密码，密码需要填写两次；用户名只能使用小写字母；

4、注册成功之后，可以点击发送私聊进入聊天窗口

注册成功之后，可以点击发送私聊进入聊天窗口

5、查找需要联系的目标用户格式为 @用户名:服务器域名比如要联系我，使用 @bruce:m.xqbn.com 在下面的建议中就会显示我的账户了

查找需要联系的目标用户格式为 @用户名:服务器域名比如要联系我，使用 @bruce:m.xqbn.com 在下面的建议中就会显示我的账户了

6、如果账户没有设置密钥的话，和人聊天发消息的时候，就会有弹窗提示需要设置密钥，点击继续

如果账户没有设置密钥的话，和人聊天发消息的时候，就会有弹窗提示需要设置密钥

7、然后就会进入设置密钥的界面，点击 Set Up recovery

进入设置密钥的界面，点击 Set Up recovery

8、点击继续生成账户恢复密钥

9、到这一步就可以看到生成的账户恢复密钥，点击后面的复制按钮，一定要保存好；点击继续会让你再输入一次密钥确认一次；

到这一步就可以看到生成的账户恢复密钥，点击后面的复制按钮，一定要保存好；点击继续会让你再输入一次密钥确认一次；

10、设置好账户恢复密钥之后，页面的状态就会显示这样

11、🔒 安全建议

注册控制：团队成员注册完成后，建议修改 homeserver.yaml：
```
enable_registration: false
enable_registration_without_verification: false
```
然后重启服务：docker-compose restart
防火墙设置：确保只开放必要的80/443端口。
定期更新：每月更新一次容器镜像：
```
docker-compose pull
docker-compose up -d
```

这个完整的方案应该能满足你的所有要求。如果在部署过程中遇到任何问题，可以查看具体的错误日志来进一步排查。

推荐订阅源

兴起百年 - XQBN.com - 学习