docker pull matrixdotorg/synapse:v1.163.0
docker pull vectorim/element-web:v1.12.32

docker.io/matrixdotorg/synapse:v1.163.0
Digest: sha256:e98ab72138d90fa8b8876c6421fe78a9fdb181c0d7cc690ad740e5173e0c65e6
Status: Downloaded newer image for matrixdotorg/synapse:v1.163.0
docker.io/vectorim/element-web:v1.12.32
Digest: sha256:f8700633d4336258af7a05b53865a4f479e0d628cf2d9ca83d28b5939314d4ce
Status: Downloaded newer image for vectorim/element-web:v1.12.32

docker --version
docker compose version

Docker version 29.8.1, build 4a63305
Docker Compose version v5.5.1

ss -ltn | grep -E ':814[12] '

mkdir -p /opt/synapse/data /opt/synapse/element-config
cd /opt/synapse

name: synapse-1.163.0-stack

services:
  synapse:
    image: matrixdotorg/synapse:v1.163.0
    container_name: synapse-1.163.0-homeserver
    restart: unless-stopped
    ports:
      - "8141:8008"
    volumes:
      - ./data:/data
    networks:
      - synapse-net

  element:
    image: vectorim/element-web:v1.12.32
    container_name: element-1.12.32-web
    restart: unless-stopped
    ports:
      - "8142:80"
    volumes:
      - ./element-config/config.json:/app/config.json:ro
    depends_on:
      - synapse
    networks:
      - synapse-net

networks:
  synapse-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.59.0/24

docker compose run --rm -e SYNAPSE_SERVER_NAME=matrix.local -e SYNAPSE_REPORT_STATS=no synapse generate

Setting ownership on /data to 991:991
Generating config file /data/homeserver.yaml
Generating signing key file /data/matrix.local.signing.key
A config file has been generated in '/data/homeserver.yaml' for server name 'matrix.local'. Please review this file and customise it to your needs.

ls -la /opt/synapse/data/

total 20
drwxr-xr-x 3  991  991 4096 10月 21 16:25 .
drwxr-xr-x 4 root root 4096 10月 21 16:25 ..
-rw-r--r--  1  991  991 1290 10月 21 16:25 homeserver.yaml
-rw-r--r--  1 root root  694 10月 21 16:25 matrix.local.log.config
-rw-r-----  1  991  991   59 10月 21 16:25 matrix.local.signing.key

# 1) 开放网页注册（Element 页面上可自助注册；无邮箱/验证码校验时必须同时放开 without_verification）
enable_registration: true
enable_registration_without_verification: true

# 2) 登录限流放宽（演示/内网环境；默认值在连续登录测试时极易触发 M_LIMIT_EXCEEDED）
rc_login:
  account:
    per_second: 5
    burst_count: 50
  address:
    per_second: 5
    burst_count: 50
  failed_attempts:
    per_second: 5
    burst_count: 50

cd /opt/synapse
docker compose up -d

 Network synapse-11630-stack_synapse-net Creating
 Network synapse-11630-stack_synapse-net Created
 Container synapse-1.163.0-homeserver Creating
 Container synapse-1.163.0-homeserver Created
 Container element-1.12.32-web Creating
 Container element-1.12.32-web Created
 Container synapse-1.163.0-homeserver Starting
 Container synapse-1.163.0-homeserver Started
 Container element-1.12.32-web Starting
 Container element-1.12.32-web Started

docker compose ps

NAME                         STATUS                    PORTS
element-1.12.32-web          Up 16 seconds (healthy)   8080/tcp, 0.0.0.0:8142->80/tcp, [::]:8142->80/tcp
synapse-1.163.0-homeserver   Up 16 seconds (healthy)   8448/tcp, 19090/tcp, 0.0.0.0:8141->8008/tcp, [::]:8141->8008/tcp

ss -ltn | grep -E ':814[12] '

LISTEN 0      4096         0.0.0.0:8141       0.0.0.0:*
LISTEN 0      4096         0.0.0.0:8142       0.0.0.0:*
LISTEN 0      4096            [::]:8141          [::]:*
LISTEN 0      4096            [::]:8142          [::]:*

curl -s http://127.0.0.1:8141/_matrix/client/versions

{"versions":["r0.0.1","r0.1.0","r0.2.0","r0.3.0","r0.4.0","r0.5.0","r0.6.0","r0.6.1","v1.1","v1.2","v1.3","v1.4","v1.5","v1.6","v1.7","v1.8","v1.9","v1.10","v1.11","v1.12","v1.13","v1.14","v1.15"],"unstable_features":{"org.matrix.label_based_filtering":true,"org.matrix.e2e_cross_signing":true,...}}

