Phase 4 CMS 基础报告

日期：2026-09-09 范围：P4-01 至 P4-03 状态：CMS 数据边界、模型、公共内容 API、可复现迁移、受控管理员、访问控制与真实内容闭环均已验收通过。

1. 已完成

新增独立 Payload CMS 应用：apps/cms。
CMS 使用独立 PostgreSQL 数据库 kaotings_cms 和独立数据库账号，不读取业务 API 用户表。
已配置 systemd 服务 kaotings-cms，仅监听 127.0.0.1:3001。
Caddy 保留 /cms 外部边界，不向公网开放 CMS 回环端口。
建立模型：Users、Products、Media、SiteSettings、HomeContent。
Product 支持 draft、published、unpublished，slug、分类、摘要、描述、媒体、features、specs、SEO 和排序字段。
Media 为受控上传集合，普通访客只读媒体，写入需要 CMS 用户。

Next.js basePath 为 /cms，Caddy 用 handle /cms/* 原样透传给 CMS 服务（不剥离前缀），避免资源地址/重定向丢失 /cms。
/cms/admin、/cms/admin/create-first-user 可正常渲染 Payload 管理界面（200），资源以 /cms/_next/... 加载正常，无重定向循环。
公共 Products API GET /cms/api/products 返回 200 和空集合，未泄露草稿。
Website 内容适配器已切换到 CMS 公共 API；lib/content.ts 的 getProducts 以 ?where[status][equals]=published 拉取，cache: no-store，CMS 未发布产品时显示明确空状态。

核对执行记录：payload_migrations 仅含 20260909_100120_initial（batch 1），与现有 kaotings_cms 结构一致。
已重新生成初始迁移并修正类型导入，命名为 20260909_100120_initial 以对齐已应用记录，避免重复应用。
迁移文件提交进仓库：apps/cms/src/migrations/20260909_100120_initial.ts。
使用独立临时库 kaotings_cms_verify 从仓库 payload migrate 重建，得到 14 张表，列类型比对 SCHEMA_IDENTICAL；随后删除临时库，现有 kaotings_cms 未清空。
迁移类型导入已修正（MigrateUpArgs/MigrateDownArgs 用 import type，sql 用值导入），本地与服务端构建均通过。

通过一次性受控路由 apps/cms/src/app/api/seed-admin/route.ts 初始化管理员，凭据来自 /etc/kaotings/cms-admin.secrets（root-only 0600），未写入 Git/报告/日志。
路由以 x-cms-seed-token 守卫，且仅在用户表为空时创建；已存在用户时返回 409 {"ok":false,"error":"user exists"}，防止重复初始化。
管理员：tech@kaotings.com（displayName: CMS Admin）。登录验证 200 {"message":"Authentication Passed"}。
修正：seed 路由不得在 Next 运行时调用 payload.destroy()（会销毁共享数据库连接池，导致后续请求 500）。

匿名 POST /cms/api/users/first-register → 403（已有用户后 create-first-user 失效）。
匿名 POST /cms/api/users（注册）→ 403。
匿名 GET /cms/api/users、GET /cms/api/users/1（读取用户资料）→ 403。
匿名 PATCH /cms/api/users/1（提权/修改）→ 403。
匿名 GET /cms/api/access：canAccessAdmin:false（枚举到字段级权限，非仅状态码）。
管理员 GET /cms/api/access：canAccessAdmin:true。
普通网站用户属独立数据库 kaotings（角色 kaotings_app），CMS 使用 kaotings_cms 且签发自有 payload-token JWT，网站 kaotings_session cookie 不会被 CMS 接受，跨库无法获取 CMS 管理会话。

以管理员登录后创建明确标注的测试产品（slug p4-test-draft-product）：
- 草稿：公共列表/API docs:[]，官网 /products 与详情不显示。
- 发布：GET /cms/api/products 返回该产品；官网 /products 列表显示，详情页渲染正确。
- 修改：更新 summary/name 后，公共列表与官网详情立即反映新内容（no-store，无缓存陈旧）。
- 下架：status:unpublished 后，公共列表/API 为空，官网详情 404 Not Found。
测试产品已下架（当前 status:unpublished），不对公网提供内容。

/cms/admin 前缀重定向/404：Next 恢复 basePath: "/cms"，Caddy 改用 handle /cms/* 透传，不再由 Caddy 剥离前缀。
Website CMS_PUBLIC_API_URL 需指向 http://127.0.0.1:3001/cms（此前缺 /cms 前缀导致官网 /products 500）：已更新 kaotings-web.service 环境变量。
Payload Admin 的 serverFunction/importMap 接线：改用生成的真实 importMap 和 @payloadcms/next/layouts 的 handleServerFunctions。
产品 slug 查询统一使用已验证的筛选方式：GET /cms/api/products?where[slug][equals]=<slug>（返回 200）。Payload 的 GET /cms/api/products/:slug 是按 id 处理的路由，不是 slug 路由，任何单产品按 slug 取数都必须用 where[slug][equals]= 筛选，不得把按 id 的路由当作按 slug 使用。

本命中遗留的按 slug 详情 REST 500（/cms/api/products/:slug）已确认是 Payload 把该路径当作按 id 处理所致；公网产品展示闭环走 where[status][equals]=published 列表与按 slug 筛选，不受影响，后续不得引入按 id 路由取 slug。
迁移、seed 路由与集成修复已提交仓库并通过本地/服务端构建；CMS 现有数据库未清空，有受控备份（infra/scripts/backup-cms-db.sh）。
CMS 管理员一次性 seed 路由已下线，初始化令牌已撤销，管理员恢复流程见 docs/cms-admin-recovery.md。