最完整AI Town混合云部署指南：从本地到云端的无缝架构实践-优快云博客

最完整AI Town混合云部署指南：从本地到云端的无缝架构实践

【免费下载链接】ai-town A MIT-licensed, deployable starter kit for building and customizing your own version of AI town - a virtual town where AI characters live, chat and socialize. 项目地址: https://gitcode.com/gh_mirrors/ai/ai-town

你是否正为AI Town部署发愁？本地开发卡顿、云端成本高昂、数据同步困难？本文将通过混合云架构彻底解决这些痛点，让你既能利用公有云弹性扩展，又能保护私有数据安全。读完本文你将掌握：Docker容器化私有云部署、Fly.io轻量云端托管、Vercel静态资源加速的全流程方案，以及跨环境数据同步的最佳实践。

混合云架构概览

AI Town混合云部署架构通过将计算密集型服务（如LLM推理、游戏引擎）部署在私有环境，而将静态资源、API网关等放在公有云，实现成本与性能的最佳平衡。这种架构特别适合需要保护用户数据同时又要保证全球访问速度的场景。

核心组件分布

服务类型	私有云部署	公有云部署
游戏引擎核心	Docker Compose	-
静态资源	-	Vercel CDN
数据库服务	Convex后端	Convex Cloud
API服务	-	Fly.io后端
管理面板	本地Dashboard	云端Dashboard

架构流程图

mermaid

私有云基础：Docker容器化部署

Docker Compose提供了AI Town完整的本地部署方案，包含前端、后端和数据库服务，适合开发环境和私有服务器部署。这种方式保留了数据控制权，同时通过容器化简化了环境一致性管理。

部署步骤

初始化环境

git clone https://gitcode.com/gh_mirrors/ai/ai-town
cd ai-town
npm install

配置Docker环境 编辑docker-compose.yml文件，根据硬件配置调整资源分配：

services:
  backend:
    image: ghcr.io/get-convex/self-hosted-backend:latest
    ports:
      - '3210:3210'  # Convex后端API
      - '3211:3211'  # 服务代理
    environment:
      - INSTANCE_NAME=ai-town-private
      - CONVEX_CLOUD_ORIGIN=http://127.0.0.1:3210

启动私有云服务
```
docker compose up --build -d
```
服务启动后，可通过以下地址访问：
- 前端界面: http://localhost:5173
- 后端API: http://localhost:3210
- 管理面板: http://localhost:6791

关键配置说明

Docker部署包含三个核心服务：

frontend: 基于Vite的前端应用，通过卷挂载实现代码热更新
backend: Convex自托管后端，处理游戏逻辑和数据库操作
dashboard: Convex管理界面，用于数据管理和监控

提示：首次启动需要生成管理员密钥，执行docker compose exec backend ./generate_admin_key.sh并保存到.env.local文件

公有云扩展：轻量级云端部署

当私有云部署完成后，我们需要将部分服务扩展到公有云以提升访问速度和可用性。Fly.io提供了简单高效的容器部署方案，特别适合API服务和轻量级后端；而Vercel则专为前端静态资源优化，提供全球CDN加速。

Fly.io后端部署

准备配置文件 fly/backend/fly.toml定义了云端后端的资源配置：

app = 'ai-town-convex-backend'
primary_region = 'sjc'

[[vm]]
  memory = '1gb'
  cpu_kind = 'shared'
  cpus = 1

部署命令
```
cd fly/backend
fly deploy
```
关键参数调整
- min_machines_running: 设置为1确保服务始终可用
- auto_stop_machines: 非生产环境可设为stop节省成本
- memory: 根据并发量调整，推荐至少1GB

Vercel前端部署

配置路由规则 vercel.json文件设置了路径重写规则，确保前端资源正确加载：

{
  "framework": "vite",
  "rewrites": [
    {
      "source": "/ai-town/:match*",
      "destination": "/:match*"
    }
  ]
}

部署流程
```
npm install -g vercel
vercel --prod
```
部署优势
- 全球边缘节点加速静态资源
- 自动HTTPS和证书管理
- 与前端开发流程无缝集成

跨环境数据同步策略

混合云架构的核心挑战是确保私有云和公有云之间的数据一致性。AI Town通过Convex数据库的双向同步能力和环境变量管理，实现了开发、测试和生产环境的无缝切换。

环境变量配置

创建.env.local文件管理不同环境的配置：

# 私有云配置
CONVEX_SELF_HOSTED_URL=http://127.0.0.1:3210
CONVEX_SELF_HOSTED_ADMIN_KEY="your-private-key"

# 公有云配置
FLY_APP_NAME=ai-town-convex-backend
VERCEL_PROJECT_ID=your-vercel-project-id

