Files
perler-lab/docs/DEPLOY-NEWPAGES.md
T

9.7 KiB
Raw Blame History

部署核对:新页面路由与静态资源部署配置(T-110)

维护者:DevOps-Engineer(T-110) 关联文件:.github/workflows/deploy.yml、perler-lab/nginx.conf、 perler-lab/Dockerfile、perler-lab-server/Dockerfile、 perler-lab-server/docker-compose.yml、docs/CI-NEWPAGES.md、docs/DEPLOY.md 更新日期:2026-08-14

核对范围

新页面(色号表 /color-chart(/...)、Showcase /showcase、图纸库 /library、 AI 专区 /chibi,路由定义于 perler-lab/src/App.tsx 第 335–348 行)与既有 部署配置的兼容性。部署路径为:SSH 生产 → git pull → docker compose -f perler-lab-server/docker-compose.yml up -d --build(.github/workflows/deploy.yml deploy job 第 101–131 行)。


核对结论(TL;DR)

# 检查项 结论
① 前端 Nginx/静态服务是否支持 SPA 路由 fallback ✅ 已支持,无需改动。nginx.conf 已有 try_files $uri $uri/ /index.html;,直访 /showcase、/color-chart/mard 等返回 index.html(200),由前端 App.tsx 按 pathname 分支渲染
② 新页面静态资源是否会被 docker build 自动包含 ✅ 已包含,无需改动。全部页面为 App.tsx 顶层静态 import,vite build 一次性打进 dist/assets/index-*.js;色号 JSON 数据由 src/lib/palette-data/*.json 经 Rollup 打包(vite build → dist/ → COPY --from=build /app/dist)
③ 后端新接口(/api/showcase/*、/api/color-chart/*)CORS/路由放行 ⚠️ 路由已放行(Nginx location /api/ 通配 + server.ts 已挂载两个 router);但生产 API 基址有缺陷,已修复(见 §2-B)
④ 健康检查路径是否受影响 ✅ 不受影响。前端 /healthz(location = /healthz 精确匹配优先于 fallback)、后端 /health 均未变,deploy job 探测的两个路径无需调整
⑤ 后端色号表数据文件是否入镜像 ❌ 发现缺陷,已修复(见 §2-A)。/api/color-chart/:brand 默认读取 /app/competitor-analysis/palettes,该目录不在镜像内,会导致色号表 API 返回空列表
⑥ CI 对新页面路由的门禁 ✅ 已在工作区就位(T-109 未提交改动):deploy.yml test job 含「Verify SPA dist & route smoke」步骤(vite preview 对 / /chibi /color-chart /color-chart/mard /color-chart/artkal-c /showcase /library 直访冒烟)

① SPA 路由 fallback(前端 Nginx)—— 已具备,无需改动

perler-lab/nginx.conf 第 94–97 行已包含 SPA 回退,无需新增:

# ── SPA 路由回退 ──
location / {
    try_files $uri $uri/ /index.html;
}

行为验证:

  • 直访 /showcase、/library、/color-chart/mard → nginx 找不到对应物理文件 → 回退 index.html(HTTP 200)→ 前端读取 window.location.pathname 渲染对应页面。
  • 不存在的路由(如 /help,App.tsx 无此分支)同样回退 index.html → 渲染 HomePage 兜底,不会 404。若 帮助 页面在规划中,需补 App.tsx 分支与组件(见 docs/CI-NEWPAGES.md ①第 42 行),非部署配置问题。
  • location = /healthz(精确匹配)优先级高于 location /,健康检查不受 fallback 影响。

生产入口路径(docs/DEPLOY.md §4.2 主机 Nginx)为 location / { proxy_pass http://127.0.0.1:8080; },把任意路径透传给 frontend 容器,fallback 职责在容器内 nginx 完成,同样无需改动。

② 静态资源 docker build 自动包含 —— 已包含,无需改动

perler-lab/Dockerfile 构建阶段执行 vite build(RUN npm run build), App.tsx 对全部新页面组件(ChibiPage / ColorChartPage / ShowcasePage / LibraryPage)为静态 import,因此:

  • 新页面组件 + 色号 JSON 数据(src/lib/palette-data/*.json)+ CSS 必然进 bundle;
  • 不存在的引用会直接触发 tsc Cannot find module 构建失败(CI typecheck 覆盖)。

结论:新页面无需任何「额外 COPY / 额外构建步骤」。

③ 后端新接口 CORS / 路由放行

路由:已放行

  • 后端 perler-lab-server/src/server.ts 第 69–70 行已挂载: app.use("/api/color-chart", createColorChartRouter())、 app.use("/api/showcase", createShowcaseRouter(db))。
  • 前端 nginx location /api/ { proxy_pass http://backend; }(nginx.conf 第 70 行)为 通配前缀,/api/showcase/*、/api/color-chart/* 自动命中,无需新增 location。
  • 主机层 nginx(docs/DEPLOY.md §4.2)的 location /api/ → 127.0.0.1:8788 同理。

CORS:生产无需放行,开发已覆盖

  • 生产:同源请求(见下 §2-B 修复后的 /api 基址)经 Nginx 反代,不触发 CORS。
  • 开发:后端 CORS 白名单 http://localhost:5173 / http://127.0.0.1:5173 (server.ts 第 27 行)覆盖 Vite dev server 的跨源调用,新接口走同一中间件,无需追加。

④ 健康检查路径 —— 不受影响

检查点 路径 状态
frontend 镜像 HEALTHCHECK(Dockerfile) GET http://localhost:80/healthz 未变
compose 中 server healthcheck fetch('http://localhost:8788/health') 未变
deploy job 探测 http://localhost:8080/healthz / http://localhost:8788/health 未变

新路由对上述路径零影响。


已落地的配置修改(本次 T-110 直接修改,均已标注)

2-A 后端色号表数据文件入镜像(修复:镜像内无色板数据)

缺陷:perler-lab-server/src/color-chart/routes.ts 第 66–71 行的 DEFAULT_PALETTES_DIR 解析到仓库根 competitor-analysis/palettes/;容器内 等价路径为 /app/competitor-analysis/palettes,而后端镜像构建上下文仅为 perler-lab-server,该目录不会进入镜像 → /api/color-chart/:brand 在容器内 读取失败,模块加载时告警并回退空列表,SEO JSON-LD 数据为空。

修改(纯部署配置 + 数据文件,源码未动):

  1. perler-lab-server/palettes/ —— 从 competitor-analysis/palettes/ 同步 6 个品牌 色板 JSON(artkal-c.json / hama.json / ikea-pyssla.json / nabbi.json / perler.json / zippland-291标准色映射.json)。后续品牌数据变更时请同步该目录。
  2. perler-lab-server/Dockerfile —— 运行阶段新增 COPY palettes ./palettes。
  3. perler-lab-server/docker-compose.yml —— server 服务新增环境变量 PALETTES_DIR: "/app/palettes"(routes.ts 第 112 行优先读 PALETTES_DIR)。 如需改用卷挂载色板,改此值为宿主机映射路径即可。

2-B 前端生产 API 基址(修复:生产浏览器 fetch 打到「用户本机」)

缺陷:perler-lab/src/lib/api.ts 第 87 行 API_BASE 默认 http://localhost:8788,且全仓无 .env.production / build-arg 覆盖。生产环境下该 绝对 URL 在用户浏览器里执行,localhost 指向用户本机 → 所有 API 调用 (含 Showcase 发布 POST /api/showcase/works)都会失败,且即使打对也会因来源 不在后端 CORS 白名单而被拦截。

修改(perler-lab/Dockerfile 构建阶段,npm run build 之前):

ARG VITE_API_BASE=/api
ENV VITE_API_BASE=$VITE_API_BASE

效果:生产 bundle 内 import.meta.env.VITE_API_BASE 变为同源 /api, fetch('/api/...') 走 Nginx /api/ 反代到后端容器,同源无 CORS。本地 npm run dev(5173)无此变量,仍回退到开发默认 http://localhost:8788,行为不变。 如需指向独立 API 域名,可用 docker compose build --build-arg VITE_API_BASE=<url> 覆盖。


仍需人工关注 / 建议(非本次修改)

项 说明 建议动作
/help 路由 App.tsx 无 /help 分支,直访回退 HomePage 若属规划页面,补路由与组件;部署侧无需改动
色板数据同步 perler-lab-server/palettes/ 与 competitor-analysis/palettes/ 需保持同步 更新色板后手动同步(或改为卷挂载 + 单独管理)
CI 冒烟步骤提交 deploy.yml 的「Verify SPA dist & route smoke」为 T-109 工作区未提交改动,随 T-109/T-110 一起入库 提交时确认包含
前端缓存 /assets/ 强缓存 30d(hash 文件名)保证新页面更新后无缓存残留 无操作

上线验证命令(部署后执行)

# 1. 路由直访(应 200 且返回 index.html)
for r in /showcase /library /color-chart/mard /chibi; do
  echo "$r → $(curl -s -o /dev/null -w '%{http_code}' http://localhost:8080$r)"
done

# 2. 新接口(经 Nginx 反代)
curl -s http://localhost:8080/api/color-chart/mard | head -c 200
curl -s http://localhost:8080/api/showcase/meta
# 预期:color-chart 返回含 colors 数组的 JSON-LD(非空),meta 返回 title/description

# 3. 健康检查
curl -sf http://localhost:8080/healthz && curl -sf http://localhost:8788/health

若 curl .../api/color-chart/mard 返回的 colors 为空,说明 PALETTES_DIR 未生效 或 perler-lab-server/palettes/ 未同步,按 §2-A 检查容器内 /app/palettes 内容(docker exec perler-lab-server ls /app/palettes)。

变更记录(T-110)

变更 文件
新增品牌色板数据目录(6 个 JSON,供色号表 API 读取) perler-lab-server/palettes/
运行阶段 COPY 色板数据入镜像 perler-lab-server/Dockerfile
server 服务新增 PALETTES_DIR=/app/palettes perler-lab-server/docker-compose.yml
构建阶段设置 VITE_API_BASE=/api(生产同源 API 基址) perler-lab/Dockerfile
新增本文档(部署核对结论 + 配置清单 + fallback 片段) docs/DEPLOY-NEWPAGES.md