零成本 Matrix 服务器部署指南

基于 Hugging Face + Neon + Filebase 的全套解决方案

前提条件： 请确保你已经注册了 Hugging Face, GitHub, Neon (数据库), 和 Filebase (文件存储) 的账号。

Phase 1环境准备与密钥设置

进入 Hugging Face Space -> Settings -> Variables and secrets，点击 New Secret 添加以下 6 个变量（注意全大写）：

Secret Name (变量名)	示例 Value (值)	说明
NEON_USER	neondb_owner	Neon 数据库用户名
NEON_PASSWORD	npg_...	Neon 数据库密码
NEON_HOST	ep-xxx...neon.tech	Neon 数据库地址 (不带 postgres://)
S3_BUCKET	my-matrix-bucket	Filebase Bucket 名字
AWS_ACCESS_KEY_ID	066...	Filebase Access Key
AWS_SECRET_ACCESS_KEY	...	Filebase Secret Key

Phase 2创建 Dockerfile

在 GitHub Codespaces 中，新建名为 Dockerfile 的文件，复制以下内容：

# 使用官方 Synapse 镜像
FROM matrixdotorg/synapse:latest

# 切换到 root 用户
USER root

# 1. 安装编译依赖 + gettext (用于替换环境变量)
RUN apt-get update && apt-get install -y \
    git \
    gcc \
    python3-dev \
    libffi-dev \
    libxml2-dev \
    libxslt-dev \
    libjpeg-dev \
    zlib1g-dev \
    libpq-dev \
    gettext-base \
    && rm -rf /var/lib/apt/lists/*

# 2. 升级 pip
RUN pip install --upgrade pip setuptools wheel

# 3. 安装 S3 插件
RUN pip install https://github.com/matrix-org/synapse-s3-storage-provider/archive/refs/heads/main.zip

# 4. 设置端口
ENV SYNAPSE_HTTP_PORT=7860

# 5. 复制配置文件 (作为模板)
COPY homeserver.yaml /data/homeserver.yaml.template

# 6. 修正权限
RUN chown -R 991:991 /data && chmod -R 755 /data

# 切换回 Synapse 用户
USER 991

# 7. 【核心修复】使用 ENTRYPOINT 覆盖默认启动脚本
# 这样 Docker 就不会去调原来的 /start.py，而是直接运行我们的 shell 命令
# 命令逻辑：先替换变量生成 yaml，然后手动调用 /start.py 启动服务
ENTRYPOINT ["/bin/sh", "-c", "envsubst < /data/homeserver.yaml.template > /data/homeserver.yaml && /start.py run"]

Phase 3生成初始配置

在 GitHub Codespaces 下方的 Terminal (终端) 中执行以下命令生成初始文件。
注意：请先修改下面的 SERVER_NAME 为你实际的空间地址。

# 替换这里(记得替换成你的真实域名)例如 sansc-chatserver.hf.space
# 注意：不带 https://
export SERVER_NAME="你的用户名-你的空间名.hf.space"

# 运行命令生成配置
docker run -it --rm \
    -v "$(pwd):/data" \
    -e SYNAPSE_SERVER_NAME=$SERVER_NAME \
    -e SYNAPSE_REPORT_STATS=no \
    matrixdotorg/synapse:latest generate

Phase 4修改 homeserver.yaml

打开生成的 homeserver.yaml 文件，依次进行以下 5 步修改：

1. 添加注册与跨域配置 (放在文件最上方)

# 允许 Synapse Admin 等外部网页工具连接
enable_cors: true

# 开启注册，家人注册完后建议改为 false
enable_registration: true

# 【关键】添加这一行：允许无验证（无邮箱/手机号）直接注册
enable_registration_without_verification: true

# 【可选】顺手把日志里的另一个警告也消掉
suppress_key_server_warning: true

2. 修改监听端口 (listeners 部分)

找到 listeners: 下的配置，确保端口是 7860 且开启转发：

listeners:
  - port: 7860          # 必须是 7860
    tls: false
    type: http
    x_forwarded: true   # 必须开启
    bind_addresses: ['0.0.0.0']
    resources:
      - names: [client, federation]
        compress: false

3. 配置数据库 (使用变量)

找到 database: 部分，替换为以下内容：

database:
  name: psycopg2
  allow_unsafe_locale: true
  args:
    user: "${NEON_USER}"         # 变成了变量
    password: "${NEON_PASSWORD}" # 变成了变量
    database: "neondb"
    host: "${NEON_HOST}"         # 变成了变量
    port: 5432
    cp_min: 5
    cp_max: 10

4. 配置 S3 存储 (放到文件末尾)

在文件最底部添加以下内容：

media_store_path: /data/media_store
media_storage_providers:
- module: s3_storage_provider.S3StorageProviderBackend
  store_local: True
  store_remote: True
  store_synchronous: True
  config:
    bucket: "${S3_BUCKET}"             # 变成了变量
    region_name: "us-east-1"
    endpoint_url: "https://s3.filebase.com"
    access_key: "${AWS_ACCESS_KEY_ID}"     # 变成了变量
    secret_key: "${AWS_SECRET_ACCESS_KEY}" # 变成了变量

5. 删除日志配置 (防止报错)

按 Ctrl+F 搜索 log_config，直接删除整行：

# 删除类似下面这行：
log_config: "/data/用户名-空间名.hf.space.hf.space.log.config"

Phase 5修复 README.md

Hugging Face 需要通过 README 来识别 Docker 端口。在 Codespaces 新建 README.md，填入以下内容：

---
title: Matrix Chat Server
emoji: 💬
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit
app_port: 7860
---

# My Matrix Chat Server
基于 Synapse 的加密聊天服务器。

Phase 6推送到 Hugging Face

在终端依次执行以下命令进行部署。注意替换第 3 条命令中的 Token 和 URL。

# 1. 初始化 git（如果需要）
git init

# 2. 添加目录信任白名单 (防止权限报错)
git config --global --add safe.directory '*'

# 3. 添加 HF 为远程仓库
# 格式：https://用户名:TOKEN@huggingface.co/spaces/用户名/空间名
# 请手动替换下面的 URL！
git remote add space https://你的用户名:你的TOKEN@huggingface.co/spaces/你的用户名/你的空间名

# 4. 提交代码
git add .
git commit -m "Deploy to HF"

# 5. 强制推送
git push --force space main

Phase 7管理与维护

部署成功后，你可以在 Neon 的 SQL Editor 中执行以下命令来管理用户。

查看用户统计

-- 查看所有用户
SELECT name, creation_ts FROM users;

-- 查看总人数
SELECT count(*) FROM users;

提升管理员权限 (提权)

-- 替换为你的完整用户名 (在 Element 设置里查看)
-- 例如: @tom:tom-chat.hf.space
UPDATE users 
SET admin = 1 
WHERE name = '@你的账户名:你的空间地址';