jw-beauty/docs/dev/04-部署指南.md

部署指南

本文档面向将 jw-beauty 项目部署到腾讯云生产环境的运维人员。

---

1. 部署架构

┌─────────────┐      HTTPS       ┌──────────────────┐
│  微信小程序  │ ───────────────► │  SCF HTTP 函数    │
└─────────────┘                  │  jw-beauty-api   │
                                 │  (Node.js 18)    │
┌─────────────┐      HTTPS       │                  │      VPC 内网      ┌──────────────┐
│  管理后台H5  │ ──► COS/CDN     │  scf_bootstrap   │ ──────────────────► │ TencentDB    │
│  (UniApp)   │                  │  → local-server  │                    │ MySQL 5.7+   │
└─────────────┘                  └──────────────────┘                    └──────────────┘
                                        │
                                        │ COS SDK
                                        ▼
                                 ┌──────────────────┐
                                 │  COS Bucket      │
                                 │  头像/固件/后台H5 │
                                 └──────────────────┘

组件	服务	说明
后端 API	腾讯云 SCF (HTTP 函数)	Express 应用，通过 scf_bootstrap 启动
数据库	TencentDB for MySQL	同 VPC 内网连接，端口 3306
对象存储	COS	存放头像、固件包、管理后台静态文件
API 域名	api.vsai.net.cn	指向 SCF 函数 URL / API 网关
CDN 域名	tx.vsai.net.cn	COS 自定义域名，用于头像和固件下载
小程序	微信小程序	通过微信开发者工具上传并提审

---

2. 后端部署（SCF）

2.1 打包

部署包以 server/ 为根目录打包，包含以下文件和目录：

index.js              # SCF 入口 (exports.main_handler)
package.json
package-lock.json
scf_bootstrap         # HTTP 函数启动脚本
scripts/              # local-server.js 等
src/                  # 应用源码
sql/                  # schema.sql
node_modules/         # 依赖

不要 把 .env 文件打进部署包。

打包命令：

cd server
npm install --production
rm -f /tmp/hox-http-function.zip
zip -qry /tmp/hox-http-function.zip \
  index.js package.json package-lock.json \
  scripts scf_bootstrap src sql node_modules

2.2 scf_bootstrap 配置

当前使用 HTTP 函数模式，scf_bootstrap 内容：

#!/bin/bash
set -e
export PORT=9000
node scripts/local-server.js

scf_bootstrap 必须有可执行权限。SCF 平台会直接运行此文件启动 HTTP 服务，监听 PORT 端口。

备注：index.js 中的 main_handler 是事件函数入口，目前未使用。如果切换到事件函数触发模式，SCF 入口改为 index.main_handler。

2.3 环境变量设置

在 SCF 控制台的函数配置中添加以下环境变量：

变量名	必填	说明
NODE_ENV	是	必须设为 production
PORT	否	默认 9000，scf_bootstrap 已设置
TENCENT_SECRET_ID	是	腾讯云 API 密钥 ID（COS 签名用）
TENCENT_SECRET_KEY	是	腾讯云 API 密钥 Key
TENCENT_REGION	否	默认 ap-guangzhou
DB_HOST	是	数据库内网地址
DB_PORT	否	默认 3306
DB_USER	是	数据库用户名
DB_PASSWORD	是	数据库密码
DB_NAME	否	默认 jw_beauty
COS_BUCKET	否	默认 jw-bucket-1426323813
COS_REGION	否	默认 ap-guangzhou
COS_CDN_DOMAIN	否	默认 tx.vsai.net.cn
WECHAT_APPID	是	微信小程序 AppID
WECHAT_SECRET	是	微信小程序 AppSecret
JWT_SECRET	是	用户 JWT 签名密钥（随机长字符串）
ADMIN_JWT_SECRET	是	管理员 JWT 签名密钥（随机长字符串）
ADMIN_USERNAME	是	初始管理员用户名（不要用默认 admin）
ADMIN_PASSWORD	是	初始管理员密码（不要用默认 admin）

生产环境安全检查：代码在 NODE_ENV=production 时会校验 JWT_SECRET 和 ADMIN_JWT_SECRET 不是默认值，ADMIN_USERNAME / ADMIN_PASSWORD 不是 admin/admin，否则启动报错。

参考模板文件：server/.env.production.example

2.4 VPC 网络配置

SCF 函数必须配置与 TencentDB 相同的 VPC 和子网，才能通过内网地址访问数据库。

操作步骤：

1. 在 SCF 控制台 → 函数管理 → 选择函数 → 函数配置 → 网络配置
2. 选择与 TencentDB 实例相同的 VPC 和子网
3. 确认安全组允许 SCF 访问数据库端口（默认 3306）

2.5 注意事项

• 冷启动：SCF 冷启动时需加载 Node.js 运行时和 node_modules，首次请求延迟较高（约 1-3 秒）。可配置预置并发实例减少冷启动。
• 超时设置：建议函数超时设为 30 秒以上。
• 内存：建议 256MB 或以上。
• 日志：错误日志通过 console.error 输出，可在 SCF 日志服务中查看。

---

3. 数据库初始化

3.1 连接 TencentDB

本地连接 TencentDB 需要：

