Matrix Well-Known 域名 #

Hagency 不要求你把自己的域名指向我们的 DNS、边缘节点或 workspace 主机。

如果你希望用户以 @alice:example.com 这样的形式登录，你只需要在自己的域名下发布 Matrix 标准发现文件：

  • /.well-known/matrix/server
  • /.well-known/matrix/client

example.com 当前的网站、DNS 和托管方式都可以保持不变。唯一要求是这两个 HTTPS 地址能返回控制台生成的 JSON。

这项配置会改变什么 #

  • Matrix ID 域名：显示在用户 ID 里的域名，例如 @alice:example.com
  • 实际 homeserver URL：仍然是 Hagency 当前为你的 workspace 提供的 homeserver 地址
  • 客户端连接方式：Matrix 客户端先读取你域名上的 /.well-known，再跳转到 JSON 里声明的 homeserver URL

1. 设置 Matrix ID 域名 #

  1. 打开 设置 → 工作区 → Matrix Server Name。
  2. 填写你希望显示在 Matrix 用户 ID 中的域名，例如 example.com。
  3. 保存。

注意：

  • 这个值会成为 Matrix server_name
  • 最好在创建第一个真实 Matrix 用户之前就设置好
  • 一旦已经存在第一个人类 Matrix 用户，这个值就会被锁定，不能再改

2. 发布 /.well-known #

  1. 继续留在 设置 → 工作区 页面，打开 Matrix Well-Known Domain 区块。
  2. 下载当前 workspace 对应的 JSON 文件。
  3. 将它们发布到你自己的域名：
    • https://example.com/.well-known/matrix/server
    • https://example.com/.well-known/matrix/client

这个流程里，你的域名 不需要 增加任何指向 Hagency 的 A、CNAME 或 TXT 记录。

你可以把这两个文件放在：

  • 现有网站
  • 静态托管
  • 站点前面的反向代理
  • 任何能在你域名上通过 HTTPS 提供文件的服务器

关键：浏览器客户端还需要正确的响应头 #

如果你用的是 https://app.element.io 这类浏览器里的 Matrix 客户端，那就不是“能打开 JSON 就行”。

浏览器会把 https://example.com/.well-known/matrix/client 当成跨域请求读取。你的地址栏里即使能看到 JSON，只要响应头不对，客户端仍然可能把这次自动发现视为失败。

至少要保证：

  • /.well-known/matrix/client 返回 Content-Type: application/json
  • /.well-known/matrix/client 返回 Access-Control-Allow-Origin: *
  • 最稳妥的做法是 /.well-known/matrix/server 也一起返回 Content-Type: application/json 和 Access-Control-Allow-Origin: *

常见误区：

  • “浏览器直接打开能看到 JSON，所以应该没问题。” 不一定。地址栏直接打开不等于跨域读取成功。
  • “控制台 Validate Published Files 通过了，所以客户端一定没问题。” 也不一定。服务端校验只会验证 URL 和 JSON 值；浏览器客户端还依赖 CORS。
  • “客户端去请求了 https://example.com/_matrix/client/versions，说明 base_url 应该改成 https://example.com。” 通常不是。更常见的原因是客户端没能成功读取 /.well-known/matrix/client，于是退回去把 example.com 当成直连 homeserver 试探。

m.homeserver.base_url 应该继续使用控制台生成的真实 workspace homeserver URL，通常是 https://<workspace>.hagency.cloud 这一类地址。除非你真的把 example.com/_matrix/client/* 这一整套 Matrix Client-Server API 正式反代出来，否则不要手工把 base_url 改成你的自定义域名。

发布后，建议用命令行直接检查响应头：

bash
curl -i https://example.com/.well-known/matrix/client
curl -i https://example.com/.well-known/matrix/server

至少应看到：

  • HTTP/1.1 200 或 HTTP/2 200
  • Content-Type: application/json
  • Access-Control-Allow-Origin: *
  • Body 与控制台当前下载的 JSON 完全一致

主流反向代理示例 #

下面的示例都假设：

  • 你的正常网站或应用仍然照常运行
  • 只有 /.well-known/matrix/client 和 /.well-known/matrix/server 这两个路径被单独拦出来
  • JSON 文件已经放在本机磁盘某个目录里

Caddy #

caddyfile
example.com {
    root * /srv/well-known

    @matrix_well_known path /.well-known/matrix/client /.well-known/matrix/server
    handle @matrix_well_known {
        header Content-Type application/json
        header Access-Control-Allow-Origin *
        file_server
    }

    reverse_proxy 127.0.0.1:8080
}

