# Taro H5 三入口部署说明

更新时间：2026-06-29

当前 `apps/taro` 按一个 Taro 工程、三套 H5 产物组织：

- 学生学习端：刷题、背单词、知识手册、分数线、资料、会员和个人中心。
- 租户后台：品牌、域名、题库、导入、学生、订单、营销、销售和数据看板。
- 平台后台：租户、SaaS 套餐、订阅账单、公共题库授权和平台审计。

## 构建命令

```bash
npm run build:taro:h5:student
npm run build:taro:h5:tenant
npm run build:taro:h5:platform
```

输出目录：

```text
apps/taro/dist/h5-student
apps/taro/dist/h5-tenant-admin
apps/taro/dist/h5-platform-admin
```

推荐部署：

| 域名 | 目录 | 说明 |
| --- | --- | --- |
| `www.example.com` 或租户自有学生端域名 | `h5-student` | 面向学生和 C 端用户 |
| `admin.example.com` | `h5-tenant-admin` | 面向租户公司运营、教师、销售、代理、管理员 |
| `console.example.com` | `h5-platform-admin` | 面向平台超级管理员 |

三个入口可以放在同一台服务器的三个静态目录，也可以放到 CDN/对象存储静态网站。API 推荐独立域名，例如 `api.example.com`。

## 环境变量

构建时只允许注入：

```text
TARO_APP_PORTAL=student | tenant-admin | platform-admin
TARO_APP_API_BASE_URL=https://api.example.com
TARO_APP_SUPABASE_URL=https://<supabase-auth-host>
TARO_APP_SUPABASE_PUBLISHABLE_KEY=<publishable-key>
TARO_APP_TENANT_CODE=<可选，小程序或预览环境使用>
```

禁止进入前端构建：

```text
SUPABASE_SERVICE_ROLE_KEY
SUPABASE_SECRET_KEY
DATABASE_URL
ALIYUN_OSS_ACCESS_KEY_SECRET
TENCENT_COS_SECRET_KEY
WECHAT_PAY_PRIVATE_KEY
ALIPAY_APP_PRIVATE_KEY
AUTH_SESSION_SECRET
PLATFORM_ADMIN_API_KEY
```

`apps/taro/src/env.ts` 会在启动时检查这些危险变量，防止误把服务端密钥打包到前端。

## Nginx 建议

H5 使用 history 路由时，静态服务器需要把未知路径回退到 `index.html`。

```nginx
server {
  server_name www.example.com;
  root /www/tiku/h5-student;

  location / {
    try_files $uri $uri/ /index.html;
  }
}

server {
  server_name admin.example.com;
  root /www/tiku/h5-tenant-admin;

  location / {
    try_files $uri $uri/ /index.html;
  }
}

server {
  server_name console.example.com;
  root /www/tiku/h5-platform-admin;

  location / {
    try_files $uri $uri/ /index.html;
  }
}
```

API CORS 必须只允许实际域名，不允许生产环境 `CORS=*`。生产前运行：

```bash
npm run readiness:production
npm run readiness:production:db
```

## 前端请求边界

- 所有页面统一通过 `apps/taro/src/services/api.ts` 调用后端。
- H5 可以用 Supabase client 管理 Auth session，但业务数据默认走 `apps/api`。
- `x-tenant-id` 只是租户上下文，不是身份来源。
- 登录后禁止传 `x-user-id` 或 body/query `userId` 表示当前用户。
- 订单、支付、权益、内容导入、后台配置、CRM、对象存储签名、视频播放签名必须走后端命令层。

## 安全审计边界

H5 线上只发布 `apps/taro/dist/**` 静态文件，不要把 `apps/taro/node_modules` 或源码目录部署到 Web 根目录。后端/API/worker 的生产依赖审计使用：

```bash
npm run audit:runtime
```

Taro 4.2.0 当前构建工具链仍会触发 `npm run audit:taro:toolchain` 的上游 high/critical 告警，主要来自构建期 CLI、webpack、swiper、lodash-es 等传递依赖。不要使用 `npm audit fix --force` 将 Taro 降级到 3.x；应等 Taro 官方升级后再处理，或者后续评估 Vite runner 替代方案。上线时以静态产物、前端密钥检查、CORS 域名白名单和 API runtime audit 作为阻断项。

## 下一步页面顺序

1. 学生端：租户启动、登录、首页、题库入口、练习、错题、收藏。
2. 学生端：背单词、知识手册、分数线、资料、会员、个人中心。
3. 租户后台：数据看板、内容导航、题目录入/导入、学生管理、营销中心。
4. 平台后台：租户、套餐、账单、公共题库授权。
5. 小程序：验证 storage/fetch/Auth 兼容性，复用同一套 API client。