peoplelib/site/DEPLOY.md

# 站点部署说明

`reader.mesalogo.com` 的 GitHub Pages 部署步骤。站点是纯静态的，没有构建步骤、没有 npm 依赖、没有 CDN 外链。

本文里凡是标注「查证」的，出处是 GitHub 官方文档（已抓取正文核对）；标注「推断」的是我根据文档与本仓库现状的判断，需要你实际操作时确认。

---

## 一、文件清单

站点全部文件在 `site/`，目录本身就是站点根。

| 路径 | 作用 |
|---|---|
| `site/index.html` | 首页。价值主张、核心能力、隐私要点、真实截图、格式对照表 |
| `site/features.html` | 功能页。按真实功能清单展开，末尾有「不包含的功能」一节 |
| `site/privacy.html` | 隐私与安全。本地优先、自带密钥、确认后外发、进程边界、不绕 DRM、联网范围表 |
| `site/download.html` | 下载与安装。Windows 免安装步骤、macOS DMG 与首次打开的处理、首启建议 |
| `site/faq.html` | 常见问题。费用、数据位置、格式、macOS 拦截、离线、更新、超大 PDF 等 |
| `site/404.html` | 自定义 404。用根绝对路径引用资源（见下文注意事项） |
| `site/assets/style.css` | 唯一样式表。深浅两套配色随 `prefers-color-scheme` 切换 |
| `site/assets/shot-*.jpg` | 产品截图，由 `docs/screenshots/` 原图缩放转码而来 |
| `site/assets/icon-{light,dark}-{32,256,512}.png` | favicon 与品牌标记，从 `icons/dist/` 复制 |
| `site/assets/og-cover.jpg` | Open Graph 分享封面，1200x630 |
| `site/assets/build-assets.ps1` | 一次性资产生成脚本。换截图时手动重跑，站点本身不依赖它。只写 `site/assets/`，只读 `docs/screenshots/` 与 `icons/dist/` |
| `site/CNAME` | 自定义域名声明，内容是单行 `reader.mesalogo.com` |
| `site/.nojekyll` | 空文件，跳过 Jekyll 处理 |
| `site/robots.txt` | 允许全部抓取，指向 sitemap |
| `site/sitemap.xml` | 五个页面的站点地图 |

没有 JavaScript。折叠式常见问题用原生 `<details>` 实现，不需要脚本。

### 已做的校验

- 六个页面在移动宽度（390px）下 `scrollWidth == clientWidth`，无横向溢出。
- 全部内部链接与资源路径存在，全部页内锚点有效。
- 页面只引用本地资源。外部地址只出现在 `<a href>`（指向 github.com）与 `<link rel="canonical">`。
- 浏览器控制台无报错、无警告。
- 深浅两套配色的正文、次要文字、按钮、链接、页脚、表头对比度全部达到 WCAG AA，最低一项 4.75:1。
- 每页一个 `h1`，`lang="zh-CN"`，全部 `<img>` 有 `alt`，装饰性图标用空 `alt`。
- 全部文件 UTF-8 无 BOM，无 emoji，无破折号。

---

## 二、部署方案

### 问题背景

本仓库有两个远端，用途不同：

- `github`（`git@github.com:lofyer/peoplelib.git`，公开）：源码与 CI，历史与本地无共同祖先。
- `origin`（私有 Gitea）：完整源码，日常开发推这里。

GitHub Pages 只能托管在公开仓库或付费计划的私有仓库上。站点要走公开仓库，所以核心问题是：**怎么让站点有自己独立的一条历史，改站点不牵动源码分支。**

顺带提醒一句（查证）：Pages 站点在互联网上始终是公开的，即使仓库是私有的。所以不要指望靠仓库权限藏住站点内容。

### 三种可选方式

GitHub 文档明确的发布源只有两类（查证）：从某个分支发布，源目录只能是该分支的根 `/` 或 `/docs`；或者用自定义 GitHub Actions 工作流发布。

