shaguabijia-app-server/docs/后端技术实现.md

傻瓜比价 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 下的测试机访问:

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. 部署要点

# 代码同步(排除 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。