feat: 正式 App 后端登录模块 v0.1.0
引入 JWT 认证、极光一键登录、短信 mock 登录与用户表，并补充技术实施文档与部署配置。 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
马润林
@@ -1,3 +1,216 @@
|
||||
# shaguabijia-app-server
|
||||
|
||||
傻瓜比价正式 app后端
|
||||
傻瓜比价正式 App 后端 — FastAPI + SQLAlchemy + JWT。
|
||||
|
||||
> 占坑期已有的试验后台 `shaguabijia-server` 是无状态 mock,本项目是正式版,
|
||||
> 引入账号体系、JWT 登录态、Alembic 迁移、SQLite 起步可平滑切 PostgreSQL。
|
||||
|
||||
详细技术说明见 [docs/后端技术实现.md](docs/后端技术实现.md)(登录链路、极光 RSA、部署 checklist)。
|
||||
|
||||
---
|
||||
|
||||
## 技术栈
|
||||
|
||||
| 维度 | 选型 | 说明 |
|
||||
|---|---|---|
|
||||
| 语言 | Python 3.11+ | |
|
||||
| Web | FastAPI 0.115+ | |
|
||||
| ASGI | uvicorn[standard] | |
|
||||
| ORM | SQLAlchemy 2.0 | Mapped/DeclarativeBase 新风格 |
|
||||
| 迁移 | Alembic | render_as_batch 兼容 SQLite |
|
||||
| DB | SQLite | 后续切 PostgreSQL 只改 `DATABASE_URL` |
|
||||
| Auth | JWT (PyJWT) | access(2h) + refresh(30d) |
|
||||
| 极光一键登录 | httpx + cryptography | RSA 解密,逻辑参考试验后台 |
|
||||
| 配置 | pydantic-settings | `.env` 加载 |
|
||||
| 测试 | pytest + TestClient | |
|
||||
|
||||
---
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
shaguabijia-app-server/
|
||||
├── app/
|
||||
│ ├── main.py FastAPI 入口 + /health + CORS
|
||||
│ ├── core/
|
||||
│ │ ├── config.py Settings (pydantic-settings)
|
||||
│ │ ├── logging.py 统一日志配置
|
||||
│ │ ├── security.py JWT 签发 / 校验 / token 对
|
||||
│ │ ├── jiguang.py 极光 REST 调用 + RSA 解密
|
||||
│ │ └── sms.py 短信验证码 (mock 实现)
|
||||
│ ├── db/
|
||||
│ │ ├── base.py DeclarativeBase
|
||||
│ │ └── session.py engine + SessionLocal + get_db
|
||||
│ ├── models/
|
||||
│ │ └── user.py User 表
|
||||
│ ├── schemas/
|
||||
│ │ └── auth.py 登录/Token 相关 Pydantic
|
||||
│ ├── crud/
|
||||
│ │ └── user.py upsert_user_for_login 等
|
||||
│ └── api/
|
||||
│ ├── deps.py get_current_user (Bearer 校验)
|
||||
│ └── v1/
|
||||
│ └── auth.py /api/v1/auth/* 路由
|
||||
│
|
||||
├── alembic/ 迁移脚本
|
||||
│ ├── env.py
|
||||
│ ├── script.py.mako
|
||||
│ └── versions/ (空,第一次跑 alembic revision 生成)
|
||||
├── alembic.ini
|
||||
│
|
||||
├── deploy/
|
||||
│ ├── shaguabijia-app-server.service systemd unit
|
||||
│ └── nginx/
|
||||
│ └── app-api.shaguabijia.com.conf
|
||||
│
|
||||
├── secrets/ 不入 git。放 jverify_rsa_private.pem
|
||||
├── data/ 不入 git。SQLite 文件默认在这里
|
||||
├── tests/ 冒烟 + auth 流程
|
||||
│
|
||||
├── pyproject.toml
|
||||
├── .env.example
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API 接口
|
||||
|
||||
| 方法 | 路径 | 说明 | 鉴权 |
|
||||
|---|---|---|---|
|
||||
| GET | `/health` | 健康检查 | 无 |
|
||||
| POST | `/api/v1/auth/jverify-login` | 极光一键登录(`loginToken` → 注册即登录 → 签发 token 对) | 无 |
|
||||
| POST | `/api/v1/auth/sms/send` | 发短信验证码(mock 阶段任意 6 位通过) | 无 |
|
||||
| POST | `/api/v1/auth/sms/login` | 手机号+验证码登录 | 无 |
|
||||
| POST | `/api/v1/auth/refresh` | 用 `refresh_token` 换新的 token 对 | 无 |
|
||||
| GET | `/api/v1/auth/me` | 获取当前登录用户 | `Bearer access_token` |
|
||||
| POST | `/api/v1/auth/logout` | 登出(占位,客户端清 token) | `Bearer access_token` |
|
||||
|
||||
登录类接口的响应统一格式:
|
||||
```json
|
||||
{
|
||||
"access_token": "eyJxxx...",
|
||||
"refresh_token": "eyJxxx...",
|
||||
"token_type": "Bearer",
|
||||
"expires_in": 7200,
|
||||
"refresh_expires_in": 2592000,
|
||||
"user": {
|
||||
"id": 1,
|
||||
"phone": "13800138000",
|
||||
"nickname": null,
|
||||
"avatar_url": null,
|
||||
"register_channel": "jverify",
|
||||
"status": "active",
|
||||
"created_at": "2026-05-23T04:30:00Z",
|
||||
"last_login_at": "2026-05-23T04:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
文档启动后看 `http://localhost:8770/docs` (Swagger UI)。
|
||||
|
||||
---
|
||||
|
||||
## 本地开发
|
||||
|
||||
### 1. 装依赖
|
||||
|
||||
```bash
|
||||
cd shaguabijia-app-server
|
||||
python3.11 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
### 2. 准备配置
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# 编辑 .env,生产部署务必改 JWT_SECRET_KEY
|
||||
```
|
||||
|
||||
如果要测极光一键登录,把 RSA 私钥放到 `./secrets/jverify_rsa_private.pem`。
|
||||
没放也不影响其他接口(`sms`/`/health` 等),只是 `jverify-login` 会 502。
|
||||
|
||||
### 3. 建表(首次)
|
||||
|
||||
```bash
|
||||
# 生成首版 migration(已有 User model,会自动生成 create_table)
|
||||
alembic revision --autogenerate -m "init user table"
|
||||
# 应用 migration
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
后续改 model 后:
|
||||
```bash
|
||||
alembic revision --autogenerate -m "add nickname index"
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
### 4. 跑起来
|
||||
|
||||
```bash
|
||||
uvicorn app.main:app --reload --port 8770
|
||||
```
|
||||
|
||||
冒烟:
|
||||
```bash
|
||||
curl http://localhost:8770/health
|
||||
# {"status":"ok"}
|
||||
|
||||
# mock 走通登录闭环
|
||||
curl -X POST http://localhost:8770/api/v1/auth/sms/send -H 'Content-Type: application/json' -d '{"phone":"13800138000"}'
|
||||
|
||||
curl -X POST http://localhost:8770/api/v1/auth/sms/login -H 'Content-Type: application/json' -d '{"phone":"13800138000","code":"123456"}'
|
||||
# 拿到 access_token 后:
|
||||
curl http://localhost:8770/api/v1/auth/me -H "Authorization: Bearer <access_token>"
|
||||
```
|
||||
|
||||
### 5. 测试
|
||||
|
||||
```bash
|
||||
pytest -q
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 部署(生产)
|
||||
|
||||
参考 `deploy/`,部署到 `app-api.shaguabijia.com`:
|
||||
|
||||
```bash
|
||||
# 一次性
|
||||
ssh server "apt-get install -y python3.11-venv python3-pip"
|
||||
|
||||
# 后续更新
|
||||
rsync -avz --exclude='__pycache__' --exclude='.venv' --exclude='data' --exclude='secrets/jverify_rsa_private.pem' \
|
||||
./ server:/opt/shaguabijia-app-server/
|
||||
|
||||
# 私钥单独同步(只首次 / 私钥更换时)
|
||||
scp secrets/jverify_rsa_private.pem server:/opt/shaguabijia-app-server/secrets/
|
||||
|
||||
ssh server "
|
||||
cd /opt/shaguabijia-app-server &&
|
||||
.venv/bin/pip install --quiet -e . &&
|
||||
.venv/bin/alembic upgrade head &&
|
||||
systemctl restart shaguabijia-app-server
|
||||
"
|
||||
```
|
||||
|
||||
详见 `deploy/shaguabijia-app-server.service` 和 `deploy/nginx/app-api.shaguabijia.com.conf`。
|
||||
|
||||
---
|
||||
|
||||
## 与试验后台的差异(为什么不直接复用 shaguabijia-server)
|
||||
|
||||
| 维度 | 试验后台 (shaguabijia-server) | 本项目 (shaguabijia-app-server) |
|
||||
|---|---|---|
|
||||
| 数据库 | stdlib sqlite3,无 ORM | SQLAlchemy 2.0 + Alembic |
|
||||
| 业务 | mock parse(无账号体系) | 完整账号体系 + JWT |
|
||||
| 登录态 | 无,客户端发 phone 当 ID | JWT access+refresh |
|
||||
| 配置 | 硬编码 | pydantic-settings + `.env` |
|
||||
| 短信登录 | 无 | 有(mock 实现,留扩展点) |
|
||||
| 域名 | api.shaguabijia.com (试验) | app-api.shaguabijia.com (正式) |
|
||||
|
||||
极光一键登录的具体实现(REST 调用、RSA padding 试错顺序)直接参考自试验后台,
|
||||
逻辑等价。
|
||||
|
||||
Reference in New Issue
Block a user