核心安全准则
- 敏感信息全部存仓库 Secrets，绝不写代码、不提交
.env； - 密钥只通过环境变量透传给容器，不落地明文文件；
- 日志自动掩码 Secrets，不会打印 Token/AK 明文；
- 构建完成无残留凭证。
一、第一步：存储敏感密钥（仓库 Secrets）
- 仓库 → Settings → Secrets and variables → Actions → New repository secret
- 添加你项目需要的密钥，示例清单：
| Secret 名称 | 用途 |
|------|------|
| DOC_GIT_PAT | GitHub Personal Token，拉取私有 AsciiDoc 文档仓库 |
| DOC_GIT_USER | 私有仓库用户名 |
| DEPLOY_SITE_TOKEN | 静态站点部署密钥（如 Pages/OSS/CDN） |
| DOCKER_REG_PWD | 私有镜像仓库密码（自定义 Antora 镜像才需要） |
二、两种注入方案（按需选择）
方案1：环境变量直接透传容器（推荐，无 .env 临时文件）
原理：Actions 读取 Secrets → 作为环境变量传给docker-compose run -e→ Antora 构建容器内直接读取，全程无磁盘明文。
1. 流水线文件.github/workflows/build-docs.yml
name:Build Antora Docson:push:branches:[main]pull_request:branches:[main]jobs:build:runs-on:ubuntu-lateststeps:-name:Checkout 构建工程代码（docker-compose/playbook等）uses:actions/checkout@v4-name:拉取文档源码私有仓库（可选，也可交给Antora内置Git拉取）uses:actions/checkout@v4with:repository:your-org/fortigate-doc-srcpath:docs-srctoken:${{secrets.DOC_GIT_PAT}}-name:使用Docker Compose构建文档env:# 把仓库Secrets注入当前Action环境变量GIT_DOC_USER:${{secrets.DOC_GIT_USER}}GIT_DOC_TOKEN:${{secrets.DOC_GIT_PAT}}TZ:Asia/Shanghairun:|# 将Action环境变量透传给Antora容器 docker-compose run --rm \ -e GIT_DOC_USER="$GIT_DOC_USER" \ -e GIT_DOC_TOKEN="$GIT_DOC_TOKEN" \ -e TZ="$TZ" \ antora-builder-name:上传构建产物（网页+PDF）uses:actions/upload-artifact@v4with:name:docs-outputpath:build-output/2. antora-playbook.yml 读取容器内环境变量拉取私有仓库
content:sources:# 私有Git仓库，拼接Token鉴权-url:https://${GIT_DOC_USER}:${GIT_DOC_TOKEN}@github.com/your-org/fortigate-doc-src.gitbranches:HEADstart_path:docs方案2：动态生成临时 .env（需要.env文件场景）
仅适合部分扩展工具必须读取.env文件的场景，构建后立刻删除，不会留存敏感文件：
run:|# 运行时临时生成.env，不提交仓库 cat > .env << EOFGIT_DOC_USER=$GIT_DOC_USER GIT_DOC_TOKEN=$GIT_DOC_TOKEN EOF docker-compose run--rm antora-builder# 构建完成立即销毁敏感文件rm-f .env三、扩展场景：私有Docker镜像仓库鉴权
如果你自己打包 Antora 私有镜像，需要登录镜像仓库再构建：
-name:登录私有容器仓库env:DOCKER_USER:${{secrets.DOCKER_REG_USER}}DOCKER_PWD:${{secrets.DOCKER_REG_PWD}}run:|echo "$DOCKER_PWD" | docker login ghcr.io -u $DOCKER_USER --password-stdin四、产物自动部署 GitHub Pages（完整发布链路）
构建出静态网页后，直接推送 GitHub Pages，部署密钥无需额外配置，使用内置GITHUB_TOKEN：
-name:部署静态文档到 GitHub Pagesuses:peaceiris/actions-gh-pages@v4with:github_token:${{github.TOKEN}}publish_dir:./build-output/site五、关键安全注意事项
- 禁止在日志打印密钥
不要写echo $GIT_DOC_TOKEN，GitHub 会自动掩码 Secrets，但主动打印无意义且有风险。 - 不要将 .env 提交进仓库
.gitignore必须包含.env，本地开发用的.env仅本地留存，不推远程。 - 细粒度 PAT 权限
拉取私有文档仓库的 PAT 只赋予repo权限，不要给全局高权限。 - 不缓存构建目录
Actions 默认不会缓存build-output，避免密钥意外存入缓存快照。 - 容器内禁止输出凭证
adoc、PDF、网页产物中不要打印 Git Token、AK/SK 等敏感字段。
六、本地开发与CI区分小技巧
本地写文档时使用本地.env（不提交），CI流水线自动覆盖注入正式密钥，一套 compose 同时适配本地+线上流水线，无需修改配置。
