web_hgdjc_h5/project.md

---
项目名称: 禁果短剧web
一级部门: 北斗
二级部门: 瑞升

DMP编码: JHA-1050

项目类型:
  PC
  # 可选值:
# H5 / APP / PC / 服务 / 组件 / 工具 / AI / 中间件

开发语言:
  Node
  # 可选值:
# GO / Java / PHP / Node

项目负责人: DN1425 # 员工编号, 多个用逗号隔开,这里的负责是这套代码的负责人

运维负责人: DN9460, DN9651, DN4792 # 负责部署、监控、K8S、发布、证书等

产品负责人: YY1166 # 项目产品经理

项目成员: DN7208, DN2185, DN8431

项目状态:
  维护中
  # 可选值:
  # 开发中 / 维护中 / 已停止 / 已归档

项目级别:
  中
  # 可选值:
  # 高 / 中 / 低 , 北斗体系 s和a为 高 b为中  c d为低

核心分支:
  main
  # 即部署时候使用的分支,可选值:
  # master / main / dev / release

代码仓库:
  - ssh://git@bd-git-sh.jsyyds.com:8082/ruisheng/jha-1021-91jhs/frontend/jha-1050-jgdj-web.git
  # 按新项目标识登记的目标地址；远端仓库创建及本地 origin 切换需另行确认。

最后审计人:

最后审计时间:

告警群:

备注: Next.js 网站与 API 代理服务；业务数据由独立 Go 后端提供。
---

# 1. 项目说明

禁果短剧 Web 项目，DMP 编码 **JHA-1050**，应用及埋点 App ID 为 **1050**。采用 Next.js App Router、React、TypeScript，实现 PC 和移动端响应式页面，布局依据提供的 HTML 原稿还原。

本文按当前仓库代码整理，更新日期为 **2026-10-26**；该日期不代表安全审计或线上验收时间。人员信息沿用原登记信息，部署目标以当前脚本默认值为准。

## 1.1 功能范围

- 首页动态栏目、轮播、顶部及侧栏导航、广告与宫格广告弹窗。
- 短剧列表、排行榜、专题、题材/标签、栏目更多页、搜索及独立分页。
- 短剧详情、章节播放、HLS 播放、图片解密、点赞、收藏、评论与分享。
- 游客/账号登录、个人中心、观看历史、我的收藏、我的点赞、已购剧集、账号设置。
- 金币充值、VIP 套餐、章节解锁、反馈、App 下载、福利应用、回家的路和独立导航页。
- 服务端 SEO 元数据、JSON-LD、robots.txt 与广告/页面/播放等埋点。

本仓库负责网站页面、浏览器交互和服务端 API 代理，不包含 Go 业务服务、管理后台或数据库部署代码。独立“剧集”入口及 `/series/`、`/video/*` 页面已移除。

## 1.2 主要目录与路由

| 位置                                            | 职责                                             |
| ----------------------------------------------- | ------------------------------------------------ |
| `src/app/`                                      | App Router 页面、API/媒体代理、robots 和健康检查 |
| `src/components/site/`                          | 首页、详情、播放、导航等页面组件                 |
| `src/lib/api/`                                  | 上游配置、接口白名单、会话、公共缓存和媒体请求   |
| `src/lib/client/`                               | 登录、账户、播放、解锁、广告、图片及埋点交互     |
| `src/lib/routing.ts`                            | 路由解析、slug/ID、分页地址与导航匹配            |
| `src/lib/seo*.ts`、`src/lib/structured-data.ts` | TDK、canonical、索引策略、SEO 快照和 JSON-LD     |
| `src/proxy.ts`                                  | 页面尾斜杠规范化和首屏会话准备                   |
| `config/`、`scripts/`、`deploy/`                | 环境配置、启动/打包脚本及辅助更新脚本            |
| `public/`、`tests/`、`docs/`                    | 静态素材、回归测试、接口与收录规则说明           |

| 页面                           | 主要路径                                                                                            |
| ------------------------------ | --------------------------------------------------------------------------------------------------- |
| 首页 / 短剧                    | `/`、`/shorts/`                                                                                     |
| 三个排行榜                     | `/rank/hot/`、`/rank/new/`、`/rank/follow/`                                                         |
| 专题 / 标签 / 更多栏目         | `/topics/`、`/topics/{key}/`、`/tag/{key}/`、`/config/{key}/`                                       |
| 详情 / 播放                    | `/detail/{key}/`、`/play/{key}/{chapterId}/`                                                        |
| 搜索                           | `/search/{keyword}/`                                                                                |
| 个人中心及书架                 | `/member/center/`、`/member/history/`、`/member/favorites/`、`/member/likes/`、`/member/purchased/` |
| 充值 / VIP                     | `/info/deposit/`、`/info/deposit/vip/`                                                              |
| 官方入口 / 回家的路 / 福利应用 | `/navigation/`、`/home-road/`、`/apps/`                                                             |

