feat: 添加 H5 小程序嵌入式应用开发模板 v2 文档
This commit is contained in:
778
docs/development-standards-v2.md
Normal file
778
docs/development-standards-v2.md
Normal file
@@ -0,0 +1,778 @@
|
||||
# H5 小程序嵌入式应用开发模板 v2
|
||||
|
||||
> 适用于嵌入微信小程序 web-view 的 H5 应用
|
||||
> 技术栈：FastAPI + MongoDB (Beanie) + React 18 + React Router 7 + Vite 6
|
||||
> 认证：小程序传 openid → 后端调 CRMEB 接口获取用户信息 → 自动补齐昵称/头像
|
||||
>
|
||||
> **v2 变更要点（实战沉淀）**
|
||||
> 1. 前端资源改**相对路径**（Vite `base: './'`），适配二级目录与 web-view，避免白屏。
|
||||
> 2. Nginx 无斜杠跳转**保留 query**，避免 `?openid` 丢失导致登录失败。
|
||||
> 3. 二级目录三处一致规则细化（base / basename / API 前缀）。
|
||||
> 4. 新增：小程序 web-view 接入要点、MongoDB 部署注意、时区统一、后台管理 + 访问埋点。
|
||||
|
||||
---
|
||||
|
||||
## 一、项目架构
|
||||
|
||||
### 1.1 技术栈
|
||||
|
||||
| 层 | 技术 | 备注 |
|
||||
|---|------|------|
|
||||
| 前端 | React 18 + React Router 7 + Vite 6 | SPA，二级目录部署，资源相对路径 |
|
||||
| UI | TailwindCSS + 自研 SVG 图标（按需 MUI/shadcn）| 母婴等品牌建议自研图标，避免堆依赖 |
|
||||
| 状态 | React Context + localStorage 持久化 | 无 Redux/Zustand |
|
||||
| 后端 | FastAPI + Uvicorn（PM2 守护，`--interpreter none`）| |
|
||||
| 数据库 | MongoDB（Motor + Beanie ODM）| localhost 绑定 + 鉴权 |
|
||||
| 认证 | openid → 后端调 CRMEB 内部接口 | 无 JWT 签名验证 |
|
||||
|
||||
### 1.2 目录结构
|
||||
|
||||
```
|
||||
project/
|
||||
├── frontend/
|
||||
│ ├── src/app/
|
||||
│ │ ├── pages/ # 页面组件
|
||||
│ │ ├── components/ # 通用组件（含自研 icons.tsx）
|
||||
│ │ ├── context/ # React Context
|
||||
│ │ ├── hooks/ # 自定义 hook（可独立测试）
|
||||
│ │ ├── services/ # api / debug / analytics
|
||||
│ │ ├── data/ # 静态数据表
|
||||
│ │ ├── routes.tsx # 路由 + 埋点 RootTracker
|
||||
│ │ └── App.tsx
|
||||
│ ├── .env / .env.production # 环境变量（生产关闭 debug）
|
||||
│ └── dist/ # 构建产物
|
||||
├── backend/
|
||||
│ ├── app/
|
||||
│ │ ├── routers/ # auth/user/sessions/events/admin...
|
||||
│ │ ├── models/ # Beanie 数据模型
|
||||
│ │ ├── services/ # 业务逻辑 + jwt_util
|
||||
│ │ ├── middleware/ # 认证（get_current_user / get_admin）
|
||||
│ │ └── config.py
|
||||
│ ├── tests/ # pytest（建议测试占比高）
|
||||
│ ├── serv.sh / backup.sh
|
||||
│ └── .env
|
||||
├── deploy/
|
||||
│ ├── nginx-<app>.conf
|
||||
│ └── admin/index.html # 独立后台（单文件，无需构建）
|
||||
└── docs/
|
||||
```
|
||||
|
||||
### 1.3 多应用同域名 / 二级目录部署
|
||||
|
||||
```
|
||||
同一 Nginx 下多个 H5 应用，各自独立后端进程；前端按二级目录部署：
|
||||
|
||||
https://mp.example.com/
|
||||
├── /app_03/ → 前端 SPA（部署在二级目录 /app_03/）
|
||||
│ └── /app_03/api/ → proxy_pass 127.0.0.1:8030/api/
|
||||
├── /baby_food/ → /baby_food/api/ → 8031
|
||||
└── /admin/（可选） → 独立后台静态页
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、前端路径规范（v2 核心，务必遵守）
|
||||
|
||||
H5 会被微信小程序 web-view 以二级目录地址打开（如 `…/app_03/?openid=xxx`）。
|
||||
路径处理不当是 web-view **白屏**最常见原因。规则如下：
|
||||
|
||||
### 2.1 资源用相对路径（关键）
|
||||
|
||||
```ts
|
||||
// vite.config.ts
|
||||
export default defineConfig({
|
||||
base: "./", // ✅ 相对路径：资源按文档所在二级目录解析
|
||||
// ❌ 不要用绝对 base: "/app_03/"（小程序/代理环境下易解析错导致白屏）
|
||||
});
|
||||
```
|
||||
|
||||
- `base: './'` 后，构建出的 `index.html` 引用为 `./assets/xxx.js`，无论挂在哪个二级目录都能正确加载。
|
||||
- 单层路由（`/home`、`/count`）下，`./assets/` 从 `/app_03/home` 解析回 `/app_03/assets/`，正常。
|
||||
- 如有**多层路由**，需改用 HashRouter 或加 `<base href>`，否则深层路由刷新会算错相对基准。
|
||||
|
||||
### 2.2 二级目录三处一致
|
||||
|
||||
| 配置项 | 位置 | 值（以 app_03 为例）| 说明 |
|
||||
|--------|------|------|------|
|
||||
| Vite `base` | `vite.config.ts` | `'./'` | **相对**，不写死二级目录 |
|
||||
| Router `basename` | `routes.tsx` | `'/app_03'` | 路由仍按二级目录（路径里编码二级目录）|
|
||||
| `VITE_API_PREFIX` | `.env` | `'/app_03/api'` | 同源绝对路径，web-view 同源可用 |
|
||||
|
||||
> 资源相对、路由二级目录、API 同源绝对——三者配合：资源可移植，路由/接口仍锚定二级目录。
|
||||
|
||||
### 2.3 生产环境关闭调试
|
||||
|
||||
```ini
|
||||
# .env.production
|
||||
VITE_API_PREFIX=/app_03/api
|
||||
VITE_DEBUG=false # 生产关闭：避免无 openid 时自动 dev-login
|
||||
```
|
||||
|
||||
`npm run build` 默认加载 `.env.production`。
|
||||
|
||||
### 2.4 Vite dev proxy
|
||||
|
||||
```ts
|
||||
server: {
|
||||
proxy: {
|
||||
[apiPrefix]: { // "/app_03/api"
|
||||
target: "http://localhost:8030",
|
||||
changeOrigin: true,
|
||||
rewrite: (p) => p.replace(/^\/app_03\/api/, "/api"),
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、小程序 web-view 接入要点（v2 新增）
|
||||
|
||||
1. **业务域名白名单**：小程序后台「业务域名」必须加入本 H5 域名（需 HTTPS、需下载校验文件放服务器）。否则 web-view 直接打不开。
|
||||
2. **打开地址**：`https://mp.example.com/app_03/?openid=<openid>`，建议带尾斜杠。
|
||||
3. **跳转保留参数**：无斜杠地址 `…/app_03?openid=xxx` 经 nginx 301 时**必须保留 query**，否则 openid 丢失、登录失败：
|
||||
```nginx
|
||||
location = /app_03 { return 301 /app_03/$is_args$args; } # ✅ 保留 ?openid
|
||||
# ❌ return 301 /app_03/; 会丢掉 ?openid
|
||||
```
|
||||
4. **openid 读取**：用 BrowserRouter 时 `useSearchParams()` 能读到 `?openid`。若改 HashRouter，`?openid` 在 `#` 之前不会被 router 读到，需 `new URLSearchParams(window.location.search)` 直接取。
|
||||
5. **真机调试**：白屏先用 vConsole / 真机调试看是不是资源 404 或域名未白名单。
|
||||
|
||||
---
|
||||
|
||||
## 四、认证规范
|
||||
|
||||
### 4.1 流程
|
||||
|
||||
```
|
||||
小程序 web-view → /app_03/?openid=xxx
|
||||
→ LoginPage 读取 openid
|
||||
→ POST /app_03/api/auth/openid-login { openid }
|
||||
→ 后端 GET CRMEB /api/internal/user-info?openid=xxx (X-Internal-Key)
|
||||
→ { nickname, phone, avatar } → 建/更新 User
|
||||
→ 返回 token → setTokenAndUser → fetchProfile → 跳首页/引导页
|
||||
```
|
||||
|
||||
### 4.2 关键约定
|
||||
|
||||
- 中间件 `get_current_user`：解 token（`verify_signature=False`），手动验 `exp`，按 openid 查/建用户。
|
||||
- CRMEB 客户端**任何异常都优雅降级**（返回空昵称/头像，不阻断登录），并 `logger.warning` 记录，便于排查。
|
||||
- `DEV_MODE=1` 才启用 `POST /api/auth/dev-login`，生产必须为 `0`。
|
||||
- **CRMEB 匹配口径**：openid 按 appid 隔离。若 CRMEB 与小程序非同一 appid，应改用 **unionid** 匹配（小程序传 unionid，CRMEB 内部接口按 unionid 查；openid 仍作本系统主键）。
|
||||
|
||||
---
|
||||
|
||||
## 五、后端规范
|
||||
|
||||
### 5.1 路由注册
|
||||
|
||||
```python
|
||||
# routers/__init__.py
|
||||
router = APIRouter(prefix="/api")
|
||||
router.include_router(auth.router) # /api/auth/*
|
||||
router.include_router(user.router) # /api/user/*
|
||||
router.include_router(sessions.router) # /api/sessions/*
|
||||
router.include_router(events.router) # /api/events （埋点上报）
|
||||
router.include_router(admin.router) # /api/admin/* （后台）
|
||||
```
|
||||
|
||||
> 注意路由顺序：`/sessions/stats` 必须声明在 `/sessions/{id}` 之前，否则 `stats` 被当作 id。
|
||||
|
||||
### 5.2 配置（pydantic-settings）
|
||||
|
||||
```ini
|
||||
# .env
|
||||
MONGODB_URL=mongodb://user:pwd@127.0.0.1:27017/app_03?authSource=admin
|
||||
MONGODB_DB_NAME=app_03
|
||||
JWT_SECRET_KEY=...
|
||||
JWT_EXPIRE_DAYS=30
|
||||
CRMEB_BASE_URL=https://shop.example.com
|
||||
CRMEB_API_KEY=sk_...
|
||||
HOST=0.0.0.0
|
||||
PORT=8030
|
||||
DEV_MODE=0
|
||||
ADMIN_USER=admin
|
||||
ADMIN_PASS=<强密码> # 后台登录，生产务必改默认
|
||||
CORS_ORIGINS=https://mp.example.com # 生产收紧，勿用 *
|
||||
```
|
||||
|
||||
### 5.3 时区统一（v2 新增，重要）
|
||||
|
||||
- 数据库统一存 **UTC**（`datetime.now(timezone.utc)`）。
|
||||
- 一切「按天分组 / 今天 / 日期反推」统一按**目标时区**（国内=北京 UTC+8）换算，前后端一致：
|
||||
- 后端聚合按天：把 `created_at` `astimezone(UTC+8)` 再取 `.date()`。
|
||||
- 前端分组：`new Date(iso).toLocaleDateString('zh-CN')`（设备本地=北京）。
|
||||
- 由 UTC 存储反推业务日期时，先转北京再比较，避免凌晨跨日差一天。
|
||||
|
||||
### 5.4 数据模型
|
||||
|
||||
```python
|
||||
class User(Document):
|
||||
openid: str = Field(..., unique=True)
|
||||
name: str = ""
|
||||
phone: Optional[str] = None
|
||||
avatar_url: Optional[str] = None
|
||||
is_onboarded: bool = False
|
||||
created_at: datetime
|
||||
class Settings:
|
||||
name = "users"
|
||||
indexes = [IndexModel("openid", unique=True)]
|
||||
```
|
||||
|
||||
> 业务集合自定义；为常用查询建复合索引（如 `[(openid,1),(created_at,-1)]`）。
|
||||
|
||||
---
|
||||
|
||||
## 六、后台管理 + 访问埋点（v2 新增）
|
||||
|
||||
### 6.1 管理员鉴权
|
||||
|
||||
```python
|
||||
def build_admin_token(): # jwt {"admin": True, exp}
|
||||
def get_admin(credentials): # 校验 payload["admin"]，否则 401/403
|
||||
```
|
||||
|
||||
- `POST /api/admin/login {username,password}` 校验 `.env` 的 ADMIN_USER/PASS → 发 admin token。
|
||||
- 后台接口统一 `Depends(get_admin)`。
|
||||
|
||||
### 6.2 独立后台页
|
||||
|
||||
- **单文件静态页**（`deploy/admin/index.html`，纯 HTML+CSS+JS，无需构建），nginx 独立 location 服务：
|
||||
```nginx
|
||||
location /admin/ { alias /opt/<app>/admin/; try_files $uri $uri/ /admin/index.html; }
|
||||
```
|
||||
- 同域调 `/app_03/api/admin/*`，token 存 localStorage。
|
||||
|
||||
### 6.3 访问埋点
|
||||
|
||||
- 模型 `PageView { openid, visit_id, path, duration_ms, created_at }`。
|
||||
- 上报：`POST /api/events {visit_id, path, duration_ms}`（带用户 token）。
|
||||
- 前端 `RootTracker`（包裹路由）监听 `useLocation` 变化与 `visibilitychange`，上报上一页停留时长；`visit_id` 用 `sessionStorage`（一次打开=一次访问）。仅登录后、停留 >0.2s 才上报。
|
||||
- 后台聚合：按 openid 出「访问次数/总时长/最近活跃」，按 visit 还原「访问路径 + 每页时长」。
|
||||
|
||||
---
|
||||
|
||||
## 七、Nginx 配置模板（v2）
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name mp.example.com;
|
||||
location /.well-known/acme-challenge/ { root /opt/app_03/frontend/dist; }
|
||||
location / { return 301 https://$host$request_uri; }
|
||||
}
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name mp.example.com;
|
||||
ssl_certificate /etc/letsencrypt/live/mp.example.com/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/mp.example.com/privkey.pem;
|
||||
include /etc/letsencrypt/options-ssl-nginx.conf;
|
||||
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
|
||||
|
||||
# 独立后台（可选，放在 catch-all 之前）
|
||||
location /admin/ { alias /opt/app_03/admin/; try_files $uri $uri/ /admin/index.html; }
|
||||
|
||||
# 无斜杠跳转：保留 query（避免丢 openid）
|
||||
location = /app_03 { return 301 /app_03/$is_args$args; }
|
||||
|
||||
# 前端 SPA（相对资源 + history 回退）
|
||||
location /app_03/ {
|
||||
alias /opt/app_03/frontend/dist/;
|
||||
try_files $uri $uri/ /app_03/index.html;
|
||||
}
|
||||
|
||||
# API 代理（proxy_pass 带尾 /api/，前缀被替换）
|
||||
location /app_03/api/ {
|
||||
proxy_pass http://127.0.0.1:8030/api/;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 证书用 `certbot certonly --webroot -w <dist目录> -d <域名>` 现签（复用已有 ACME 账号，无需邮箱）。
|
||||
|
||||
---
|
||||
|
||||
## 八、MongoDB 部署注意（v2 新增）
|
||||
|
||||
国内服务器优先**原生安装**，比 Docker 拉镜像稳：
|
||||
|
||||
- Docker Hub / 常见镜像源拉 `mongo` 大层常**卡死/0 速**（验证：`docker pull` 长时间无进度）。若必须 Docker，确认有可用国内 registry-mirror 且能拉 blob。
|
||||
- **推荐原生 apt 装**（清华源稳）：
|
||||
```bash
|
||||
echo "deb [trusted=yes] https://mirrors.tuna.tsinghua.edu.cn/mongodb/apt/ubuntu <codename>/mongodb-org/8.0 multiverse" \
|
||||
> /etc/apt/sources.list.d/mongodb-org-8.0.list
|
||||
apt-get update && apt-get install -y mongodb-org # 注意 codename 与版本匹配（如 noble→8.0）
|
||||
```
|
||||
- **安全基线**：`bindIp: 127.0.0.1`（仅本地）+ `security.authorization: enabled`，建 root 用户；连接串带 `?authSource=admin`。
|
||||
- **每日备份**：`mongodump --gzip --archive` + cron，保留最近 N 份。
|
||||
|
||||
---
|
||||
|
||||
## 九、部署与运维
|
||||
|
||||
- 后端 PM2：`pm2 start .venv/bin/uvicorn --name <app> --interpreter none --cwd <backend> -- app.main:app --host 127.0.0.1 --port <port>`（`--interpreter none` 让 PM2 用 Python shebang，否则会当 Node 跑报错）；`pm2 save` 持久化。
|
||||
- 后端绑 `127.0.0.1`，由 nginx 反代，不对公网直接暴露端口。
|
||||
- pip 用阿里源加速：`pip install -i https://mirrors.aliyun.com/pypi/simple/ -r requirements.txt`。
|
||||
- 前端：`npm run build` → `rsync dist/` 到 `/opt/<app>/frontend/dist/`（nginx 直接服务静态，无需 reload）。
|
||||
|
||||
---
|
||||
|
||||
## 十、新建应用 Checklist（v2）
|
||||
|
||||
- [ ] 项目标识 snake_case；二级目录三处一致：Vite `base:'./'` / Router `basename:'/xxx'` / `VITE_API_PREFIX:'/xxx/api'`
|
||||
- [ ] 生产 `.env.production` 设 `VITE_DEBUG=false`
|
||||
- [ ] 后端 `.env`：MongoDB(带 authSource) / JWT / CRMEB / `DEV_MODE=0` / `ADMIN_PASS` 改默认 / `CORS_ORIGINS` 收紧
|
||||
- [ ] 全站时区：UTC 存储 + 北京(UTC+8)分组/反推，前后端一致
|
||||
- [ ] Nginx：`location = /xxx` 跳转**保留 query**；`/xxx/` 相对资源 + try_files；`/xxx/api/` 代理；（可选）`/admin/`
|
||||
- [ ] MongoDB：原生安装 + localhost + 鉴权 + 每日备份 cron
|
||||
- [ ] PM2 `--interpreter none` 启动后端 + `pm2 save`
|
||||
- [ ] 小程序：业务域名白名单 + HTTPS + `/xxx/?openid=` 打开
|
||||
- [ ] 后台 `/admin/` 可登录；前端埋点上报通；CRMEB openid/unionid 口径确认
|
||||
- [ ] 真机 web-view 实测打开（带/不带斜杠都不丢 openid）
|
||||
|
||||
---
|
||||
|
||||
## 十一、从零起一个新应用 · 命令级 step-by-step
|
||||
|
||||
下面以新应用 `app_03`、端口 `8030`、域名 `mp.example.com`、二级目录 `/app_03/` 为例。
|
||||
先定义变量（本地和服务器都可复用）：
|
||||
|
||||
```bash
|
||||
APP=app_03 # 应用标识（全小写 snake_case）
|
||||
PORT=8030 # 后端端口（确认未占用）
|
||||
DOMAIN=mp.example.com # 访问域名（已解析、能签 HTTPS）
|
||||
DBNAME=$APP # Mongo 库名
|
||||
SERVER=root@1.2.3.4 # 目标服务器
|
||||
```
|
||||
|
||||
### 0. 本地建仓
|
||||
|
||||
```bash
|
||||
mkdir -p ~/work/$APP && cd ~/work/$APP
|
||||
git init -b main
|
||||
printf "node_modules/\ndist/\n__pycache__/\n*.pyc\n.env\n.venv/\ntsconfig.tsbuildinfo\n" > .gitignore
|
||||
mkdir -p backend/app/{routers,models,services,middleware} backend/tests frontend deploy/admin docs
|
||||
```
|
||||
|
||||
### 1. 后端骨架
|
||||
|
||||
```bash
|
||||
cd ~/work/$APP/backend
|
||||
cat > requirements.txt <<'EOF'
|
||||
fastapi==0.115.*
|
||||
uvicorn[standard]==0.32.*
|
||||
motor==3.6.*
|
||||
beanie==1.27.*
|
||||
pydantic-settings==2.6.*
|
||||
PyJWT==2.10.*
|
||||
httpx==0.27.*
|
||||
pytest==8.3.*
|
||||
pytest-asyncio==0.24.*
|
||||
mongomock-motor==0.0.34
|
||||
EOF
|
||||
|
||||
python3 -m venv .venv && . .venv/bin/activate
|
||||
pip install -i https://mirrors.aliyun.com/pypi/simple/ -r requirements.txt
|
||||
printf "[pytest]\nasyncio_mode = auto\npythonpath = .\n" > pytest.ini
|
||||
|
||||
# .env（按需改密钥）
|
||||
cat > .env <<EOF
|
||||
MONGODB_URL=mongodb://127.0.0.1:27017
|
||||
MONGODB_DB_NAME=${DBNAME}_dev
|
||||
JWT_SECRET_KEY=$(openssl rand -hex 32)
|
||||
JWT_EXPIRE_DAYS=30
|
||||
CRMEB_BASE_URL=https://shop.example.com
|
||||
CRMEB_API_KEY=sk_change_me
|
||||
HOST=0.0.0.0
|
||||
PORT=${PORT}
|
||||
DEV_MODE=1
|
||||
ADMIN_USER=admin
|
||||
ADMIN_PASS=admin888
|
||||
CORS_ORIGINS=*
|
||||
EOF
|
||||
```
|
||||
|
||||
> 然后按第二~六节写 `config.py / db.py / models / routers / main.py`（可直接复制模板应用改标识）。
|
||||
> 最小可跑：`main.py` 注册 `router`，`GET /api/health` 返回 `{"status":"ok"}`。
|
||||
|
||||
本地起后端（开发）：
|
||||
|
||||
```bash
|
||||
DEV_MODE=1 .venv/bin/uvicorn app.main:app --host 0.0.0.0 --port $PORT --reload
|
||||
# 另开终端验证
|
||||
curl -s localhost:$PORT/api/health # {"status":"ok"}
|
||||
pytest -q # 跑测试
|
||||
```
|
||||
|
||||
### 2. 前端骨架
|
||||
|
||||
```bash
|
||||
cd ~/work/$APP/frontend
|
||||
npm create vite@latest . -- --template react-ts # 或手动建
|
||||
npm i react-router-dom framer-motion recharts
|
||||
npm i -D tailwindcss@3 postcss autoprefixer jsdom @testing-library/react vitest
|
||||
npx tailwindcss init -p
|
||||
```
|
||||
|
||||
关键配置（三处一致 + 相对资源）：
|
||||
|
||||
```bash
|
||||
# vite.config.ts: base: "./"，dev proxy 见第 2.4 节
|
||||
# routes.tsx: createBrowserRouter([...], { basename: "/app_03" })
|
||||
# .env
|
||||
printf "VITE_API_PREFIX=/app_03/api\nVITE_DEBUG=true\n" > .env
|
||||
# .env.production（生产关调试）
|
||||
printf "VITE_API_PREFIX=/app_03/api\nVITE_DEBUG=false\n" > .env.production
|
||||
```
|
||||
|
||||
本地开发 / 构建：
|
||||
|
||||
```bash
|
||||
npm run dev # 代理到后端 $PORT
|
||||
npm run build # 产出 dist/（资源为 ./assets/...）
|
||||
grep assets dist/index.html # 确认是 ./assets（相对）
|
||||
```
|
||||
|
||||
### 3. 服务器：MongoDB（原生，首次装一次）
|
||||
|
||||
```bash
|
||||
ssh $SERVER
|
||||
CODENAME=$(. /etc/os-release; echo $VERSION_CODENAME) # 如 noble
|
||||
echo "deb [trusted=yes] https://mirrors.tuna.tsinghua.edu.cn/mongodb/apt/ubuntu $CODENAME/mongodb-org/8.0 multiverse" \
|
||||
> /etc/apt/sources.list.d/mongodb-org-8.0.list
|
||||
apt-get update && apt-get install -y mongodb-org
|
||||
systemctl enable --now mongod
|
||||
|
||||
# 建用户 + 开鉴权
|
||||
MPWD=$(openssl rand -hex 24); echo "MONGO_PWD=$MPWD" # 记下来
|
||||
mongosh --quiet --eval "db.getSiblingDB('admin').createUser({user:'$APP',pwd:'$MPWD',roles:[{role:'root',db:'admin'}]})"
|
||||
grep -q 'authorization: enabled' /etc/mongod.conf || printf '\nsecurity:\n authorization: enabled\n' >> /etc/mongod.conf
|
||||
systemctl restart mongod
|
||||
```
|
||||
|
||||
### 4. 部署代码到服务器
|
||||
|
||||
```bash
|
||||
# 本地：同步代码 + 构建产物
|
||||
cd ~/work/$APP
|
||||
rsync -az --exclude node_modules --exclude .venv --exclude __pycache__ --exclude dist \
|
||||
backend deploy docs $SERVER:/opt/$APP/
|
||||
rsync -az --delete frontend/dist/ $SERVER:/opt/$APP/frontend/dist/
|
||||
|
||||
# 服务器：建 venv + 写生产 .env（MONGODB_URL 用上一步的 MPWD）
|
||||
ssh $SERVER bash -lc "
|
||||
cd /opt/$APP/backend && python3 -m venv .venv &&
|
||||
.venv/bin/pip install -i https://mirrors.aliyun.com/pypi/simple/ -r requirements.txt &&
|
||||
sed -i 's#^MONGODB_URL=.*#MONGODB_URL=mongodb://$APP:<MPWD>@127.0.0.1:27017/$DBNAME?authSource=admin#;
|
||||
s#^MONGODB_DB_NAME=.*#MONGODB_DB_NAME=$DBNAME#;
|
||||
s#^DEV_MODE=.*#DEV_MODE=0#;
|
||||
s#^CORS_ORIGINS=.*#CORS_ORIGINS=https://$DOMAIN#' .env
|
||||
"
|
||||
```
|
||||
|
||||
### 5. 服务器：PM2 起后端
|
||||
|
||||
```bash
|
||||
ssh $SERVER bash -lc "
|
||||
cd /opt/$APP/backend &&
|
||||
pm2 start .venv/bin/uvicorn --name $APP --interpreter none --cwd /opt/$APP/backend -- app.main:app --host 127.0.0.1 --port $PORT &&
|
||||
pm2 save &&
|
||||
sleep 3 && curl -s localhost:$PORT/api/health
|
||||
"
|
||||
```
|
||||
|
||||
> `--interpreter none` 必加，否则 PM2 当 Node 跑 uvicorn 会报 ESM 错。
|
||||
|
||||
### 6. 服务器：Nginx + HTTPS
|
||||
|
||||
```bash
|
||||
ssh $SERVER bash -lc "
|
||||
# 先放一个 HTTP server 块（含 acme 与 /$APP/）做证书校验，再签证书
|
||||
certbot certonly --webroot -w /opt/$APP/frontend/dist -d $DOMAIN --non-interactive --agree-tos --keep-until-expiring
|
||||
"
|
||||
# 然后写第七节的完整 vhost（含 location = /$APP 保留 query、/$APP/ 相对资源、/$APP/api/ 代理、可选 /admin/）
|
||||
ssh $SERVER bash -lc "ln -sf /etc/nginx/sites-available/$APP /etc/nginx/sites-enabled/$APP && nginx -t && systemctl reload nginx"
|
||||
```
|
||||
|
||||
### 7. 小程序接入
|
||||
|
||||
- 小程序后台「业务域名」加入 `https://$DOMAIN`（下载校验文件放到 dist 根，nginx 可访问）。
|
||||
- web-view 打开：`https://$DOMAIN/$APP/?openid=<openid>`。
|
||||
|
||||
### 8. 上线验证（一键自检）
|
||||
|
||||
```bash
|
||||
B=https://$DOMAIN
|
||||
curl -s -o /dev/null -w "http跳转: %{http_code}\n" http://$DOMAIN/$APP/
|
||||
curl -s -o /dev/null -w "首页: %{http_code}\n" $B/$APP/
|
||||
curl -s $B/$APP/ | grep -o './assets/[^"]*\.js' | head -1 # 相对资源
|
||||
curl -s -I "$B/$APP?openid=t1" | grep -i location # 应保留 ?openid=t1
|
||||
curl -s $B/$APP/api/health # {"status":"ok"}
|
||||
# 走一遍登录
|
||||
TOK=$(curl -s -X POST $B/$APP/api/auth/openid-login -H 'Content-Type: application/json' -d '{"openid":"t1"}' | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")
|
||||
curl -s $B/$APP/api/user/profile -H "Authorization: Bearer $TOK"
|
||||
```
|
||||
|
||||
### 9. 每日备份 cron（可选但推荐）
|
||||
|
||||
```bash
|
||||
ssh $SERVER bash -lc "
|
||||
cat > /opt/$APP/backup.sh <<'EOS'
|
||||
#!/usr/bin/env bash
|
||||
set -e; TS=\$(date +%Y%m%d-%H%M); OUT=/opt/$APP/backups; mkdir -p \$OUT
|
||||
mongodump --uri='mongodb://$APP:<MPWD>@127.0.0.1:27017/$DBNAME?authSource=admin' --gzip --archive=\"\$OUT/$APP-\$TS.gz\"
|
||||
ls -1t \$OUT/$APP-*.gz | tail -n +15 | xargs -r rm -f
|
||||
EOS
|
||||
chmod +x /opt/$APP/backup.sh
|
||||
( crontab -l 2>/dev/null | grep -v $APP/backup.sh; echo '30 3 * * * /opt/$APP/backup.sh >> /var/log/$APP-backup.log 2>&1' ) | crontab -
|
||||
"
|
||||
```
|
||||
|
||||
### 日常更新（改完代码再次发布）
|
||||
|
||||
```bash
|
||||
# 后端改动
|
||||
rsync -az --exclude __pycache__ backend/app $SERVER:/opt/$APP/backend/
|
||||
ssh $SERVER "pm2 restart $APP"
|
||||
# 前端改动
|
||||
npm run build && rsync -az --delete frontend/dist/ $SERVER:/opt/$APP/frontend/dist/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十二、WebView Bridge：分享 & 复制链接（v2 新增）
|
||||
|
||||
H5 页面在微信小程序 `<web-view>` 中运行，无法直接调用微信原生分享 API 或系统剪贴板。
|
||||
需通过 **Mini Program Bridge** 模式实现：H5 发 `postMessage` → 小程序 `@message` 事件监听 → 小程序调用原生 API。
|
||||
|
||||
### 12.1 架构图
|
||||
|
||||
```
|
||||
H5 (React SPA) 小程序 (uni-app web-view) 微信原生
|
||||
┌─────────────────┐ ┌────────────────────┐ ┌─────────┐
|
||||
│ 用户点"分享好友" │ │ │ │ │
|
||||
│ bridge.share() │──postMessage────→│ @message │──调用──→ │ 分享面板 │
|
||||
│ wx.miniProgram │ │ handleMessage() │ │ │
|
||||
│ .postMessage() │ │ uni.share() │ └─────────┘
|
||||
│ │ │ │ ┌─────────┐
|
||||
│ 用户点"复制链接" │──postMessage────→│ @message │──调用──→ │ 剪贴板 │
|
||||
│ bridge.copyLink()│ │ handleMessage() │ │ │
|
||||
│ │ │ uni.setClipboard() │ └─────────┘
|
||||
└─────────────────┘ └────────────────────┘
|
||||
```
|
||||
|
||||
### 12.2 小程序侧：web-view 组件配置
|
||||
|
||||
在 `<web-view>` 上声明 `@message` 事件监听：
|
||||
|
||||
```html
|
||||
<web-view :src="url" @message="handleMessage"></web-view>
|
||||
```
|
||||
|
||||
实现 `handleMessage` 方法（uni-app / Vue 2 语法）：
|
||||
|
||||
```javascript
|
||||
handleMessage(e) {
|
||||
const data = e.detail && e.detail.data ? e.detail.data[0] : null
|
||||
if (!data) return
|
||||
|
||||
switch (data.action) {
|
||||
case 'share':
|
||||
uni.share({
|
||||
provider: 'weixin',
|
||||
scene: data.scene || 'WXSceneSession',
|
||||
type: data.type || 0,
|
||||
title: data.title || '',
|
||||
href: data.href || this.url,
|
||||
imageUrl: data.imageUrl || '',
|
||||
summary: data.summary || '',
|
||||
})
|
||||
break
|
||||
|
||||
case 'copyLink':
|
||||
uni.setClipboardData({
|
||||
data: data.href || this.url,
|
||||
success() { uni.showToast({ title: '链接已复制', icon: 'success' }) },
|
||||
fail(err) { console.warn('[webview] 复制失败:', err) }
|
||||
})
|
||||
break
|
||||
|
||||
case 'setTitle':
|
||||
if (data.title) uni.setNavigationBarTitle({ title: data.title })
|
||||
break
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 12.3 小程序侧：原生"..."菜单分享
|
||||
|
||||
web-view 页面的右上角"..."菜单默认显示"转发/分享"为灰色不可点。
|
||||
需要实现以下两个生命周期钩子使其可用：
|
||||
|
||||
```javascript
|
||||
// 在 onLoad 中主动显示分享菜单
|
||||
onLoad(option) {
|
||||
// #ifdef MP
|
||||
uni.showShareMenu({
|
||||
menus: ['shareAppMessage', 'shareTimeline']
|
||||
});
|
||||
// #endif
|
||||
}
|
||||
|
||||
// 处理转发给朋友
|
||||
onShareAppMessage() {
|
||||
return {
|
||||
title: '页面标题',
|
||||
path: '/pages/web-view-path?url=' + encodeURIComponent(this.url),
|
||||
}
|
||||
}
|
||||
|
||||
// 处理分享到朋友圈（微信限制：web-view 不支持，此钩子不会被触发）
|
||||
onShareTimeline() {
|
||||
return {
|
||||
title: '页面标题',
|
||||
query: 'url=' + encodeURIComponent(this.url)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **已知限制**：`onShareTimeline`（分享到朋友圈）在 `<web-view>` 页面中**不支持**，微信 SDK 将其永久灰化。
|
||||
> 替代方案：使用「生成分享图片 → 保存到相册 → 手动发朋友圈」。
|
||||
|
||||
### 12.4 H5 侧：bridge.ts 工具
|
||||
|
||||
在新应用的 `src/app/services/` 下创建 `bridge.ts`：
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* 小程序 WebView 桥接工具
|
||||
*/
|
||||
declare const wx: any
|
||||
|
||||
function getMiniProgram() {
|
||||
try {
|
||||
if (typeof wx !== 'undefined' && wx.miniProgram) {
|
||||
return wx.miniProgram
|
||||
}
|
||||
} catch { /* ignore */ }
|
||||
return null
|
||||
}
|
||||
|
||||
const bridge = {
|
||||
postMessage(data: Record<string, any>) {
|
||||
const mp = getMiniProgram()
|
||||
if (mp) {
|
||||
mp.postMessage({ data })
|
||||
} else {
|
||||
console.warn('[bridge] 不在小程序 web-view 环境中')
|
||||
}
|
||||
},
|
||||
|
||||
/** 分享给微信好友 / 朋友圈 */
|
||||
share(opts: {
|
||||
title: string
|
||||
href?: string
|
||||
summary?: string
|
||||
imageUrl?: string
|
||||
scene?: 'WXSceneSession' | 'WXSceneTimeline'
|
||||
}) {
|
||||
this.postMessage({
|
||||
action: 'share',
|
||||
title: opts.title || '',
|
||||
href: opts.href || window.location.href,
|
||||
summary: opts.summary || '',
|
||||
imageUrl: opts.imageUrl || '',
|
||||
scene: opts.scene || 'WXSceneSession',
|
||||
})
|
||||
},
|
||||
|
||||
/** 复制链接到剪贴板（通过 bridge 兜底） */
|
||||
copyLink(link?: string) {
|
||||
this.postMessage({
|
||||
action: 'copyLink',
|
||||
href: link || window.location.href,
|
||||
})
|
||||
},
|
||||
|
||||
/** 设置小程序导航栏标题 */
|
||||
setTitle(title: string) {
|
||||
if (!title) return
|
||||
this.postMessage({ action: 'setTitle', title })
|
||||
},
|
||||
}
|
||||
|
||||
export default bridge
|
||||
```
|
||||
|
||||
### 12.5 H5 侧：复制链接的正确方案
|
||||
|
||||
微信 web-view 中 `navigator.clipboard.writeText()` **不支持**，
|
||||
需用 `document.execCommand('copy')` 作为主方案，bridge `postMessage` 作为兜底：
|
||||
|
||||
```typescript
|
||||
async function handleCopyLink(url: string) {
|
||||
let copied = false
|
||||
const textArea = document.createElement('textarea')
|
||||
textArea.value = url
|
||||
textArea.style.position = 'fixed'
|
||||
textArea.style.left = '-999999px'
|
||||
textArea.style.top = '-999999px'
|
||||
textArea.style.opacity = '0'
|
||||
document.body.appendChild(textArea)
|
||||
textArea.focus()
|
||||
textArea.select()
|
||||
|
||||
try {
|
||||
copied = document.execCommand('copy')
|
||||
} catch (e) {
|
||||
console.warn('[copy] execCommand failed:', e)
|
||||
}
|
||||
document.body.removeChild(textArea)
|
||||
|
||||
if (copied) {
|
||||
setLinkCopied(true)
|
||||
setTimeout(() => setLinkCopied(false), 2000)
|
||||
} else {
|
||||
// 兜底：通过 bridge postMessage（消息在页面离开时才触发）
|
||||
bridge.copyLink(url)
|
||||
// 乐观提示用户
|
||||
setLinkCopied(true)
|
||||
setTimeout(() => setLinkCopied(false), 2000)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 12.6 postMessage 时序限制
|
||||
|
||||
| 问题 | 说明 |
|
||||
|------|------|
|
||||
| `wx.miniProgram.postMessage()` 消息不会立即送达 | 仅在**页面跳转/导航离开**时才会触发小程序的 `@message` 事件 |
|
||||
| 不适合"立即复制"场景 | 点完按钮希望"立即复制到剪贴板"时，postMessage 无法实时响应 |
|
||||
| **最终方案** | `execCommand('copy')` 做实时复制（主方案），postMessage 做兜底（用户离开页面时最终确认） |
|
||||
|
||||
### 12.7 微信 web-view 分享限制
|
||||
|
||||
| 分享方式 | 支持 | 备注 |
|
||||
|---------|:----:|------|
|
||||
| 转发给朋友（"..."菜单） | ✅ | 需实现 `onShareAppMessage` + `uni.showShareMenu()` |
|
||||
| 分享到朋友圈（"..."菜单） | ❌ | **微信平台限制**，所有 web-view 页面均不支持 |
|
||||
| H5 内部"分享给好友"按钮 | ✅ | 通过 `bridge.share()` → postMessage → `uni.share()` |
|
||||
| H5 内部复制链接 | ✅ | `document.execCommand('copy')` 主方案 + bridge 兜底 |
|
||||
| 生成分享图→存相册→手动发圈 | ✅ | 替代方案，需 `html-to-image` 等截图库 |
|
||||
|
||||
---
|
||||
|
||||
## 十三、新建应用 Checklist 补充（v2）
|
||||
|
||||
在原有 Checklist（第十节）基础上增加以下项：
|
||||
|
||||
- [ ] WebView Bridge: 小程序 web-view 加 `@message` + `handleMessage` 方法
|
||||
- [ ] WebView Bridge: 实现 `onShareAppMessage()` + `uni.showShareMenu()` 启用原生"..."分享
|
||||
- [ ] WebView Bridge: H5 端创建 `src/app/services/bridge.ts` 桥接工具
|
||||
- [ ] WebView Bridge: H5 复制链接优先用 `document.execCommand('copy')`，bridge 兜底
|
||||
- [ ] WebView Bridge: 确认微信 JS-SDK 已加载（`jweixin-1.2.0.js`），否则 `wx.miniProgram` 不可用
|
||||
- [ ] WebView Bridge: 生成分享图片场景使用 `html-to-image` 等截图库
|
||||
Reference in New Issue
Block a user