forked from wangziqi/gongxue-base
130 lines
4.1 KiB
Markdown
130 lines
4.1 KiB
Markdown
# 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。
|