# 跨环境共享配置
OLLAMA_MODEL=llama3
NUM_MEMORIES_TO_SEARCH=5

数据迁移命令

从私有云导出数据

npx convex export --out convex-export.zip

导入到公有云

npx convex import --prod convex-export.zip

定期同步脚本 创建定时任务自动同步关键数据：

#!/bin/bash
# sync-data.sh
npx convex export --out /tmp/convex-sync.zip
npx convex import --prod /tmp/convex-sync.zip

数据一致性保障

使用convex/init.ts初始化脚本确保环境一致性
通过convex/testing.ts测试数据迁移兼容性
利用convex/crons.ts定时任务同步跨环境数据

性能优化与成本控制

混合云架构的一大优势是能够根据负载动态调整资源分配。通过合理配置私有云和公有云的资源比例，可以在保证性能的同时最大化降低成本。

资源调配建议

负载情况	优化策略	配置文件
开发环境	最小化本地资源，禁用云端服务	docker-compose.yml
测试环境	轻量云端部署，共享开发数据库	fly/backend/fly.toml
生产环境	私有云处理核心业务，公有云扩展访问	vercel.json

成本优化技巧

自动扩缩容配置 在Fly.io配置中设置自动扩缩容规则：

[http_service]
  auto_stop_machines = 'stop'  # 低负载时自动停止
  auto_start_machines = true   # 有请求时自动启动
  min_machines_running = 0     # 最小运行实例数

本地资源限制 在Docker Compose中限制资源使用：

services:
  backend:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G

静态资源优化 通过Vercel优化前端资源：
```
vercel build --prod  # 启用生产环境优化
```

性能监控

使用Convex Dashboard监控数据库性能
通过Fly.io metrics跟踪API响应时间
利用浏览器开发工具分析前端性能

常见问题与解决方案

混合云部署涉及多个环境和服务，可能会遇到各种集成问题。以下是一些常见问题的解决方案和最佳实践。

跨环境网络连接

问题：私有云Ollama服务无法被云端应用访问
解决方案：使用Tunnelmole创建安全隧道：

# 在私有服务器上运行
tmole 11434
# 设置环境变量
npx convex env set OLLAMA_HOST "https://your-tunnel-url.tunnelmole.net"

数据同步冲突

问题：私有云和公有云数据版本不一致
解决方案：使用乐观锁机制和冲突解决策略：

// 在convex/mutation.ts中实现冲突检测
export const updateData = mutation({
  args: { id: v.id('data'), data: v.any(), version: v.number() },
  handler: async (ctx, args) => {
    const existing = await ctx.db.get(args.id);
    if (existing?.version !== args.version) {
      throw new Error("Data conflict detected");
    }
    // 执行更新
    await ctx.db.patch(args.id, { ...args.data, version: args.version + 1 });
  }
});

资源访问控制

问题：需要限制对私有云服务的访问
解决方案：配置网络访问控制列表：

# docker-compose.yml 网络配置
networks:
  ai-town-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.28.0.0/16
    driver_opts:
      com.docker.network.bridge.name: aitownbr0

部署 checklist 与最佳实践

为确保部署过程顺利，建议遵循以下步骤和最佳实践，从准备到上线全程无忧。

部署前准备

检查Docker版本≥20.10.0
配置Node.js 18环境：nvm use 18
准备Convex账号和API密钥
注册Fly.io和Vercel账号
配置域名和SSL证书

部署后验证

私有云服务检查

docker compose ps  # 确认所有容器正常运行
curl http://localhost:3210/version  # 验证Convex后端

公有云服务检查

fly status  # 检查Fly.io服务状态
vercel logs  # 查看Vercel部署日志

端到端功能测试
- 访问前端界面确认资源加载正常
- 测试AI角色对话功能验证LLM连接
- 检查游戏引擎和物理模拟性能

持续维护建议

定期更新Docker镜像确保安全补丁
使用convex/testing.ts自动化测试环境兼容性
监控convex/engine/性能指标优化资源分配
定期备份数据并测试恢复流程

总结与展望

AI Town混合云部署架构通过精心设计的服务拆分和资源调配，完美平衡了性能、成本和数据安全需求。无论是小型团队的开发测试，还是企业级的生产部署，这种架构都能提供灵活可扩展的解决方案。

随着AI技术的发展，未来可以进一步优化：

实现基于Kubernetes的混合云自动编排
利用边缘计算节点降低全球访问延迟
结合AI预测模型动态调整资源分配

通过本文介绍的方案，你已经掌握了AI Town从本地开发到全球部署的完整流程。立即开始构建你的混合云AI小镇，体验私有云安全与公有云弹性的完美结合！

官方文档：README.md
部署配置文件：docker-compose.yml
云端部署指南：fly/README.md
前端部署配置：vercel.json

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考