matrix-docker-ansible-deploy版本迁移：v1到v2升级指南

matrix-docker-ansible-deploy版本迁移：v1到v2升级指南

Matrix作为去中心化通信网络，其部署工具matrix-docker-ansible-deploy的v2版本带来多项架构优化与安全增强。本文档系统梳理从v1到v2的迁移路径，帮助管理员平稳过渡至新版本，规避潜在风险。

版本迁移核心变化

v2版本重构了底层服务架构，主要变更包括：

1. 依赖组件升级

• PostgreSQL强制要求v13+：Synapse v1.122.0起不再支持旧版PostgreSQL，需通过维护指南升级。检查当前版本命令：

  cat /matrix/postgres/data/PG_VERSION

• Valkey替代Redis/KeyDB：作为Redis兼容内存数据库，Valkey成为默认组件，自动替换旧版Redis/KeyDB。若需保留旧配置，需修改变量定义。

2. 网络安全强化

• STUN端口默认仅UDP开放：为缓解DDoS攻击，Coturn服务默认仅暴露3478/UDP端口。如需兼容旧客户端，可通过配置项恢复TCP支持：

  matrix_coturn_container_stun_plain_host_bind_port_tcp: "3478"

• 媒体文件强制认证：Synapse默认启用媒体文件访问认证，影响旧版桥接服务。可通过变量控制临时关闭：

  matrix_synapse_enable_authenticated_media: false

迁移准备工作

环境检查清单

1. 组件版本确认：

   • 执行grep -r "matrix_synapse_version" vars.yml确认Synapse版本
   • 检查CHANGELOG.md中v2相关Breaking Changes

2. 数据备份：

   # 数据库备份 ansible-playbook -i inventory/hosts setup.yml --tags=postgres-backup # 媒体文件备份 cp -r /matrix/synapse/storage/media /backup/

配置文件迁移

需重点更新以下配置文件：

旧版配置文件	v2对应路径	变更说明
inventory/hosts	inventory/hosts	新增Traefik入口点配置
vars.yml	vars.yml	Valkey变量替换Redis/KeyDB
group_vars/matrix_servers	roles/custom/matrix-synapse/defaults/main.yml	服务参数规范化

分步实施迁移

1. 升级Playbook代码

# 克隆新版代码库 git clone https://gitcode.com/GitHub_Trending/ma/matrix-docker-ansible-deploy matrix-v2 cd matrix-v2 # 更新依赖角色 just roles

2. 数据库升级

若PostgreSQL版本<13，执行升级流程：

# 停止服务 ansible-playbook -i inventory/hosts setup.yml --tags=stop # 执行升级 ansible-playbook -i inventory/hosts setup.yml --tags=upgrade-postgres

3. 配置迁移与验证

# 迁移自定义配置 cp ../matrix-docker-ansible-deploy/vars.yml ./ # 自动修复配置项 just fix-config # 验证配置 ansible-playbook -i inventory/hosts setup.yml --tags=check

4. 执行部署

# 全量部署 just install-all # 验证服务状态 systemctl status matrix-*

常见问题解决方案

1. Valkey迁移后服务启动失败

现象：Synapse日志显示redis connection refused
解决：检查Valkey容器状态并重启：

docker restart matrix-valkey # 验证连接 docker exec -it matrix-synapse redis-cli -h matrix-valkey ping

2. 媒体文件访问权限问题

现象：客户端无法加载历史图片
解决：修复文件权限并重启Synapse：

chown -R matrix:matrix /matrix/synapse/storage/media ansible-playbook -i inventory/hosts setup.yml --tags=restart-synapse

3. 联邦通信异常

现象：federationtester.matrix.org显示连接失败
解决：检查Traefik联邦端点配置：

# 在vars.yml中确认 matrix_traefik_config_entrypoint_matrix_federation_enabled: true

迁移后优化建议

1. 启用IPv6支持：通过配置指南开启IPv6，提升网络兼容性
2. 实施监控告警：部署Prometheus+Grafana监控关键指标
3. 定期安全审计：执行维护脚本检查潜在风险

迁移验证清单

• 所有服务正常启动（systemctl status matrix-*无失败项）
• 客户端可正常登录并发送消息
• 联邦通信测试通过（curl https://matrix.example.com/_matrix/federation/v1/version返回版本信息）
• 媒体文件上传/下载功能正常
• 备份机制自动运行（检查/matrix/backup目录最新文件）

通过以上步骤，可实现从v1到v2的平稳迁移。建议在非高峰时段操作，全程保留迁移日志以便问题追溯。更多细节可参考官方维护文档。