内容地址优先使用有效英文/拼音 slug，无效或缺失时使用 ID；播放页章节段使用真实章节 ID。搜索词作为单个路径段编码。支持分页的页面使用 `/page/{N}/`，第一页使用基础路径；详情和播放页的分页对应评论。有效页面无尾斜杠访问返回 308，API、媒体和静态资源保留原路径。确认不存在的资源或越界分页返回 404，上游业务服务异常与资源不存在分别处理。

# 2. 基础设施与中间件

## 2.1 运行依赖与请求链路

- Node.js 最低 **20.9.0**，推荐 **22.17.1**；生产跨平台打包要求 **npm >=10.9.2**。依赖版本以 [package-lock.json](package-lock.json) 为准，使用 `npm ci` 安装。
- Next.js 16、React 19、TypeScript 5.9；主要运行库包括 `hls.js`、`qrcode`、`dotenv`。
- 网站需要运行 Node.js 服务，使用 Next.js `standalone` 产物，不是静态 `out/` 部署。
- 页面在服务端取数并输出当前页面正文与 head；浏览器复用首屏数据绑定交互，页面链接和分页使用原生路径访问。
- 浏览器与服务端业务接口统一使用 `/api/app/*`。请求进入 Next.js 后按白名单转发到独立 Go 上游的同名路径，旧 `/api/*` 入口保留兼容。`UPSTREAM_API_URL` 仅服务端使用，`API_BASE_URL` 是兼容别名。
- `/h5/m3u8/*`、`/enkey`、`/newenkey` 由媒体代理处理，保留签名查询、客户端相关请求信息；媒体和密钥不缓存，不转发应用登录 Cookie 或 Authorization。

登录会话通过 HttpOnly Cookie 传递；SSR 启动数据按字段白名单输出，不向浏览器暴露后端登录凭证。公共接口和账户、余额、订单、付费权限数据采用不同缓存策略。

本仓库不直接连接 MongoDB、Redis 或 Elasticsearch。Go 后端是否使用这些中间件及其拓扑，由后端/运维文档确认；本仓库没有 Telegram Bot 部署通知实现。

## 2.2 环境配置

| 环境 | 配置文件                 | Go API 上游                   | 网站端口 | 构建目录      |
| ---- | ------------------------ | ----------------------------- | -------- | ------------- |
| 开发 | `config/development.env` | `http://172.104.181.99:26792` | `21030`  | `.next-dev/`  |
| 测试 | `config/test.env`        | `http://172.104.181.99:26792` | `21030`  | `.next-test/` |
| 生产 | `config/production.env`  | `http://139.162.49.252:21040` | `21042`  | `.next/`      |

配置由 [scripts/next-env.mjs](scripts/next-env.mjs) 加载，优先级为：进程环境变量 > `config/{环境}.local.env` > `config/{环境}.env`。开发环境兼容旧 `.env.local`，优先级低于 `config/development.local.env`；测试和生产不从旧 `.env.local` 加载本站业务配置。

`APP_ENV` 区分业务环境；测试构建/启动仍使用 `NODE_ENV=production`，`dev` 命令使用 `NODE_ENV=development`。服务端配置修改后需重启，`NEXT_PUBLIC_*` 修改后需重新构建。私有覆盖文件已忽略提交和打包。

## 2.3 缓存、SEO 与外部配置

- 公共配置、页脚、导航、分类和标签选项默认缓存 60 秒，首页缓存 30 秒，进程内最多 128 条并合并并发请求；开发配置关闭缓存。`PUBLIC_DATA_CACHE_TTL_MS=0` 可关闭，正数仅缩短既有缓存上限。
- 公共缓存按上游地址隔离，各实例独立；配置和首页刷新失败可沿用已成功的数据。账户及付费权限不进入公共缓存。
- canonical 和站点身份取后台配置的永久域名，优先 `config.foreverUrlAddr`，其次 `newAddressInfo.foreverUrlAddr`。有效 SEO 配置保存在对应构建目录的 `cache/seo/`，异常时复用最近一次有效快照；不以 API IP 或访问 Host 作为正式域名。
- 生产 `/robots.txt` 允许抓取公开资源，限制 `/api/` 和 `/healthz`；开发、测试禁止全站抓取。账户、充值、搜索、工具等页面另有页面级 `noindex` 规则。
- 生产 robots 在取得有效永久域名后声明 `https://{永久域名}/sitemap.xml` 形式的绝对 URL。**本仓库没有 sitemap XML 生成或读取路由**；现有 XSL 和响应头配置不等于已提供 XML，需由后端/反向代理另行接入。规则见 [后端 Sitemap 对接约定](docs/sitemap-backend-contract.md)。
- 导航、官方入口、商务 TG、用户反馈 TG 群、广告和下载地址由接口动态配置；未配置有效 App 下载链接时隐藏入口。
- 埋点使用 App ID `1050`，优先读取接口 `reportSdkConfig`，构建配置 `NEXT_PUBLIC_TRACKER_ENCRYPTED_CONFIG` 为兜底；配置及上报链路需与后端保持一致。

