19 · 课程网站部署与维护¶

19.1 本次部署结构¶

域名 pi.baoer.me，用户已将 *.baoer.me 指向这台服务器。本课程使用现有服务器 Nginx 直接发布，符合用户指定的自有服务器与域名方式。

Markdown 原稿 → MkDocs build → site/ → /var/www/pi-course → Nginx → pi.baoer.me

它是静态课程，不依赖长期运行的 Python / Node server。浏览器可看课程、搜索、渲染图和下载资料，不能通过站点操作你的服务器 Agent。

19.2 关键文件¶

位置	用途
`/home/debian/codex/learn/pi/docs`	分章原稿
`/home/debian/codex/learn/pi/mkdocs.yml`	导航和 Markdown 配置
`/home/debian/codex/learn/pi/site`	构建产物
`/var/www/pi-course`	Nginx 静态发布目录
`/etc/nginx/conf.d/pi-course.conf`	本站独立 Nginx 配置
`/etc/letsencrypt/live/pi.baoer.me`	新申请的本站证书，key 不公开
`deployment/requirements.lock`	网站构建与浏览器 QA Python 依赖版本
`deployment/renewal-hook.sh`	证书续期后测试并 reload Nginx

使用独立证书而不是改已有站点的通配证书，避免影响服务器其他域名。

19.3 改文档后重新发布¶

cd /home/debian/codex/learn/pi
python3 scripts/prepare_course.py
python3 scripts/assemble_course.py
.venv/bin/mkdocs build --strict
python3 scripts/check_course.py
sudo mkdir -p /var/www/pi-course
sudo rsync -a --delete --exclude='.well-known/' site/ /var/www/pi-course/

静态内容更新不需要重启 Nginx。改 Nginx 配置才需要 test / reload。

完整单文件 Markdown 是自动合并产物，不要直接编辑它；改对应章节再 assemble。

19.4 HTTPS 与续期¶

本次以 webroot HTTP-01 方式申请 pi.baoer.me 证书。80 端口保留 ACME challenge 路径，其余跳转 HTTPS。Certbot 定时器负责续期，deploy hook 成功后 reload Nginx。

sudo /usr/sbin/nginx -t
sudo systemctl status certbot.timer
sudo certbot certificates

浏览器经 Cloudflare 返回的证书与 origin 本机证书是两个链路，验收分别检查。不要把外部 HTTPS 200 当作 origin 证书一定有效。

19.5 本地重建环境¶

uv venv .venv
uv pip install --python .venv/bin/python -r deployment/requirements.lock
.venv/bin/mkdocs build --strict

课程自身不需要外部字体。Mermaid 脚本固定下载并本地托管，图表不依赖读者访问 CDN；保留第三方许可证。网站搜索也用本地索引。

19.6 备份与迁移¶

备份 docs、examples（含 lockfile）、scripts、deployment、research、mkdocs.yml 和 README。上游源码可按固定 commits 重新下载；要离线读则保留 upstream 和 pi-1.0。

证书私钥与任何未来 Agent auth.json 不加入公开课程压缩包。迁移网站时在新机器重新申请证书或通过安全方式迁移，不把密钥放进静态目录。

网站停止或回滚只操作本站 conf 和发布目录；不重写服务器其他已有站点配置。

19.7 下载缓存与版本¶

本轮公网字节比对发现 Cloudflare 在 ZIP 更新后仍返回第一版缓存。当前课程下载链接附 revision=20261003-review2，绕开旧 cache key；本站 Nginx 对 assets 下的 Markdown/ZIP 返回 Cache-Control: no-store，使新链接的下载更新不被旧 edge 缓存掩盖。普通本地图表脚本不走此下载 location。

改写下载包后运行 python3 scripts/verify_public_downloads.py，它请求课程实际使用的 revision 链接，核对所有字节与 SHA-256。公网 HTTP 200 并不能证明文件是新版；证据以实际下载比对为准。未来大版本可换 revision 名称，配合原站 no-store 规则；不要只刷新本地 site/ 便认为 CDN 已刷新。