• 数据库已开启公网访问，或通过 VPN/跳板机连接内网
• 安全组白名单中已添加本机公网 IP
• DB_PORT 使用控制台显示的公网端口

在 server/.env 中配置连接信息后执行：

cd server
npm install
npm run db:init

3.2 执行 schema.sql

db:init 脚本会自动执行 sql/schema.sql，创建以下业务表：

表名	说明
users	用户信息
devices	设备（产品码）
bindings	用户-设备绑定关系
subscriptions	订阅记录
treatment_records	护理记录
device_events	设备事件
device_commands	远程指令队列
operation_logs	操作日志
admin_accounts	管理员账户
system_settings	系统设置
firmware_files	固件版本

同时写入默认系统设置（月卡价格、年卡价格、试用天数等）。

3.3 初始管理员创建

db:init 会使用环境变量 ADMIN_USERNAME / ADMIN_PASSWORD 创建初始管理员账户。

首次登录后应立即在管理后台修改默认密码。

---

4. 管理后台部署（COS）

4.1 构建

确认 admin-console/src/config/env.js 中 ENV 已设为 prod（或 API 地址正确）：

const ENV = 'prod'

然后构建：

cd admin-console
npm install
npm run build:h5

构建产物位于 admin-console/dist/build/h5/。

4.2 上传到 COS

方式一：使用部署脚本（推荐）

cd admin-console
npm run deploy:cos

脚本会读取 server/.env 中的 COS 凭证，将构建产物上传到 COS bucket 的 admin/ 前缀下。

可通过环境变量自定义前缀：

ADMIN_COS_PREFIX=admin-test/ npm run deploy:cos

方式二：手动上传

通过 COS 控制台或 COSCMD 工具将 dist/build/h5/ 目录下所有文件上传到 bucket 的 admin/ 目录。

4.3 CDN/域名配置

管理后台通过 COS 的自定义域名（tx.vsai.net.cn）访问：

• 在 COS 控制台为 bucket 绑定自定义域名
• 配置 CDN 加速（可选）
• 访问地址：https://tx.vsai.net.cn/admin/

4.4 base path 设置

管理后台的路由 base path 为 /admin/，确保 COS 上传前缀与此一致。

如果需要配置单页应用（SPA）的 history 模式回退，可在 COS 静态网站配置中设置错误文档为 /admin/index.html。

---

5. 小程序发布

5.1 环境切换

发布前将 miniprogram/config/env.js 中的 ENV 改为 prod：

var ENV = 'prod'

5.2 微信开发者工具上传

1. 打开微信开发者工具
2. 导入项目目录 miniprogram/
3. 确认 AppID 正确
4. 点击"上传"，填写版本号和备注
5. 在微信公众平台 → 版本管理 → 提交审核

5.3 审核注意事项

• 用户协议 和 隐私政策 页面必须存在且内容完整，否则审核不通过
• 涉及蓝牙权限的小程序需要在 app.json 中声明并说明用途
• 隐私信息收集弹窗需符合微信规范
• 建议提交审核前在体验版充分测试

---

6. 域名和证书

6.1 API 域名

域名	用途	指向
api.vsai.net.cn	后端 API	SCF 函数 URL / API 网关

需要配置 HTTPS 证书（腾讯云可申请免费 SSL 证书）。

6.2 COS CDN 域名

域名	用途	指向
tx.vsai.net.cn	头像/固件下载/管理后台	COS bucket CDN

在 COS 控制台绑定自定义域名并配置 HTTPS。

6.3 小程序合法域名配置

在微信公众平台 → 开发管理 → 开发设置 → 服务器域名中配置：

类型	域名
request 合法域名	https://api.vsai.net.cn
downloadFile 合法域名	https://tx.vsai.net.cn
uploadFile 合法域名	https://api.vsai.net.cn

---

7. 上线检查清单

环境配置

• NODE_ENV=production 已设置
• JWT_SECRET 和 ADMIN_JWT_SECRET 已更换为强随机字符串
• ADMIN_USERNAME / ADMIN_PASSWORD 已更换默认值
• 数据库连接使用 VPC 内网地址
• 安全组规则正确（SCF → MySQL 3306）
• COS 凭证配置正确

数据库

• schema.sql 已执行成功，所有表已创建
• 初始管理员已创建并更改了默认密码
• 默认系统设置已写入 system_settings 表

后端

• GET /health 返回 {"code":0}
• POST /api/v1/admin/login 可正常登录
• GET /api/v1/admin/dashboard 返回统计数据
• GET /api/v1/admin/settings 返回系统设置

管理后台

• 构建时 ENV 已设为 prod
• 构建产物已上传到 COS admin/ 目录
• https://tx.vsai.net.cn/admin/ 可正常访问
• 管理员可登录并查看仪表盘

小程序

• miniprogram/config/env.js 中 ENV='prod'
• 微信公众平台已配置 request/download/upload 合法域名
• 小程序登录流程正常
• 蓝牙扫码绑定流程正常
• 护理记录同步正常
• 用户协议和隐私政策页面内容完整

安全

• .env 文件未包含在部署包中
• 生产环境 mock-bind 和 mock-purchase 接口已自动禁用
• CORS 策略按需收紧（当前为 *）
• Rate limiting 已生效（登录 15min/10次，管理员 15min/5次）