feat: 正式 App 后端登录模块 v0.1.0
引入 JWT 认证、极光一键登录、短信 mock 登录与用户表，并补充技术实施文档与部署配置。 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
马润林
+250
@@ -0,0 +1,250 @@
|
||||
# 傻瓜比价 App Server — 后端技术实现
|
||||
|
||||
> 域名:`app-api.shaguabijia.com`(HTTPS,nginx 反代)
|
||||
> 仓库:`shaguabijia-app-server`
|
||||
> 当前版本:v0.1.0(登录模块)
|
||||
> 最后更新:2026-05-23
|
||||
|
||||
---
|
||||
|
||||
## 1. 本次实施范围
|
||||
|
||||
本阶段目标是搭正式 App 后端的**账号与登录**能力,供 Android 正式版(`shaguabijia-app-android`)对接。
|
||||
|
||||
已实现:
|
||||
|
||||
| 能力 | 状态 | 说明 |
|
||||
|---|---|---|
|
||||
| 极光一键登录 | ✅ 已联调 | `loginToken` → 极光 REST 验真 → RSA 解密手机号 → 注册/登录 |
|
||||
| 短信验证码登录 | ✅ mock 可用 | 开发阶段任意 6 位通过,便于无短信供应商时联调 |
|
||||
| JWT 双 token | ✅ | access(2h) + refresh(30d) |
|
||||
| 用户表 + ORM | ✅ | SQLAlchemy 2.0 + Alembic |
|
||||
| `/me` 鉴权 | ✅ | Bearer access_token |
|
||||
| 单元测试 | ✅ | health + sms 登录闭环 + refresh + 限流 |
|
||||
|
||||
未做(后续迭代):
|
||||
|
||||
- 真实短信供应商(阿里云/腾讯云)
|
||||
- logout 服务端 token 黑名单(jti)
|
||||
- 昵称/头像修改、注销账号
|
||||
- PostgreSQL 生产切库(当前 SQLite 起步)
|
||||
|
||||
---
|
||||
|
||||
## 2. 与试验后台的关系
|
||||
|
||||
| 维度 | 试验后台 `shaguabijia-server` | 正式后台 `shaguabijia-app-server` |
|
||||
|---|---|---|
|
||||
| 域名 | `api.shaguabijia.com` | `app-api.shaguabijia.com` |
|
||||
| 数据库 | stdlib sqlite3,手写 SQL | SQLAlchemy 2.0 + Alembic |
|
||||
| 账号体系 | 仅占坑(phone 当 ID) | User 表 + JWT |
|
||||
| 极光验 token | ✅ 有 | ✅ 移植并增强 |
|
||||
| 短信登录 | ❌ | ✅ mock |
|
||||
| 配置 | 硬编码 | pydantic-settings + `.env` |
|
||||
|
||||
**极光一键登录的核心逻辑**(REST 调用、RSA padding 试错顺序)直接参考试验后台 `app/api/auth.py`,
|
||||
等价实现在 `app/core/jiguang.py`。
|
||||
|
||||
试验后台 RSA 私钥部署在服务器 `/opt/shaguabijia-server/secrets/jverify_rsa_private.pem`(不入 git)。
|
||||
正式后台因原私钥不可用,在极光控制台**重新生成 1024-bit RSA 密钥对**并上传公钥。
|
||||
|
||||
---
|
||||
|
||||
## 3. 技术栈
|
||||
|
||||
| 维度 | 选型 | 说明 |
|
||||
|---|---|---|
|
||||
| 语言 | Python 3.11+ | 本地开发用 3.13 |
|
||||
| Web | FastAPI 0.115+ | OpenAPI 自动生成 |
|
||||
| ASGI | uvicorn[standard] | 生产 `--host 127.0.0.1 --port 8770` |
|
||||
| ORM | SQLAlchemy 2.0 | Mapped 新风格 |
|
||||
| 迁移 | Alembic | `render_as_batch` 兼容 SQLite |
|
||||
| DB | SQLite | 生产可改 `DATABASE_URL` 切 PostgreSQL |
|
||||
| Auth | PyJWT | HS256,access + refresh |
|
||||
| 极光 | httpx + cryptography | REST 验 token + RSA 解密 |
|
||||
| 配置 | pydantic-settings | `.env` 加载 |
|
||||
| 测试 | pytest + httpx TestClient | 临时文件 SQLite |
|
||||
|
||||
---
|
||||
|
||||
## 4. 登录链路
|
||||
|
||||
### 4.1 极光一键登录(主路径)
|
||||
|
||||
```
|
||||
Android SDK loginAuth
|
||||
→ 客户端拿到 loginToken
|
||||
→ POST /api/v1/auth/jverify-login { login_token, operator }
|
||||
→ 后端 POST 极光 loginTokenVerify (Basic Auth = AppKey:MasterSecret)
|
||||
→ 极光返回 RSA 加密的手机号(base64)
|
||||
→ 后端用私钥解密(PKCS1v15,实测电信 CT 走此 padding)
|
||||
→ upsert User(phone 唯一) → 签 JWT → 返回 TokenWithUser
|
||||
```
|
||||
|
||||
**关键配置**(与 Android 端必须一致):
|
||||
|
||||
| 项 | 值 |
|
||||
|---|---|
|
||||
| 包名 | `com.jishisongfu.shaguabijia` |
|
||||
| 极光 AppKey | `966b451a8d9cfe12d173ea9d` |
|
||||
| RSA 公钥 | 极光控制台「加密公钥」(1024-bit,≤220 字符) |
|
||||
| RSA 私钥 | `secrets/jverify_rsa_private.pem`(不入 git) |
|
||||
|
||||
**RSA 密钥说明**:
|
||||
|
||||
- 密钥对由我方生成(`openssl genrsa 1024`),公钥上传极光控制台
|
||||
- 极光控制台限制公钥长度 ≤220 字符,因此用 **1024-bit** 而非 2048-bit
|
||||
- 私钥路径由 `JG_PRIVATE_KEY_PATH` 指定,懒加载;文件不存在时 `jverify-login` 返回 502
|
||||
|
||||
### 4.2 短信登录(mock 路径)
|
||||
|
||||
```
|
||||
POST /api/v1/auth/sms/send { phone } → 60s 冷却,不真发短信
|
||||
POST /api/v1/auth/sms/login { phone, code } → 任意 6 位通过(SMS_MOCK=true)
|
||||
→ upsert User → 签 JWT → 返回 TokenWithUser
|
||||
```
|
||||
|
||||
### 4.3 Token 刷新
|
||||
|
||||
```
|
||||
POST /api/v1/auth/refresh { refresh_token }
|
||||
→ 校验 refresh token → 签新 access+refresh 对
|
||||
```
|
||||
|
||||
Android 端通过 OkHttp `Authenticator` 在 401 时自动调用。
|
||||
|
||||
---
|
||||
|
||||
## 5. 数据模型
|
||||
|
||||
### User 表
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| id | INTEGER PK | 自增 |
|
||||
| phone | VARCHAR UNIQUE | 手机号,登录主键 |
|
||||
| register_channel | VARCHAR | `jverify` / `sms` |
|
||||
| nickname | VARCHAR NULL | 预留 |
|
||||
| avatar_url | VARCHAR NULL | 预留 |
|
||||
| status | VARCHAR | `active` / `disabled` |
|
||||
| created_at | DATETIME | 注册时间 |
|
||||
| last_login_at | DATETIME | 最近登录 |
|
||||
|
||||
`upsert_user_for_login`:phone 存在则更新 `last_login_at`,不存在则注册。
|
||||
|
||||
---
|
||||
|
||||
## 6. API 一览
|
||||
|
||||
| 方法 | 路径 | 鉴权 | 说明 |
|
||||
|---|---|---|---|
|
||||
| GET | `/health` | 无 | 健康检查 |
|
||||
| POST | `/api/v1/auth/jverify-login` | 无 | 极光一键登录 |
|
||||
| POST | `/api/v1/auth/sms/send` | 无 | 发短信(mock) |
|
||||
| POST | `/api/v1/auth/sms/login` | 无 | 短信登录 |
|
||||
| POST | `/api/v1/auth/refresh` | 无 | 刷新 token |
|
||||
| GET | `/api/v1/auth/me` | Bearer | 当前用户 |
|
||||
| POST | `/api/v1/auth/logout` | Bearer | 登出占位 |
|
||||
|
||||
Swagger UI: `http://localhost:8770/docs`
|
||||
|
||||
---
|
||||
|
||||
## 7. 目录结构
|
||||
|
||||
```
|
||||
app/
|
||||
├── main.py # FastAPI 入口,lifespan,CORS
|
||||
├── core/
|
||||
│ ├── config.py # pydantic-settings
|
||||
│ ├── security.py # JWT 签发/校验
|
||||
│ ├── jiguang.py # 极光 REST + RSA 解密
|
||||
│ └── sms.py # 短信 mock(内存验证码)
|
||||
├── db/
|
||||
│ ├── base.py
|
||||
│ └── session.py # engine + get_db
|
||||
├── models/user.py
|
||||
├── schemas/auth.py
|
||||
├── crud/user.py
|
||||
└── api/
|
||||
├── deps.py # get_current_user
|
||||
└── v1/auth.py # 登录路由
|
||||
|
||||
alembic/ # 数据库迁移
|
||||
deploy/ # systemd + nginx
|
||||
secrets/ # RSA 私钥(不入 git)
|
||||
tests/ # pytest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 本地联调(真机 + LAN)
|
||||
|
||||
后端监听所有网卡,供同一 WiFi 下的测试机访问:
|
||||
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8770 --reload
|
||||
```
|
||||
|
||||
Android debug 包 `BASE_URL` 指向开发机 LAN IP(配置在 `local.properties`,不入 git):
|
||||
|
||||
```
|
||||
debug.api.host=192.168.x.x
|
||||
debug.api.port=8770
|
||||
```
|
||||
|
||||
真机浏览器访问 `http://192.168.x.x:8770/health` 应返回 `{"status":"ok"}`。
|
||||
|
||||
---
|
||||
|
||||
## 9. 部署要点
|
||||
|
||||
```bash
|
||||
# 代码同步(排除 secrets 和 data)
|
||||
rsync -avz --exclude='.venv' --exclude='data' --exclude='secrets/*.pem' \
|
||||
./ server:/opt/shaguabijia-app-server/
|
||||
|
||||
# 私钥单独 scp(仅首次或轮换时)
|
||||
scp secrets/jverify_rsa_private.pem server:/opt/shaguabijia-app-server/secrets/
|
||||
|
||||
# 迁移 + 重启
|
||||
ssh server "cd /opt/shaguabijia-app-server && .venv/bin/alembic upgrade head && systemctl restart shaguabijia-app-server"
|
||||
```
|
||||
|
||||
生产 checklist:
|
||||
|
||||
- [ ] `JWT_SECRET_KEY` 换成随机长字符串
|
||||
- [ ] `APP_ENV=prod`, `APP_DEBUG=false`
|
||||
- [ ] RSA 私钥权限 `chmod 600`
|
||||
- [ ] nginx SSL 证书有效
|
||||
- [ ] `alembic upgrade head` 已执行
|
||||
|
||||
---
|
||||
|
||||
## 10. 已知问题与后续
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| logout 无服务端失效 | 目前靠客户端清 token;后续可加 jti 黑名单表 |
|
||||
| SMS 为 mock | 上线前需接真实短信供应商并设 `SMS_MOCK=false` |
|
||||
| SQLite 并发 | 生产流量上来后切 PostgreSQL,只改 `DATABASE_URL` |
|
||||
| 极光 RSA 1024-bit | 极光控制台限制所致;仅加密 11 位手机号,可接受 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 联调验证记录(2026-05-23)
|
||||
|
||||
本地 LAN 联调已通过:
|
||||
|
||||
```
|
||||
# 短信登录
|
||||
POST /api/v1/auth/sms/login → 200, user_id=2, phone=177****82
|
||||
|
||||
# 极光一键登录
|
||||
POST /api/v1/auth/jverify-login → 200, operator=CT, token_len=448
|
||||
[JG] decrypted with padding=PKCS1v15
|
||||
jverify_login ok user_id=3, phone=153****91
|
||||
```
|
||||
|
||||
Android 端包名、签名、极光 AppKey 与控制台一致,SDK init 8000,loginAuth 6000。
|
||||
Reference in New Issue
Block a user