十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Hydra-AI(Tambo)自托管部署指南:基于 Docker Compose 的 Web、API 与 PostgreSQL 一键私有化部署

Hydra-AI(Tambo)自托管部署指南:基于 Docker Compose 的 Web、API 与 PostgreSQL 一键私有化部署 Hydra-AITambo自托管部署指南基于 Docker Compose 的 Web、API 与 PostgreSQL 一键私有化部署【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai本指南面向希望将 TamboGenerative UI SDK for React 的云端后端与仪表盘部署到自有基础设施的开发者完整讲解基于 Docker Compose 的三服务架构Next.js Web 仪表盘、NestJS API、PostgreSQL 17、环境变量配置、数据库初始化与日常运维命令。读完本文你将能够从零拉起一套可访问的自托管实例并能基于仓库内的真实配置与源码理解每个参数的作用与底层实现。一、架构总览三服务如何协作Tambo 的自托管形态由三个核心服务组成SELF-HOSTING.md 给出了明确的分工与端口约定服务技术栈对外端口职责WebNext.js8260仪表盘与用户界面APINestJS8261面向客户端请求的 REST APIPostgreSQLPostgreSQL 175433数据库值得注意的细节是主机对外端口与容器内端口并不一致。查看 docker-compose.yml 可以发现Web 与 API 容器内部都以PORT3000运行通过8260:3000、8261:3000映射到宿主机PostgreSQL 容器内部使用标准 5432映射为宿主机 5433从而避免与本机已有的 Postgres/其他服务端口冲突。此外compose 文件中还包含第四个服务MinIOS3 兼容对象存储控制台端口 9001、API 端口 9000用于存储文件类资源它与数据库、Web、API 一起组成了完整的数据面。二、Docker 快速启动从零到可访问的六步2.1 前置条件已安装 Docker 与 Docker Compose一个 OpenAI API Key或兼容的 Provider Key。2.2 克隆仓库git clone https://gitcode.com/GitHub_Trending/hy/hydra-ai.git cd hydra-ai若想参与本地开发而非部署请参阅 CONTRIBUTING.md。2.3 生成环境配置文件./scripts/cloud/tambo-setup.sh该脚本会完成三项工作见 tambo-setup.sh前置检查校验 Docker、Docker Compose 是否安装生成docker.env若文件不存在则将docker.env.example复制为docker.env打印后续步骤提示编辑配置 → 构建镜像 → 启动栈 → 初始化数据库 → 访问应用。2.4 配置环境变量编辑docker.env至少需要设置以下五项# Required POSTGRES_PASSWORDyour-secure-password-here API_KEY_SECRETyour-32-character-api-key-secret PROVIDER_KEY_SECRETyour-32-character-provider-secret NEXTAUTH_SECRETyour-nextauth-secret FALLBACK_OPENAI_API_KEYyour-openai-api-keydocker.env.example中自带占位值启动前必须替换为强密钥。关于每一项的具体含义与完整参数清单见本文第三节。2.5 启动服务./scripts/cloud/tambo-start.sh该脚本见 tambo-start.sh内部依次完成校验docker.env存在、Docker 守护进程运行中创建tambo_network自定义网络已存在则忽略非 CI 环境下先docker compose --env-file docker.env pull --ignore-buildable拉取最新镜像以 BuildKit 模式docker compose --env-file docker.env up -d启动全部服务轮询等待 PostgreSQL 容器进入 healthy 状态输出最终服务状态与访问地址。2.6 初始化数据库./scripts/cloud/init-database.sh数据库初始化脚本init-database.sh采用双模式设计宿主机模式检测到不在容器内时脚本会检查 API 容器是否已启动docker compose ps api需为Up然后自动委派给 API 容器内部执行docker compose --env-file docker.env exec -T api sh -lc ./scripts/cloud/init-database.sh容器内模式检测到/ .dockerenv或 cgroup 标记后直接使用容器环境中的DATABASE_URL执行迁移npm -w tambo-ai-cloud/db run db:migrate迁移命令实际指向 packages/db/package.json 中的db:migrate: drizzle-kit migrate即使用Drizzle ORM的迁移器执行位于 packages/db/migrations 下的 SQL 迁移文件从0000_init_setup.sql起的完整迁移序列。2.7 访问你的部署Web 仪表盘http://localhost:8260API 服务http://localhost:8261PostgreSQL 数据库localhost:5433如用psql连接端口为 5433三、环境变量完整参考基于 docker.env.example仓库根目录的 docker.env.example 是配置的权威来源按功能域分类如下3.1 PostgreSQL 配置变量说明示例/默认POSTGRES_PASSWORD数据库密码postgres必须修改POSTGRES_DB数据库名tamboPOSTGRES_USER数据库用户postgresDATABASE_URL由 docker-compose 自动推导生成postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}postgres:5432/${POSTGRES_DB}一般无需手工设置如需覆盖可取消注释示例中的对应行。3.2 密钥与 API Key变量说明API_KEY_SECRETAPI 请求签名密钥建议openssl rand -hex 32生成PROVIDER_KEY_SECRETLLM Provider 密钥加密密钥同样建议 32 字符以上OPENAI_API_KEY主 OpenAI KeyEXTRACTION_OPENAI_API_KEY内容提取专用 KeyFALLBACK_OPENAI_API_KEY免费层项目未配置用户 Key 时的兜底 Key3.3 Web 客户端配置NEXT_PUBLIC_ 前缀变量说明NEXT_PUBLIC_TAMBO_API_URL前端调用的 API 地址默认http://localhost:8261NEXT_PUBLIC_TAMBO_API_KEY前端直连 API 的 Key用于自举自用 APINEXT_PUBLIC_TAMBO_DASH_KEY仪表盘 KeyNEXT_PUBLIC_SMOKETEST_TAMBO_API_KEY/NEXT_PUBLIC_SMOKETEST_PROJECT_ID冒烟测试用3.4 可观测性PostHog / Langfuse / Sentry前端NEXT_PUBLIC_POSTHOG_HOST、NEXT_PUBLIC_POSTHOG_KEY、NEXT_PUBLIC_SENTRY_DSN、NEXT_PUBLIC_SENTRY_ORG、NEXT_PUBLIC_SENTRY_PROJECT后端POSTHOG_API_KEY、POSTHOG_HOST、SENTRY_DSNLLM 追踪LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY、LANGFUSE_HOST默认https://cloud.langfuse.com。3.5 邮件ResendRESEND_API_KEY、RESEND_AUDIENCE_ID以及发件人配置EMAIL_FROM_DEFAULT、EMAIL_FROM_PERSONAL、EMAIL_REPLY_TO_PERSONAL、EMAIL_REPLY_TO_SUPPORT。3.6 认证NextAuth与登录限制NEXTAUTH_SECRETyour-nextauth-secret NEXTAUTH_URLhttp://localhost:8260 GOOGLE_CLIENT_IDyour-google-client-id GOOGLE_CLIENT_SECRETyour-google-client-secret GITHUB_CLIENT_IDyour-github-client-id GITHUB_CLIENT_SECRETyour-github-client-secret ALLOWED_LOGIN_DOMAIN # 留空放行所有已验证邮箱 DISALLOWED_EMAIL_DOMAINSexample.comNEXTAUTH_URL必须指向客户端应用地址以便认证后回跳ALLOWED_LOGIN_DOMAIN可在自托管时把登录限制到某个已验证的企业域名。3.7 可选功能与白标TAMBO_WHITELABEL_ORG_NAME/TAMBO_WHITELABEL_ORG_LOGO在 Logo 旁显示的自定义组织名与 Logo 地址SLACK_OAUTH_TOKEN/SLACK_TEAM_ID/INTERNAL_SLACK_USER_IDSlack 集成WEATHER_API_KEY天气工具ALLOW_LOCAL_MCP_SERVERS设置为true允许测试本机运行的 MCP 服务器仅开发场景GITHUB_TOKENGitHub 工具调用NODE_ENVproduction运行环境。3.8 源码层的校验逻辑重要并非所有变量都是填了就生效Web 端通过 apps/web/lib/env.ts 中的t3-oss/env-nextjs zod schema 在启动时做类型校验。从源码看API_KEY_SECRET、PROVIDER_KEY_SECRET、NEXTAUTH_SECRET均要求min(8)注释建议用openssl rand -hex 32生成NEXTAUTH_URL必须是合法 URL其余大多数为可选optional()且空字符串会被转换为undefined若缺失必需变量应用启动时会直接报错这可以作为一种部署前的自检手段。四、docker-compose.yml 深入解析完整的服务定义位于 docker-compose.yml核心要点4.1 服务与健康检查postgrespostgres:17镜像数据卷tambo_postgres_data通过pg_isready做健康检查间隔 8s、启动宽限 20sapi构建自 apps/api/Dockerfiledepends_on: postgres (service_healthy)即数据库健康后才启动web构建自 apps/web/Dockerfiledepends_on同时要求postgres 与 api 都 healthy保证仪表盘启动时后端已就绪miniominio/minio:latest通过curl /minio/health/ready做健康检查。4.2 网络与数据持久化三个应用服务不直接写死网络启动脚本会创建tambo_networkCompose 默认网络即可满足服务间通过服务名互访如postgres:5432数据库数据与 MinIO 对象数据分别由命名卷tambo_postgres_data、minio_data持久化docker compose down不会丢失数据。4.3 Dockerfile 的构建细节两个应用镜像都采用多阶段构建 非 root 运行基础镜像node:22-alpine并升级 npm 到 v11规避 node:22-alpine 自带 npm 的 promise-retry 缺陷使用npx turbo prune pkg --docker裁剪 monorepo 工作区后再npm ci与构建显著减小镜像体积运行阶段创建 uid1001 的nodejs用户以非 root 运行Web 镜像使用 Next.jsstandalone 输出apps/web/.next/standalone并单独拷贝.next/static与public两个容器均配置HEALTHCHECKwget -qO- http://${HOSTNAME}:${PORT}供 compose 依赖编排使用API 镜像以dumb-init启动避免 Node 以 PID 1 运行带来的信号处理问题。五、日常运维日志、停止与查看状态scripts/cloud 目录集中了全部运维脚本公共的日志着色与退出逻辑封装在 _cloud-helpers.sh 中提供info/warn/error/success/fail及get_repo_root等函数。脚本用途./scripts/cloud/tambo-start.sh启动整个栈含拉镜像、等健康./scripts/cloud/tambo-stop.sh停止服务并清理tambo_network保留数据卷./scripts/cloud/tambo-logs.sh查看日志支持web/api/postgres单服务过滤--help查看用法./scripts/cloud/init-database.sh初始化/迁移数据库自动委派进容器./scripts/cloud/tambo-psql.sh进入 PostgreSQL 交互终端./scripts/cloud/smoke-mcp.shMCP 冒烟测试./scripts/cloud/tambo-setup.sh首次环境初始化示例./scripts/cloud/tambo-logs.sh api # 只看 API 日志 ./scripts/cloud/tambo-logs.sh # 查看全部服务日志 ./scripts/cloud/tambo-stop.sh # 停止整个栈六、生产化与安全建议基于上述配置与源码自托管到生产环境时请重点关注密钥强度API_KEY_SECRET、PROVIDER_KEY_SECRET、NEXTAUTH_SECRET至少 8 字符官方注释建议用openssl rand -hex 32生成切勿沿用示例占位值认证收敛设置ALLOWED_LOGIN_DOMAIN将登录限定到自有域名按需配置 Google/GitHub OAuth对应 docker.env.example 中的GOOGLE_CLIENT_*、GITHUB_CLIENT_*数据库口令修改POSTGRES_PASSWORD数据由命名卷持久化升级前务必先做备份对外暴露NEXTAUTH_URL需为可回跳的公网地址如有反向代理注意将 8260/8261 端口正确转发调试开关ALLOW_LOCAL_MCP_SERVERStrue仅用于本地开发测试生产应关闭。七、常见问题速查API 容器未启动导致初始化失败init-database.sh在宿主机模式要求 API 容器处于Up状态请先执行./scripts/cloud/tambo-start.sh再初始化启动时报环境变量校验错误检查docker.env是否满足 apps/web/lib/env.ts 中的最小长度与 URL 格式要求想重置整个栈先./scripts/cloud/tambo-stop.sh再重新执行tambo-start.sh数据卷保留如需彻底重建镜像按tambo-setup.sh提示使用构建命令后启动查看具体容器状态docker compose --env-file docker.env ps日志可用tambo-logs.sh按服务过滤定位问题。以上流程覆盖了从环境准备、配置、构建、启动到数据库初始化的完整闭环所有命令与参数均以仓库当前内容为准docker-compose.yml、docker.env.example 与 scripts/cloud可作为私有化部署的直接参考手册。【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表