zhuzihao
357b2312af
为 #92 的 scripts/sync_pangle_revenue.py 补 systemd 部署单元,让穿山甲 GroMore T+1 后台收益每天自动拉取入库,免人工敲命令。纯部署/文档文件,不改运行时代码。 - service:oneshot,跑 `--days 3` 回补近 3 天(幂等 upsert,扛偶发漏跑与穿山甲历史订正);10min 硬超时;加固块对齐主服务。 - timer:每天 10:30 触发(穿山甲约 10:00 出数留余量),Persistent 宕机后补跑。 - md:运维手册——上线前置(.env 填 PANGLE_REPORT_* 凭证、子账号需授权否则接口 118)、部署/健康检查/参数/注意事项(join key 用 ad_unit_id 非 code_id 等)。 - 风格对齐现有 deploy/daily-exchange.* 与 deploy/meituan-etl.*。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: zzhyyyyy <2685922758@qq.com> Reviewed-on: #100 Co-authored-by: zhuzihao <zhuzihao@wonderable.ai> Co-committed-by: zhuzihao <zhuzihao@wonderable.ai>
68 lines
4.6 KiB
Markdown
68 lines
4.6 KiB
Markdown
# 穿山甲 GroMore 收益拉取 定时任务 — 运维手册
|
||
|
||
> 对象:维护「每天拉穿山甲后台收益入库」这套定时任务的同事。
|
||
> 🔒 服务器登录信息见**私密交接清单**,不入库。
|
||
|
||
## 它是什么
|
||
admin「广告收益报表」里的「穿山甲后台收益(T+1)」读的是**本地表 `ad_pangle_daily_revenue` 的快照,不是实时查穿山甲**。穿山甲只通过 GroMore 数据 API 给数、且 **T+1**(次日约 10:00 出昨天的数),所以每天得拉一次入库,报表才会往前走。
|
||
|
||
- 每天 10:30 跑一轮 `scripts/sync_pangle_revenue.py`,默认 `--days 3` 回补近 3 天。
|
||
- 维度 = 日期 × 应用(site_id)× 广告位(ad_unit_id);指标 = `revenue`(预估)+ `api_revenue`(结算口径)。
|
||
- **幂等 upsert**:同一(日期×应用×代码位)重跑只覆盖、不重复,故回补 / 重跑 / catch-up 都安全。
|
||
- 穿山甲无用户/设备维度 → 只能落「汇总/趋势级」,报表带 user_id 过滤时这块收益置空(显示「-」)。
|
||
|
||
## 文件
|
||
| 项 | 路径 |
|
||
|---|---|
|
||
| 脚本入口 | `scripts/sync_pangle_revenue.py` |
|
||
| 拉取 / 签名 | `app/integrations/pangle_report.py`(签名=参数字典序拼接+secure_key 后 MD5) |
|
||
| 入库表 | `ad_pangle_daily_revenue`(读写在 `app/repositories/ad_pangle_revenue.py`) |
|
||
| 凭证 | `.env` 的 `PANGLE_REPORT_USER_ID` / `PANGLE_REPORT_ROLE_ID` / `PANGLE_REPORT_SECURITY_KEY` |
|
||
| 应用映射 | `.env` 的 `PANGLE_REPORT_SITE_ID_PROD`(5830519)/ `PANGLE_REPORT_SITE_ID_TEST`(5832303) |
|
||
| systemd 单元 | `deploy/pangle-revenue.{service,timer}` |
|
||
|
||
## 上线前置(只做一次)
|
||
1. **填凭证**:后台「接入中心 → GroMore-API」领 user_id / role_id / Security Key(`secure_key`,**≠ 发奖 m-key**),填进线上 `.env` 的 `PANGLE_REPORT_*`。三项填齐脚本才工作,缺任一 → no-op 退出。
|
||
2. **子账号要授权**:线上若用子账号(role_id ≠ user_id),需主账号给它授「查看全部数据」,否则接口报 **118**(无权限)。本人自查自己(user_id=role_id)无此问题。
|
||
3. 凭证泄露:后台「重置 key 值」即可,改完同步线上 `.env` 重跑。
|
||
|
||
## 部署(Linux 服务器,需 root)
|
||
```bash
|
||
sudo cp deploy/pangle-revenue.{service,timer} /etc/systemd/system/
|
||
sudo systemctl daemon-reload && sudo systemctl enable --now pangle-revenue.timer
|
||
systemctl list-timers pangle-revenue.timer # 确认下次触发时间(应是次日 10:30)
|
||
```
|
||
|
||
## 怎么看健康 / 手动跑一次
|
||
```bash
|
||
sudo systemctl start pangle-revenue.service # 立即手动跑一轮(不等 10:30)
|
||
journalctl -u pangle-revenue -n 30 --no-pager # 看日志:拉取区间 / 入库行数 / 新增更新 / 预估收益合计
|
||
```
|
||
成功日志形如:`✅ 完成:接口 N 行 → 入库 M 行(跳过 x),新增 a / 更新 b;预估收益合计 ¥19.42`。
|
||
> 看不到收益、提示 `PANGLE_REPORT_* 未配置`→ 回「上线前置」补 `.env`;报 118 → 子账号没授「查看全部数据」。
|
||
|
||
## 本机 Windows 开发(无 systemd)
|
||
直接手动跑:
|
||
```
|
||
.venv\Scripts\python -m scripts.sync_pangle_revenue # 拉昨天
|
||
.venv\Scripts\python -m scripts.sync_pangle_revenue --days 3 # 回补近 3 天
|
||
.venv\Scripts\python -m scripts.sync_pangle_revenue --date 2026-06-27 # 指定单天
|
||
.venv\Scripts\python -m scripts.sync_pangle_revenue --start 2026-06-01 --end 2026-06-27 # 区间回补
|
||
```
|
||
|
||
## 脚本参数
|
||
- 无参:拉**昨天**(北京时间)。timer 用的是 `--days 3`。
|
||
- `--days N`:从昨天起往前回补 N 天(含昨天)。
|
||
- `--date YYYY-MM-DD`:指定单天。
|
||
- `--start / --end`:指定闭区间(跨度 ≤ 31 天,接口上限 1 个月,超了报 114)。
|
||
|
||
## 注意事项
|
||
- **触发时间**:`OnCalendar=*-*-* 10:30:00`。穿山甲 ~10:00 出数,故别早于 10:00 跑(会拉到空/不全)。
|
||
- **catch-up**:`Persistent=true` 补跑错过的那一轮;叠加 `--days 3`,漏一两天重新触发即自愈。
|
||
- **今天 / 今天以前要分开查**:脚本默认只拉昨天及更早,不混查今天(接口约束),无需关心。
|
||
- **join key 是 `ad_unit_id`(我们配的 104xxx)不是 `code_id`**:`code_id` 是底层各 ADN 代码位,对不上口径;`ad_unit_id='-1'` 是未归因桶。改维度时务必注意(详见脚本头注释)。
|
||
- **`api_revenue` 很稀疏**:测试应用 ADN 没配 Reporting → 全 0,仅 prod 个别位有;`revenue`(预估)才是稳的主力。
|
||
- **DB 无关**:sqlite / postgres 均可(upsert 逐行 select-then-write,不像美团 ETL 需要 PG)。
|
||
- **别和别的触发方式双跑**:本 systemd timer 与「手动 cron / 进程内任务」二选一,虽幂等不会重复入库,纯属多余。
|
||
- **改脚本 / 改部署**:走 git + PR,由有 root 的人部署。
|