curl -s http://127.0.0.1:8141/_synapse/admin/v1/server_version

{"server_version":"1.163.0"}

docker compose exec synapse register_new_matrix_user -c /data/homeserver.yaml -a -u admin -p q1w2e3r4 http://localhost:8008

Sending registration request...
Success!

docker compose exec synapse register_new_matrix_user -c /data/homeserver.yaml --no-admin -u alice -p q1w2e3r4 http://localhost:8008

Sending registration request...
Success!

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "http://192.168.146.128:8141",
      "server_name": "matrix.local"
    }
  },
  "brand": "Element",
  "default_country_code": "CN",
  "disable_guests": true,
  "room_directory": {
    "servers": ["matrix.local"]
  }
}

curl -s http://192.168.146.128:8142/config.json

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "http://192.168.146.128:8141",
      "server_name": "matrix.local"
    }
  },
  "brand": "Element",
  "default_country_code": "CN",
  "disable_guests": true,
  "room_directory": {
    "servers": ["matrix.local"]
  }
}

curl -s -o /dev/null -w 'element HTTP %{http_code}\n' http://192.168.146.128:8142/

element HTTP 200

# 1) admin 登录，取得 access_token
curl -s -X POST http://127.0.0.1:8141/_matrix/client/v3/login \
  -H 'Content-Type: application/json' \
  -d '{"type":"m.login.password","user":"admin","password":"q1w2e3r4"}'

{"user_id":"@admin:matrix.local","access_token":"syt_YWRtaW4_isbgbZbnWSzGOajhfWoh_1n9Kgk","home_server":"matrix.local","device_id":"SXJPNTLUEH"}

# 2) 创建房间「研发部交流」并邀请 alice
curl -s -X POST "http://127.0.0.1:8141/_matrix/client/v3/createRoom" \
  -H "Authorization: Bearer syt_YWRtaW4_isbgbZbnWSzGOajhfWoh_1n9Kgk" \
  -H 'Content-Type: application/json' \
  -d '{"preset":"private_chat","name":"研发部交流","invite":["@alice:matrix.local"]}'

{"room_id":"!QxXyaG7NjuhTQvRBskG5B65awcmIpke22rIF_bmStrk"}

# 3) alice 登录
curl -s -X POST http://127.0.0.1:8141/_matrix/client/v3/login \
  -H 'Content-Type: application/json' \
  -d '{"type":"m.login.password","user":"alice","password":"q1w2e3r4"}'

{"user_id":"@alice:matrix.local","access_token":"syt_YWxpY2U_tNnKJcVurmokpzghHgiJ_18QwSc","home_server":"matrix.local","device_id":"PDOWZVFCQQ"}

# 4) alice 同步，看到邀请
curl -s "http://127.0.0.1:8141/_matrix/client/v3/sync?timeout=0" \
  -H "Authorization: Bearer syt_YWxpY2U_tNnKJcVurmokpzghHgiJ_18QwSc" \
  | python3 -c 'import json,sys; d=json.load(sys.stdin); print({"invite":list(d.get("rooms",{}).get("invite",{}).keys())})'

{'invite': ['!QxXyaG7NjuhTQvRBskG5B65awcmIpke22rIF_bmStrk']}

# 5) alice 接受邀请
curl -s -X POST "http://127.0.0.1:8141/_matrix/client/v3/rooms/!QxXyaG7NjuhTQvRBskG5B65awcmIpke22rIF_bmStrk/join" \
  -H "Authorization: Bearer syt_YWxpY2U_tNnKJcVurmokpzghHgiJ_18QwSc" -d '{}'

{"room_id":"!QxXyaG7NjuhTQvRBskG5B65awcmIpke22rIF_bmStrk"}

# 6) admin 发送消息
curl -s -X PUT "http://127.0.0.1:8141/_matrix/client/v3/rooms/!QxXyaG7NjuhTQvRBskG5B65awcmIpke22rIF_bmStrk/send/m.room.message/tx1001" \
  -H "Authorization: Bearer syt_YWRtaW4_isbgbZbnWSzGOajhfWoh_1n9Kgk" \
  -H 'Content-Type: application/json' \
  -d '{"msgtype":"m.text","body":"大家好，这是 admin 在研发部交流房间发的第一条消息"}'

{"event_id":"$LYOt81gGP7zIwxyUvpgG-sLDR9oKkrMW9UYkvTc6HqA"}

