如何5分钟跑起来太卜:本地开发环境与一键Docker部署完整指南

原创2026-11-01 15:24:211,659 阅读

如何5分钟跑起来太卜:本地开发环境与一键Docker部署完整指南

太卜是一款高精度 AI 算命工具,涵盖八字、紫微斗数、六爻、梅花易数、奇门遁甲、塔罗、MBTI、合盘配对、每日运势等体系,并支持 MCP 服务和 Skills。本文将手把手带你完成太卜本地开发环境搭建与一键 Docker 部署,从零到访问页面只要 5 分钟。

一、先认识太卜:一个多端 AI 命理平台

太卜基于 Next.js + TypeScript + Supabase(PostgreSQL)构建,支持 Web 与 iOS/Android 客户端,核心亮点:

  • 多命理体系:八字、紫微斗数、六爻、奇门遁甲、大六壬、梅花易数、塔罗、MBTI、面相手相、合盘、周公解梦等
  • AI 智能分析:多模型支持、深度推理、Agent 对话排盘
  • MCP Server:可在支持 MCP 的 agent 中直接调用全部命理工具

整体项目结构速览:

目录 作用
src/ Web 应用(Next.js 路由、组件、API)
packages/core/ 命理计算核心引擎(可独立发布为 taibu-core)
packages/mcp-server/ 独立 MCP Server
docker-compose.yml / Dockerfile 一键 Docker 部署
docs/manual/Self-Hosting.md 自托管完整说明

太卜应用启动画面

二、方式一:本地开发环境 5 分钟启动

适合想参与开发、二次改造或调试 AI 功能的用户。

2.1 环境要求

  • Node.js 18+(自托管完整栈建议 Node 22.19+)
  • pnpm(推荐,Docker 镜像内固定 pnpm 10.33.0)

2.2 克隆、安装、启动三步走

# 1) 克隆仓库
git clone https://gitcode.com/gh_mirrors/ta/taibu
cd taibu

# 2) 安装依赖(monorepo,会一并安装 packages 下的子包)
pnpm install

# 3) 配置环境变量
cp .env.example .env
# 编辑 .env 填入必要的 API Keys(如 AI 网关 NEWAPI_BASE_URL / NEWAPI_API_KEY 等)

# 4) 启动开发服务器
pnpm dev

打开浏览器访问 http://localhost:3000 即可看到应用。

💡 说明:pnpm dev 实际调用 scripts/dev-with-core-watch.mjs,会自动监听并重建 packages/core 核心包,改核心算法代码也能热更新。

2.3 常用开发命令

pnpm test      # 运行单元、路由与协议守卫测试
pnpm typecheck # 全仓类型检查
pnpm lint      # ESLint + 架构守卫检查
pnpm verify    # 一次性完整验收(需本地 Docker)

三、方式二:一键 Docker 部署(推荐普通用户)

不想装 Node 环境?Docker 方式一条命令拉起。仓库根目录提供了三个 Compose 文件,部署前先准备环境变量(首次):

cp .env.example .env
# 按需编辑 .env,重点配置 Supabase 地址/密钥与 AI 网关 Key

3.1 一键启动 Web + MCP

docker compose up -d --build

docker-compose.yml 会同时构建三个服务:

服务 镜像 默认端口
web taibu-web:latest 3000 → http://localhost:3000
worker taibu-web:latest(后台 Agent 执行器,无宿主端口) —
mcp taibu-mcp:latest 3001 → http://localhost:3001/mcp

构建过程由 Dockerfile 多阶段完成:依赖安装 → pnpm build 构建 Next standalone 产物 → 非 root 用户运行,并在启动时自动执行 /api/health 健康检查。

3.2 仅部署 Web 或仅部署 MCP

# 仅部署 Web
docker compose -f docker-compose.web.yml up -d --build

# 仅部署 MCP Server(给 agent 提供命理工具)
docker compose -f docker-compose.mcp.yml up -d --build

MCP 服务的安全参数(MCP_ALLOWED_ORIGINS、MCP_RATE_LIMIT_PER_MINUTE 等)可在 .env.example 中查看注释说明,生产环境建议至少配置 MCP_ALLOWED_ORIGINS,不要使用 *。

四、方式三:完全本地自托管(PostgreSQL + Redis)

如果你希望不依赖任何托管 Supabase、彻底离线私有化,太卜提供了内置自托管原型:一条命令拉起 PostgreSQL(pgvector)、Redis、Auth、PostgREST、Storage、Agent worker 等完整栈。

pnpm selfhost init --demo   # 生成隔离配置(demo 使用本地确定性模型,无 AI 费用)
pnpm selfhost up            # 启动全部容器

访问 http://127.0.0.1:3080,登录账号密码为随机生成,保存在 .taibu-local/taibu-local/credentials.json(请勿公开该文件):

pnpm selfhost status  # 查看状态
pnpm selfhost logs    # 受控日志
pnpm selfhost down    # 停止(保留数据库与头像卷)

太卜移动端启动页

⚠️ 注意:该方案属于自托管第一阶段本地原型,--demo 模式是明确标注的确定性演示模型,用于验证真实 HTTP/SSE/计费链路,不代表真实 AI 推理质量。生产迁移门槛详见 docs/manual/Self-Hosting.md。

五、常见问题快速排查

Q1:pnpm dev 启动失败或依赖安装报错? 确认 Node 版本 ≥ 18,并删除 node_modules 后重新 pnpm install;monorepo 子包构建失败时先单独执行 pnpm build:core 查看具体报错。

Q2:Docker 构建很慢或失败? 首次 --build 需要拉取 Node 基础镜像并安装全部依赖,建议等待;确认 .env 中已填写 SUPABASE_URL、SUPABASE_ANON_KEY 等必要变量,构建时 SUPABASE_PUBLIC_URL 作为公开 build arg 传入。

Q3:访问 3000 端口被占用? 在 .env 中修改 WEB_PORT(Web)或 MCP_PORT(MCP)后重新 docker compose up -d --build。

Q4:如何验证服务健康? Web 内置健康检查接口 /api/health,可直接 curl http://localhost:3000/api/health 验证。

六、小结

场景 推荐方式 关键命令
开发/二次开发 本地环境 pnpm install && pnpm dev
快速体验完整功能 Docker 一键 docker compose up -d --build
私有化离线部署 自托管原型 pnpm selfhost init --demo && pnpm selfhost up

至此,你已掌握太卜的三种启动方式:5 分钟本地开发、一条命令 Docker 部署、以及完全离线的自托管方案。接下来可以进一步阅读 packages/core/ALGORITHM_RULES.md 了解命理算法规则,或在 docs/manual/MCP-Server-Manual.md 中查看如何在自己的 agent 里接入太卜的 15 个命理工具。

登录后查看全文
taibu