178 lines
9.7 KiB
Markdown
178 lines
9.7 KiB
Markdown
# 部署核对:新页面路由与静态资源部署配置(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` |
|