# 7) alice 拉取房间历史，看到 admin 的消息
curl -s "http://127.0.0.1:8141/_matrix/client/v3/rooms/!QxXyaG7NjuhTQvRBskG5B65awcmIpke22rIF_bmStrk/messages?dir=b&limit=5" \
  -H "Authorization: Bearer syt_YWxpY2U_tNnKJcVurmokpzghHgiJ_18QwSc" \
  | python3 -c 'import json,sys; d=json.load(sys.stdin); [print({"sender":e["sender"],"body":e["content"]["body"]}) for e in d.get("chunk",[]) if e["type"]=="m.room.message"]'

{'sender': '@admin:matrix.local', 'body': '大家好，这是 admin 在研发部交流房间发的第一条消息'}

# 8) alice 回复
curl -s -X PUT "http://127.0.0.1:8141/_matrix/client/v3/rooms/!QxXyaG7NjuhTQvRBskG5B65awcmIpke22rIF_bmStrk/send/m.room.message/tx2001" \
  -H "Authorization: Bearer syt_YWxpY2U_tNnKJcVurmokpzghHgiJ_18QwSc" \
  -H 'Content-Type: application/json' \
  -d '{"msgtype":"m.text","body":"收到！alice 这边显示互通正常"}'

{"event_id":"$qYS4RBMEMPe4gSRrWJ5yrECGfSNW3PAxWYAkTK_Jui0"}

# 9) admin 再拉取历史，看到双向两条消息（互通闭环）
curl -s "http://127.0.0.1:8141/_matrix/client/v3/rooms/!QxXyaG7NjuhTQvRBskG5B65awcmIpke22rIF_bmStrk/messages?dir=b&limit=5" \
  -H "Authorization: Bearer syt_YWRtaW4_isbgbZbnWSzGOajhfWoh_1n9Kgk" \
  | python3 -c 'import json,sys; d=json.load(sys.stdin); [print({"sender":e["sender"],"body":e["content"]["body"]}) for e in d.get("chunk",[]) if e["type"]=="m.room.message"]'

{'sender': '@alice:matrix.local', 'body': '收到！alice 这边显示互通正常'}
{'sender': '@admin:matrix.local', 'body': '大家好，这是 admin 在研发部交流房间发的第一条消息'}

# Synapse（数据目录持久化到宿主机；启动命令固定为 run 模式）
docker run -d --name synapse \
  -v /opt/synapse/data:/data \
  -p 8141:8008 \
  matrixdotorg/synapse:v1.163.0 run

# Element Web（只读挂载配置）
docker run -d --name element-web \
  -v /opt/synapse/element-config/config.json:/app/config.json:ro \
  -p 8142:80 \
  vectorim/element-web:v1.12.32

cd /opt/synapse   # 以下命令均在该目录执行
docker compose ps                       # 两服务状态（healthy 检查），回显见 4.5
docker compose logs synapse --tail 50   # 服务端日志（配置错误首屏即现）
docker compose logs element --tail 20   # Web 端访问日志
docker compose restart synapse          # 改 homeserver.yaml 后重启生效（实测见 FAQ Q4）
docker compose restart element          # 改 config.json 后重启生效
docker compose stop / start / down      # 停止/启动/拆除（down 不删 bind 数据）
docker compose up -d                    # 重建/变更后拉起
docker compose pull && docker compose up -d   # 换版本标签后升级（见 4.11）

curl -s http://127.0.0.1:8141/_matrix/client/versions | head -c 80; echo   # API 活性
curl -s http://127.0.0.1:8141/_synapse/admin/v1/server_version              # 版本
docker compose ps --format '{{.Name}} {{.Status}}'                          # 双服务 healthy

{"versions":["r0.0.1","r0.1.0","r0.2.0","r0.3.0","r0.4.0","r0.5.0","r0.6.0","r0.6.1","v1.1","v1.2","v1.3","v1.4","v1.5","v1.6","v1.7","v1.8","v1.9","v1.10","v1.11","v1.12","v1.13","v1.14","v1.15"],
{"server_version":"1.163.0"}
element-1.12.32-web Up (healthy)
synapse-1.163.0-homeserver Up (healthy)

synapse-1.163.0-homeserver  | Error in configuration:
synapse-1.163.0-homeserver  |   You have enabled open registration without any verification. This is a known vector for spam and abuse. If you would like to allow public registration, please consider adding email, captcha, or token-based verification. Otherwise this check can be removed by setting the `enable_registration_without_verification` config option to `true`.

Make admin [no]: Traceback (most recent call last):
  File "/usr/local/bin/register_new_matrix_user", line 10, in <module>
    sys.exit(main())
EOFError: EOF when reading a line

{"errcode":"M_LIMIT_EXCEEDED","error":"Too Many Requests","retry_after_ms":85252}