部署本书网站

本章解决什么问题：如何把这本书部署到你自己的 Linux 服务器上，以及如何更新和回滚。 前置知识：会用 SSH 登录服务器即可。不需要了解 Node.js——生产服务器上根本不运行 Node.js。

架构

本书是纯静态网站。生产环境只有一个托管静态文件的 Caddy 进程：

Markdown / TypeScript / 图片
              ↓
       VitePress 构建（仅在构建机/CI 上运行 Node.js）
              ↓
       静态网站 dist（HTML/CSS/JS/图片）
              ↓
       Caddy 静态托管（生产服务器）
              ↓
          浏览器访问

• 不需要数据库。
• 生产环境不运行 Node.js：Dockerfile 是多阶段构建，Node.js 只存在于构建阶段；最终镜像基于 caddy:2-alpine，只包含静态文件。
• 不依赖任何 CDN：全文搜索在浏览器本地执行，Mermaid、字体、全部 JavaScript 都打包在站点内。

快速部署（Docker Compose）

在装有 Docker 的服务器上：

git clone <本书仓库地址> pi-harness-book

cd pi-harness-book && docker compose up -d --build

然后浏览器访问 http://服务器IP:8080。

构建需要网络

docker compose build 阶段会执行 npm ci 下载依赖，这一步需要网络。构建完成后的运行阶段不需要访问任何外部资源。

修改端口

编辑 compose.yml，改左边的宿主机端口：

services:
  pi-harness-book:
    ports:
      - "3000:80"   # 宿主机 3000 → 容器 80

然后 docker compose up -d 重新生效。

配置域名与 HTTPS

推荐做法：容器只监听本机端口，由宿主机上的外层反向代理负责域名和证书。

外层用 Caddy（自动 HTTPS，最简单）——宿主机 /etc/caddy/Caddyfile：

book.example.com {
	reverse_proxy 127.0.0.1:8080
}

Caddy 会自动申请并续期 Let's Encrypt 证书。

外层用 Nginx：

server {
    listen 443 ssl;
    server_name book.example.com;
    ssl_certificate     /etc/letsencrypt/live/book.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/book.example.com/privkey.pem;
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
    }
}

同时建议把 compose.yml 的端口绑定收紧为 127.0.0.1:8080:80，避免绕过反向代理直接访问。

部署在子路径下

如果站点要挂在 https://example.com/pi-book/ 这样的子路径：

1. 修改 docs/.vitepress/config.mts，加上 base: '/pi-book/'；
2. 重新构建镜像（docker compose up -d --build）；
3. 外层代理把 /pi-book/ 转发到容器。

站内链接与资源路径由 VitePress 根据 base 自动处理，无需逐页修改。

更新书籍内容

git pull && docker compose up -d --build

Docker 会重新构建镜像并原地替换容器，中断时间通常在秒级。

回滚到旧版本

方式一（推荐）——按 git 版本回滚：

git log --oneline          # 找到要回退的 commit

git checkout <旧commit> && docker compose up -d --build

方式二——保留旧镜像回滚：每次发布前给镜像打标签：

docker tag pi-harness-book-pi-harness-book:latest pi-harness-book:2026-07-30

需要回滚时直接运行旧镜像：

docker run -d -p 8080:80 pi-harness-book:2026-07-30

静态文件在哪里

• 构建产物在镜像内的 /srv 目录（来自构建阶段的 docs/.vitepress/dist）。
• 如果不想用 Docker，也可以在任何装有 Node.js 的机器上运行 npm ci && npm run build，然后把 docs/.vitepress/dist/ 整个目录拷到任意静态服务器（Nginx、对象存储、GitHub Pages 均可）。Caddyfile 中的 try_files 规则对应 VitePress 的 cleanUrls，换其他服务器时需要等价配置（把 /foo 重写到 /foo.html）。

安全注意事项

• 仓库与镜像中不包含任何证书、密码或 API Key；请不要把它们提交进来。
• 本书 labs 中的实验全部无需 API Key。如果你在服务器上做第八部分的可选真实模型实验，请用环境变量传入 Key，不要写进文件。

小结

• 生产架构 = 静态文件 + Caddy，一条 docker compose up -d --build 完成部署。
• 域名与 HTTPS 交给外层反向代理；子路径部署改 base 配置。
• 更新 = git pull + 重新构建；回滚 = checkout 旧 commit 或运行旧镜像。