docs-site 公网部署

本目录保存 apps/docs-site 的 Nginx 配置参考。当前公网入口为 https://ai-voice.wangijun.com/，服务器通过 ssh aliyun 连接。

部署结构

文档站是 VitePress 静态站点，不运行 Bun、Node 或 systemd 服务：

text

/home/wlf/ai-voice-docs/
├── current -> releases/<release-id>
└── releases/
    └── <release-id>/
        ├── index.html
        ├── assets/
        ├── downloads/
        └── ...

Nginx 配置安装为 /etc/nginx/conf.d/ai-voice-docs.conf。cleanUrls: true 生成的 /guide/demo 等地址由 try_files $uri $uri.html $uri/ =404 解析。

构建与上传

文档站提供交互式 PowerShell 脚本 apps/docs-site/manage.ps1，菜单包含“生成（编译）”、 “部署（上传当前产物）”和“生成并部署”。从仓库根目录运行：

powershell

./apps/docs-site/manage.ps1

也可以使用 Bun workspace 脚本启动交互菜单：

powershell

bun run --cwd apps/docs-site manage

自动化或明确操作时可传入动作参数：

powershell

./apps/docs-site/manage.ps1 -Action build
./apps/docs-site/manage.ps1 -Action deploy -Yes
./apps/docs-site/manage.ps1 -Action build-deploy -Yes

默认 SSH 别名为 aliyun，远端根目录为 /home/wlf/ai-voice-docs。部署脚本先将产物压缩上传到该目录下的临时文件，解压并校验 index.html、assets/ 和权限后，再移动到版本目录并切换 current 软链接；不会把半上传目录直接暴露给 Nginx。可用 -SshHost 和 -RemoteRoot 覆盖默认值。

在仓库根目录构建：

powershell

bun run docs:check

构建产物位于 apps/docs-site/.vitepress/dist/。为每次部署创建新的 <release-id>，将该目录内的内容完整上传到 /home/wlf/ai-voice-docs/releases/<release-id>/，确认权限为目录 0755、文件 0644 后再原子切换 current 软链接。不要把 .vitepress/cache/、源码或 node_modules/ 上传到服务器。

首次配置 HTTPS

确认 ai-voice.wangijun.com 的 A 记录指向目标服务器，且公网 TCP 80/443 可达。
临时安装 nginx-http-bootstrap.conf，执行 nginx -t 后 reload。

使用 Nginx authenticator 扩展现有 wangijun.com 证书。重新签发时必须保留证书当前的全部域名，不能只传新增子域名：

bash

certbot certonly --nginx \
  --cert-name wangijun.com \
  -d wangijun.com \
  -d www.wangijun.com \
  -d ai-voice.wangijun.com \
  --expand --non-interactive --agree-tos

用 nginx.conf 替换临时配置，再次执行 nginx -t 和 reload。

扩展后 /etc/letsencrypt/live/wangijun.com/ 路径不变，三个站点共用一张 SAN 证书。Certbot 续期任务必须保持启用；续期演练使用 certbot renew --dry-run。共享证书意味着续期时三个域名都必须继续解析到能够完成 ACME HTTP 验证的服务器。

验证

bash

curl -fsSI http://ai-voice.wangijun.com/
curl -fsSI https://ai-voice.wangijun.com/
curl -fsS https://ai-voice.wangijun.com/guide/demo | grep -F '演示环境'
curl -fsSI https://ai-voice.wangijun.com/downloads/start-chrome-softphone.ps1
openssl s_client -connect ai-voice.wangijun.com:443 \
  -servername ai-voice.wangijun.com </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

预期 HTTP 返回 301 到 HTTPS，首页和无扩展名文档路由返回 200，下载文件返回 Content-Disposition: attachment，证书 SAN 包含 DNS:ai-voice.wangijun.com。

回滚

保留至少一个上一版本目录。站点内容异常时，把 current 重新指向上一版本并 reload Nginx：

bash

ln -sfn /home/wlf/ai-voice-docs/releases/<previous-release-id> \
  /home/wlf/ai-voice-docs/current
nginx -t && systemctl reload nginx

若 HTTPS 配置异常，先恢复 /etc/nginx/conf.d/ai-voice-docs.conf 的备份并 reload。不要删除 wangijun.com 证书，因为现有博客站点也在使用它；从证书中移除子域名需要重新签发，并继续显式传入 wangijun.com 与 www.wangijun.com。

docs-site 公网部署 ​

部署结构 ​

构建与上传 ​

首次配置 HTTPS ​

验证 ​

回滚 ​

docs-site 公网部署

部署结构

构建与上传

首次配置 HTTPS

验证

回滚