forked from wangziqi/gongxue-base
docs: align web launch checks and postgres tuning
This commit is contained in:
Codex
@@ -12,7 +12,7 @@
|
||||
- PostgreSQL 官方 WAL/Checkpoint：https://www.postgresql.org/docs/current/runtime-config-wal.html
|
||||
- PostgreSQL 官方 Connections：https://www.postgresql.org/docs/current/runtime-config-connection.html
|
||||
|
||||
说明：postgresqlco.nf 的 tuning guide 适合作为 `postgresql.conf` 参数分类和调参入口参考；具体参数语义、重启要求、风险边界和版本差异仍以 PostgreSQL 官方文档为准。当前 Codex 环境直接访问 `https://postgresqlco.nf/tuning-guide` 会返回 403，因此落地值不直接抓取该站页面，而是把它作为导航来源，并以 PostgreSQL 官方文档、本项目真实压测结果和上线可观测性共同校验。
|
||||
说明：postgresqlco.nf 的 tuning guide 适合作为 `postgresql.conf` 参数分类和调参入口参考；具体参数语义、重启要求、风险边界和版本差异仍以 PostgreSQL 官方文档为准。如果当前网络环境无法直接打开 `https://postgresqlco.nf/tuning-guide`，不要用第三方转载内容直接替代生产参数，应继续以 PostgreSQL 官方文档、本项目真实压测结果和上线可观测性共同校验。
|
||||
|
||||
## 适用前提
|
||||
|
||||
@@ -23,6 +23,19 @@
|
||||
|
||||
如果 PostgreSQL 是唯一重负载服务，可以使用下方 `dedicated-db` 值；如果 API/worker/Nginx 也在同机，先使用 `shared-host` 值。
|
||||
|
||||
## 2026-07-01 调参复核结论
|
||||
|
||||
本轮按 postgresqlco.nf 的参数导航重新对照 PostgreSQL 官方文档后，保留当前 `shared-host` profile，不把 4 核 16G 机器简单按“数据库独占”调满。原因：
|
||||
|
||||
- `shared_buffers`：官方文档说明专用数据库服务器可从约 25% 内存起步，超过 40% 通常不一定更好，因为 PostgreSQL 仍依赖操作系统缓存。同机还要运行 Supabase/API/worker/Nginx，因此 `shared-host=3GB` 比 4GB 更保守；独立数据库主机才使用 `dedicated-db=4GB`。
|
||||
- `effective_cache_size`：它只是 planner 对共享缓冲和 OS cache 的估算，不会真实预留内存。`shared-host=10GB` 用来引导 SSD 上合理使用索引，但上线后必须结合 `EXPLAIN (ANALYZE, BUFFERS)` 与慢 SQL 复核。
|
||||
- `work_mem`：官方文档强调它是每个排序/哈希操作的基准，不是每个连接的总内存。后台报表、导入和复杂查询可能一次使用多份 `work_mem`，所以 `16MB` 是上线起步值，不建议在未观察 temp file spill 和 OOM 风险前直接放大。
|
||||
- `maintenance_work_mem` / `autovacuum_work_mem`：导入、建索引和 vacuum 会受益，但 autovacuum 多 worker 并发时可能叠加占用内存，因此保留 `512MB/256MB`。
|
||||
- `random_page_cost=1.1`：SSD 云盘下可以鼓励索引扫描，但官方文档也提示 planner cost 没有统一理想值，不能只凭单个查询实验盲调。上线后以真实慢 SQL、缓存命中和查询计划为准。
|
||||
- `max_connections=80`：4 vCPU 不靠大量直连抗并发，优先控制 API/worker 连接池和 Supabase pooler。连接数放大只会把数据库推向上下文切换、锁等待和内存压力。
|
||||
|
||||
本地 DB 受限压测已经证明：只限制容器 CPU/内存但不调 PostgreSQL 参数时，系统可以保持 0 错误，但 P95 延迟不满足上线门禁。因此生产验收必须按“调参证据 + API 阶梯压测 + 慢 SQL/pg_stat_statements”闭环完成，而不是只填一组参数。
|
||||
|
||||
## 推荐起步值
|
||||
|
||||
| 参数 | shared-host 起步值 | dedicated-db 起步值 | 说明 |
|
||||
|
||||
@@ -197,7 +197,7 @@ H5 正式回归时建议把前端登录态切到 Supabase Auth，并观察业务
|
||||
node scripts/taro-h5-release-guardrails-test.js --require-dist
|
||||
```
|
||||
|
||||
`smoke:taro:h5` 会用临时静态服务器检查三套 H5 产物可托管、资源可加载、history fallback 可用，并用 mock API 验证租户解析契约。`smoke:taro:h5:interaction` 会用真实 Chrome/Edge 打开三套发布产物并点击学生刷题/收藏/会员、租户题库内容/财务、平台租户/账务中心关键路径；若服务器没有默认浏览器，可设置 `TARO_H5_SMOKE_BROWSER=/path/to/chrome`。`manifest:taro:h5` 会生成三套 H5 的部署清单，包含构建命令、发布目录、入口路由、`index.html` hash、资源数量、runtime-config 是否存在、租户解析模式和公开配置状态。发布守卫会检查三套 H5 产物是否存在 `index.html`，源码和产物是否混入 `x-user-id`、`x-platform-admin-key`、PocketBase 引用、数据库连接串、服务端密钥形态，并检查运行时配置示例只包含公开字段。若还没有把真实 `runtime-config.json` 放入静态目录，会显示 warning；正式发布前必须在每个 H5 目录根部补齐该文件。
|
||||
`smoke:taro:h5` 会用临时静态服务器检查三套 H5 产物可托管、资源可加载、history fallback 可用，并用 mock API 验证租户解析契约。`smoke:taro:h5:interaction` 会用真实 Chrome/Edge 打开三套发布产物并点击 32 项关键路径：学生刷题、收藏、错题/收藏复习、背单词、知识手册、资料、视频、分数线、AI 择校、消息、会员下单和订单状态，租户后台内容导入、公共题库采纳/同步/冲突处理、学生运营、营销/CRM/分佣、主题/角色/成员写操作，以及平台后台租户、账务、公共题库授权和员工写操作；若服务器没有默认浏览器，可设置 `TARO_H5_SMOKE_BROWSER=/path/to/chrome`。`manifest:taro:h5` 会生成三套 H5 的部署清单，包含构建命令、发布目录、入口路由、`index.html` hash、资源数量、runtime-config 是否存在、租户解析模式和公开配置状态。发布守卫会检查三套 H5 产物是否存在 `index.html`，源码和产物是否混入 `x-user-id`、`x-platform-admin-key`、PocketBase 引用、数据库连接串、服务端密钥形态，并检查运行时配置示例只包含公开字段。若还没有把真实 `runtime-config.json` 放入静态目录，会显示 warning；正式发布前必须在每个 H5 目录根部补齐该文件。
|
||||
|
||||
写入 `production-launch-evidence.json` 的正式证据必须使用严格模式，确保三套发布目录都已放置真实公开 `runtime-config.json` 且没有 warning：
|
||||
|
||||
|
||||
@@ -90,7 +90,7 @@ node scripts/taro-h5-release-guardrails-test.js --require-dist
|
||||
npm run smoke:launch-persona
|
||||
```
|
||||
|
||||
`smoke:taro:h5` 会启动临时静态服务器和 mock API，验证三套 H5 的 `index.html`、JS/CSS 资源、history fallback、公开 runtime config 和 `/api/tenant/resolve` 契约。`smoke:taro:h5:interaction` 会在真实 Chrome/Edge 中点击学生、租户后台、平台后台关键路径，覆盖静态烟测发现不了的 JS 运行时、直接 history 路由刷新和 Taro 点击事件问题；当前脚本覆盖 26 项检查，包括学生首页、题库、答题、收藏、错题/收藏复习、背单词、知识手册、资料短签名和水印、视频播放授权、分数线、AI 择校、消息中心、会员收银台下单/支付参数/订单状态，租户后台六个主模块，以及平台后台四个主模块。`taro-h5-release-guardrails-test` 会扫描源码、三套 H5 产物和 runtime-config 边界，防止旧 PocketBase、`x-user-id`、`x-platform-admin-key`、数据库连接串和服务端密钥形态进入前端发布目录。若刚构建完但未放入真实 `runtime-config.json`，脚本允许 warning；正式部署目录必须补齐。
|
||||
`smoke:taro:h5` 会启动临时静态服务器和 mock API，验证三套 H5 的 `index.html`、JS/CSS 资源、history fallback、公开 runtime config 和 `/api/tenant/resolve` 契约。`smoke:taro:h5:interaction` 会在真实 Chrome/Edge 中点击学生、租户后台、平台后台关键路径，覆盖静态烟测发现不了的 JS 运行时、直接 history 路由刷新和 Taro 点击事件问题；当前脚本覆盖 32 项检查，包括学生首页、题库、答题、收藏、错题/收藏复习、背单词、知识手册、资料短签名和水印、视频播放授权、分数线、AI 择校、消息中心、会员收银台下单/支付参数/订单状态，租户后台内容导入、公共题库采纳/同步/冲突处理、学生运营、营销/CRM/分佣、主题/角色/成员写操作，以及平台后台租户、账务、公共题库授权和员工写操作。`taro-h5-release-guardrails-test` 会扫描源码、三套 H5 产物和 runtime-config 边界，防止旧 PocketBase、`x-user-id`、`x-platform-admin-key`、数据库连接串和服务端密钥形态进入前端发布目录。若刚构建完但未放入真实 `runtime-config.json`，脚本允许 warning；正式部署目录必须补齐。
|
||||
|
||||
写入生产上线证据时，三套正式发布目录必须先放入真实公开 `runtime-config.json`，再运行严格模式：
|
||||
|
||||
|
||||
Reference in New Issue
Block a user