部署官网与后台

目标：将官网和演示部署到静态服务器，或将真实后端版本与 API 一起交付。两站独立构建，也可以放在同一个域名的不同目录。

自动发布到 Cloudflare Pages

pnpm release

本地使用临时 Git 索引捕获已暂存、未暂存、删除和未被忽略的新文件，以中文提交信息生成快照并普通 push 到 origin 的 deploy 分支。不会改变当前分支、HEAD 或暂存区；其他会话尚未提交的内容也会进入快照。相同内容不重复触发，可在 Gitea Actions 重跑。并发推送被拒绝时重新执行即可，不使用强制推送。

.gitea/workflows/deploy.yml 在服务器获取此次 push 的准确 SHA，安装锁定依赖、构建共享包、纯前端 demo 和官网，然后只上传两站静态产物。pnpm release 成功只代表快照已推送，必须在 Gitea Actions 确认两次上传成功。

域名	Pages Direct Upload 项目	构建路径
uadminui.com	uadmin-website	apps/website/.vitepress/dist
demo.uadminui.com	uadmin-demo	apps/demo/dist

首次配置

1. 创建可接收本仓库任务的 Gitea Runner，标签为 uadminui-ci，支持 Docker 任务容器，并接入能解析 gitea 的 Docker 网络。工作流使用 node:22-bookworm，内部仓库地址为 http://gitea:3000/…；若服务器使用不同地址，同步修改工作流 REPOSITORY_URL。服务器需能下载 Node 镜像及 npm 依赖、访问 Cloudflare API；不需要常驻 nginx 或 API 容器。
2. 在 Cloudflare 创建上述两个 Direct Upload Pages 项目，将两者生产分支设为 main；该值需与 deploy/release.env 的 PAGES_PRODUCTION_BRANCH 一致。Git 触发分支 deploy 与 Pages 生产分支是独立配置。
3. 在 Gitea 仓库 Settings → Actions 配置 Variable CLOUDFLARE_ACCOUNT_ID 和 Secret CLOUDFLARE_API_TOKEN；Token 需要目标账户的 Account → Cloudflare Pages → Edit 权限。缺少配置时在构建前失败。Token 只注入配置检查和上传步骤，不进入构建环境或仓库。
4. 在两个 Pages 项目的 Custom domains 分别绑定 uadminui.com 和 demo.uadminui.com，按 Cloudflare 提示完成 DNS 配置。脚本不会自动绑定域名或修改 DNS。
5. 执行 pnpm release，确认 Gitea Actions 成功，再验收官网、演示链接、登录和刷新。

公开构建地址与项目名集中在 deploy/release.env。两站均使用 / 基路径，官网演示入口为 https://demo.uadminui.com，官网 sitemap 使用 https://uadminui.com。SOURCE_URL 可按实际公开仓库另行配置。修改公开配置后需要重新发布。

上传先 demo 后官网，使用同一个快照 SHA。两项目不支持原子发布：官网上传失败时 demo 可能已经更新，工作流仍会失败；重跑同一任务补齐。回滚时可在 Pages 分别选择先前生产部署，或重新发布所需源码版本。

发布脚本验证：pnpm release:test。npm 发版已迁移到 pnpm release:packages，详见包发布流程。

1. 构建根站点和演示子目录

在仓库根目录执行：

pnpm install --frozen-lockfile
pnpm build:packages
VITE_BASE_PATH=/demo/ pnpm build:demo
DEMO_URL=/demo/ pnpm docs:build

对应产物：

apps/website/.vitepress/dist/   → 站点根目录
apps/demo/dist/                → 站点根目录下 demo/

先复制官网产物，再把 demo 产物内容复制到目标 demo 目录。仅设置 DEMO_URL 会修改入口链接，不会替你复制或部署后台文件。

官网 VitePress 使用 .html 文档链接；后台默认 hash 路由，示例深链为 /demo/#/tasks。静态服务器必须提供正确文件类型，不应将 JS 404 返回为 HTML。

2. 部署到子路径

假设整个站点位于 /uadmin/，后台位于 /uadmin/demo/：

VITE_BASE_PATH=/uadmin/demo/ pnpm build:demo
WEBSITE_BASE_PATH=/uadmin/ DEMO_URL=/uadmin/demo/ pnpm docs:build

变量使用前后斜杠完整的路径。发布时将官网内容放到 /uadmin/ 对应目录，再将后台内容放到其中 demo/。官网和后台各自的 base 必须与实际资源位置一致。

两个站点也可独立域名部署：给 DEMO_URL 设置你实际拥有的演示地址，demo 按自身域名的部署路径构建。

3. 官网的可选地址

变量	作用
DEMO_URL	首页与导航的演示链接
SOURCE_URL	已公开源码地址，未配置时不展示源码入口
WEBSITE_URL	正式站点地址，用于 sitemap
WEBSITE_BASE_PATH	文档与资源的部署基路径

配置在 apps/website/.vitepress/config.ts。这些是构建输入，修改托管平台环境变量后仍需重新构建。

4. 真实后端版本

pnpm build
node scripts/check-demo-bundle.mjs apps/demo/dist

此版本不安装浏览器 adapter，也不提供演示账号。部署服务器必须提供 /api，或使用构建时指定的真实 baseURL。Vite 开发代理不会被打进生产产物。会话、刷新、导航与业务端点必须遵循HTTP 契约。

上线前验证

pnpm build:demo
pnpm test:e2e:static
VITE_BASE_PATH=/uadmin/demo/ pnpm build:demo
pnpm test:e2e:static:subpath

测试命令不替代前面的构建。最后一次测试使用子路径产物，正式部署到根路径前需要按实际 base 再构建。

另外验证官网首页、任意文档深链、本地搜索、演示入口、登录后页面刷新，以及移动端和深色主题。GitHub CI 输出两个独立静态 artifact；Gitea 发布流程上传到已配置的 Pages 项目，不自动创建托管账户或绑定域名。

部署故障定位

首页有内容但文档 404： 检查复制是否包含所有 .html 文件。后台空白且 JS 404： 检查构建 base。API 返回首页 HTML： 静态 fallback 抢占了 /api，应先配置 API 转发。上传或持久化不可用： 使用正常 HTTP(S) 静态服务，不直接双击 index.html，并检查浏览器存储权限。