把两个文件放到：

  • /srv/well-known/.well-known/matrix/client
  • /srv/well-known/.well-known/matrix/server

Nginx #

nginx
server {
    listen 443 ssl http2;
    server_name example.com;

    root /var/www/example.com;

    location = /.well-known/matrix/client {
        default_type application/json;
        add_header Access-Control-Allow-Origin * always;
        try_files $uri =404;
    }

    location = /.well-known/matrix/server {
        default_type application/json;
        add_header Access-Control-Allow-Origin * always;
        try_files $uri =404;
    }

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

这里的两个文件路径是：

  • /var/www/example.com/.well-known/matrix/client
  • /var/www/example.com/.well-known/matrix/server

Apache HTTP Server #

启用 mod_proxy、mod_proxy_http、mod_alias、mod_headers 后，可以这样写：

apache
<VirtualHost *:443>
    ServerName example.com

    ProxyPreserveHost On

    ProxyPass /.well-known/matrix/ !
    Alias /.well-known/matrix/ "/var/www/example.com/.well-known/matrix/"

    <Directory "/var/www/example.com/.well-known/matrix">
        Require all granted
    </Directory>

    <LocationMatch "^/\.well-known/matrix/(client|server)$">
        ForceType application/json
        Header always set Access-Control-Allow-Origin "*"
    </LocationMatch>

    ProxyPass / http://127.0.0.1:8080/
    ProxyPassReverse / http://127.0.0.1:8080/
</VirtualHost>

Traefik #

Traefik 本身只负责路由和加头；你仍然需要一个实际提供这两个 JSON 文件的后端服务，例如一个很小的静态 Nginx 容器。下面是给这个静态服务挂的 labels 示例：

yaml
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.example-matrix-wellknown.rule=Host(`example.com`) && (Path(`/.well-known/matrix/client`) || Path(`/.well-known/matrix/server`))"
  - "traefik.http.routers.example-matrix-wellknown.priority=100"
  - "traefik.http.routers.example-matrix-wellknown.entrypoints=websecure"
  - "traefik.http.routers.example-matrix-wellknown.tls=true"
  - "traefik.http.routers.example-matrix-wellknown.middlewares=matrix-wellknown-headers"
  - "traefik.http.routers.example-matrix-wellknown.service=matrix-wellknown"
  - "traefik.http.middlewares.matrix-wellknown-headers.headers.customresponseheaders.Content-Type=application/json"
  - "traefik.http.middlewares.matrix-wellknown-headers.headers.customresponseheaders.Access-Control-Allow-Origin=*"
  - "traefik.http.services.matrix-wellknown.loadbalancer.server.port=80"

你的主应用继续用原来的 router 处理其余路径即可；/.well-known/matrix/* 这两个请求会优先落到这个静态服务。

3. 校验已发布文件 #

发布后，回到控制台点击 Validate Published Files。

系统会检查：

  • /.well-known/matrix/server 是否返回预期值
  • /.well-known/matrix/client 是否返回预期值
  • 生成出来的地址是否仍然指向你当前 workspace 的 homeserver

推荐理解方式 #

  • Hagency 当前的 workspace homeserver 地址保持不变
  • 你的 Matrix ID 域名是 example.com
  • https://example.com/.well-known/matrix/server 告诉客户端真正该连到哪里
  • https://example.com/.well-known/matrix/client 告诉客户端真正的 base_url

换句话说，你的域名只负责 Matrix 身份和发现入口，不需要把普通 Web 流量转发给 Hagency。

故障排查 #

  • Matrix /.well-known 校验失败：确认两个文件发布在准确路径，且内容与控制台当前显示的 JSON 完全一致。
  • 控制台校验通过，但 app.element.io 仍然失败：优先检查 /.well-known/matrix/client 是否真的返回了 Content-Type: application/json 和 Access-Control-Allow-Origin: *。
  • 客户端去请求 https://example.com/_matrix/client/versions：这通常说明浏览器侧自动发现失败了，不要先去改 m.homeserver.base_url；先检查 /.well-known/matrix/client 的 CORS 和 Content-Type。
  • 域名仍然指向旧的 homeserver URL：在 workspace 配置变更后重新下载最新 JSON，再覆盖发布。
  • 你的网站已经在使用 /.well-known：直接把 Matrix 文件合并进同一个 /.well-known 目录即可，不需要迁移整个站点。
  • 你以为还需要配 DNS：这个流程不需要。除非你有别的独立需求，否则不要为了这里额外添加指向 Hagency 的 A、CNAME 或 TXT 记录。