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

178 lines
9.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 部署核对:新页面路由与静态资源部署配置(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 回退,无需新增:
```nginx
# ── 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` 之前):
```dockerfile
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 文件名)保证新页面更新后无缓存残留 | 无操作 |
## 上线验证命令(部署后执行)
```bash
# 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` |