web_hgcg_h5/project.md

项目名称, 一级部门, 二级部门, DMP编码, 项目类型, 开发语言, 项目负责人, 运维负责人, 产品负责人, 项目成员, 项目状态, 项目级别, 核心分支, 代码仓库, 最后审计人, 最后审计时间, 告警群, 备注

项目名称	一级部门	二级部门	DMP编码	项目类型	开发语言	项目负责人	运维负责人	产品负责人	项目成员	项目状态	项目级别	核心分支	代码仓库	最后审计人	最后审计时间	告警群	备注
黄果吃瓜web	北斗	瑞升	JHA-1047	PC	Node	DN1425	DN9460, DN9651, DN4792	YY1166	DN7208, DN2185, DN8431	维护中	中	main	ssh://git@bd-git-sh.jsyyds.com:8082/ruisheng/jha-1021-91jhs/frontend/jha-1047-91dj-web.git				Next.js 网站与 API 代理服务；业务数据由独立 Go 后端提供。

1. 项目说明

黄果吃瓜 Web 项目，DMP 编码 JHA-1047，站点域名为 huangguocg.com。采用 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}/
官方入口 / 回家的路 / 福利应用	/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 为准，使用 npm ci 安装。
• Next.js 16、React 19、TypeScript 5.9；主要运行库包括 hls.js、qrcode、dotenv。
• 网站需要运行 Node.js 服务，使用 Next.js standalone 产物，不是静态 out/ 部署。
• 页面在服务端取数并输出当前页面正文与 head；浏览器复用首屏数据绑定交互，页面链接和分页使用原生路径访问。
• 浏览器请求本站 /api/*，Next.js 按白名单转发到 Go 后端的 /api/app/*。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	https://webhgcgapi.mfcg.me	21021	.next-dev/
测试	config/test.env	https://webhgcgapi.mfcg.me	21021	.next-test/
生产	config/production.env	https://webhgcgapi.mfcg.me	21021	.next/

配置由 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、sitemap 和页面展示的站点地址固定为 https://huangguocg.com（src/lib/site.ts），不读取后台 foreverUrlAddr。有效 SEO 配置保存在对应构建目录的 cache/seo/，异常时复用最近一次有效快照；不以 API IP 或访问 Host 作为正式域名。
• 生产 /robots.txt 允许抓取公开资源，限制 /api/ 和 /healthz；开发、测试禁止全站抓取。搜索、工具等页面另有页面级 noindex 规则。
• 生产 robots 声明 https://huangguocg.com/sitemap.xml。本仓库没有 sitemap XML 生成或读取路由；现有 XSL 和响应头配置不等于已提供 XML，需由后端/反向代理另行接入。规则见 后端 Sitemap 对接约定。
• 站名（导航页固定“黄果吃瓜”）、官方入口和联系方式（官方 TG @jbd125）固定；广告和下载地址由接口动态配置，未配置有效 App 下载链接时隐藏入口。

3. 运维部署

3.1 开发、验证和启动

nvm use 22.17.1
npm ci
npm run dev                 # 开发配置，默认 http://localhost:21021
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

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

3.2 打包与发布目标

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_91dj/h5	22889 / 22889	bash run.sh
生产	server@34.92.204.175	/home/server/web_91dj/h5	22889 / 22889	bash rsupdate.sh

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

• 测试脚本：deploy_test.sh。执行 build:test、测试、bundle:test，生成 web_91dj_h5.tar.gz 和 web_91dj_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。执行 check、bundle、bundle:linux，生成 web_91dj_h5.tar.gz 和纯哈希格式 web_91dj_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 是测试环境辅助更新脚本，默认 Supervisor 程序为 91dj_next_h5，可通过 DEPLOY_PROGRAM 覆盖。它支持 SHA-256 校验、解包、安装依赖、保留本地配置和 SEO 缓存、切换版本、检查和失败回退；是否由服务器 run.sh 调用，应核对远端实现。

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

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

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

4. 风险说明

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

5. 历史事故（可选）

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

6. 交接说明（可选）

• 应用标识：DMP 为 JHA-1047。
• 新增页面：复用集中路由、slug/ID、分页和 SEO 规则，补充有效/缺失/异常状态处理。导航与下载入口优先消费动态配置，不写死演示链接。
• 配置交接：确认实际运行目录的私有覆盖、上游连通性、广告及下载配置。新版本切换需保留服务器私有配置和对应 SEO 快照。
• 发布交接：确认 SSH 权限、远端 run.sh/rsupdate.sh、服务管理名称、日志与回退方法；本文记录的是仓库默认值，不替代服务器实际配置验收。
• 待补登记：最后审计人、最后审计时间、告警群，以及运维确认后的监控和事故台账；不将本次文档整理视为已完成审计。
• 参考资料：运行与部署说明、页面接口对照、索引策略、Sitemap 对接约定。历史核对记录以其日期为界，当前配置和行为以代码为准。