SimStudioAI本地开发环境Docker Compose配置详解
2025-07-09 01:23:08作者：吴年前Myrtle
概述
本文深入解析SimStudioAI项目的本地开发环境Docker Compose配置文件，帮助开发者理解各服务组件及其配置要点。该配置文件定义了四个核心服务：主应用服务(simstudio)、实时服务(realtime)、数据库迁移服务(migrations)和数据库服务(db)，构建了一个完整的本地开发环境。
服务架构解析
1. 主应用服务(simstudio)
主应用服务是SimStudioAI的核心组件，基于Next.js框架构建，提供Web界面和主要业务逻辑。
关键配置项：
- 端口映射：3000端口映射到宿主机3000端口
- 资源限制：内存上限8GB
- 环境变量：
- 数据库连接(DATABASE_URL)
- 应用URL(BETTER_AUTH_URL, NEXT_PUBLIC_APP_URL)
- 认证密钥(BETTER_AUTH_SECRET)
- 加密密钥(ENCRYPTION_KEY)
- 各种API密钥(FREESTYLE_API_KEY, GOOGLE_CLIENT_ID等)
- OLLAMA服务地址(OLLAMA_URL)
- 实时服务地址(SOCKET_SERVER_URL)
健康检查机制：
- 每90秒检查一次
- 通过wget命令检测3000端口是否可访问
- 最多重试3次
- 启动后10秒开始检查
2. 实时服务(realtime)
实时服务处理WebSocket连接和实时数据推送。
特点：
- 独立于主应用运行
- 使用3002端口
- 同样限制8GB内存
- 依赖数据库服务
- 配置了自动重启策略(除非手动停止)
健康检查：
- 检测3002端口可用性
- 参数与主应用服务类似
3. 数据库迁移服务(migrations)
该服务负责执行数据库迁移脚本，确保数据库结构与代码保持同步。
关键点：
- 使用bun运行时执行迁移命令
- 迁移完成后不会重启
- 依赖数据库服务健康状态
- 使用专用Dockerfile构建
4. 数据库服务(db)
基于pgvector/pgvector镜像的PostgreSQL数据库服务，支持向量操作。
配置详情：
- 使用PostgreSQL 17版本
- 默认端口5432映射
- 持久化数据卷(postgres_data)
- 默认用户/密码/数据库名均为可配置
- 健康检查通过pg_isready命令实现
环境变量管理
配置文件采用了灵活的变量管理策略：
- 使用${VARIABLE:-default}语法提供默认值
- 关键安全参数(如BETTER_AUTH_SECRET)需要开发者自行配置
- 支持从宿主机环境变量注入
部署资源控制
两个主要服务(simstudio和realtime)都配置了内存限制：
- 上限8GB内存
- 防止单个服务占用过多资源
- 适合开发环境资源分配
服务依赖关系
明确定义了服务启动顺序：
- 数据库服务(db)必须健康运行
- 迁移服务(migrations)必须成功完成
- 主应用和实时服务才能启动
持久化存储
使用Docker卷(postgres_data)持久化数据库数据：
- 确保开发环境重启后数据不丢失
- 数据存储在/var/lib/postgresql/data目录
- 独立于容器生命周期
最佳实践建议
- 安全配置：务必替换所有placeholder和默认密钥
- 资源调整：根据开发机性能调整内存限制
- 变量管理：建议使用.env文件管理环境变量
- 健康检查：可调整间隔时间适应不同开发场景
- 数据库备份：定期备份postgres_data卷数据
总结
该Docker Compose配置为SimStudioAI项目提供了完整的本地开发环境，合理划分了服务边界，配置了必要的健康检查和资源限制，是开发者在本地搭建和测试项目的理想起点。理解这些配置细节有助于开发者根据实际需求进行定制化调整。
