site-deploy — Playbook 驱动的部署管线

site-deploy/ 是所有站点服务的部署大本营：一个服务一份 playbook，脚本读取 playbook 与配置执行 rsync、可选的远程 Docker Compose、健康检查，并可启用 AI 辅助 审查；另含 GitLab 批量克隆工具。

警告

本工作空间的硬性规则。修改 site-deploy 前必须先读 site-deploy/AGENTS.md： playbook 是事实来源；禁止臆造主机名/路径/凭据；先 dry-run；不提交密钥； 日志 append-only 不可改；一切下载走 http://172.24.240.1:7897 代理。

目录布局

site-deploy/
├── AGENTS.md               # 子项目硬性规则（agent 必读）
├── config/
│   ├── hosts.env           # SSH 主机 / docker 目标（gitignored，从 .example 复制）
│   └── services.yaml       # 服务定义（从 .example 复制）
├── playbooks/              # 每服务一份 .md，指令的事实来源
│   ├── _template.md        #   新服务从模板派生
│   ├── casdoor.md          #   Casdoor 生产部署
│   └── auth-proxy.md       #   sl-entry nginx 反代（手工操作文档）
├── scripts/
│   ├── lib.sh              # 共享层：日志、代理、host_var 解析
│   ├── deploy.sh           # 部署（rsync + 可选 docker compose + 健康检查）
│   ├── validate.sh         # 部署前校验（结构检查 + 可选 AI 审查 + dry-run）
│   ├── ai.sh               # AI 生成/校验辅助
│   └── gitlab.sh           # GitLab 批量克隆 repos/
├── docs/
│   ├── runbook.md          # 操作手册（部署、回滚、查日志）
│   ├── ai-workflow.md      # AI 辅助工作流
│   └── oauth-integration.md# 跨项目 OIDC/PKCE 统一接入指南
└── logs/                   # 时间戳部署日志（gitignored，不可改）

配置解析约定

  • hosts.env 变量命名 HOST_<NAME>_<KEY>（脚本用简单文本匹配解析，改名会破坏解析）。

  • services.yaml 每个服务一个块，常用键：host、source、remote、docker、 healthcheck、playbook（缺省 <service>.md）。

  • playbook 中 Deploy steps / Post-deploy verification 里的命令必须单行、 POSIX sh、可在远程直接执行——它们会被脚本原样提取运行。

标准工作流

cp config/hosts.example.env config/hosts.env      # 填真实主机
cp config/services.example.yaml config/services.yaml

scripts/validate.sh <service>          # 1. 校验
scripts/deploy.sh <service> --dry-run  # 2. 干跑（默认动作，先看落点）
scripts/deploy.sh <service>            # 3. 真部署
# 4. 验证：logs/ 下对应日志出现 "deploy complete"，
#    且 playbook 的 Post-deploy verification 命令通过

部署步骤（deploy.sh 内部）：rsync 源目录 → 远端 → 若 docker: true 则在远端跑 compose → 执行 playbook 的健康检查 → 可选 AI 审查（AI_ENABLED=1，默认 AI 后端 claude -p，见 docs/ai-workflow.md）。

已知注意事项（历史 bug，已修复，防回退）

  • deploy.sh 的 rsync 实跑与 dry-run 落点必须一致（历史上 --relative --dirs 用法不一致）。

  • compose v2 没有 --no-reload flag，不要加回去。

  • read_yaml_value 必须剥离值两侧引号，否则 healthcheck 会被当文件名执行。

  • lib.sh 需尽早 source hosts.env；变量默认值用 ${VAR-default}（无冒号）， 避免覆盖用户显式设置的空值。