DoTouchAI/docs/demo-runbook-v1.6.0.md

DoTouch.AI 团队自部署与演示脚本 v1.6.0

版本：v1.6.0 ｜ 日期：2026-08-09 ｜ 用途：① 团队本地部署 demo；② 讲解现场 step-by-step 演示脚本 代码仓库即 demo 完整代码（docker-compose.demo.yml 已在 git），clone 后一条命令部署

---

一、环境要求

依赖	版本	说明
Docker Desktop	≥ 4.x	macOS / Windows / Linux 均可
空闲端口	3000 / 8081 / 5433 / 6380	官网 / API / 演示库 / 演示 Redis
资源	≥ 4GB 内存	演示含 5 个容器

二、部署（3 分钟）

# 1. 克隆仓库
git clone <仓库地址> dotouch-ai && cd dotouch-ai

# 2. 启动演示环境（自动构建 5 容器：PG/Redis/mock上游/API/官网）
docker compose -f docker-compose.demo.yml up -d --build

# 3. 验证（等 15–30 秒初始化）
curl http://localhost:8081/v1/health          # 预期：{"status":"ok","version":"1.6.0",...}
open http://localhost:3000                     # 官网（默认越南语）

• 首次启动自动完成：数据库迁移 → Prisma 生成 → 236 模型 seed（幂等）→ 启动 API
• 关闭：docker compose -f docker-compose.demo.yml down
• 彻底清理（含数据）：docker compose -f docker-compose.demo.yml down -v

三、演示账号

账号	密码	用途
demo.user@dotouch.ai	User2026!	官网 / 用户控制台（余额 $150）
admin@dotouch.ai	Admin2026!	管理后台
test-e2e@dotouch.ai	Test1234	接口联调（admin 角色）
social.demo@dotouch.ai	—（mock 社交登录）	社交登录演示

四、演示脚本（讲解现场 20 分钟版）

A. 官网全貌（3 min）

1. 打开 http://localhost:3000 → 展示 Hero / 模型卡 / 定价预览 / 邀请奖励区块
2. 9 语言切换：右上角语言下拉 → 依次切 Tiếng Việt / English / Bahasa Indonesia / ไทย / العربية
   • 关键点：ar-SA 页面整体 RTL（右侧开始排版）；每种语言价格显示本币（vi→₫ / id→Rp / ar→SAR）
3. 模型卡价格：USD 基准价 + 本币换算（稳定汇率）

B. 认证闭环（3 min）

1. 点「登入」→ 用 demo.user@dotouch.ai / User2026! 登录 → 自动跳转控制台

2. 演示注册流程（可选）：退出 → 注册 → 邮箱验证码（演示环境验证码打印在 API 日志）：

   docker logs demo-dotouch-api | grep -iE "code|mã|验证码" | tail -3
   

3. 社交登录（可选）：登录弹窗 → Google/Facebook 按钮 → mock 一键登录

C. 控制台（4 min）

1. 总览：余额（$150）/ 今日请求 / Token / 7 天用量
2. API Keys：创建 Key（dt_ 前缀，仅显示一次）→ 撤销/轮换演示
3. 用量限额：设置限额 → 触发 80% 预警横幅（q_banner_80 文案）
4. 钱包：充值（mock 支付直通）→ 余额变化 → 流水记录
5. 邀请奖励：复制邀请链接 → 展示规则（10% + $5 上限）

D. 调 API（3 min，核心亮点）

# 用控制台创建的 Key 调用（mock 上游即时响应）
curl -s http://localhost:8081/v1/chat/completions \
  -H "Authorization: Bearer <你的Key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4","messages":[{"role":"user","content":"你好"}]}'

• 演示流式："stream": true → 观察 SSE data: 块 + [DONE]
• 演示错误格式：错 Key → 401；余额不足 → 402（OpenAI 规范错误体）

E. 管理后台（3 min）

1. http://localhost:3000/admin → admin@dotouch.ai / Admin2026! 登录
2. 数据看板：订单 / 活跃用户 / 付费率 / 留存
3. 模型管理：236 全量目录
4. 邀请策略配置卡：奖励比例 / 上限（演示 SystemConfig 可配）

F. 关键机制讲解（4 min，配合代码）

1. 稳定汇率链路：apps/api/src/config/config.service.ts（SystemConfig → 7 币种）→ apps/web/src/components/FxPrice.tsx（本币主价）→ 管理后台汇率卡
2. 网关计费链路：gateway/（OpenAI 兼容 + SSE）→ wallet/（预扣-结算-退款）→ usage/（明细）
3. i18n 五件套：middleware.ts（9 locale 路由）→ src/i18n/request.ts → lib/seo.ts（LOCALES）→ [locale]/layout.tsx（RTL）→ LocaleSwitcher.tsx（下拉）
4. 演示环境拓扑：docker-compose.demo.yml（PG/Redis/mock 上游 19090）

五、常见问题（FAQ）

症状	原因与解法
官网 500 / API 连不上	初始化未完成：docker compose -f docker-compose.demo.yml ps 等 demo-dotouch-api Up 后再试
验证码找不到	演示环境邮件打印在容器日志：docker logs demo-dotouch-api \| grep -i code
端口被占用	改 docker-compose.demo.yml 端口映射（3000→3001 等）后 up -d
改了代码想更新	docker compose -f docker-compose.demo.yml up -d --build（镜像重建）
数据乱了想重置	down -v 后重新 up -d --build（自动重新 seed）
想调真实 DashScope	改 .env 的 DASHSCOPE_API_KEY，演示环境默认指向 mock 上游（零成本、可离线）

六、生产部署差异提醒

demo 与生产的差异：mock 上游 → DashScope 真实 Key；PAYMENT_PROVIDER=mock → momo/zalopay；演示数据 → 空库冷启动；本地端口 → 香港节点 + 域名/SSL。生产部署见 docs/team-tasks-v1.6.0.md T-03。