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