Initial homepage

docs/AI-HANDOFF.md

@@ -0,0 +1,63 @@
+# AI 交接说明
+
+更新日期：2026-08-18
+
+## 当前状态
+
+项目是 `midctrl.com` 的纯静态首页，无数据库、API 或构建步骤。网站运行文件位于 `site/`。当前版本已完成代码复审、冷启动修复、移动端检查和公开文件白名单验证，但本仓库版本尚未上传生产服务器。
+
+## 最近完成的修复
+
+- WebGL 从等待 `window.load` 改为 DOM 就绪后初始化，字体或图片请求不会阻塞 Sakura。
+- 初始化函数幂等，避免重复创建场景。
+- 初始化时重新读取页面可见性和 reduced-motion 状态。
+- `pagehide` 取消待执行帧，`pageshow` 重新同步并恢复。
+- generation guard 隔离浏览器队列中未及时移除的旧 rAF 回调。
+- `site-config.json` 请求超时为三秒，失败时使用 HTML 中的链接。
+- 资源查询版本为 `20260818-3`。
+
+## 渲染约束
+
+- 粒子数：1,600。
+- 花瓣 draw call：五次。
+- Bloom directional blur draw：四次。
+- 帧率上限：120 FPS，跟随显示器 `requestAnimationFrame`。
+- 内部像素预算：普通设备 1,000 万像素，浏览器报告内存不高于 4 GB 时为 600 万像素。
+- resize 稳定窗口：140 ms。
+- reduced-motion：WebGL 静态帧，头像框使用静态图片。
+
+不要在没有用户明确批准的情况下通过降低粒子、Bloom 或绘制次数解决性能问题。
+
+## 关键文件
+
+- `site/assets/js/main.js`：链接配置、Shader、Sakura、Render Target 和生命周期。
+- `site/assets/css/main.css`：布局、字体、文字和头像效果。
+- `site/assets/js/site-config.json`：站点名称、描述、规范 URL、外链名称和 URL。
+- `tests/test-render-target-resize.js`：无第三方依赖的 VM 测试。
+- `scripts/verify-production.ps1`：生产检查和公开目录白名单。
+- `nginx/midctrl.com.example.conf`：脱敏示例，不是生产服务器完整配置。
+
+## 推荐工作流程
+
+```powershell
+python -m http.server 9010 --bind 127.0.0.1 --directory site
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-production.ps1
+```
+
+修改后先运行自动检查，再用真实浏览器检查首页、移动端和 `/404.html`。检查控制台并对纯 Sakura 区域间隔采样，确认画面确实变化。
+
+## 生产边界
+
+- Cloudflare SSL/TLS 使用 `Full (strict)`。
+- 源站为 AlmaLinux 9 和 Nginx。
+- 生产主机还有不属于本仓库的私有 location，部署时必须从现有服务器配置中保留。
+- 证书私钥、服务器地址、私有 location、备份和上传凭据不得进入仓库。
+- 用户授权部署前，只能在本地修改和验证。
+
+## 新会话启动提示
+
+可以在新 AI 会话中直接说明：“请先阅读 `AGENTS.md` 和 `docs/AI-HANDOFF.md`，运行生产检查，再继续处理我的需求。”
+
+## 域名配置边界
+
+运行时站点身份从 `site/assets/js/site-config.json` 读取，首页的标题、canonical 和 Open Graph 元数据不会再分别写死域名。`site/robots.txt` 与 `site/sitemap.xml` 是需要绝对 URL 的静态 SEO 文件；更换站点域名时必须一并更新它们，并运行生产检查。

docs/DEPLOYMENT.md

@@ -0,0 +1,72 @@
+# 部署说明
+
+## 环境
+
+- AlmaLinux 9
+- Nginx
+- Cloudflare CDN
+- Cloudflare SSL/TLS：`Full (strict)`
+
+网站是纯静态文件，不需要数据库、Node.js 服务或常驻应用进程。
+
+## 生成发布包
+
+在仓库根目录执行：
+
+```powershell
+Compress-Archive -Path .\site\* -DestinationPath .\midctrl-homepage-public.zip -CompressionLevel Optimal
+Get-FileHash .\midctrl-homepage-public.zip -Algorithm SHA256
+```
+
+发布 ZIP 不应提交到 Git。
+
+## 部署网站文件
+
+将 ZIP 上传后解压到独立网站目录：
+
+```bash
+mkdir -p /var/www/midctrl.com
+unzip -o /root/midctrl-homepage-public.zip -d /var/www/midctrl.com
+chown -R root:nginx /var/www/midctrl.com
+find /var/www/midctrl.com -type d -exec chmod 755 {} \;
+find /var/www/midctrl.com -type f -exec chmod 644 {} \;
+```
+
+如果 SELinux 已启用，再执行：
+
+```bash
+restorecon -Rv /var/www/midctrl.com
+```
+
+## Nginx
+
+`nginx/midctrl.com.example.conf` 是公开、脱敏的参考模板。不要直接覆盖生产配置。部署时需要：
+
+1. 将现有站点 `root` 指向 `/var/www/midctrl.com`。
+2. 合并安全响应头、缓存和 gzip 规则。
+3. 保留服务器现有的所有私有 location 和代理请求头。
+4. 保留有效的 Cloudflare Origin Certificate 路径。
+5. 确认字体使用 `font/woff2` 或兼容的 MIME 类型。
+
+生效前必须执行：
+
+```bash
+nginx -t
+systemctl reload nginx
+```
+
+只有 `nginx -t` 成功后才能 reload。
+
+## 部署后检查
+
+- 首页和 404 页面正常。
+- Blog 与 Tools 在新标签页打开。
+- Noto Serif SC 字体返回 200。
+- 控制台无 JavaScript、WebGL 或资源错误。
+- Sakura 在前台页面持续运动，页面进入后台后暂停并能恢复。
+- 服务器原有私有服务仍正常。
+- 仓库 README、测试和 Nginx 示例没有出现在网站根目录。
+
+## 回滚
+
+部署前备份当前网站目录和 Nginx 配置。发生问题时恢复备份，运行 `nginx -t`，成功后 reload。不要把生产备份提交到 Git。