| 方式 | 是否可行 | 评价 |
|---|---|---|
| 公开仓库 `main` 分支的 `/docs` | 可行 | 但公开仓库的 `docs/screenshots/` 已被 README 引用，站点文件混进同一目录后，`docs/` 既是文档目录又是站点根，语义混乱。而且 README 与站点共用一次提交，改站点会污染 README 的历史 |
| 公开仓库独立 `gh-pages` 分支，根目录就是站点 | **推荐** | 分支里只有站点文件，改站点不牵动 `main` 的源码历史，两条线互不干扰 |
| GitHub Actions 工作流 | 不推荐 | 站点零构建，Actions 唯一的价值是自动化，收益抵不上多出来的运行时依赖与调试面。`main` 上的工作流只管应用的构建与发布 |

### 结论：公开仓库的 `gh-pages` orphan 分支，源目录 `/`

三个问题的答案：

1. **部署方式**：从公开仓库的 `gh-pages` 分支发布，源目录选根 `/`。不用 `/docs`，不用 Actions。
2. **CNAME 位置**：放在**发布分支的根目录**。因为 `site/` 的内容会成为 `gh-pages` 的根，所以 `site/CNAME` 推上去之后自然就在 `gh-pages` 根上，位置正确，不需要移动。（查证：从分支发布时，在 Settings 里保存自定义域名会自动在源分支根目录提交一个 `CNAME` 文件；反过来，你自己先放好这个文件也一样生效。用 Actions 发布则不会创建 `CNAME`，已有的也会被忽略。）
3. **`site/` 目录名会不会冲突**：不冲突，但**前提是用上面这个方案**。Pages 认不了名为 `site` 的源目录，它只认分支根或 `/docs`。而在本方案里 `site/` 只是私有仓库里的源目录，推送时把它的**内容**摊到 `gh-pages` 的根，Pages 看到的是根目录，所以目录叫什么都无所谓。**不需要改名，也不需要动仓库里其他任何地方。**

---

## 三、发布操作

### 3.1 首次发布

用一个临时 worktree 挂 orphan 分支，避免污染主工作区。以下命令在 PowerShell 下逐条执行，`$repo` 换成你的实际路径。

```powershell
$repo = "D:\my_git\peoplelib"
$wt   = "D:\my_git\peoplelib-pages"   # 临时工作树，放在仓库外面

cd $repo

# 1. 建一个挂着 orphan 分支的工作树。orphan 意味着无父提交，天然与源码历史无共同祖先
git worktree add --orphan -b gh-pages $wt

# 2. 把站点内容摊到工作树根目录。注意是 site\ 的内容，不是 site 这个目录本身
Copy-Item -Path "$repo\site\*" -Destination $wt -Recurse -Force
Copy-Item -Path "$repo\site\.nojekyll" -Destination $wt -Force   # 点开头的文件通配符可能漏掉，单独补一次

# 3. 确认工作树里只有站点文件，没有任何源码
cd $wt
git status --porcelain
Get-ChildItem -Force | Select-Object Name

# 4. 提交
git add -A
git commit -m "站点：发布 reader.mesalogo.com 首版"

# 5. 推到公开远端
git push github gh-pages
```

`git worktree add --orphan` 需要 Git 2.42 或更高。本机是 2.55.0，可用。

发布脚本里不要 `git add` 那个 `assets/build-assets.ps1`，其实带上也无妨，它只是个纯文本工具脚本，不含源码逻辑，留着方便日后换图。你若不想让它进公开仓库，第 3 步之后删掉即可：

```powershell
Remove-Item "$wt\assets\build-assets.ps1"
```

### 3.2 后续更新

工作树保留着的话，更新只要重复复制加提交：