# 3. 运维部署

## 3.1 开发、验证和启动

```sh
nvm use 22.17.1
npm ci
npm run dev                 # 开发配置，默认 http://localhost:21030
npm run typecheck           # 类型检查
npm test                    # 本地回归测试
npm run check               # 生产构建 + 回归测试
```

| 环境 | 构建                 | 启动                                                  |
| ---- | -------------------- | ----------------------------------------------------- |
| 开发 | `npm run build:dev`  | `npm run dev`；已有构建用 `npm run start:dev`         |
| 测试 | `npm run build:test` | `npm run start:test`；开发调试可用 `npm run dev:test` |
| 生产 | `npm run build`      | `npm start`                                           |

启动前确认 `21030` 未被本项目的旧进程或其他服务占用。不同环境须使用对应构建产物，不能互换构建目录。

## 3.2 打包与发布目标

```sh
bash deploy_test.sh --dry-run       # 仅预览，不构建、不联网
bash deploy_prod.sh --dry-run
bash deploy_test.sh --package-only  # 仅本地构建、测试、打包
bash deploy_prod.sh --package-only
```

| 环境 | 默认 SSH 目标          | 上传及执行目录             | SCP / SSH 端口  | 上传后执行         |
| ---- | ---------------------- | -------------------------- | --------------- | ------------------ |
| 测试 | `root@172.104.181.99`  | `/server/web_jgdj/h5`      | `22889 / 22889` | `bash run.sh`      |
| 生产 | `server@34.92.204.175` | `/home/server/web_jgdj/h5` | `22889 / 22889` | `bash rsupdate.sh` |

直接执行 `bash deploy_test.sh` 或 `bash deploy_prod.sh` 会构建、测试、打包、上传并执行远端脚本。生产上传主机与生产 API 主机不同，不要混用。

- **测试脚本**：[deploy_test.sh](deploy_test.sh)。执行 `build:test`、测试、`bundle:test`，生成 `web_jgdj_h5.tar.gz` 和 `web_jgdj_h5.tar.gz.sha256`，上传这两份文件及 `deploy/up_next_h5.sh`；同时刷新本地兼容 MD5 文件。测试包不含 `node_modules`，Linux 解包后需 `npm ci --omit=dev --no-audit --no-fund`，再运行 `node start.mjs`。
- **生产脚本**：[deploy_prod.sh](deploy_prod.sh)。执行 `check`、`bundle`、`bundle:linux`，生成 `web_jgdj_h5.tar.gz` 和纯哈希格式 `web_jgdj_h5.md5`，两份文件一并上传。包内含 standalone 裁剪依赖，默认 Linux x64/glibc，可运行 `node start.mjs`；打包时安装并校验目标平台 Sharp/libvips。
- 两种包只带对应环境的基础配置，不包含私有 `*.local.env`、`.env*` 和 SEO 缓存。服务器覆盖配置放在实际运行目录的 `config/` 下。
- 测试与生产使用**同名压缩包**，后一次打包会覆盖根目录旧产物；发布前核对环境和校验文件。`dist/`、压缩包和校验文件均已忽略提交，两份脚本共用 `dist/.deploy.lock` 防止并发打包。

测试目标可通过 `DEPLOY_HOST`、`DEPLOY_DIR`、`DEPLOY_RUN_DIR`、`DEPLOY_SSH_PORT` 覆盖；上传目录和执行目录分别配置。生产使用 `DEPLOY_JUMP_HOST`、`DEPLOY_JUMP_DIR`、`DEPLOY_SCP_PORT`、`DEPLOY_SSH_PORT`，执行目录跟随上传目录。两者支持 `DEPLOY_PACKAGE_NAME`；生产另支持 `DEPLOY_TARGET_ARCH=x64|arm64`、`DEPLOY_TARGET_LIBC=glibc|musl`。

上传失败不会执行远端更新；远端命令失败会使发布退出。生产脚本还检查远端输出中的失败状态，并将执行日志写入 `dist/production-rsupdate.*`。

## 3.3 服务管理、检查和回退

远端现有 `run.sh`、`rsupdate.sh` 不在本仓库，发布脚本不会覆盖它们。服务启动方式、私有配置保留、日志位置和线上回退步骤，需由运维结合服务器脚本确认。

