VMax 文档站部署

状态：自动部署与回滚演练已通过。公开站点为 https://vmax-docs.codecat.studio/，允许公众访问；2026-09-24 的 Gitea Actions 第 4、5 次运行完成了首次发布及连续更新，第 7 次运行验证了受保护 main 的文档推送可直接完成验证与部署。首页、中文路径、图示、严格 TLS 和禁止文件检查已通过。专用部署账户 vmaxdocs、站点目录权限、主分支白名单、Runner 标签、仓库变量与部署 Secrets 已核对。第 5 次发布后曾切回第 4 次版本，确认页面内容回退，再恢复最新版本。

本地预览

要求 Node.js 20 或更高版本。安装锁定依赖后运行开发服务器：

npm ci
npm run docs:dev

生产构建及预览：

npm run docs:check
npm run docs:preview

构建产物位于 docs/.vitepress/dist/。本站使用中文路径与无扩展名 URL；静态服务器需要支持 UTF-8，并在请求无扩展名路径时回退到同名 .html。

若站点托管在子路径，例如 https://example.com/vmax/，构建时显式设置：

VITEPRESS_BASE=/vmax/ npm run docs:build

独立容器

仓库根目录提供只包含静态文件的多阶段 Dockerfile.docs。最终镜像不包含源码、原始 DOCX、Node.js 或管理接口：

docker build -f Dockerfile.docs -t vmax-docs:local .
docker run --rm -p 8080:8080 vmax-docs:local

访问 http://127.0.0.1:8080/。容器以非 root 用户运行，Nginx 配置了中文 URL、缓存策略、基础安全响应头与健康检查端点 /healthz。VitePress 会内嵌主题初始化与页面索引脚本，因此 CSP 仅对构建生成的 inline script 放行；外部脚本、外部连接和对象嵌入仍被禁止，Markdown 合并前必须经过仓库审阅。

Gitea 自动构建与发布

仓库远端已确认是 Gitea。.gitea/workflows/docs-site.yml 以受保护的 main 分支作为唯一发布入口：

1. 工作流只响应 main 上 docs/、文档构建脚本或工作流配置的 push，不响应 pull request 或 fork；审核在推送受保护分支之前完成。Nginx 服务配置变更仍需单独核对并应用；
2. 发布分支推送执行锁定依赖安装、依赖审计、链接和发布边界检查，并保存带提交哈希与 SHA-256 的静态产物；
3. 部署使用验证任务生成的同一份产物，不从服务器重新构建；
4. 只有仓库变量 DOCS_DEPLOY_ENABLED 精确等于 true 时，验证成功后才会运行部署任务。变量、地址或 Secrets 缺失时不会连接服务器；
5. 远端先写入独立版本目录，确认首页和禁止文件边界后才原子切换 current 软链接。上传、解压或校验失败不会改变现网站点。

公开发布前还会扫描全部可达 Git 历史中的敏感文件扩展名和高置信度私钥/令牌特征。该检查只把提交与路径写入日志，不输出命中内容；它是发布底线，不替代人工隐私审阅或专门的秘密扫描工具。

工作流使用固定提交哈希引用官方 Actions，避免标签漂移。文档正文和图示仍以 docs/ 内文件为唯一来源；构建结果只作为短期 Actions 产物保留，不提交回 Git。

Gitea 上线前配置

域名、公众访问范围、严格 TLS、专用部署账户、DOCS_SITE_BASE=/ 和部署 Secrets 已完成配置。首次发布前后的核对项：

1. 仓库 Actions 已启用，Runner 标签包含 ubuntu-latest；若未来更换 Runner，应先验证构建和 SSH 工具；
2. main 已受保护，推送白名单仅包含维护者 codecat，禁止强制推送。单人仓库不要求形式上无法满足的“另一人批准”，但每次推送前仍须审阅差异与发布边界；
3. 服务器上的专用非 root 账户 vmaxdocs 对 /srv/vmax-docs-site 及其 releases 子目录有写权限，Nginx 对活动版本有只读和目录遍历权限；
4. 已配置的值应保持为 DOCS_SITE_BASE=/、DOCS_DEPLOY_HOST=203.88.115.4、DOCS_DEPLOY_USER=vmaxdocs、DOCS_DEPLOY_ROOT=/srv/vmax-docs-site；私钥与 known_hosts 只保存在 Gitea Secrets；
5. DOCS_DEPLOY_ENABLED=true 已启用，受保护 main 的文档推送已自动上线，两个版本之间的回滚与恢复演练已通过。

2026-09-24 直连 203.88.115.4 并分别发送 git.codecat.studio、vmax-docs.codecat.studio SNI，严格 TLS 均验证通过；Gitea 和已发布文档站首页均返回 200。后续验证仍不得使用 curl -k、关闭 Git/Runner TLS 校验或跳过 SSH 主机校验；证书续期由服务器现有 acme.sh 运维流程维护，并定期严格复验。

秘密只能写入 Gitea Actions Secrets，不进入聊天、仓库、构建产物或日志。部署脚本只接受专用账户 vmaxdocs，不会使用 root。DOCS_DEPLOY_KNOWN_HOSTS 必须从可信渠道核对服务器主机密钥；工作流不会临时运行 ssh-keyscan。DOCS_DEPLOY_ROOT 固定为专用绝对目录 /srv/vmax-docs-site，脚本会拒绝 /、/srv、/var 等过宽路径。

现有 Gitea Runner 若以读写方式挂载宿主机 Docker socket，就具备近似宿主 root 的能力。该 Runner 只能执行受保护分支上的已审核代码，不能接收不受信任的 fork/PR 事件。未来若要增加合并前检查，必须另建不挂载宿主 Docker socket、没有部署 Secrets 的隔离 Runner，并将 PR 验证放到独立工作流。

服务器与回滚约定

静态服务器的文档根目录应指向 <DOCS_DEPLOY_ROOT>/current，并保证 releases 与 current 位于同一文件系统。公开站点无需登录认证，但必须启用有效 TLS 和最小化访问日志。首次启用前需验证首页、中文 URL、八张图、SVG、搜索、深浅模式、移动端和 noindex，并再次确认产物不含 DOCX、DOT、密钥、环境文件或数据库。

每次部署切换后，Runner 会访问 https://vmax-docs.codecat.studio/，要求 HTTPS 成功且首页仍含“系统初步设计”标识。健康检查失败会立即恢复先前的 current 指向；如果此前没有线上版本，则移除失败版本的活动链接。

旧版本暂不自动删除，以保留人工回滚能力。回滚时由管理员将 current.next 指向先前已验证版本，再使用同一文件系统内的原子移动替换 current。旧版本自动清理必须等备份和保留策略确定后另行启用。

持续发布检查

noindex 只能阻止正常搜索引擎收录，不能替代认证。外网发布前至少确认：

1. vmax-docs.codecat.studio 的有效 TLS 证书、终止位置和部署责任人；
2. 已确认的公众访问范围是否已经通过内容负责人审批；
3. Nginx 访问日志的字段、权限和保留期；
4. 安全设计草案和 ADR 的发布审批记录；
5. main 的 codecat 唯一推送白名单、Runner 标签、验证任务和回滚演练结果。

公开范围、发布分支门禁、线上页面检查和回滚演练已确认。后续每次修改仍需审阅发布差异，并留意 Actions 结果、证书续期和秘密轮换。