```powershell
$repo = "D:\my_git\peoplelib"
$wt   = "D:\my_git\peoplelib-pages"

cd $wt
# 先清干净，避免删掉的文件残留在分支上（保留 .git）
Get-ChildItem -Force | Where-Object { $_.Name -ne '.git' } | Remove-Item -Recurse -Force

Copy-Item -Path "$repo\site\*" -Destination $wt -Recurse -Force
Copy-Item -Path "$repo\site\.nojekyll" -Destination $wt -Force

git add -A
git commit -m "站点：更新下载说明"
git push github gh-pages
```

不再需要工作树时清理：

```powershell
cd $repo
git worktree remove ..\peoplelib-pages
```

### 3.3 需要你决定的两件事

这两件都在 `site/` 之外，我没有动，交给你：

1. **`.gitignore`**：`site/` 目前**没有**被忽略，`git status` 能看到它。如果你希望站点源文件跟着私有仓库一起走版本管理（推荐，这样才有历史可查），就什么都不用改。如果你不想让它进私有仓库，自己在 `.gitignore` 里加 `/site/`，注意要带前导斜杠，否则会连带匹配其他层级的同名目录，这和仓库里 `/dist/` 那条规则是同一个坑。

2. **不要加 GitHub Actions workflow**。上面已经论证过不推荐。如果你后来改主意要走 Actions，记住一条（查证）：用 Actions 发布时 `CNAME` 文件不会被创建，已存在的也会被忽略且不是必需的，域名完全由 Settings 里的配置决定，那时 `site/CNAME` 就成了无用文件。

---

## 四、GitHub 仓库设置

在 `https://github.com/lofyer/peoplelib` 上操作。

1. 进 **Settings**，左侧 **Code and automation** 分组里点 **Pages**。
2. **Build and deployment** 的 Source 选 **Deploy from a branch**。
3. Branch 选 **`gh-pages`**，Folder 选 **`/ (root)`**，点 **Save**。
4. **Custom domain** 填 `reader.mesalogo.com`，点 **Save**。

第 4 步之后 GitHub 会自动跑一次 DNS 检查。因为 `site/CNAME` 已经在分支根上且内容正确，这一步通常不会再产生额外提交；如果 GitHub 仍然自己提交了一次 `CNAME`，那是正常行为（查证：从分支发布时保存自定义域名会在源分支根目录提交 `CNAME`），下次更新前先 `git pull github gh-pages` 同步一下即可。

### 关于域名验证

GitHub 文档建议（查证）：**先验证自定义域名，再把它加到仓库里**，以提升安全性、避免域名被抢占。验证入口在个人或组织的 **Settings → Pages → Add a domain**，它会要求你加一条 `_github-pages-challenge-<user>.mesalogo.com` 的 TXT 记录。

这一步不是必须的，但如果你以后停用了 Pages 而 DNS 记录还留着，未验证的域名可能被别人拿去托管他们自己的站点。建议做。（查证：文档明确说明未验证且站点停用时存在被接管的风险。）

---

## 五、DNS 配置

`reader.mesalogo.com` 是**子域名**，不是 apex 域名。这个区别决定了记录类型。

### 需要加的记录

一条，就一条（查证）：

| 类型 | 名称 | 值 | TTL |
|---|---|---|---|
| `CNAME` | `reader`（即 `reader.mesalogo.com`） | `lofyer.github.io` | 自动 / 默认 |

要点：

- 值是 `lofyer.github.io`，**不带仓库名**。文档原文是 CNAME 记录应始终指向 `<user>.github.io` 或 `<organization>.github.io`，排除仓库名。（查证）
- 值不带 `https://`，不带结尾斜杠。有些 DNS 面板要求结尾带点写成 `lofyer.github.io.`，按面板的格式来。
- **不要**加 A 记录或 AAAA 记录。那四个 `185.199.10x.153` 与对应的 IPv6 地址是给 **apex 域名**（`example.com` 这种）用的。子域名只需要 CNAME。（查证）
- **不要**用通配符记录如 `*.mesalogo.com`。文档强烈反对，因为即使验证了域名，通配符覆盖下的更深层子域名仍可能被接管。（查证）

