发布文档站到宝塔
文档使用 VitePress 1.6.4，产物为纯静态文件。服务器只需 Nginx，不需要为文档创建 Node 项目。现有授权站点、上传服务和文档站分别部署。
开发与构建
在仓库根目录执行：
pnpm install --frozen-lockfile
pnpm docs:dev
pnpm docs:build开发地址默认 http://localhost:5174，构建产物位于 docs/.vitepress/dist/。导航配置在 docs/.vitepress/config.mts，支持中文本地搜索、深色模式及页面目录；新增文档后应同步侧边栏。构建会检查站内死链接。
创建独立发布配置
Windows PowerShell 中执行（已有配置时不要覆盖）：
Copy-Item deploy.docs.example.json deploy.docs.local.json编辑生成的文件：
{
"target": "docs",
"host": "你的服务器IP",
"port": 22,
"user": "root",
"identityFile": "~/.ssh/weixin_web_auth_ed25519",
"deployRoot": "/www/wwwroot/weixin-web-auth-docs"
}SSH 密钥生成、服务器公钥配置和首次指纹确认见Windows SSH 指南。可以复用已有 SSH 登录凭据，但文档目录必须独立。配置文件已加入 Git 和格式化忽略列表。
target 必须为 docs，deployRoot 必须以 -docs 结尾，且不能与本地授权站配置的发布目录相同。这些检查用于防止误将文档发布到授权站点。不要将两个目录通过软链接关联。
一键发布
# 先构建并检查发布目标，不连接服务器
pnpm docs:build
pnpm docs:plan
# 重新构建并发布
pnpm docs:deploy
# 仅上传已经构建的文档
pnpm docs:deploy:dist支持 pnpm docs:plan --config 自定义配置.json；实际发布命令 pnpm docs:deploy:dist --config 自定义配置.json 使用同一配置。自定义本地配置需自行加入 Git 忽略。
发布复用既有 SSH 流程：打包、上传、SHA-256 校验、新版本解压、共享 .well-known 链接和 current 原子切换；失败会停止，保留历史版本。不改变授权网站或上传后端，也不自动修改宝塔 Nginx。
宝塔首次设置
按“先发布，再创建 HTML 项目”的顺序操作。此处以 docs.auth.iducloud.cn 为文档域名；请确认它已解析到 deploy.docs.local.json 指定的服务器。脚本不会申请域名或修改 DNS。
1. 先发布，生成 current 软链接
确认本地部署配置中的路径为：
"deployRoot": "/www/wwwroot/weixin-web-auth-docs"在项目根目录执行：
pnpm docs:deploy发布成功后，脚本自动创建如下结构（版本目录名以实际输出为准）：
/www/wwwroot/weixin-web-auth-docs/
current -> releases/当前版本号
releases/
当前版本号/
index.html
integration.html
assets/
shared/
.well-known/在宝塔文件管理中确认 current 是软链接，且通过该路径可以看到 index.html。首次发布不依赖文档网站已经创建。
不要提前手工创建 current 文件夹，也不要在发布前让宝塔创建这个实体目录。脚本检测到它是实体目录时会报 current is a real directory; refusing to overwrite it。如已出现该情况，先检查目录内容并备份、迁移，再处理冲突；不要直接删除可能含有站点文件或校验文件的目录。
2. 创建 HTML 项目时直接填写最终根目录
进入宝塔“网站 → HTML 项目 → 添加项目”，按表格填写：
| 界面字段 | 填写内容 |
|---|---|
| 绑定域名 | docs.auth.iducloud.cn（不带协议或路径） |
| 备注 | 微信网页授权文档 |
| 根目录 | /www/wwwroot/weixin-web-auth-docs/current |
| FTP | 不创建 |
在创建界面的“根目录”中直接填写包含 /current 的完整路径，无需后续修改运行目录。 此 HTML 项目界面没有单独的运行目录设置，不需要寻找或配置该选项。
两处目录用途不同：
| 配置位置 | 路径 | 用途 |
|---|---|---|
本地 deployRoot | /www/wwwroot/weixin-web-auth-docs | 管理版本、上传暂存和共享文件 |
| 宝塔 HTML 项目根目录 | /www/wwwroot/weixin-web-auth-docs/current | 对外提供当前版本的文档 |
不要将发布管理目录或某个固定的 releases 版本目录填写为网站根目录。后续执行 pnpm docs:deploy 或回滚时，脚本切换 current 的指向，宝塔根目录保持不变。
3. 配置 HTTPS 和文档路由
配置证书和 HTTPS，保留宝塔生成的 ACME 验证规则。文档站同样使用持久化 shared/.well-known。
在该文档网站的 Nginx 配置中合并以下规则，已有相同 location 或 error_page 时修改原配置，不要重复添加：
location / {
try_files $uri $uri.html $uri/ =404;
}
location ~* \.html$ {
expires off;
add_header Cache-Control "public, max-age=60, s-maxage=300";
}
error_page 404 /404.html;配置检查通过后重载 Nginx。cleanUrls: true 对应 $uri.html 查找，因此 /integration 刷新时可直接读取 integration.html。文档站不是授权应用的 SPA，不要使用 /index.html 兜底所有未知路径。保留现有证书、HTTPS、隐藏文件访问限制。
默认文档部署在独立域名根路径 /；不要直接将产物挂在授权域名 /docs/，子路径部署需要同步修改 VitePress 的 base 和 Nginx 映射，本方案不包含此模式。
手动上传方式
如果不使用 SSH 脚本，可在宝塔创建独立静态网站，将 docs/.vitepress/dist/ 内的全部内容上传到它的网站根目录，沿用上述 Nginx 路由规则。不要上传整个仓库、私钥或部署配置。手动方式不具备脚本的版本切换和回滚机制，也不要与脚本管理的 current 目录混用。
回滚与验证
pnpm docs:rollback 20260924003000-abcdef123456 --dry-run
pnpm docs:rollback 20260924003000-abcdef123456版本号需替换为实际历史发布版本。回滚沿用独立文档配置；自定义配置时追加 --config 参数。确认不再需要后才清理历史版本，不要删除 current 指向版本、shared 或软链接目标。
发布后核对：
- 首页、侧边栏、深色模式及中文搜索正常。
/integration、/verification-upload、/docs-deployment可以直接打开并刷新。- 随机不存在的路径返回 HTTP 404。
- HTTPS 与 ACME 验证文件正常，授权站点及上传服务保持正常。
本地构建成功不代表服务器配置已完成。首次发布仍需填写真实目标并按上述步骤配置宝塔。
参考：VitePress 官方部署指南。
文档站使用 ESA
文档 HTML 使用上方正数 TTL（浏览器 60 秒、边缘 300 秒），需在 ESA 显式允许文档页面缓存。发布和回滚后清理文档 HTML 的边缘缓存；浏览器缓存仍可能保留 60 秒。ACME 路径绕过缓存，不要套用授权站点专用的 request_uri map。对于 logo.png 等文件名不变的图片，使用短 TTL 或更新文件名，不能直接设置一年 immutable。授权站点的独立策略见ESA 缓存配置。