造物矩阵模板

Appearance

文档站部署 ​

源码中的 VitePress 文档站用于保存功能、配置、部署、升级与安全说明。它是可选服务：可以部署到独立子域名供团队查阅，也可以只在本地或受保护的内网使用。

本地开发 ​

如果希望同时查看文档、社区 Web 和完整 Mock 数据，在源码根目录运行：

bash
pnpm dev:community-template

如果只修改文档站，运行：

bash
pnpm install --frozen-lockfile
pnpm dev:template-docs

默认地址为 http://localhost:4173。

生产构建 ​

bash
pnpm build:template-docs

静态产物位于：

text
apps/template-docs/.vitepress/dist

将该目录发布到静态托管或 Nginx 即可。开启 HTTPS、静态资源长期缓存与 HTML 短缓存；若使用无 .html 的 clean URL，托管平台需按 VitePress 路由规则回源。

发布到七牛 Kodo ​

如果使用七牛 Kodo + CDN，可以使用仓库内的发布脚本。脚本只新增或覆盖当前构建产物，不会删除 Bucket 中的其他对象；同时会为每个 HTML 页面上传无扩展名别名，保证 /manual-deployment 这类文档地址可直接访问。

先在七牛控制台完成以下配置：

  1. 新建专用于文档站的公开空间，不要和数据库备份、用户上传或软件交付文件混用。
  2. 开启空间的“默认首页”，让根目录的 index.html 能通过域名根路径访问。
  3. 绑定已备案的 CDN 域名，配置 HTTPS 证书，并在 DNS 服务商处把子域名 CNAME 指向七牛给出的目标。
  4. HTML 使用短缓存，带内容哈希的 JS、CSS、字体和图片可使用长期缓存；每次发布后按需刷新首页和文档页缓存。发布脚本会把 HTML、clean URL 和搜索映射设为 5 分钟，把 assets/ 下的哈希资源设为 1 年，其他固定文件设为 1 小时。

构建并先检查上传清单：

bash
SPACE_PUBLIC_URL=https://你的社区域名 \
TEMPLATE_DOCS_LAST_UPDATED=false \
pnpm build:template-docs

TEMPLATE_DOCS_QINIU_BUCKET=你的文档空间 \
TEMPLATE_DOCS_QINIU_UPLOAD_URL=https://upload-z1.qiniup.com \
pnpm deploy:template-docs:qiniu -- --dry-run

确认 Bucket、上传区域和对象清单无误后再上传：

bash
TEMPLATE_DOCS_QINIU_BUCKET=你的文档空间 \
TEMPLATE_DOCS_QINIU_UPLOAD_URL=https://对应区域的上传地址 \
TEMPLATE_DOCS_QINIU_PUBLIC_URL=https://你的文档域名 \
pnpm deploy:template-docs:qiniu -- --activate

脚本从环境变量读取 QINIU_ACCESS_KEY 和 QINIU_SECRET_KEY，不会接受命令行密钥参数，也不会打印密钥。可用 --env-file /绝对路径/.env 显式加载凭证。首次切换 DNS 前，可以暂时不设置 TEMPLATE_DOCS_QINIU_PUBLIC_URL，上传后先通过七牛测试域名检查 index.html；正式域名生效后，再带公开地址执行一次完整上传与在线校验。

自托管替代方案 ​

随源码提供的 Docker Compose 也包含 template-docs 静态服务，供私有部署、内网使用或七牛不可用时切换。使用整套 Compose 自托管时，可和网关一起构建：

bash
docker compose --env-file .env up -d --build template-docs nginx

默认网关域名示例为 docs.example.com。部署时应将 Nginx 中的域名替换为自己的文档子域名，并确认 DNS、通配符或单域名证书均已覆盖该地址。如果公网 DNS 仍指向 CDN，只启动 Compose 容器不会切换公网流量。

灾难恢复 ​

  • 主站服务器损坏、七牛仍正常：模板站公网对象不受服务器磁盘损坏影响。新服务器恢复已验证源码、生产 .env / Secret 后，运行预检和 bash scripts/production-deploy.sh template-docs 重建自托管回退容器，再用 pnpm deploy:template-docs:qiniu -- --dry-run 校验七牛对象。
  • 七牛空间对象丢失、源码仍正常：从已验证的 Git tag 或 main 重建 template-docs 服务，运行标准发布命令重新生成全部对象；CDN 缓存不是备份，不能作为恢复来源。
  • 服务器和七牛同时损坏：先按主站灾难恢复文档取回加密恢复包中的环境配置，轮换七牛凭据，再从 Git 的已验证版本重建并发布。模板站不保存数据库和用户上传，恢复资产是源码、环境配置、DNS/CDN 配置，而不是服务器容器卷。
  • 切换为服务器自托管：必须先把 DNS 从七牛 CNAME 切到服务器入口，确认 Nginx 路由与证书覆盖，再验证 clean URL、静态资源缓存和 Umami；不能只启动容器就假定公网已切换。

恢复后至少验证 DNS 链路、HTTPS、首页、/manual-deployment、哈希资源、Umami tracker 和一次真实统计落库，并在运维记录中写明当时采用“七牛 CDN”还是“服务器自托管”。

自托管 Umami ​

生产构建可以注入独立的模板文档站 Website ID：

bash
UMAMI_SCRIPT_URL=https://analytics.example.com/script.js \
UMAMI_WEBSITE_ID=<template docs website id> \
UMAMI_ALLOWED_HOSTS=docs.example.com \
pnpm build:template-docs

Compose 会把根目录 .env 中的 UMAMI_SCRIPT_URL、TEMPLATE_DOCS_UMAMI_WEBSITE_ID 和 TEMPLATE_DOCS_UMAMI_ALLOWED_HOSTS 映射成这些构建参数。ID 或脚本地址为空时不注入 tracker；脚本地址必须是 HTTPS，白名单不接受通配符。注入后 tracker 排除 URL search/hash 并尊重 DNT。

与社区站配合 ​

  • 通过 TEMPLATE_DOCS_PUBLIC_URL 指定文档站地址，首页“独立部署”和后台“配置与文档”会直接打开该地址。
  • 如果文档只供团队使用，可以放在 VPN、访问控制或单点登录之后，但需要确保部署人员能够访问。
  • 文档站是纯静态站点，不处理注册、支付、订单、下载权限，也不保存数据库连接或云服务密钥。
  • 不要把 .env、对象存储 key、永久下载 URL、生产日志或用户数据写进 Markdown 和前端资源。
  • 如果不准备长期托管文档站，至少保留当前版本的本地文档和 README，供升级与故障恢复时查阅。

发布前验证桌面与移动端导航、全文搜索、文档内链、404、站点地图和 HTTPS canonical URL。