`site/CNAME` 文件与 DNS 里的 CNAME 记录是两件不同的东西，名字撞车而已：文件告诉 GitHub「这个站点用哪个域名」，DNS 记录告诉全世界「这个域名指向哪台服务器」。两边都要配。

### 当前状态

我查过（`Resolve-DnsName`）：

- `reader.mesalogo.com` 目前**不存在**，返回「DNS 名称不存在」。所以是全新添加，不会覆盖已有记录。
- `mesalogo.com` 的权威 NS 是 `serena.ns.cloudflare.com` 与 `aarav.ns.cloudflare.com`，也就是**域名托管在 Cloudflare**。

### Cloudflare 特有注意事项（推断，非 GitHub 文档内容）

在 Cloudflare 面板加这条 CNAME 时，右侧有个 Proxy status 开关：

- 建议先设成 **DNS only**（灰色云朵）。橙色云朵代表 Cloudflare 代理，此时 Cloudflare 会自己终止 TLS，GitHub 那边的 DNS 检查可能拿不到期望的应答，导致证书签发卡住或反复失败。
- 等 GitHub 侧证书签发成功、`https://reader.mesalogo.com` 能正常打开之后，如果你确实想用 Cloudflare 的 CDN，再切成橙色云朵，并把 SSL/TLS 模式设为 **Full (strict)**。不要用 Flexible，那会造成 Cloudflare 到 GitHub 之间走明文。
- Cloudflare 默认 TTL 是 Auto，不用改。

这一节是我的操作建议，GitHub 文档不涉及具体 DNS 服务商。请以实际结果为准，卡住了先把云朵切灰。

### 验证 DNS 是否生效

Windows 没有 `dig`（查证：文档明确提到这一点并推荐 `Resolve-DnsName`）：

```powershell
Resolve-DnsName reader.mesalogo.com -Type CNAME
```

期望看到 `NameHost` 是 `lofyer.github.io`。

DNS 变更最多需要 24 小时传播（查证）。多数情况几分钟就好，但如果刚改完查不到，先等，别急着反复改。

---

## 六、HTTPS 证书

顺序很重要：**先 DNS 生效，再等证书，最后勾 Enforce HTTPS。**

流程（查证）：

1. 你在 Settings → Pages 里保存或修改自定义域名后，GitHub 自动开始一次 DNS 检查。
2. 检查通过后，GitHub 排队向 Let's Encrypt 申请 TLS 证书，拿到后自动部署到负责 Pages TLS 终止的服务器上。
3. 全流程成功后，Settings → Pages 的自定义域名旁边会出现一个**对勾**。
4. 这时再勾选 **Enforce HTTPS**，所有 HTTP 请求会被透明重定向到 HTTPS。

排障（查证）：如果点了 Save 之后**几分钟**还没完成，出现「Certificate not yet created」，就点域名旁边的 **Remove**，重新输入域名再 **Save**，这会取消并重启签发流程。

关于 Enforce HTTPS 的勾选时机：文档说所有 Pages 站点包括正确配置了自定义域名的站点都支持 HTTPS 与 HTTPS 强制。**推断**：在证书还没签发出来（域名旁边没有对勾）时，这个复选框通常是灰的点不动，或者勾上会导致站点短时间打不开。所以按上面的顺序走，看到对勾再勾它。

混合内容（查证）：如果页面里有 `http://` 开头的图片、CSS 或 JS，站点会被判定为混合内容。本站点不存在这个问题，所有资源都是相对路径引用的本地文件，已经校验过。

---

## 七、注意事项与已知坑

### 404 页面用的是根绝对路径

`site/404.html` 里的资源引用写成 `/assets/style.css` 这样的根绝对路径，因为 GitHub 会拿这个页面响应任意深度的错误路径，相对路径在 `/a/b/c` 这种地址下会解析错。

