Files

T

Reviewed-on: #128

2026-07-09 14:24:46 +08:00

29 KiB

Raw Permalink Blame History

傻瓜比价 App Server — 后端技术方案

域名:app-api.shaguabijia.com(HTTPS,nginx 反代) 仓库:shaguabijia-app-server 接口协议详见 docs/api/(索引 + 一接口一文件) 最后更新:2026-07-09(§1/§6.2 比价透传改「软鉴权 + trace_id 签发 + harvest 落库」不再是纯透传;§3 目录树补全到当前 22 个 v1 路由 + core 三 worker + utils/geo;§1 补邀请奖励金/埋点/领券看板/设备存活;§5 美团 feed/top-sales 按城市过滤 #116;§7 45 张表、98 迁移;§8 部署对齐 ecs1 git-clone + systemd 定时器;§10 刷新。上一次 2026-06-23)

1. 这个后端是干什么的

为正式版 App(shaguabijia-app-android,包名 com.jishisongfu.shaguabijia)提供以下能力:

能力	说明
账号与登录	极光一键登录 + 短信验证码登录(SMS_MOCK 切换)→ 签发 JWT;新手引导标记(设备+账号,含用户自助重置 #114)
用户资料	昵称 / 头像(上传图片含魔数嗅探) / 注销账号(软删除+匿名化)
美团 CPS 选品	feed 多 tab(rec 离线库 / distance 实时)+ 销量榜,按设备坐标离线反查城市、只出同城券(#116);点击换推广链接(分佣);未配凭证降级返空
领券透传	`/coupon/step` 透传到 pricebot-backend(一键领券核心,不鉴权,前端已接通)+ best-effort 写领券三表;`/coupon/session` 领券任务流水(admin 看板,#99)
外卖比价透传 + 落库	`/intent/` + `/price/step` + `/trace/finalize`、`/trace/epilogue` 透传 pricebot,软鉴权 + 首帧签发 trace_id + harvest 三段式落 `comparison_record`*(2026-07 起,见 §6.2)
金币 / 现金钱包	金币账户/流水/兑换/微信绑定/提现单;邀请奖励金独立账本(#82,与现金物理隔离,`source` 分账提现 #121)
好友邀请	邀请码/落地页指纹归因;发奖口径=好友比价并下单(#113,发邀请奖励金)
签到 + 任务 + 省钱战绩	福利模块
看广告发奖	穿山甲 GroMore 激励视频 S2S 回调(SHA256 验签)+ 信息流/Draw 结算(ad_type/feed_scene 分场景)+ 穿山甲后台收益日表拉取(#92)
帮助与反馈	反馈工单(来源/场景/端环境采集 + admin 采纳发币/拒绝/运营回复,#94/#105)+ 静态 `/media` 服务
埋点	`/analytics/events` 批量上报落 `analytics_event`(#83)
设备存活监控	无障碍心跳 + 掉线检出(worker,超时 1h #107)+ 召回 ack;admin 存活看板(#80)
平台配置 / OTA	`/platform/*`:门面统计、feature flags、广告配置下发、App 版本检查更新(全不鉴权)
CPS 群发联盟	`/c/{code}` 短链落地 + 微信授权 + 联盟对账(美团+京东 #90),运营台在 admin
运营后台 admin	独立子应用(8771,独立 JWT):用户/钱包/提现审核/反馈/大盘/收益报表/领券看板/RBAC 自定义角色(#117/#126)等,全量端点见 api/README Admin 段

"比价/领券"的执行核心在 pricebot-backend(另一个 repo),本服务对 step 类接口做透传;但 2026-07 起比价透传不再是纯壳——app-server 直接负责比价记录落库(§6.2)。无爬虫、无 LLM,业务模型已扩展到 45 张业务表(见 §7 / database/OVERVIEW.md)。仓库根另有 h5/(mine 我的页 + shared bridge/api,#89,H5 化的我的页静态资源)。

2. 技术栈

维度	选型	说明
语言	Python ≥3.10	本地开发用 conda 环境 `price`
Web	FastAPI 0.115+	OpenAPI 自动生成(非 prod 开 `/docs`)
ASGI	uvicorn[standard]	生产 `--host 127.0.0.1 --port 8770`
ORM	SQLAlchemy 2.0(Mapped 风格)
迁移	Alembic
DB	PostgreSQL 16(生产)/ SQLite(开发兜底)	一键脚本 `scripts/init_postgres.py` 建库 + 写 `.env` + 跑迁移;开发环境改 `DATABASE_URL=sqlite:///./data/app.db` 即回退。无 Redis。详见 docs/database/postgres-migration.md
DB 驱动	psycopg3(`psycopg[binary]>=3.1`)	`DATABASE_URL=postgresql+psycopg://...`,不要装 psycopg2——SQLAlchemy 2.0 时代默认 psycopg3
Auth	PyJWT(HS256)	access + refresh
极光	httpx + cryptography	REST 验 token + RSA 解密手机号
美团 / pricebot	httpx(含 async)	美团 S-Ca 网关签名;领券 async 透传
配置	pydantic-settings	`.env` 加载
测试	pytest + httpx TestClient

3. 分层架构与目录结构

标准 FastAPI 分层,一个请求自上而下穿过:api(薄,收发) → integrations(外部 SDK) / repositories(数据) → models / db。重逻辑(SDK 签名/加解密/外部 HTTP)落 integrations,集成层细节见 docs/integrations/。

app/
├── main.py                  # FastAPI 入口:注册 21 个 v1 router + 4 个 internal router、CORS、
│                            #   lifespan(预热 pricebot client + 离线地理库,启 3 个后台 worker)、
│                            #   /media 静态服务 + /media/shaguabijia.apk 官网直链(强制下载头)
├── api/
│   ├── deps.py              # 共享依赖:get_current_user / OptionalUser(软鉴权) / get_db
│   ├── internal/            # server→server 内部端点(X-Internal-Secret):app_version / launch_confirm / price / store
│   └── v1/                  # 接口层(薄),21 个路由文件:
│       ├── auth.py user.py feedback.py            # 登录 / 资料+引导(含 reset #114) / 反馈工单
│       ├── coupon.py                              # 领券透传 step + session 流水 + prompt/completed 频控族
│       ├── compare.py                             # 比价透传 + trace_id 签发 + harvest 落库(§6.2)
│       ├── compare_record.py compare_milestone.py # 比价记录(鉴权兜底上报/列表/详情/stats)+ 里程碑
│       ├── meituan.py                             # CPS 选品 4 端点(feed 多 tab / top-sales 按城市 #116)
│       ├── wallet.py wxpay.py                     # 钱包/提现(source 分账 #121)/transfer-auth 族 + 微信回调 stub
│       ├── signin.py tasks.py savings.py          # 福利
│       ├── ad.py                                  # 激励视频 S2S + 信息流/Draw 结算 + eCPM/noshow/watch
│       ├── invite.py order.py report.py           # 邀请 / 支付归因(触发邀请发奖 #113) / 上报更低价
│       ├── analytics.py device.py platform.py     # 埋点 #83 / 无障碍存活 #65 / 门面+flags+ad-config+OTA
│       └── cps_redirect.py                        # /c/{code} 短链落地 + 微信 OAuth(挂域名根)
├── admin/                   # 运营后台独立子应用(8771,独立 JWT;app.main 不 import 它)
│   ├── main.py deps.py security.py permissions.py # 入口 / 鉴权链 / RBAC 页面目录(#117)
│   └── routers/             # 23 个路由:users wallet withdraw feedback(+qr) dashboard comparison
│                            #   coupon_data device_liveness event_logs price_report onboarding
│                            #   ops_marquee_seed ops_stat_config ad_audit ad_revenue ad_config
│                            #   config admins roles(#126) audit auth cps
├── schemas/                 # Pydantic 契约(17 个文件,与客户端对齐字段看这里)
├── integrations/            # 外部 SDK(重逻辑):jiguang / meituan(S-Ca 签名) / sms / pangle / wxpay
├── core/                    # 基础设施:config(+config_schema 运营可配项定义) / security / ratelimit /
│   │                        #   rewards / media / logging / ad_cooldown / test_account(测试号免验证码 #69)
│   ├── pricebot_router.py   # pricebot 多实例一致性 hash(ketama 1000 虚节点,按 trace_id 亲和)
│   ├── pricebot_client.py   # 共享 httpx AsyncClient 单例(#87:免每请求重建 SSL 上下文、绕进程代理)
│   ├── withdraw_reconcile_worker.py  # 提现对账 worker(lifespan 启动)
│   ├── heartbeat_monitor_worker.py   # 无障碍心跳掉线检出 worker(#65,超时 1h #107)
│   └── daily_exchange_worker.py      # 金币自动兑换 worker
├── utils/                   # geo.py(离线经纬度→城市反查,~2.5M 行 CSV+KDTree,启动预热)
│                            #   + meituan_city.py(城市→美团 city_id,#116)
├── repositories/            # 数据访问 + 事务(28 个文件;comparison.py 含 harvest_running/done/abort 三段)
├── models/                  # ORM 表结构(34 个文件,45 张业务表,见 database/OVERVIEW.md)
└── db/                      # DeclarativeBase + engine/get_db(非 SQLite 启 pool 10+20)

h5/                          # H5 静态页(#89):mine 我的页 + shared bridge/api
alembic/                     # 数据库迁移(98 个,含 14+ merge;单 head,见 §7)
deploy/                      # systemd:app-server + admin 两服务;定时器 meituan-etl(选品 ETL)/
│                            #   pangle-revenue(穿山甲收益,每天 10:30 #100)/daily-exchange;nginx 配置
secrets/                     # 极光 RSA 私钥 / 微信支付证书(不入 git)
scripts/                     # init_postgres / migrate.sh / create_admin / 美团券 ETL(pull_meituan_coupons +
│                            #   load_meituan_coupon_tsv) / sync_pangle_revenue(#92) / publish_apk /
│                            #   reconcile_withdraws / reset_* / sim_pangle_callback / seed_mock_*(造数)
tests/                       # pytest(外部集成全 monkeypatch,不打真 HTTP)
run.sh                       # 本地启动(钉定 .venv 解释器 #75,先迁移再起服务)
docs/api/ docs/database/ docs/integrations/ docs/guides/   # 文档(各自带索引)

命名说明:api/v1/ 的 v1 用于 URL 版本化(移动端无法强制即时升级,需新旧版本并存能力);integrations 装外部 SDK 集成、repositories 装数据访问、core 装基础设施,三者分离。数据访问层统一在 repositories/(早期叫 crud/,2026-05 已整体并入,crud/ 不再存在)。coupon.py 是领券透传,勿与 meituan.py 里的 coupons(券列表)混淆。

4. 登录链路

4.1 极光一键登录(主路径)

Android SDK loginAuth → 客户端拿到 loginToken
  → POST /api/v1/auth/jverify-login  { login_token, operator }
  → 后端 POST 极光 loginTokenVerify (Basic Auth = AppKey:MasterSecret)
  → 极光返回 RSA 公钥加密的手机号(base64)
  → 后端用配套私钥解密 → 明文手机号
  → upsert_user_for_login(phone 唯一) → 签 JWT → 返回 TokenWithUser

RSA 解密(integrations/jiguang.py 的 _decrypt_phone):极光文档未明示 padding,代码按 OAEP-SHA1 → OAEP-SHA256 → PKCS1v15 依次试,解出 11 位纯数字手机号即采用(PKCS1v15 对错误密文会"假成功"返回非 UTF-8 垃圾,据此跳过)。

关键配置(须与 Android 端一致):

项	值
包名	`com.jishisongfu.shaguabijia`
极光 AppKey	`966b451a8d9cfe12d173ea9d`(`JG_APP_KEY`)
RSA 公钥	极光控制台「加密公钥」(1024-bit,极光限制 ≤220 字符)
RSA 私钥	`secrets/jverify_rsa_private.pem`(PKCS#8,不入 git,`JG_PRIVATE_KEY_PATH` 指定,懒加载)

密钥对配对关系是关键:极光用控制台上传的公钥加密,后端必须用配对的私钥解密。私钥不配对时 jverify-login 报 502 all RSA paddings failed(密钥不对,非 padding 问题);私钥文件缺失则报 502 private key not found。 2026-05-27 现状:历史遗留的两套本地密钥均不配对当前 AppKey 公钥,已重新生成一对 1024-bit/PKCS#8 密钥,公钥需在极光控制台更新。⚠️ 该 AppKey 公钥为全局配置,若占坑版后端仍在用同一 AppKey,换公钥会使其旧私钥失效,需同步部署新私钥。

4.2 短信登录(已接极光,SMS_MOCK 切 mock / real)

POST /api/v1/auth/sms/send   { phone }       → 60s 冷却,不真发(SMS_MOCK=true)
POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过 → upsert → 签 JWT

短信冷却表存进程内存(--workers 1 下够用,多 worker/重启即失效)。

real 模式(SMS_MOCK=false,生产):自定义验证码——本服务 secrets 生成 6 位码 → 极光 /v1/messages 只负责发 → 本地校验(一次性 / 防爆破),鉴权复用 JG_APP_KEY/JG_MASTER_SECRET(短信与一键登录同一极光应用,上线只需 SMS_MOCK=false)。防刷(单号冷却 + 单设备频控 + 单码失败次数;2026-07-03 精简删单号每日上限与登录纯 IP 限流)+ 错误码 429/503/400。详见 integrations/sms。

4.3 Token 与刷新

access(2h)+ refresh(30d),HS256 自包含,payload 含 sub/typ/iat/exp,无 session 表、无 jti 黑名单。
refresh 校验 token + 查库确认用户 active 后,签发全新一对。
客户端 OkHttp Authenticator 在 401 时自动调 /refresh 续期重放。
logout 为占位(服务端不吊销 token)。

5. 美团 CPS

5.1 网关签名(`integrations/meituan.py` 的 `_sign` / `_call`)

类阿里云 S-Ca 网关签名,stringToSign 只有 4 段:METHOD\n + Content-MD5\n + 排序后的 signed_headers + path,不含 Accept / Content-Type / Date 行(加了签名失败)。头:S-Ca-App(=appkey)、S-Ca-Timestamp、S-Ca-Signature、S-Ca-Signature-Headers。配置项 MT_CPS_APP_KEY / MT_CPS_APP_SECRET / MT_CPS_DEFAULT_SID(默认 sgbjia)。

美团请求字段 listTopiId(少个 c)是官方拼写,非笔误。经纬度 *1_000_000 取整。

5.2 对外四个接口

接口级入参/出参/各 tab 行为详见 api/meituan/meituan-feed.md 等,本节只讲后端形态。

coupons:对外的搜索/榜单接口(底层 query_coupon),客户端暂未接入。
feed:首页推荐流,已是多 tab(入参 tab):
- rec 智能推荐:走离线库 meituan_coupon(筛佣金率≥3%、DISTINCT ON 去重、按销量降序分页),纯库查询、不打美团、不依赖 MT 凭证(实测同城热销中位佣金 ~0.8%,实时筛≥3% 每页剩 0–1 条又撞 402,故从库出)。不显示距离。#116 起按城市过滤:设备经纬度经 utils/geo(离线反查,启动预热)+ meituan_city 映射成美团 city_id,只出同城券;拿不到坐标/城市 → 返空 + status=degraded。
- distance 距离最近:实时拉外卖+到店两路,按用户坐标由近及远。
- 默认(空 tab):旧的逐轮分页混合 feed(2 外卖 + 1 到店交叉,写死 3 页爆款/今日必推/精选+限时,第 4 页返空),仅老客户端兼容。
- 任何失败场景返 200 + 空 items + status=degraded(不抛 5xx)。
top-sales:独立的销量榜接口,离线库 meituan_coupon 按销量降序 + 跨源去重 + 同城过滤(#116,同 rec 的城市反查),不实时打美团。
referral-link:换推广链接,客户端取 link_map["3"](deeplink)优先跳美团 App。
query_coupon:底层取数(被 coupons/distance feed 共用),不直接对外。

5.3 风险点

对外接口无鉴权:任何人可调,消耗你的美团 appkey 能力/配额。
sid 可被客户端覆盖:他人可借接口刷自己渠道分佣,建议服务端锁定。
feed 失败返 status=degraded:任何失败场景返 200 + 空 items + status=degraded(不抛 5xx,避免前端弹报错 toast)。排查时看 status 字段区分 empty(真没数据)与 degraded(上游/库查询失败);或改用 coupons(它以 502 暴露错误)。rec/top-sales 走离线库,prod 刚部署 ETL 未灌则返 empty——开内测前先手动跑一次 ETL。

6. 领券透传(coupon/step)

产品"一键领券"的核心接入点,真正的领券逻辑不在本服务——在另一个 repo pricebot-backend(GoalEngine + 事件驱动)。但 coupon/step 不是纯透传壳:它在转发 pricebot 之余,还best-effort 写库。(比价透传 compare.py 2026-07 起同样带落库副作用,见 §6.2——现在全站已没有"只转发不写库"的透传端点,只有 trace/epilogue 例外。)

客户端 → POST /api/v1/coupon/step  (任意 JSON body,含 device_id/trace_id/step)
  → coupon.py:不做 schema 校验,仅读 device_id/trace_id/step
  → [副作用1] step==0 → 写 coupon_prompt_engagement(claim_started)
  → async httpx 把 body 原样 POST 到 PRICEBOT_BASE_URL/api/coupon/step(按 trace_id 一致性 hash 选实例)
  → [副作用2] 从响应抽券结果(去重)→ 写 coupon_claim_record
  → [副作用3] action.command==done → 写 coupon_daily_completion(首页「去领取」卡置灰源)
  → 把 pricebot 的响应原样返回

三处写库(_mark_engagement_blocking / _record_claims_blocking / _mark_completed_blocking)全 best-effort:各自独立 session、经 run_in_threadpool 不阻塞事件循环,写失败只 logger.warning、绝不连累领券返回。判断维度是 device_id(user_id 可空旁路,仅资产留痕)。落库细节见 database/coupon_state.md。

MVP 不鉴权:已去掉 CurrentUser 依赖。device_id 透传给 pricebot 区分设备,但后端拿不到 user_id → 领券行为暂时绑不到登录用户(采集不到用户级画像)。待补 JWT,见 待办与技术债.md P1。
不做 schema 校验:body 原样透传,pricebot 自己校验。
错误:body 非合法 JSON → 400;pricebot 不可达或返回 5xx → 502。
配置:PRICEBOT_BASE_URL(默认 http://localhost:8000)、PRICEBOT_REQUEST_TIMEOUT_SEC(默认 30s,因领券单帧最多 wait 6s)。
现状:前端已接通——首页「去领取」→ CouponPromptDialog → 权限检查 → 无障碍引擎 startCouponClaim → 循环调本接口,逐张券下发 launch/wait/done。pricebot-backend 不在本目录。
配套:POST /coupon/session(#99)由客户端独立两段上报(发起建行/收尾更新)落 coupon_session 流水,供 admin「领券数据」看板算发起数/完成率/中途流失/耗时——与 step 透传链路解耦。

6.2 外卖比价透传:软鉴权 + trace_id 签发 + harvest 落库(2026-07)

compare.py 的 /intent/recognize、/intent/step、/intent/precoupon/step、/price/step、/trace/finalize、/trace/epilogue 透传 pricebot 之余,由 app-server 直接落库比价记录(不再依赖客户端 POST /compare/record):

客户端首帧(可不带 trace_id)
  → compare._forward:app-server 用 uuid 签发 trace_id、注入转发 body、回填响应顶层
  → [harvest_running] 仅 mint 那帧:按 trace_id 建 comparison_record 的 running 行
  → 后续帧原样透传(原始 bytes 快路,不再写库)
  → done 帧(price/step)→ [harvest_done] 写 success/failed + 派生 best_*/saved_amount_cents
  → 用户终止/未识别 → 客户端打 /trace/finalize → [harvest_abort] 写 cancelled/failed(不降级已 success)
  → /trace/epilogue(#112):App 结果页截图透传入 trace,纯透传、不落库

软鉴权(OptionalUser):新客户端带 JWT → 记录绑 user_id;老客户端不带 → user_id 暂空,由其后续带 JWT 的 POST /compare/record 上报补齐(灰度期两条写路径按 trace_id reconcile)。
写库全 best-effort:run_in_threadpool + 独立 SessionLocal,失败只 warning、绝不连累比价返回(同 coupon.py 口径)。
trace_url 从 pricebot 响应顶层取(pricebot 每帧都带);查看权限按 user.debug_trace_enabled 控制。
邀请发奖不在 harvest:#113 口径 = 好友「比价并下单」,发放在 POST /order/report(invite.try_reward_on_compare,compare_reward_granted 幂等闸,发邀请奖励金入独立账本)。
透传基建:core/pricebot_router.pick_pricebot(按 trace_id 一致性 hash 选实例)+ core/pricebot_client(共享 httpx 单例,#87)。

6.5 pricebot 回写:内部端点(server→server)

§6 是 app-server 透传给 pricebot;反过来 pricebot 也会把少量数据回写 app-server 落库,走 app/api/internal/* —— 不走用户 JWT,靠共享密钥头 X-Internal-Secret(== INTERNAL_API_SECRET,未配则 503,防裸奔写端点)校验。

启动确认窗兜底样本(2026-06):国产 ROM 打开别的 App 时弹"想要打开 XX"确认窗,pricebot 对没见过文案(繁体/英文/ROM 改版)的窗用 LLM 兜底放行后,把样本 POST 到 /internal/launch-confirm-sample 落 launch_confirm_sample 表(host 包 + 弹窗树 + LLM plan + 设备 locale/机型),供研发定期人工沉淀回 pricebot 的规则 yaml(回到快路径)。需 pricebot 与 app-server 两边 .env 配同一 INTERNAL_API_SECRET 才生效(未配则 pricebot 侧跳过上报、不影响比价/领券)。

同类内部回写端点(同走 X-Internal-Secret)还有:/internal/price-observation(价格观测)、/internal/store-mapping + /store-mapping/lookup + /store-mapping/invalidate(跨平台店铺映射沉淀/反查/失效)等 pricebot 比价资产沉淀;GET /internal/launch-confirm-samples(#91,样本列表供 pricebot distill_launch_confirm.py 聚合沉淀回静态规则);以及 /internal/app-version(OTA)——发布流程(非 pricebot)出 APK 后写最新版本号/下载链接/sha256 落 app_config,客户端再 GET /api/v1/platform/app-version 读做检查更新。完整 7 个内部端点见 api/internal/internal.md。

7. 数据模型

完整表清单不在本文维护(避免双份漂移)——共 45 张业务表 + alembic_version 框架表,逐表字段级说明 + 跨表关系/写入路径见 database/OVERVIEW.md(总览)与 database/README.md(一表一文件索引)。生产 PG / 开发可回退 SQLite。2026-06 下旬以来新增:coupon_session(#99)、analytics_event(#83)、invite_cash_transaction(#82)、admin_role(#117)、ad_pangle_daily_revenue(#92)。

本文只保留分层与高频维度的速查:数据访问统一在 repositories/,ORM 表结构在 models/(钱包/福利在 wallet.py/signin.py/task.py、比价在 comparison.py、领券今日状态在 coupon_state.py、CPS 群发在 cps_*.py、pricebot 内部沉淀在 price_observation.py/store_mapping.py/launch_confirm_sample.py、无障碍存活在 device.py)。下面单列最常用的 user 表字段。

user 表字段速查:

字段	类型	说明
id	INTEGER PK	自增
phone	VARCHAR(20) UNIQUE	登录主键(注销后变 `deleted_<id>` 占位)
register_channel	VARCHAR(20)	`jverify` / `sms`
nickname	VARCHAR(64) NULL	由 `PATCH /api/v1/user/profile` 写入
avatar_url	VARCHAR(512) NULL	相对路径(`/media/avatars/...`),由 `POST /api/v1/user/avatar` 写入
wechat_openid	VARCHAR(64) NULL UNIQUE	微信绑定(提现用),一个微信只绑一个账号
wechat_nickname / wechat_avatar_url	VARCHAR NULL	微信侧资料(绑定时拉取)
status	VARCHAR(20)	`active` / `disabled` / `deleted`,仅 active 可登录/鉴权
created_at / last_login_at	DATETIME(tz)

upsert_user_for_login:phone 存在则更新 last_login_at,不存在则注册(注册即登录)。

Alembic 迁移:alembic/versions/ 当前 98 个迁移文件(含 14+ 个合并迁移),当前单一 head admin_user_pages_override(2026-07-08,#126)。多人/多分支并行改表频繁产生多 head,靠 alembic merge 收敛回单 head。规模随改表增长,别背具体链,以 alembic history/alembic heads 实时输出为准。⚠️ revision id 长度 ≤32 字符(alembic_version 列宽,超长部署时截断报错——0.2.1 实踩)。详见数据库迁移.md。

8. 配置与部署

配置见 core/config.py(pydantic-settings 读 .env)。分组:环境、DATABASE_URL(默认 SQLite,生产应切 PG)、JWT(+独立 ADMIN_JWT_SECRET)、极光(JG_*)、短信(SMS_MOCK 默认 true)、美团(MT_CPS_*)、pricebot 上游(PRICEBOT_BASE_URL / 多实例 PRICEBOT_INSTANCES / PRICEBOT_REQUEST_TIMEOUT_SEC=30 / PRICEBOT_COMPARE_TIMEOUT_SEC=60)、内部密钥(INTERNAL_API_SECRET,internal 族)、穿山甲(PANGLE_*,含收益 API)、微信支付(WXPAY_*)、媒体存储(MEDIA_ROOT=./data/media / MEDIA_URL_PREFIX=/media)、CORS;运营可覆盖的业务常量在 core/config_schema.py 定义、app_config 表落值(admin GET/PATCH /config)。

生产部署(2026-06-06 起在 ecs1):双 systemd 服务 shaguabijia-app-server.service(uvicorn 127.0.0.1:8770,--workers 1)+ shaguabijia-admin.service(8771),WorkingDirectory /opt/shaguabijia-app-server,EnvironmentFile=.env,nginx 443 反代 app-api.shaguabijia.com → 8770。无 Docker。PostgreSQL 16 同机部署。代码走 git clone(main 分支)+ Gitea 只读部署密钥,日常发布用服务器上的 deploy 一键命令 / release.sh 发车 / deploy.shaguabijia.com 发车台(不再 rsync 整目录;secrets/ 私钥证书单独放置、不入 git)。

# 首次 PG 初始化(新机器或新环境):
ssh server "sudo apt install -y postgresql-16 && sudo systemctl enable --now postgresql"
ssh server "cd /opt/shaguabijia-app-server && .venv/bin/python scripts/init_postgres.py"
# 该脚本会建业务用户 + 建库 + 写 .env 的 DATABASE_URL + 跑 alembic upgrade head

# 日常部署(deploy 一键命令等价动作):
ssh server "cd /opt/shaguabijia-app-server && git pull && .venv/bin/alembic upgrade head \
  && systemctl restart shaguabijia-app-server shaguabijia-admin"

systemd 定时器(deploy/,各带 .md 运维手册):meituan-etl(美团 CPS 选品 ETL → meituan_coupon,rec/top-sales 数据源)、pangle-revenue(穿山甲 GroMore 后台收益拉取,每天 10:30,#100)、daily-exchange(金币自动兑换;lifespan 里另有 in-process worker,两套并存以部署材料为准)。

完整 PG 切换流程见 docs/database/postgres-migration.md。

生产 checklist(均为上线必查):

JWT_SECRET_KEY 改为高熵随机串——默认值 change-me 可被伪造 token
SMS_MOCK=false 并接真实短信供应商——mock 下任意 6 位码可登录任意手机号
MT_CPS_APP_KEY / MT_CPS_APP_SECRET 已填(未配凭证时美团 3 端点降级返空,前端首页空白)
PRICEBOT_BASE_URL 指向真实 pricebot-backend(否则领券 502)
RSA 私钥就位且与极光控制台公钥配对,权限 600
DATABASE_URL 已切 PG(默认 SQLite 单文件并发写锁库,扩 worker 立即撞墙)
psycopg3 已装(pip install "psycopg[binary]>=3.1")
MEDIA_ROOT 目录可写(头像/反馈截图落盘);建议 nginx 直接 serve 该目录绕过应用进程
APP_ENV=prod、APP_DEBUG=false、nginx SSL 有效、alembic upgrade head 已执行

9. 本地联调(真机)

conda activate price          # 首次:pip install -e .
./run.sh                       # 校验 .env → alembic 建表 → uvicorn 监听 0.0.0.0:8770

真机两种连法(详见前端文档):

adb reverse(推荐):adb reverse tcp:8770 tcp:8770,前端 debug.api.host=127.0.0.1,USB 直连不依赖 WiFi。
局域网 IP:前端 debug.api.host=<开发机 LAN IP>,手机电脑同 WiFi。

前端 debug 包对明文 HTTP 整体放行(src/debug 的 network_security_config),换 IP 只改 local.properties、无需改 xml。

10. 已知问题与后续

项	说明
logout 无服务端失效	靠客户端清 token;后续加 jti 黑名单表(注销账号也是同问题——软删后旧 token 仍能用到自然过期)
美团接口无鉴权 + sid 可覆盖	评估加鉴权/锁定 sid(注意首页要求未登录可见)
美团接口未配凭证降级	未配 `MT_CPS_APP_KEY` 时 3 端点返空(不报 502),`/feed` 跟"已配但调用失败"路径无法区分——见 integrations/meituan
领券/比价依赖 pricebot	执行核心在 pricebot-backend;比价透传 2026-07 起带 harvest 落库(§6.2),领券 `coupon/step` 带三表副作用,均非纯壳
领券 step 仍不鉴权;比价已软鉴权	比价透传族改 OptionalUser:带 JWT 即绑 `user_id`(用户级画像已能落到比价记录);`coupon/step` 仍拿不到 user_id(device 维度),老客户端比价记录靠 `/compare/record` 兜底补绑。见待办与技术债.md
SMS 已接极光(2026-06-03)	real 模式自定义验证码,上线只需 `SMS_MOCK=false`(复用极光凭证)。详见 integrations/sms
短信冷却存内存	扩 worker 前需迁移到 Redis
`MEDIA_ROOT` 进程内 serve	头像/反馈截图当前用 FastAPI StaticFiles,生产建议 nginx 直 serve 该目录
`init_postgres.py` 已知小 bug	5 条小坑,见待办与技术债.md
Alembic 多 head 风险	跨分支并行开发要在 PR 合并前 `alembic heads` 检查只有一个;漏检会出现 "Multiple head revisions",需要 `alembic merge` 合并

完整接口协议见 docs/api/(70+ 接口,一接口一文件 + /health + /media 静态服务),以 docs/api/README.md 索引和代码为准。

29 KiB Raw Permalink Blame History