01 系统架构设计

分册定位：本册是《播客目录展示服务》交付文档的架构总览，面向工程师与 AI Agent，描述实际落地的三端系统（数据底座 / 服务端 / 桌面客户端）。 真源对照：架构决策真源为 deepresearch_podcast-catalog-api-architecture_20260604_v4.md（下称 v4）；实际部署见 DELIVERY.md；依赖链与运维见 docs/SERVICE-OPS.md。 真实性约定：所有"已落地"结论均给出 file_path:line 锚点；v4 设计但本项目未做/简化的，统一在 §7 标注，正文不臆造。 最后更新：2026-06-11。

0. 一页速览（TL;DR）

与 v4 最大的落地差异：v4 推荐 k8s 多副本容器 + Redis 7 + ioredis + JWT/API Key 双层鉴权；本项目落地为 单机 colima 容器 + PostgreSQL 单库 + 进程内缓存 + 固定 token 内网鉴权。v4 中框架无关的契约（数据库 Schema、REST/keyset 分页、错误码、音频不代理）原样落地；v4 中为公网高并发设计的部分（Redis、k8s、JWT 轮换、CORS）按"内网单机"现实裁掉或降级。

1. 项目定位与全景

1.1 一句话定位

为公司内网提供一个只读的播客目录展示与播放服务：服务端把一份离线构建的播客数据集（dataset.7z）灌入数据库并以 REST API 暴露；macOS 桌面客户端通过 HTTP API 浏览分类、搜索播客、查看剧集、并直接从外部 CDN 播放音频。

1.2 数据形态（来自 v4，已核验）

• 数据是批量构建的只读快照（buildId），偏只读、周期重建（deepresearch...v4.md:51）。
• 剧集是大表：audioUrl 指向外部 CDN（如 traffic.libsyn.com），非自托管（deepresearch...v4.md:66）。
• 分类体系沿用 Apple Podcasts 同款分类法，主类用 -- 表示复合词（如 health--fitness）（deepresearch...v4.md:71）。

1.3 部署形态（来自 DELIVERY，实际落地）

• 方案 B · 内网服务端模式：本机（10.10.20.207）作为内网服务端，同事安装 PodcastDesktop.dmg，app 通过 HTTP API 取数据并展示/播放（DELIVERY.md:3）。
• 客户端范围：仅 Apple Silicon (arm64) / macOS；Intel / Windows 不在本次交付范围（DELIVERY.md:19）。

1.4 三端职责划分

2. 三端总体架构图

┌──────────────────────────────────────────────────────────────────────────────┐
│  桌面客户端 (PodcastDesktop.app, macOS arm64)                                   │
│  ┌────────────────────────────┐   嵌入   ┌──────────────────────────────────┐  │
│  │ Qt6 主窗口 (QMainWindow)    │ ───────▶ │ CEF (Chromium Embedded Framework)│  │
│  │ desktop/src/qt_window.cpp   │          │ + 5 个 Helper 进程               │  │
│  │ + 10ms QTimer 驱动消息泵     │          │ desktop/src/cef_client.cc        │  │
│  └────────────────────────────┘          │   加载 → http://10.10.20.207:3000 │  │
│                                          │          /app/index.html (Web UI) │  │
│                                          │   音频在 Chromium 内解码播放      │  │
│                                          └──────────────────────────────────┘  │
└───────────────────────────────┬──────────────────────────────────────────────┘
                                 │ HTTP (Authorization: Bearer <token>)
                                 │ LAN: http://10.10.20.207:3000
                                 ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  服务端  Next.js 16.2.7 (App Router · 仅 Route Handlers · Node runtime)         │