**代价**：在自定义域名生效之前，站点临时地址是 `https://lofyer.github.io/peoplelib/`，此时 404 页面的样式与图标会加载失败（它去找 `lofyer.github.io/assets/...` 而不是 `/peoplelib/assets/...`）。域名生效后站点在根路径上，一切正常。其他五个页面全部用相对路径，两种地址下都正常。

如果你想在临时地址下也让 404 页面完整，把该文件里的 `/assets/` 与 `/features.html` 等改成相对路径，代价是深层路径下样式丢失。二者不能同时满足，建议维持现状，等域名生效。

### `.nojekyll`

空文件，作用是跳过 Jekyll 处理。当前站点里没有下划线开头的文件或目录，严格说不加也能正常发布；加上是防御性的，避免以后新增 `_something` 之类的路径时被 Jekyll 悄悄吞掉。（Jekyll 忽略下划线前缀路径这一行为属于既有共识，本次未逐字查证 GitHub 文档；`.nojekyll` 本身在发布源文档里被提到是外部 CI 部署的常见做法。）

复制文件时留意：PowerShell 的 `Copy-Item site\*` 通配符可能不匹配点开头的文件，所以上面的命令里单独补了一次 `.nojekyll`。这个坑很容易漏，漏了不会报错，只是文件没过去。

### 版本号会过期

页脚、首页与下载页都写了 **2.0.0**，取自 `package.json` 的 `version` 字段。发新版时记得改，一共出现在这几处：

```powershell
Select-String -Path D:\my_git\peoplelib\site\*.html -Pattern '1\.3\.0'
```

### 站点不引用 `docs/screenshots/` 原图

`site/assets/shot-*.jpg` 是压缩转码后的副本，和 `docs/screenshots/` 的原始 PNG 相互独立。换截图时替换 `docs/screenshots/` 里的原图，然后重跑：

```powershell
pwsh -NoProfile -File D:\my_git\peoplelib\site\assets\build-assets.ps1
```

脚本只写 `site/assets/`，只读 `docs/screenshots/` 与 `icons/dist/`。

### 仓库根目录的诊断图没有被使用

`font-missing-diagnostic.png`、`probe*.json` 之类的诊断产物一个都没进站点。

---

## 八、需要你补的资产

### 现在用的是真实截图，不是占位图

站点已经用上了 `docs/screenshots/` 里的六张真实截图，缩放到 1600px 宽、JPEG 质量 88：

| 站点文件 | 来源 | 用在哪 |
|---|---|---|
| `shot-library.jpg` | `PeopleLib_bAecy2Izab.png` | 首页主视觉、OG 封面 |
| `shot-search.jpg` | `PeopleLib_34BtvLsqDE.png` | 首页画廊、功能页检索节 |
| `shot-reader.jpg` | `PeopleLib_ScQMUA2D24.png` | 首页画廊、功能页阅读节 |
| `shot-ai.jpg` | `PeopleLib_2N6zVpCFBA.png` | 首页画廊、功能页 AI 节 |
| `shot-ai-confirm.jpg` | `ai-send-confirmation.png` | 首页画廊、隐私页确认框一节 |
| `shot-annotations.jpg` | `pdf-annotations.png` | 功能页批注节 |

所以站点**不缺图也能直接上线**。下面是可以让它更好的补充项，都是可选的。

### 建议补拍的截图

