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，公开）：只放 README 与截图，不推源码，历史与本地无共同祖先。
• origin（ssh://git@git.digiman.live:11022/root/peoplelib.git，私有）：完整源码。

GitHub Pages 只能托管在公开仓库或付费计划的私有仓库上。站点要走公开仓库，所以核心问题是：怎么把 site/ 推上公开仓库，同时一行源码都不带过去。

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

三种可选方式

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

方式	是否可行	评价
公开仓库 main 分支的 /docs	可行	但公开仓库的 docs/screenshots/ 已被 README 引用，站点文件混进同一目录后，docs/ 既是文档目录又是站点根，语义混乱。而且 README 与站点共用一次提交，改站点会污染 README 的历史
公开仓库独立 gh-pages 分支，根目录就是站点	推荐	分支里只有站点文件，物理上不可能带上源码。与现有的「用独立 orphan 提交推公开仓库」约定同构。README 留在 main，两条线互不干扰
GitHub Actions 工作流	不推荐	需要在公开仓库放 .github/workflows/，与「只放 README 与截图」的约定冲突；而且站点零构建，Actions 唯一的价值是自动化，收益抵不上多出来的运行时依赖与调试面

结论：公开仓库的 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 换成你的实际路径。

$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 步之后删掉即可：

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

3.2 后续更新

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

$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

不再需要工作树时清理：

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）：

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。这个坑很容易漏，漏了不会报错，只是文件没过去。

版本号会过期

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

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

站点不引用 docs/screenshots/ 原图

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

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 尺寸声明就不用动。

---

九、上线后的自查清单

# 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 出现「跳到主要内容」。