9.7 KiB
部署核对:新页面路由与静态资源部署配置(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 数据为空。
修改(纯部署配置 + 数据文件,源码未动):
perler-lab-server/palettes/—— 从competitor-analysis/palettes/同步 6 个品牌 色板 JSON(artkal-c.json/hama.json/ikea-pyssla.json/nabbi.json/perler.json/zippland-291标准色映射.json)。后续品牌数据变更时请同步该目录。perler-lab-server/Dockerfile—— 运行阶段新增COPY palettes ./palettes。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 |