| 优先级 | 内容 | 用在哪 | 建议尺寸 | 说明 |
|---|---|---:|---|---|
| 高 | **AI 设置页**，展示接口地址、协议选择与 Key 输入框 | 隐私页「AI 密钥」一节 | 宽 ≥ 1600px，16:10 左右 | 目前这一节全是文字。给出真实界面能显著提升「自带密钥」这个卖点的说服力。**截图前务必清空或涂掉真实 Key** |
| 高 | **画布笔记**，最好是以 PDF 页面作底版的那种 | 功能页「笔记与批注」节 | 宽 ≥ 1600px | 画布笔记是差异化功能，现在只有文字描述 |
| 中 | **书架与标签的批量整理**，多选状态下的操作栏 | 功能页「本地书库」节 | 宽 ≥ 1600px | 那一节现在是定义列表，没有配图 |
| 中 | **macOS 首次打开的系统提示框**，以及右键菜单里的「打开」 | 下载页 macOS 节、常见问题 | 宽 800 至 1200px 即可 | 这是最容易让用户误判为病毒的环节，配图比文字管用得多。需要在 macOS 上截 |
| 中 | **EPUB 阅读界面**，带目录侧栏 | 功能页 EPUB 卡片 | 宽 ≥ 1600px | 现有截图全是 PDF，看不出 EPUB 的重排效果 |
| 低 | **浅色主题下的书库界面** | 首页主视觉的浅色替换 | 宽 ≥ 1600px | 现有截图都是深色界面，浅色站点配色下略显突兀。若要做，需要给 `<picture>` 加 `prefers-color-scheme` 分支，改动量不大但需要我再写一次 |
| 低 | **代理设置界面** | 功能页「代理与镜像容错」节 | 宽 ≥ 1600px | 截图前遮掉真实代理地址 |

补图流程：把新 PNG 放进 `docs/screenshots/`，在 `site/assets/build-assets.ps1` 的 `$map` 数组里加一行映射，重跑脚本，然后在对应 HTML 里插 `<figure class="shot">`。

### 图标

已经复用 `icons/dist/` 的应用图标，浅色深色两套按 `prefers-color-scheme` 切换，不需要新画。

唯一缺的是 **`favicon.ico`**。当前只提供 32px PNG favicon，现代浏览器都认，但少数老浏览器和某些抓取器会去根目录硬找 `/favicon.ico`。要补的话把 `icons/dist/book-ai-light.ico` 复制成 `site/favicon.ico` 即可，属于可选项。

### Open Graph 图

`site/assets/og-cover.jpg` 已生成，1200x630，81 KB，内容是深色底加应用图标、产品名、两行说明与域名，右侧放书库截图。由 `build-assets.ps1` 用 GDI+ 绘制，字体是「Microsoft YaHei」。

**推断**：如果这张图要在正式场合露脸，建议你用设计工具重做一版。脚本生成的版式够用但排版粗糙，尤其是文字与截图之间的留白比例。替换时直接覆盖 `site/assets/og-cover.jpg`，保持 1200x630 与文件名不变，HTML 里的 `og:image` 尺寸声明就不用动。

---

## 九、上线后的自查清单

```powershell
# DNS
Resolve-DnsName reader.mesalogo.com -Type CNAME

# 首页可达且是 200
curl.exe -sSI https://reader.mesalogo.com/ | Select-Object -First 1

# HTTP 是否重定向到 HTTPS（勾了 Enforce HTTPS 之后应该是 301）
curl.exe -sSI http://reader.mesalogo.com/ | Select-Object -First 3

# 404 页面生效（应返回 404 且内容是中文自定义页）
curl.exe -sS -o NUL -w "%{http_code}`n" https://reader.mesalogo.com/nonexistent

# 五个页面全部可达
'', 'features.html', 'privacy.html', 'download.html', 'faq.html' | ForEach-Object {
  $u = "https://reader.mesalogo.com/$_"
  "{0} {1}" -f (curl.exe -sS -o NUL -w "%{http_code}" $u), $u
}
```

浏览器里再手工看四件事：

1. 切换系统深浅色主题，页面配色跟着变。
2. 手机上打开，导航与卡片不溢出。
3. 把首页链接贴进任意支持 Open Graph 预览的地方，标题、描述与封面图正常显示。
4. 键盘按 Tab，焦点框可见，第一次 Tab 出现「跳到主要内容」。