你是否在升级Supabase Realtime时遇到配置不兼容、依赖冲突或功能失效等问题？本文将帮助你一文解决从v1到v2版本的迁移难题，确保业务系统平滑过渡，数据同步不受影响。读完本文后，你将能够：
项目地址: https://gitcode.com/gh_mirrors/re/realtime - 清晰了解v1与v2版本的核心差异
- 掌握迁移前的环境检查与准备工作
- 分步实施配置文件升级与依赖更新
- 解决常见迁移问题并验证迁移结果
- 了解新功能并规划后续优化方向
版本差异概览
Supabase Realtime v2版本在架构设计和功能实现上进行了重大优化，主要变化包括：
核心模块重构
- CDC RLS扩展：新增extensions/postgres_cdc_rls目录，提供更细粒度的数据变更捕获与行级安全控制
- 广播适配器：引入GenRPC作为默认广播适配器，提升分布式环境下的消息同步效率
- 租户管理：增强tenants模块，支持多租户隔离与资源配额管理
配置文件变更
v2版本对配置文件结构进行了重组，主要变更文件包括：
| v1配置文件 | v2对应文件 | 主要变更 |
|---|---|---|
config.exs | config/config.exs | 新增租户默认配置项 |
prod.exs | config/prod.exs | 调整数据库连接池设置 |
runtime.exs | config/runtime.exs | 重构环境变量加载逻辑 |
迁移准备工作
环境检查
在开始迁移前，请确保你的环境满足以下要求：
# 检查Elixir版本（需≥1.14）
elixir --version
# 检查PostgreSQL版本（需≥14）
psql --version
# 克隆最新代码
git clone https://gitcode.com/gh_mirrors/re/realtime
cd realtime
数据备份
执行以下命令备份关键数据：
# 备份数据库
pg_dump -U postgres -d realtime > realtime_backup_$(date +%Y%m%d).sql
# 备份配置文件
cp config/prod.exs config/prod.exs.bak
cp config/runtime.exs config/runtime.exs.bak
依赖分析
查看项目依赖变更情况：
# 比较依赖差异
diff -u mix.lock.bak mix.lock
v2版本主要新增依赖包括：
gen_rpc：分布式节点通信broadway：消息处理管道telemetry_metrics_prometheus：监控指标收集
分步迁移实施
1. 配置文件升级
数据库连接配置
更新config/prod.exs中的数据库连接设置：
config :realtime, Realtime.Repo,
url: System.get_env("DATABASE_URL"),
pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10"),
socket_options: [:inet6],
parameters: [application_name: "realtime_prod"]
租户配置迁移
新增租户默认配置到config/config.exs：
config :realtime, :tenants,
default_broadcast_adapter: :gen_rpc,
max_events_per_second: 100,
max_presence_events_per_second: 50
2. 数据库迁移
执行v2版本新增的数据库迁移脚本：
# 运行迁移
mix ecto.migrate
# 验证迁移结果
psql -U postgres -d realtime -c "SELECT version FROM schema_migrations ORDER BY version DESC LIMIT 1;"
关键迁移文件包括：
- 20241019105805_uuid_auto_generation.ex：UUID自动生成功能
- 20250123174212_remove_unused_publications.ex：清理未使用的数据库发布
- 20250613072131_add_tenant_broadcast_adapter.ex：添加租户广播适配器配置
3. 依赖更新
更新项目依赖并安装：
# 更新依赖文件
mix deps.update --all
# 安装依赖
mix deps.get
# 编译项目
mix compile
主要依赖变更记录在mix.exs中，重点关注以下包版本：
defp deps do
[
{:phoenix, "~> 1.7"},
{:ecto_sql, "~> 3.10"},
{:postgrex, "~> 0.17"},
{:gen_rpc, "~> 0.4"},
# 其他依赖...
]
end
迁移验证与问题解决
服务启动验证
# 启动服务
mix phx.server
# 或使用Docker部署
docker-compose up -d
检查服务日志确认启动正常：
docker logs -f realtime_web
预期输出应包含：Realtime.Application started successfully
功能验证清单
完成以下测试确保核心功能正常工作：
- 数据同步测试：修改数据库记录，验证实时推送功能
- 权限控制测试：使用不同角色账号验证RLS策略生效
- 负载测试：使用bench/gen_counter.exs进行压力测试
常见问题解决
问题1：配置文件格式错误
症状：启动时报错invalid configuration
解决：检查config/runtime.exs中的环境变量引用，确保格式正确：
# 错误示例
config :realtime, :db, System.get_env("DB_URL")
# 正确示例
config :realtime, :db,
url: System.get_env("DB_URL"),
pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10")
问题2：CDC RLS扩展加载失败
症状：日志中出现PostgresCDC.RLS not loaded
解决：确保extensions/postgres_cdc_rls/process.ex正确配置：
def start_link(opts) do
Agent.start_link(fn -> %{} end, name: __MODULE__)
end
新功能探索
v2版本引入了多项实用功能，建议优先了解：
分布式追踪
通过monitoring/prom_ex模块集成Prometheus监控，配置示例：
# 在config/prod.exs中添加
config :realtime, Realtime.PromEx,
metrics_server: [port: 4000]
访问http://localhost:4000/metrics查看监控指标。
批量广播优化
使用tenants/batch_broadcast.ex提升高并发场景下的消息处理效率：
# 批量发送示例
Realtime.Tenants.BatchBroadcast.enqueue(tenant_id, messages)
迁移总结与后续规划
迁移检查清单
- 配置文件已全部更新
- 数据库迁移已执行
- 依赖包已正确安装
- 核心功能验证通过
- 监控指标正常采集
后续优化建议
- 性能调优：根据metrics_controller.ex收集的数据进行针对性优化
- 容灾备份：配置deploy/fly实现多区域部署
- 功能扩展：探索extensions目录下的扩展接口，开发自定义业务逻辑
通过本文的指南，你已成功完成Supabase Realtime从v1到v2的迁移。如有其他问题，可参考test/integration目录下的测试用例或提交issue获取社区支持。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
