feat: build legacy practice navigation

2026-06-30 12:47:27 +08:00
parent fce5513464
commit d005f65fe7
12 changed files with 2460 additions and 11 deletions
--- a/docs/refactor/postgresql-4c16g-tuning.md
+++ b/docs/refactor/postgresql-4c16g-tuning.md
@@ -0,0 +1,230 @@
+# PostgreSQL 4 核 16G 生产调参基线
+
+更新时间：2026-06-30
+
+这份文档用于后续把 Supabase/PostgreSQL 自托管到 4 核 16G 云服务器时做生产起步配置。目标是先给题库 SaaS 一个安全、可回滚、可观测的基线，而不是追求一次性压满硬件。
+
+参考来源：
+
+- postgresqlco.nf Tuning Guide：https://postgresqlco.nf/tuning-guide
+- PostgreSQL 官方 Resource Consumption：https://www.postgresql.org/docs/current/runtime-config-resource.html
+- PostgreSQL 官方 Query Planning：https://www.postgresql.org/docs/current/runtime-config-query.html
+- 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 的页面可作为参数分类和调参入口参考；具体参数语义、重启要求和风险以 PostgreSQL 官方文档为准。
+
+## 适用前提
+
+- 单台 4 vCPU、16 GB RAM 云服务器。
+- 同机可能运行 Supabase 服务、API、worker、Nginx、日志/监控 agent。
+- 数据库以题库读多写少、后台批量导入、支付/订单小事务、学习记录持续写入为主。
+- 生产必须使用 SSD 云盘，数据库数据盘和备份盘分开更好。
+
+如果 PostgreSQL 是唯一重负载服务，可以使用下方 `dedicated-db` 值；如果 API/worker/Nginx 也在同机，先使用 `shared-host` 值。
+
+## 推荐起步值
+
+| 参数 | shared-host 起步值 | dedicated-db 起步值 | 说明 |
+| --- | --- | --- | --- |
+| `max_connections` | `80` | `120` | 4 核机器不宜靠大量直连抗并发；API 侧连接池和 Supabase pooler 更重要 |
+| `shared_buffers` | `3GB` | `4GB` | 官方建议专用库可从约 25% RAM 起步；同机多服务要给 OS cache 和应用留空间 |
+| `effective_cache_size` | `10GB` | `12GB` | 这是优化器估算值，不实际占内存 |
+| `work_mem` | `16MB` | `16MB` | 每个排序/哈希操作都可能分配一次，不按连接数简单相乘 |
+| `maintenance_work_mem` | `512MB` | `768MB` | 导入、建索引、VACUUM 可受益；注意 autovacuum worker 并发 |
+| `autovacuum_work_mem` | `256MB` | `256MB` | 避免多个 autovacuum 同时吃掉过多内存 |
+| `wal_buffers` | `16MB` | `16MB` | 默认自动通常够用；16MB 是常见稳妥上限 |
+| `min_wal_size` | `1GB` | `2GB` | 给批量导入和写入波峰预留 WAL |
+| `max_wal_size` | `6GB` | `8GB` | 减少频繁 checkpoint；值越大，崩溃恢复时间可能更长 |
+| `checkpoint_timeout` | `10min` | `15min` | 降低 checkpoint 频率；配合 `max_wal_size` 观察恢复窗口 |
+| `checkpoint_completion_target` | `0.9` | `0.9` | 平滑 checkpoint I/O |
+| `effective_io_concurrency` | `100` | `100` | SSD 云盘起步值；机械盘不适用 |
+| `random_page_cost` | `1.1` | `1.1` | SSD 上鼓励合理索引扫描；上线后用 EXPLAIN 复核 |
+| `jit` | `off` | `off` | 题库 API 多为短查询，先避免 JIT 带来的计划开销 |
+| `log_min_duration_statement` | `500ms` | `500ms` | 上线初期捕捉慢 SQL；稳定后可调到 `1000ms` |
+| `idle_in_transaction_session_timeout` | `60s` | `60s` | 防止后台或脚本长事务占锁 |
+| `statement_timeout` | `30s` | `30s` | API 请求不应长期占用数据库；导入脚本用会话级覆盖 |
+| `lock_timeout` | `5s` | `5s` | 防止普通请求长时间等锁 |
+
+## 应用连接池边界
+
+4 核机器的关键不是把 `max_connections` 拉大，而是控制同时活跃 SQL 的数量。
+
+建议：
+
+- `apps/api` 主进程连接池：`DB_POOL_MAX=10` 到 `20`。
+- `apps/worker` 每类 worker 连接池：`DB_POOL_MAX=4` 到 `8`。
+- 导入、导出、对账、公共题库同步等 worker 不要全部高并发同时跑。
+- H5/Taro 前端永远不直连数据库，只走 Supabase Auth 或 `apps/api`。
+- 生产如使用 Supabase pooler，应限制事务池大小，避免 API 扩容后数据库连接被打满。
+
+## ALTER SYSTEM 示例
+
+上线前先保存当前值：
+
+```sql
+select name, setting, unit, source, pending_restart
+from pg_settings
+where name in (
+  'max_connections',
+  'shared_buffers',
+  'effective_cache_size',
+  'work_mem',
+  'maintenance_work_mem',
+  'autovacuum_work_mem',
+  'wal_buffers',
+  'min_wal_size',
+  'max_wal_size',
+  'checkpoint_timeout',
+  'checkpoint_completion_target',
+  'effective_io_concurrency',
+  'random_page_cost',
+  'jit',
+  'log_min_duration_statement',
+  'idle_in_transaction_session_timeout',
+  'statement_timeout',
+  'lock_timeout'
+)
+order by name;
+```
+
+同机部署推荐先执行：
+
+```sql
+alter system set max_connections = '80';
+alter system set shared_buffers = '3GB';
+alter system set effective_cache_size = '10GB';
+alter system set work_mem = '16MB';
+alter system set maintenance_work_mem = '512MB';
+alter system set autovacuum_work_mem = '256MB';
+alter system set wal_buffers = '16MB';
+alter system set min_wal_size = '1GB';
+alter system set max_wal_size = '6GB';
+alter system set checkpoint_timeout = '10min';
+alter system set checkpoint_completion_target = '0.9';
+alter system set effective_io_concurrency = '100';
+alter system set random_page_cost = '1.1';
+alter system set jit = 'off';
+alter system set log_min_duration_statement = '500ms';
+alter system set idle_in_transaction_session_timeout = '60s';
+alter system set statement_timeout = '30s';
+alter system set lock_timeout = '5s';
+select pg_reload_conf();
+```
+
+以下参数需要重启 PostgreSQL 才会生效：`max_connections`、`shared_buffers`、`wal_buffers`。执行后用下面语句确认：
+
+```sql
+select name, setting, unit, pending_restart
+from pg_settings
+where pending_restart = true
+order by name;
+```
+
+## 导入脚本会话级覆盖
+
+真实迁移导入、批量导入、建索引可能超过普通 API 的 `statement_timeout`。不要为了导入放大生产全局超时，应该在导入连接上局部设置：
+
+```sql
+set statement_timeout = '30min';
+set lock_timeout = '30s';
+set maintenance_work_mem = '1GB';
+```
+
+正式切换仍以 `pb:import:dry-run --profile=production`、`pb:import:json`、`pb:import:validate` 和业务抽样为准。
+
+## 观察和验收
+
+上线后至少观察 24 到 72 小时：
+
+```sql
+select state, wait_event_type, wait_event, count(*)::int
+from pg_stat_activity
+where datname = current_database()
+group by state, wait_event_type, wait_event
+order by count desc;
+```
+
+```sql
+select datname, xact_commit, xact_rollback, blks_read, blks_hit,
+       round(blks_hit * 100.0 / nullif(blks_hit + blks_read, 0), 2) as cache_hit_ratio
+from pg_stat_database
+where datname = current_database();
+```
+
+```sql
+select checkpoints_timed, checkpoints_req, checkpoint_write_time, checkpoint_sync_time
+from pg_stat_bgwriter;
+```
+
+```sql
+select pid, usename, now() - xact_start as xact_age, state, query
+from pg_stat_activity
+where xact_start is not null
+order by xact_age desc
+limit 20;
+```
+
+验收标准：
+
+- API P95 延迟稳定，没有大量 `ClientRead/ClientWrite`、锁等待或 I/O wait。
+- `pb:import:validate` 无 failure。
+- `checkpoints_req` 不应持续快速增长；如增长明显，优先调大 `max_wal_size` 或检查写入峰值。
+- 没有 OOM、没有频繁连接耗尽、没有长时间 idle in transaction。
+- 慢 SQL 日志能对应到具体接口、worker 或迁移脚本。
+
+## 压测闭环
+
+调参后必须跑 API 压测，不要只凭参数表判断容量。当前仓库提供本地压测脚本：
+
+```bash
+npm run perf:api:local
+```
+
+默认压测只读路径，会自动发现真实迁移后的租户、学生、题库入口、合集、蓝图、单词和手册数据，并输出报告到已忽略的 `docs/refactor/performance-reports/`。详细环境变量、4 核 16G 阶梯并发矩阵和报告归档方式见：
+
+- `docs/refactor/performance-benchmark-runbook.md`
+
+4 核 16G 首次上云建议至少跑：
+
+- `smoke`：6 并发 30 秒，只读。
+- `baseline-30`：30 并发 5 分钟，只读。
+- `baseline-50`：50 并发 5 分钟，只读。
+- `mixed-30`：30 并发 5 分钟，开启少量练习 session 写入。
+
+若 P95/P99 明显升高，优先结合慢 SQL、`pg_stat_activity` 和报告中的接口明细定位，再考虑索引、预聚合、连接池和 worker 调度；不要直接继续放大 `max_connections`。
+
+## 回滚方式
+
+如果调参后出现内存压力、启动失败或查询计划异常：
+
+```sql
+alter system reset shared_buffers;
+alter system reset effective_cache_size;
+alter system reset work_mem;
+alter system reset maintenance_work_mem;
+alter system reset autovacuum_work_mem;
+alter system reset wal_buffers;
+alter system reset min_wal_size;
+alter system reset max_wal_size;
+alter system reset checkpoint_timeout;
+alter system reset checkpoint_completion_target;
+alter system reset effective_io_concurrency;
+alter system reset random_page_cost;
+alter system reset jit;
+alter system reset log_min_duration_statement;
+alter system reset idle_in_transaction_session_timeout;
+alter system reset statement_timeout;
+alter system reset lock_timeout;
+select pg_reload_conf();
+```
+
+若 `shared_buffers`、`wal_buffers`、`max_connections` 已改，需要重启后才算完全回滚。
+
+## 后续优化方向
+
+- 上线后启用 `pg_stat_statements`，按总耗时和平均耗时定位慢 SQL。
+- 为 `answer_records`、`practice_sessions`、`content_asset_access_events`、`video_play_events` 等大表规划按月或按租户分区。
+- 对租户后台 dashboard、排行榜、销售转化、分佣报表做日/小时预聚合。
+- 对真实 `pb:import:json` 增加阶段耗时统计，继续批量化 `questions/question_versions`。
+- 如果三套 H5、API、worker、Supabase 全部同机，优先加连接池和 worker 调度，而不是继续放大 PostgreSQL 内存参数。