gavindiaz/PolyWeather
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update docs for v1.5.3 release

Browse Source
This commit is contained in:
2569718930@qq.com
2026-04-10 08:04:25 +08:00
parent 27d4fc7c2b
commit a5eff0031c
10 changed files with 298 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CONFIGURATION_ZH.md
+65 -1
View File
@@ -110,6 +110,8 @@ PolyWeather 的环境变量很多，但不是所有变量都属于同一层级
- `TELEGRAM_ALERT_PUSH_ENABLED`
- `TELEGRAM_MARKET_FOCUS_DIGEST_ENABLED`
- `POLYMARKET_WALLET_ACTIVITY_ENABLED`（已退役，建议保持 `false`）
- `POLYWEATHER_DASHBOARD_PREWARM_ENABLED`
- `POLYWEATHER_GROQ_COMMENTARY_ENABLED`
### 4.3 L3：运行调优项
@@ -129,6 +131,15 @@ PolyWeather 的环境变量很多，但不是所有变量都属于同一层级
- `TELEGRAM_MARKET_FOCUS_DIGEST_TOP_N`
- `POLYWEATHER_PAYMENT_RPC_URLS`
- `TAF_CACHE_TTL_SEC`
- `POLYWEATHER_PREWARM_INTERVAL_SEC`
- `POLYWEATHER_PREWARM_JITTER_SEC`
- `POLYWEATHER_PREWARM_CITIES`
- `POLYWEATHER_PREWARM_INCLUDE_DETAIL`
- `POLYWEATHER_PREWARM_INCLUDE_MARKET`
- `POLYWEATHER_PREWARM_FORCE_REFRESH`
- `POLYWEATHER_GROQ_COMMENTARY_MODEL`
- `POLYWEATHER_GROQ_COMMENTARY_TIMEOUT_SEC`
- `POLYWEATHER_GROQ_COMMENTARY_CACHE_TTL_SEC`
策略：
@@ -148,6 +159,7 @@ PolyWeather 的环境变量很多，但不是所有变量都属于同一层级
- `METEOBLUE_API_KEY`
- `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID`
- `POLYMARKET_SECRET_KEY`
- `GROQ_API_KEY`
## 5. 推荐部署矩阵
@@ -173,6 +185,9 @@ PolyWeather 的环境变量很多，但不是所有变量都属于同一层级
- `POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN`
- `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID`
- `NEXT_PUBLIC_WALLETCONNECT_POLYGON_RPC_URL`
- `NEXT_PUBLIC_POLYWEATHER_APP_ANALYTICS`
- `NEXT_PUBLIC_POLYWEATHER_WEB_VITALS`
- `NEXT_PUBLIC_POLYWEATHER_EAGER_CITY_SUMMARIES`
说明：
@@ -203,6 +218,9 @@ NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
POLYWEATHER_AUTH_ENABLED=true
POLYWEATHER_AUTH_REQUIRED=true
NEXT_PUBLIC_POLYWEATHER_APP_ANALYTICS=false
NEXT_PUBLIC_POLYWEATHER_WEB_VITALS=false
NEXT_PUBLIC_POLYWEATHER_EAGER_CITY_SUMMARIES=false
```
### 6.2 后端最小变量
@@ -234,6 +252,16 @@ TELEGRAM_MARKET_FOCUS_DIGEST_ENABLED=true
TELEGRAM_MARKET_FOCUS_DIGEST_INTERVAL_SEC=1800
TELEGRAM_MARKET_FOCUS_DIGEST_TOP_N=5
POLYMARKET_WALLET_ACTIVITY_ENABLED=false
POLYWEATHER_DASHBOARD_PREWARM_ENABLED=true
POLYWEATHER_PREWARM_INTERVAL_SEC=300
POLYWEATHER_PREWARM_JITTER_SEC=20
POLYWEATHER_PREWARM_INCLUDE_DETAIL=true
POLYWEATHER_PREWARM_INCLUDE_MARKET=true
POLYWEATHER_BACKEND_URL=http://polyweather_web:8000
POLYWEATHER_GROQ_COMMENTARY_ENABLED=false
POLYWEATHER_GROQ_COMMENTARY_MODEL=openai/gpt-oss-20b
POLYWEATHER_GROQ_COMMENTARY_TIMEOUT_SEC=8
POLYWEATHER_GROQ_COMMENTARY_CACHE_TTL_SEC=1800
```
说明：
@@ -247,8 +275,44 @@ POLYMARKET_WALLET_ACTIVITY_ENABLED=false
- 机器人市场监控当前以 `关注清单` 为主，按固定间隔主动推送。
- `TELEGRAM_MARKET_FOCUS_DIGEST_INTERVAL_SEC` 表示主动推送间隔，默认 `1800` 秒（30 分钟）。
- `POLYMARKET_WALLET_ACTIVITY_ENABLED` 已退役，保留为 `false` 即可，不建议再启用钱包异动监听。
- `POLYWEATHER_DASHBOARD_PREWARM_ENABLED=true` 时，建议同时启用独立 worker 或 bot 内嵌预热线程。
- `POLYWEATHER_BACKEND_URL` 仅在独立 `polyweather_prewarm` worker 容器中使用，建议设为 `http://polyweather_web:8000`，不要写 `127.0.0.1`。
- `POLYWEATHER_GROQ_COMMENTARY_ENABLED=false` 表示默认仍走规则文案；只有在确实配置了 `GROQ_API_KEY` 时才建议开启。
### 6.3 机器人市场监控建议配置
### 6.3 Dashboard 预热 worker 推荐变量
```env
POLYWEATHER_DASHBOARD_PREWARM_ENABLED=true
POLYWEATHER_PREWARM_INTERVAL_SEC=300
POLYWEATHER_PREWARM_JITTER_SEC=20
POLYWEATHER_PREWARM_CITIES=ankara,istanbul,shanghai,beijing,shenzhen,wuhan,chengdu,chongqing,hong kong,taipei,london,paris,new york,los angeles
POLYWEATHER_PREWARM_INCLUDE_DETAIL=true
POLYWEATHER_PREWARM_INCLUDE_MARKET=true
POLYWEATHER_PREWARM_FORCE_REFRESH=false
POLYWEATHER_BACKEND_URL=http://polyweather_web:8000
```
说明：
- 这组变量用于后台定向预热热点城市，避免用户点击城市时才冷启动拉 detail。
- 如果使用独立 `polyweather_prewarm` 容器，`POLYWEATHER_BACKEND_URL` 必须指向容器网络中的 `polyweather_web`。
### 6.4 Groq 解读增强层
```env
POLYWEATHER_GROQ_COMMENTARY_ENABLED=true
GROQ_API_KEY=...
POLYWEATHER_GROQ_COMMENTARY_MODEL=openai/gpt-oss-20b
POLYWEATHER_GROQ_COMMENTARY_TIMEOUT_SEC=8
POLYWEATHER_GROQ_COMMENTARY_CACHE_TTL_SEC=1800
```
说明：
- 这层只负责把结构化信号改写成短摘要，不替代真实模型、机场锚点和结算逻辑。
- Groq 调用失败时，系统会自动回退到规则文案。
### 6.5 机器人市场监控建议配置
这套配置用于替代旧的钱包异动监听，围绕市场本身做两类推送：
docs/FRONTEND_DEPLOYMENT_ZH.md
+45 -1
View File
@@ -23,7 +23,7 @@
- Framework Preset: `Next.js`
- Root Directory: `frontend`
- Build Command: `npm run build`
- Install Command: `npm install`
- Install Command: `npm ci`
如果仓库已经连接过 Vercel，通常只需要确认 `Root Directory` 仍然是 `frontend`。
@@ -98,6 +98,20 @@ NEXT_PUBLIC_TELEGRAM_BOT_URL=https://t.me/WeatherQuant_bot
只影响按钮跳转，不影响核心页面加载。
### 6. 前端观测与预热开关（推荐默认关闭）
```env
NEXT_PUBLIC_POLYWEATHER_APP_ANALYTICS=false
NEXT_PUBLIC_POLYWEATHER_WEB_VITALS=false
NEXT_PUBLIC_POLYWEATHER_EAGER_CITY_SUMMARIES=false
```
说明：
- `NEXT_PUBLIC_POLYWEATHER_APP_ANALYTICS=false`：关闭前端自建埋点。
- `NEXT_PUBLIC_POLYWEATHER_WEB_VITALS=false`：关闭前端 Web Vitals 上报。
- `NEXT_PUBLIC_POLYWEATHER_EAGER_CITY_SUMMARIES=false`：关闭首页全量城市 summary 预热，避免白白消耗 Vercel function / edge 成本。
## 五、支付配置与旧部署治理
支付区现在有一层额外防护：
@@ -209,3 +223,33 @@ NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID
```
这是钱包连接的必需项。
## 十、Vercel 成本与节流建议
### 1. 建议先关闭的项目级能力
- `Web Analytics`
- `Speed Insights`
它们对排查前端体验有价值，但在 Hobby / 低预算阶段会额外消耗数据点和边缘资源。
### 2. 建议加的 Firewall 自定义规则
如果你的 Next.js 项目根本不提供 WordPress / PHP 路径，建议在 Vercel Firewall 里先 `Log` 再 `Deny` 这条规则：
```regex
(^/(wp-admin|wp-includes|wp-content|wp-login|wordpress|xmlrpc\.php))|\.php($|\?)
```
目的：
- 在边缘层提前拦截 WordPress / PHP 扫描流量
- 避免无效请求继续触发 middleware 与 route handler
### 3. 建议的上线前检查
除了功能本身，额外确认：
1. `Web Analytics` 和 `Speed Insights` 是否真的关闭
2. `NEXT_PUBLIC_POLYWEATHER_APP_ANALYTICS` / `NEXT_PUBLIC_POLYWEATHER_WEB_VITALS` / `NEXT_PUBLIC_POLYWEATHER_EAGER_CITY_SUMMARIES` 是否保持关闭
3. Firewall 自定义规则是否已从 `Log` 切到 `Deny`
docs/MONITORING_ZH.md
+34 -2
View File
@@ -1,6 +1,6 @@
# 外部监控与告警说明
最后更新：`2026-04-01`
最后更新：`2026-04-10`
## 1. 目标
@@ -105,7 +105,39 @@ python scripts/check_ops_health.py --base-url http://127.0.0.1:8000
任何一项失败都会非零退出，适合挂到 crontab 或 systemd timer。
## 8. 备注
## 8. 当前内置运行态观测
除了 Prometheus / Grafana 这套外部监控，当前后端还内置了更贴业务的只读运行态：
- `/api/system/status`
- `/ops`
目前已覆盖：
- `prewarm` worker 是否启用、线程 / heartbeat 是否活着
- 最近一轮 prewarm 的：
- `cycle_count`
- `success_count / failure_count`
- `last_started_at / last_finished_at`
- `last_summary_ok / last_detail_ok / last_market_ok`
- 缓存桶条目数：
- `api_cache`
- `metar`
- `taf`
- `nmc`
- `settlement`
- `open_meteo forecast / ensemble / multi-model`
- `summary` 分析缓存命中率：
- `total_requests`
- `cache_hits / cache_misses`
- `hit_rate / miss_rate`
这意味着：
- 外部监控负责“服务活没活、错误有没有暴增”
- `/ops` 和 `/api/system/status` 负责“预热有没有真的跑、缓存有没有真的被打热”
## 9. 备注
这套监控现在已经具备：
docs/OPS_ADMIN_ZH.md
+28 -1
View File
@@ -1,6 +1,6 @@
# Ops 运营后台说明
最后更新：`2026-04-01`
最后更新：`2026-04-10`
## 1. 入口
@@ -25,6 +25,8 @@ POLYWEATHER_OPS_ADMIN_EMAILS=yhrsc30@gmail.com
- 系统健康
- SQLite / rollout / metrics 摘要
- 支付运行态
- prewarm worker 运行态
- 缓存桶状态与 summary cache hit/miss
- 当前会员
- 周榜
- 支付异常单
@@ -99,6 +101,31 @@ python scripts/reconcile_subscription_by_email.py --email <user_email>
## 7. 备注
### 7.1 当前 prewarm / 缓存观测项
`/ops` 里的系统状态卡目前已额外展示：
- `prewarm` 是否启用
- `thread_alive` / `heartbeat_age_sec`
- 最近一轮：
- `cycle_count`
- `success_count / failure_count`
- `last_started_at / last_finished_at`
- `last_summary_ok / last_detail_ok / last_market_ok`
- 缓存桶数量：
- `api_cache`
- `metar`
- `taf`
- `nmc`
- `settlement`
- `open_meteo forecast / ensemble / multi-model`
- `summary` 层缓存命中率：
- `total_requests`
- `cache_hits / cache_misses`
- `hit_rate / miss_rate`
### 7.2 当前用途边界
`/ops` 是运营后台最小版，不是完整 Admin 平台。当前目标是：
- 让会员、积分、支付事故、系统状态可查