仓库提供的 [deploy/up_next_h5.sh](deploy/up_next_h5.sh) 是测试环境辅助更新脚本，默认 Supervisor 程序为 `jgdj_next_h5`，可通过 `DEPLOY_PROGRAM` 覆盖。它支持 SHA-256 校验、解包、安装依赖、保留本地配置和 SEO 缓存、切换版本、检查和失败回退；是否由服务器 `run.sh` 调用，应核对远端实现。

`/healthz` 返回进程状态、应用名和环境，不请求 Go 后端。发布后可执行：

```sh
node scripts/check-health.mjs http://127.0.0.1:21030 production
# 测试环境将最后一个参数改为 test
PREVIEW_URL=http://127.0.0.1:21030 npm run smoke:api
```

健康检查同时检查 `/healthz` 和首页；测试发布可设置 `DEPLOY_CHECK_URL` 自动执行。API 冒烟检查可能创建临时游客会话，使用 `SMOKE_PUBLIC_ONLY=1` 可仅检查公共部分。支付、解锁、媒体播放及埋点仍需对应业务验收，不能仅以进程存活判定全部功能正常。

# 4. 风险说明

| 风险点                      | 影响及处理要求                                                                                                                                                                          |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 上游及反向代理配置错误      | SSR、登录或媒体可能失败；区分 H5（开发/测试 `21030`、生产 `21042`）、API（生产 `21040`）和 SSH `22889`。默认将本站 `/api/app/*` 交给 Next.js，并配置独立 Go 上游。若 Nginx 直接转发 Go（包括可选 `current` 模式），需单独验证 Go 鉴权及会话，避免跳过 Next.js Cookie 处理或造成上游回环。 |
| 播放签名、IP、UA 或密钥异常 | 可能出现播放 502；保留签名查询和客户端信息，检查真实上游响应，AES 密钥必须为 16 字节。H.265 解码受设备及浏览器限制，前端不提供转码。                                                    |
| 个人数据误入共享缓存        | 可能造成身份或权限混用；新增接口需延续公开数据与账户、订单、付费权限隔离，首屏输出遵守字段白名单。                                                                                      |
| 发布包平台或环境不匹配      | 生产需匹配 Linux 架构/libc，测试包需安装运行依赖；同名产物发布前核对配置和校验值。                                                                                                      |
| SEO 配置或 sitemap 未接入   | 测试环境禁止抓取；生产需核对 `APP_ENV`、永久域名、robots、页面索引标记及实际 sitemap 响应，不能只确认 Sitemap 声明。                                                                    |
| 服务器更新脚本未交接        | 本地脚本成功不等于业务验收通过；运维应提供远端脚本、服务管理、日志、监控告警及回退说明。                                                                                                |

# 5. 历史事故（可选）

仓库内未提供经确认的生产事故台账。负责人可按“时间、环境、影响范围、原因、处置及预防措施”补充；开发调试错误不直接登记为生产事故。

# 6. 交接说明（可选）

- **应用标识**：DMP 为 `JHA-1050`；三套环境的 `NEXT_PUBLIC_TRACKER_APP_ID` 均为 `1050`，对接后台与 SDK 时保持一致。
- **标识迁移**：包名与健康检查应用名为 `jha-1050-jgdj-web`，发布包为 `web_jgdj_h5.tar.gz`，Supervisor 默认为 `jgdj_next_h5`。服务器地址和端口沿用现有配置；发布前需准备新的 `web_jgdj/h5` 目录、更新脚本及对应 Supervisor 配置，并确认 Go 上游和 `reportSdkConfig` 属于应用 `1050`。
- **新增页面**：复用集中路由、slug/ID、分页和 SEO 规则，补充有效/缺失/异常状态处理。导航与下载入口优先消费动态配置，不写死演示链接。
- **个人列表**：我的点赞入口为 `/member/likes/`，上游接口为 `GET /api/app/playlet/like/list`，与收藏、历史、已购共同保持私有响应及禁止索引。
- **配置交接**：确认实际运行目录的私有覆盖、上游连通性、正式永久域名、TG 联系方式、广告、下载及埋点配置。新版本切换需保留服务器私有配置和对应 SEO 快照。
- **发布交接**：确认 SSH 权限、远端 `run.sh`/`rsupdate.sh`、服务管理名称、日志与回退方法；本文记录的是仓库默认值，不替代服务器实际配置验收。
- **待补登记**：最后审计人、最后审计时间、告警群，以及运维确认后的监控和事故台账；不将本次文档整理视为已完成审计。
- **参考资料**：[运行与部署说明](README.md)、[页面接口对照](docs/api-contract.md)、[索引策略](docs/indexation-policy.md)、[Sitemap 对接约定](docs/sitemap-backend-contract.md)。历史核对记录以其日期为界，当前配置和行为以代码为准。