3.9 KiB
3.9 KiB
启动记录
1. 项目结构
当前项目包含 3 个子系统：
backend/：FastAPI 后端miniprogram/：微信小程序admin-web/：后台管理端
本次启动优先保证：后端可用，小程序可打开。
2. 首次启动顺序
建议按下面顺序启动：
- 启动 MySQL
- 启动后端
backend/ - 检查后端健康状态
- 打开微信开发者工具并加载
miniprogram/ - 编译小程序
3. 后端首次启动记录
3.1 进入目录
cd backend
3.2 创建虚拟环境
python -m venv .venv
.\.venv\Scripts\Activate.ps1
3.3 安装依赖
pip install -r requirements.txt
3.4 配置环境变量
将：
backend/.env.example
复制为：
backend/.env
至少需要确认这些配置已填写：
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=123456
MYSQL_DATABASE=dating_app
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_DB=0
JWT_SECRET_KEY=replace_with_a_secure_secret
WX_APPID=your_wx_appid
WX_SECRET=your_wx_secret
3.5 准备数据库
先创建数据库：
CREATE DATABASE dating_app DEFAULT CHARACTER SET utf8mb4;
3.6 执行迁移
alembic upgrade head
3.7 启动后端
uvicorn main:app --reload
3.8 健康检查
启动后访问：
http://127.0.0.1:8000/health
如果返回：
{"status":"ok"}
说明后端启动成功。
4. 小程序启动记录
4.1 打开目录
使用微信开发者工具打开：
miniprogram/
4.2 本地接口地址
当前小程序接口地址已调整为：
http://127.0.0.1:8000/api/v1
涉及文件：
miniprogram/utils/constants.jsminiprogram/app.js
4.3 开发者工具配置
本地联调时建议勾选：
不校验合法域名不校验 HTTPS 证书
否则可能出现：
request:fail url not in domain list
4.4 当前已处理的问题
之前小程序存在一个启动风险：
app.js启动时会立刻登录- 登录依赖后端接口和
wx.login - 一旦接口不可用，页面可能表现为打不开或白屏
当前已做处理：
miniprogram/app.js启动登录增加了容错miniprogram/pages/home/home.js首页接口请求增加了失败兜底- 接口地址从
localhost统一改成了127.0.0.1
现在即使后端暂时异常，小程序页面也不应因为启动登录失败而直接打不开；只是页面数据可能为空。
5. 真机调试说明
真机不要使用：
localhost127.0.0.1
原因：
- 手机访问不到你电脑本机地址
- 小程序请求域名需要在微信后台配置
真机联调时应改成：
- 电脑局域网 IP
- 或可访问的正式域名
6. 常见错误排查
6.1 小程序页面打不开
优先检查：
- 后端是否已启动
http://127.0.0.1:8000/health是否可访问- 微信开发者工具是否关闭了域名校验限制
- 控制台是否有
request:fail - 控制台是否有
wx.login相关错误
6.2 微信登录不可用
当前 miniprogram/project.config.json 中使用的是：
touristappid
这适合先看页面结构，但如果要走完整微信登录，通常需要替换成真实小程序 appid。
6.3 接口请求失败
检查项：
- 后端服务是否运行在
127.0.0.1:8000 - 路径前缀是否为
/api/v1 - 后端数据库是否可连接
.env中微信配置是否正确
7. 本次记录结论
本项目第一次启动时，正确顺序是先启动后端，再打开小程序。
如果只是看页面：
- 可以先打开小程序
- 即使接口失败，页面现在也应能打开
如果要完整联调登录和数据：
- 必须先启动后端
- 必须保证数据库和相关环境变量配置正确
- 最好使用真实小程序
appid进行微信能力联调