│  监听 *:3000（全部网卡，LAN 可达）        工作目录 podcast-api/                  │
│                                                                                │
│   静态 Web UI  /app/*  ──────────────▶ public/app/{index.html,app.js,styles.css}│
│                                                                                │
│   REST API     /api/health                                                     │
│                /api/v1/podcasts/*   (13 个 route.ts)                            │
│        ┌─────────────────────────────────────────────────────────────┐        │
│        │ route.ts: authenticate() → zod 校验 → service → envelope(ok/fail)│      │
│        │   lib/api/auth.ts  lib/validations/*  lib/api/envelope.ts       │      │
│        └───────────────────────────────┬─────────────────────────────┘        │
│   4 个 service (lib/services/*)         │  进程内 TTL memo (lib/api/memo.ts)    │
│   catalog / playback / downloads / health                                      │
│                                         │ Drizzle ORM + postgres-js (连接池 max:10)│
└─────────────────────────────────────────┼─────────────────────────────────────┘
                                          │ DATABASE_URL → 127.0.0.1:5432
                                          ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  数据底座  PostgreSQL 16  (容器 podcast-pg, 只绑 127.0.0.1:5432)                 │
│  在 colima VM 内运行；VM 磁盘镜像位于外置盘 /Volumes/External/develop/.colima    │
│                                                                                │
│  8 张表：podcasts / episodes / podcast_categories                              │
│          playback_progress / download_tasks                                    │
│          language_stats / category_stats / category_sub_stats (ETL 预聚合)     │
│  17 索引：GIN(tsv 全文) · GIN(name trgm) · keyset(popular/name/recent) · ...     │
└──────────────────────────────────────────────────────────────────────────────┘
        ▲
        │ 离线 ETL（约 20 分钟一次性入库）
   dataset.7z → transform.mjs → COPY staging → finalize.sql → perf-stats.sql

  音频：客户端拿 episode 的 audioUrl，由 Chromium 直连外部 CDN（默认不经服务端）

锚点：客户端结构 desktop/README.md:1、desktop/src/qt_window.cpp、desktop/src/cef_client.cc；服务端监听 docs/SERVICE-OPS.md:14；DB 只绑本地 docs/SERVICE-OPS.md:12、DELIVERY.md:36；依赖链 docs/SERVICE-OPS.md:9。

3. 技术栈选型与裁决

3.1 实际技术栈（来自 podcast-api/package.json）

注：v4 执行摘要写的是 next@16.2.6 / drizzle@0.38 / zod@3.24 / pino@9 / ioredis@5.10，实际落地版本更新且用 postgres-js 取代 node-postgres、用进程内 memo 取代 ioredis/Redis。版本以 package.json 为准。

3.2 逐项裁决

Next.js 16（App Router · 仅 Route Handlers）— 公司钦定栈

• 为什么：v4 §3.1 明确"公司钦定 Next.js 栈"，覆盖早期 Go/Hono 备选（deepresearch...v4.md:19）。官方支持纯 API 后端，route.ts 嵌套实现 /v1 路径版本化。
• 落地证据：13 个 route.ts，全部为命名导出 export async function GET/POST(...)，统一 export const dynamic = 'force-dynamic'（如 src/app/api/v1/podcasts/shows/route.ts:11、src/app/api/health/route.ts:6）。
• runtime：全部跑默认 Node.js runtime（未声明 runtime='edge'），因为 postgres-js / pino 依赖 Node 核心模块——与 v4 §3.2 的运行时事实链一致（deepresearch...v4.md:109）。

Drizzle ORM + PostgreSQL 16

• 为什么 PG：v4 §2 论证"必须要数据库"——~2287 万剧集要按分类/语言/关键词做有索引筛选 + 分页，裸 JSONL 全表扫描不可行（deepresearch...v4.md:83）。
• 为什么 Drizzle：官方有 PostgreSQL Full-Text Search 与 Cursor-based Pagination 指南。落地中全文检索用 sql\`片段表达websearch_to_tsquery/ts_rank（src/lib/services/catalog.service.ts:371、:377）；keyset 用行值比较 (col, id) < (v, id)（catalog.service.ts:398`）。
• schema 即 DDL 镜像：src/lib/db/schema.ts 注释明确"mirroring scripts/etl/finalize.sql"，索引由 ETL 创建，API 从不在目录表 INSERT（schema.ts:1、schema.ts:13）。

postgres-js（取代 v4 的 node-postgres）

• 落地：src/lib/db/client.ts:15 用 postgres(env.DATABASE_URL, { max: 10 }) 建常驻连接池，drizzle 绑定该 client（client.ts:24）。dev HMR 下复用全局单例避免连接堆积（client.ts:8）。
• 与 v4 差异：v4 文中以 node-postgres 为例论证"Workers 跨请求隔离不兼容"，本项目在 Node 容器内不受此限，且换用更轻的 postgres-js。两者都是常驻连接池模型，结论一致（容器内直连、无需 Hyperdrive）。

Zod 4 / pino 10 / Vitest 4

• Zod：每端点入口校验，searchParamsToObject(req.nextUrl) → schema.safeParse(...)，失败映射业务码 1000（src/app/api/v1/podcasts/shows/route.ts:25、src/lib/api/errors.ts:12）。
• pino：单例 logger，dev 用 pino-pretty、prod 输出 JSON 给采集层；注释强制"禁 console.*"（src/lib/logger.ts:1、:12）。
• Vitest：npm run test / test:coverage 已配置（package.json:14）。

CEF（Chromium Embedded Framework）— 客户端壳

• 为什么 CEF 而非 Qt WebEngine：desktop/README.md:6 明确"音频播放发生在 Chromium 内——不使用 Qt WebEngine"。CEF 提供完整 Chromium 渲染 + 媒体解码，且发行版扁平布局与 Chrome/Electron 同款、公证兼容（DELIVERY.md:16）。
• 集成方式：Qt6 主窗口把 CEF 浏览器作为中央控件的子 NSView 嵌入（SetAsChild），10ms QTimer 驱动 CefDoMessageLoopWork()；CEF 版本 144，5 个 Helper 变体（desktop/README.md Architecture 段）。

3.3 与 v4 "k8s 方案" 对照本项目"本机内网"落地的差异

4. 部署拓扑

4.1 依赖链（启动顺序，来自 SERVICE-OPS）

外置盘挂载 (/Volumes/External)               ← 一切的前提
  └─ colima 虚拟机 (4C/6G, docker 运行时)     ← VM 镜像在外置盘 .colima（经 ~/.colima 符号链接）
       └─ podcast-pg 容器 (PostgreSQL 16)     ← 只绑 127.0.0.1:5432，数据卷 podcast-pgdata
            └─ Next.js 生产服务 (端口 3000)    ← 监听全部网卡，LAN 可达
                 ├─ REST API  /api/v1/*
                 └─ Web UI    /app/index.html  ← 桌面端加载的页面

锚点：docs/SERVICE-OPS.md:9。为什么是这个顺序：DB 镜像在外置盘上的 colima VM 磁盘里，必须先有外置盘 → 再有 VM → 再有 DB 容器，最后 Next 才能连库（docs/SERVICE-OPS.md:18）。

4.2 拓扑要点表

4.3 一键启停

• 启动：podcast-api/scripts/serve.sh（幂等）——colima → podcast-pg（等 pg_isready）→ 无 .next 先 npm run build → npm run start → 回显本机与 LAN 健康检查（podcast-api/scripts/serve.sh:1，末行输出 READY — clients connect to: http://10.10.20.207:3000/app/index.html）。
• 停止：scripts/stop.sh（--vm 连 VM 一起停，拔外置盘前必须）（docs/SERVICE-OPS.md:71）。

4.4 客户端服务地址解析优先级

桌面端按以下顺序解析服务端地址（DELIVERY.md:21）：

IP 变更只需重打包（SERVER_URL=... ./package.sh）或让用户按 ③ 放一行文本文件，无需重装（DELIVERY.md:28）。

5. 端到端数据流

5.1 离线入库链（一次性，约 20 分钟）

dataset.7z
  └─(解压)→ dataset/ JSONL
       └─ scripts/etl/transform.mjs   逐行解析，脏行容错跳过并计数 → 三份 TSV
            └─ COPY → *_staging 表
                 └─ scripts/etl/finalize.sql   staging → 最终表（DISTINCT ON 去重、
                 │     外键约束、孤儿行丢弃计数）→ 批量后建索引 → ANALYZE
                 └─ scripts/etl/perf-stats.sql  预聚合 language_stats / category_stats /
                       category_sub_stats + 3 个 keyset 索引

锚点：ETL 目录 podcast-api/scripts/etl/；入库步骤 finalize.sql:1（"staging → final tables ... then indexes (after bulk load), then ANALYZE"）；预聚合表 perf-stats.sql:8；重建入口 reload.sh / run-etl.sh（docs/SERVICE-OPS.md:135）。

预聚合的工程意义：目录是只读快照，语言/分类计数在入库时算一次存进 *_stats 表，API 直接读，避免每请求 count(DISTINCT) 跨 join（src/lib/db/schema.ts:115、listLanguages 走 language_stats 见 catalog.service.ts:252）。

5.2 在线读取链（每请求）

桌面端 CEF / Web UI
  └─ fetch(http://10.10.20.207:3000/api/v1/podcasts/shows?..., Authorization: Bearer <token>)
       └─ route.ts:  authenticate(req)            鉴权 → 失败 401 / code 1001
       │             zod.safeParse(searchParams)  校验 → 失败 400 / code 1000
       │             decodeCursor + 类型守卫       游标合法性
       └─ catalog.service.listShows(...)          Drizzle 构造 SQL（含 keyset / tsv）
            └─ postgres-js 连接池 → PostgreSQL 16  走 GIN / keyset 索引
       └─ envelope.ok(data, requestId)            { code:0, message:"OK", data, request_id }
  └─ Web UI 渲染列表/详情
  └─ 播放：取 episode.audioUrl → Chromium 直连外部 CDN（不经服务端）

锚点：鉴权 src/lib/api/auth.ts:36；校验/游标 src/app/api/v1/podcasts/shows/route.ts:25；service catalog.service.ts:356；统一信封 src/lib/api/envelope.ts:11；音频直连 catalog.service.ts:769（D-5）。

5.3 响应信封与错误码（实际落地）

成功：{ code: 0, message: "OK", data, request_id }（envelope.ts:11）。错误码（src/lib/api/errors.ts:8）：

5.4 API 路由全景（13 个，已核验）

注：API 基路径是 /api/v1/podcasts/...（业务前缀 podcasts），与 v4 文中示例的 /v1/... 路径不同；以代码为准。

6. 关键架构决策与权衡表

7. 与设计文档 (v4) 的落地对照表

维度图例：✅ 已落地 / 🔸 简化落地 / ❌ 未做。

7.1 已落地（✅）

7.2 简化落地（🔸）

7.3 未做（❌）

8. 已知边界与待确认

9. 相关分册与文件索引