Add config validation and deployment docs

2026-03-20 22:00:02 +08:00
parent 3196552c78
commit f6771247a6
13 changed files with 849 additions and 102 deletions
@@ -1,12 +1,33 @@
+# PolyWeather 前端最小配置（本地 / Vercel）
+# 只部署天气看板时，先填下面 4 项即可。
+
+# 必填：后端 FastAPI 基础地址
 POLYWEATHER_API_BASE_URL=http://127.0.0.1:8000
-# Supabase Auth (Google + Email)
+
+# 必填：Supabase 前端公钥（鉴权开启时必须）
 NEXT_PUBLIC_SUPABASE_URL=
 NEXT_PUBLIC_SUPABASE_ANON_KEY=
+
+# 常用：前端鉴权开关
+# true: 启用 Supabase 登录
+# false: 关闭登录能力，访客模式
 POLYWEATHER_AUTH_ENABLED=false
-# If true: middleware forces login; if false: optional login mode (guests allowed).
+
+# 常用：是否强制登录
+# true: middleware 强制登录后才能访问主页面
+# false: 登录可选，访客可浏览
 POLYWEATHER_AUTH_REQUIRED=false
-# Optional dashboard guard (Next.js middleware)
-# If set, open dashboard with: /?access_token=<token>
+
+# 可选：分享式看板访问令牌
+# 设置后，可通过 /?access_token=<token> 打开受保护看板
 POLYWEATHER_DASHBOARD_ACCESS_TOKEN=
-# Shared secret forwarded by Next API routes to backend
+
+# 可选：前端 API Route 转发到后端时附带的共享令牌
+# 仅当后端启用了 entitlement / 订阅校验时需要
 POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN=
+
+# 可选：钱包支付 / Telegram 入口
+NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=
+NEXT_PUBLIC_WALLETCONNECT_POLYGON_RPC_URL=https://polygon-bor-rpc.publicnode.com
+NEXT_PUBLIC_TELEGRAM_GROUP_URL=https://t.me/your_group
+NEXT_PUBLIC_TELEGRAM_BOT_URL=https://t.me/WeatherQuant_bot
@@ -28,30 +28,53 @@ npm install
 npm run dev
 ```

-## 必需环境变量
+## Vercel 最小部署配置
+
+只跑看板和基础鉴权时，先填这 4 项：

 ```env
 POLYWEATHER_API_BASE_URL=https://<your-fastapi-host>
-NEXT_PUBLIC_SUPABASE_URL=
-NEXT_PUBLIC_SUPABASE_ANON_KEY=
+NEXT_PUBLIC_SUPABASE_URL=https://<your-supabase-project>.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=<your-anon-key>
 POLYWEATHER_AUTH_ENABLED=true
-POLYWEATHER_AUTH_REQUIRED=false
-POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN=
 ```

-WalletConnect：
+建议显式补：

 ```env
+POLYWEATHER_AUTH_REQUIRED=true
+```
+
+如果你只是开放游客浏览，可改成：
+
+```env
+POLYWEATHER_AUTH_ENABLED=false
+POLYWEATHER_AUTH_REQUIRED=false
+```
+
+## 可选环境变量
+
+仅在对应功能启用时填写：
+
+```env
+# 看板分享令牌
+POLYWEATHER_DASHBOARD_ACCESS_TOKEN=
+
+# 前端 API 转发到后端时使用的共享令牌
+POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN=
+
+# 钱包支付
 NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=
 NEXT_PUBLIC_WALLETCONNECT_POLYGON_RPC_URL=https://polygon-bor-rpc.publicnode.com
-```

-浮层链接：
-
-```env
+# 社群入口
 NEXT_PUBLIC_TELEGRAM_GROUP_URL=https://t.me/<your_group>
+NEXT_PUBLIC_TELEGRAM_BOT_URL=https://t.me/WeatherQuant_bot
 ```

+更完整的 Vercel 配置说明见：
+- [docs/FRONTEND_DEPLOYMENT_ZH.md](/E:/web/PolyWeather/docs/FRONTEND_DEPLOYMENT_ZH.md)
+
 ## 路由处理器

 天气：
@@ -90,4 +113,4 @@ NEXT_PUBLIC_TELEGRAM_GROUP_URL=https://t.me/<your_group>

 详见根目录策略文档：`docs/OPEN_CORE_POLICY.md`

-最后更新：`2026-03-14`
+最后更新：`2026-03-20`