jw-beauty/docs/dev/02-配置说明.md

配置说明

环境变量总表

后端所有配置通过 server/.env 文件管理（通过 dotenv 加载）。下表列出全部变量：

变量名	用途	示例值	必填	默认值
NODE_ENV	运行环境	development / production	否	development
PORT	监听端口	3000	否	3000
DB_HOST	MySQL 主机地址	127.0.0.1	是	无
DB_PORT	MySQL 端口	3306	否	3306
DB_USER	MySQL 用户名	root	否	root
DB_PASSWORD	MySQL 密码	mypassword	是	无
DB_NAME	数据库名	jw_beauty	否	jw_beauty
WECHAT_APPID	微信小程序 AppID	wxc4045074ef298510	生产必填	无
WECHAT_SECRET	微信小程序 AppSecret	abcdef1234567890...	生产必填	无
JWT_SECRET	用户 JWT 签名密钥	a-long-random-string	生产必填	dev-user-secret
ADMIN_JWT_SECRET	管理员 JWT 签名密钥	another-long-random-string	生产必填	dev-admin-secret
ADMIN_USERNAME	初始管理员用户名	admin	否	admin
ADMIN_PASSWORD	初始管理员密码	strongpassword	生产必填	admin
TENCENT_SECRET_ID	腾讯云 API SecretId	AKIDxxxx	COS 功能需要	无
TENCENT_SECRET_KEY	腾讯云 API SecretKey	xxxx	COS 功能需要	无
TENCENT_REGION	腾讯云默认地域	ap-guangzhou	否	ap-guangzhou
COS_BUCKET	COS 存储桶名称	jw-bucket-1426323813	否	jw-bucket-1426323813
COS_REGION	COS 存储桶地域	ap-guangzhou	否	同 TENCENT_REGION
COS_CDN_DOMAIN	COS CDN 加速域名	tx.vsai.net.cn	否	tx.vsai.net.cn

生产环境安全检查

当 NODE_ENV=production 时，服务启动会强制检查以下条件，不满足则拒绝启动：

• JWT_SECRET 不能是默认值 dev-user-secret
• ADMIN_JWT_SECRET 不能是默认值 dev-admin-secret
• ADMIN_USERNAME 和 ADMIN_PASSWORD 不能是默认值 admin

微信配置

获取 WECHAT_APPID 和 WECHAT_SECRET

1. 登录 微信公众平台 -> 开发管理 -> 开发设置
2. AppID(小程序ID) 即为 WECHAT_APPID
3. AppSecret(小程序密钥) 即为 WECHAT_SECRET（需要管理员扫码后才能查看，只显示一次）

WECHAT_APPID=wxc4045074ef298510
WECHAT_SECRET=你的AppSecret

开发环境

本地开发时不填这两个值也能运行，但微信登录（wx.login -> code2Session）会失败。此时可以通过 mock 端点绕过。

数据库配置

本地开发

DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=你的本地MySQL密码
DB_NAME=jw_beauty

使用 Docker 快速启动 MySQL：

docker run -d \
  --name jw-mysql \
  -p 3306:3306 \
  -e MYSQL_ROOT_PASSWORD=rootpass \
  -e MYSQL_DATABASE=jw_beauty \
  mysql:8.0 \
  --character-set-server=utf8mb4 \
  --collation-server=utf8mb4_unicode_ci

然后 .env 中填：

DB_HOST=127.0.0.1
DB_PASSWORD=rootpass

腾讯云 TencentDB

SCF 函数部署时，需要将函数放在与 TencentDB 同一 VPC/子网中：

DB_HOST=10.0.0.x     # VPC 内网地址
DB_PORT=3306
DB_USER=root
DB_PASSWORD=腾讯云数据库密码
DB_NAME=jw_beauty

数据库表结构

共 10 张表（定义在 server/sql/schema.sql）：

表名	说明
users	小程序用户，openid 唯一索引
devices	美容仪设备，device_id 为主键
bindings	用户-设备绑定关系
subscriptions	用户订阅记录（月卡/年卡）
treatment_records	护理记录，含时长、模式、光密度等
device_events	设备事件日志（错误、告警等）
device_commands	下发给设备的远程指令
operation_logs	操作审计日志
admin_accounts	管理员账号
system_settings	系统设置键值对（定价、功能开关等）
firmware_files	固件版本记录

初始化时会自动插入默认系统设置：月卡 99 元、年卡 899 元、试用 7 天等。

