Convex 后端自托管部署指南

前言

Convex 是一个现代化的全栈开发平台，提供数据库、API 和实时功能的一体化解决方案。本文将详细介绍如何将 Convex 后端服务部署到您自己的基础设施上，实现完全自主托管。

自托管方案概述

Convex 自托管方案包含三个核心组件：

1. Convex 后端服务 - 处理所有数据库操作和业务逻辑
2. Convex 仪表盘 - 提供可视化管理和监控界面
3. 前端应用 - 您的业务应用前端，可独立部署

快速开始：Docker 部署

对于初次尝试的用户，我们推荐使用 Docker 进行快速部署：

1. 首先获取 docker-compose.yml 配置文件
2. 执行以下命令启动服务：

   docker compose up
   

3. 生成管理员密钥：

   docker compose exec backend ./generate_admin_key.sh
   

服务启动后，各组件默认监听端口：

• 后端服务：3210
• HTTP 动作端点：3211
• 仪表盘：6791

生产环境部署建议

对于生产环境，我们建议采用以下配置：

数据库选择

Convex 支持多种数据库后端：

• SQLite (默认，适合开发和测试)
• PostgreSQL (生产推荐)
• MySQL (生产推荐)

PostgreSQL 配置示例

export POSTGRES_URL=postgresql://user:password@host:5432
docker compose up

MySQL 配置示例

export MYSQL_URL=mysql://user:password@host:3306
docker compose up

存储配置

生产环境建议使用 S3 兼容存储：

export AWS_REGION="your-region"
export AWS_ACCESS_KEY_ID="your-access-key-id"
export AWS_SECRET_ACCESS_KEY="your-secret-access-key"
export S3_STORAGE_EXPORTS_BUCKET="convex-snapshot-exports"
# 其他存储桶配置...

高级部署选项

直接运行二进制

对于需要更高定制化的场景，可以直接运行 Convex 后端二进制：

1. 生成实例密钥：

   cargo run -p keybroker --bin generate_secret
   

2. 生成管理员密钥：

   cargo run -p keybroker --bin generate_key -- <实例名> <实例密钥>
   

3. 启动服务：

   ./convex-local-backend --instance-name <实例名> --instance-secret <实例密钥>
   

自定义基础设施部署

在自有服务器上部署时，建议配置：

1. 域名路由：
   • API 端点指向 3210 端口
   • HTTP 动作指向 3211 端口
   • 仪表盘指向 6791 端口
2. 环境变量配置：

   CONVEX_CLOUD_ORIGIN='https://api.your-domain.com'
   CONVEX_SITE_ORIGIN='https://your-domain.com'
   NEXT_PUBLIC_DEPLOYMENT_URL='https://api.your-domain.com'
   

数据迁移指南

当需要更换存储或数据库时：

1. 导出数据：

   npx convex export --path backup.convex
   

2. 在新环境部署服务
3. 导入数据：

   npx convex import --replace-all backup.convex
   

系统升级策略

方案一：导出/导入升级

1. 停止服务流量
2. 导出数据
3. 升级后端版本
4. 导入数据
5. 恢复服务

方案二：原地升级

1. 按顺序升级到每个中间版本
2. 监控迁移日志：

   Executing Migration 114/115. MigrationComplete(115)
   

3. 确认每个迁移完成后再继续

安全与监控配置

日志脱敏

启用日志脱敏防止 PII 泄露：

export REDACT_LOGS_TO_CLIENT=true

禁用使用统计

Convex 默认会发送匿名使用统计，可禁用：

export DISABLE_BEACON=true

前端应用部署

部署前端应用时，需要配置以下环境变量：

CONVEX_SELF_HOSTED_URL='https://api.your-domain.com'
CONVEX_SELF_HOSTED_ADMIN_KEY='your-admin-key'

性能优化建议

1. 确保后端与数据库位于同一区域
2. 对于高负载场景，考虑：
   • 数据库连接池优化
   • 适当的缓存策略
   • 水平扩展后端实例

常见问题解答

Q: 自托管版本与云托管版本功能有何差异？ A: 自托管版本包含云托管免费层的所有功能，但云托管版本针对大规模应用进行了优化。

Q: 如何监控自托管实例的性能？ A: 可以使用内置的 LoadGenerator 工具进行基准测试和负载测试。

Q: 数据库迁移过程中出现错误如何处理？ A: 建议先在测试环境验证迁移流程，确保备份完整后再在生产环境执行。