COS 配置

COS（对象存储）用于存储用户头像和固件文件，通过 CDN 域名对外提供访问。

TENCENT_SECRET_ID=AKIDxxxx          # 腾讯云控制台 -> 访问管理 -> API密钥管理
TENCENT_SECRET_KEY=xxxx
COS_BUCKET=jw-bucket-1426323813     # 存储桶名称（含 APPID 后缀）
COS_REGION=ap-guangzhou             # 存储桶所在地域
COS_CDN_DOMAIN=tx.vsai.net.cn       # CDN 加速域名（可选，不填有默认值）

获取密钥

1. 登录 腾讯云控制台
2. 访问管理 -> API 密钥管理 -> 新建密钥
3. 复制 SecretId 和 SecretKey

建议创建子用户，只授予 COS 相关权限，不要使用主账号密钥。

本地开发

不配置 COS 相关变量时，头像上传和固件上传功能会报错，但不影响其他功能开发。

安全配置

JWT_SECRET

用于签发用户端 JWT token，有效期 7 天。生成方法：

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

将输出填入 .env：

JWT_SECRET=生成的64位十六进制字符串

ADMIN_JWT_SECRET

用于签发管理后台 JWT token，必须与 JWT_SECRET 不同。用同样的方法生成：

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

ADMIN_JWT_SECRET=另一个64位十六进制字符串

管理员初始密码

npm run db:init 会使用 .env 中的 ADMIN_USERNAME 和 ADMIN_PASSWORD 创建管理员账号（bcrypt 哈希存储）。

ADMIN_USERNAME=admin
ADMIN_PASSWORD=一个强密码

生产环境不能使用默认值 admin/admin，服务启动时会报错退出。

CORS

当前 CORS 设置为 Access-Control-Allow-Origin: *（见 server/src/app.js），允许所有来源。这是开发阶段的配置，生产环境应收紧为具体域名。

允许的自定义请求头：

Content-Type, Authorization, X-Device-Id, X-App-Version, X-Platform

小程序配置

env.js

文件路径：miniprogram/config/env.js

var ENV = 'test'    // 可选值：local / test / prod

var API_BASES = {
  local: 'http://localhost:3000',
  test: 'https://api.vsai.net.cn',
  prod: 'https://api.vsai.net.cn'
}

var __DEV__ = ENV !== 'prod'

ENV 取值说明

值	API 地址	__DEV__	说明
local	http://localhost:3000	true	本地开发
test	https://api.vsai.net.cn	true	连接测试环境
prod	https://api.vsai.net.cn	false	生产环境

__DEV__ 的作用

当 __DEV__ 为 true 时：

• 启用 mock 绑定设备（无需蓝牙握手）
• 启用 mock 购买订阅（无需微信支付）
• 可能显示额外的调试信息

发布正式版时务必将 ENV 设为 prod。

project.config.json

文件中的 appid 字段需要与实际的小程序 AppID 一致：

{
  "appid": "wxc4045074ef298510",
  "projectname": "hox-beauty"
}

如果没有该 AppID 权限，在微信开发者工具中可以选择测试号。

管理后台配置

env.js

文件路径：admin-console/src/config/env.js

const ENV = 'test'    // 可选值：local / test / prod

const API_BASES = {
  local: 'http://localhost:3000',
  test: 'https://api.vsai.net.cn',
  prod: 'https://api.vsai.net.cn'
}

与小程序的 env.js 功能一致，本地开发时改为 local。

Vite base path

admin-console/vite.config.js 配置了 base 路径：

export default defineConfig({
  base: process.env.PUBLIC_PATH || '/admin/',
  plugins: [uni()]
})

• 默认 base 为 /admin/，意味着所有静态资源路径都会加上 /admin/ 前缀
• 部署到 COS 后通过 https://你的域名/admin/ 访问
• 本地开发时访问地址为 http://localhost:5173/admin/
• 如需改变路径前缀，设置环境变量 PUBLIC_PATH：

PUBLIC_PATH=/console/ npm run build:h5

构建与部署

# 开发
npm run dev

# 构建 H5 产物
npm run build:h5

# 构建并部署到 COS
npm run deploy:cos

deploy:cos 脚本会将 dist/build/h5/ 目录的文件上传到 COS 存储桶，需要在 server/.env（或管理后台自己的 .env）中配置好 TENCENT_SECRET_ID、TENCENT_SECRET_KEY、COS_BUCKET 等变量。