部署方案评估：从 sup + bluegreen.sh 迁移到 Kamal 2

背景

IntelliFutureDeploy 仓库当前使用 sup + 手写 bluegreen.sh + docker-compose 进行部署。在对 yomiya 相关服务的部署文件做 review 时，发现了一些问题（服务名错误、变量名不一致、蓝绿脚本存在停机窗口等），由此引出对部署工具的讨论。

现有方案的问题

蓝绿脚本先停后起：bluegreen.sh 先 docker compose down 旧容器，sleep 10 秒，再启新容器，存在约 10 秒停机窗口
文件多且分散：每个服务需要 Supfile.yml + docker-compose.yml + bluegreen.sh + config.yml，维护成本高
依赖 sup 二进制：sup 工具不再活跃维护
回滚靠手动操作：没有内置回滚机制

评估的替代方案

方案	定位	适用场景
Kamal（推荐）	CLI 部署工具，专为单机/少量服务器	和现有架构最接近，学习成本低
Coolify	自托管 PaaS，有 Web UI	想要可视化管理
K3s	轻量 Kubernetes	服务数量持续增长时

Kamal 2 评估结论

核心优势

一条命令部署：kamal deploy -d staging -P 替代 sup + bluegreen.sh
真正零停机：先启新容器 → 健康检查通过 → 切流量 → drain 旧容器
内置回滚：kamal rollback -d staging <version>
每服务一个配置文件：替代原来的 3-4 个文件
支持 GitHub Actions：gem install kamal 后直接使用
支持多服务器：servers.web.hosts 列多个 IP，自动滚动部署

关于 kamal-proxy 的决策

Kamal 2 内置了 kamal-proxy（轻量反向代理），但经评估决定关闭（proxy: false），原因：

我们的 Caddy 还负责静态文件托管（bolinhansen.top、app.yomiya.app）
Caddy 有路径匹配 + rewrite 规则（subscription-agreement）
Caddy 处理响应头清理、gzip 压缩、Cloudflare trusted_proxies、日志
kamal-proxy 不支持以上功能

最终方案：Kamal（关闭 proxy）+ Caddy（保留现有配置不变）

Kamal 负责：容器编排、滚动部署、零停机切换、回滚
Caddy 负责：域名路由、SSL、静态文件、header 处理、日志

参考配置

已提交到 IntelliFutureDeploy 仓库的 kamal-reference/ 目录（PR #29），包含：

文件	说明
`deploy.staging.yml`	apiserver + Redis accessory
`deploy.consumer.staging.yml`	consumer worker
`deploy.youtube-gateway.staging.yml`	youtube-gateway
`deploy.github-actions.yml`	GitHub Actions workflow 示例

迁移注意事项

服务器上需安装 Docker（已有）
设置 Aliyun CR 的 registry 认证（GitHub Secrets: ALIYUN_CR_USERNAME、ALIYUN_CR_PASSWORD）
首次执行 kamal setup 会安装 Kamal 运行时（不安装 kamal-proxy，因为已关闭）
Caddy 配置完全不需要改动
配置文件（config.yml）仍通过 volumes 挂载，需提前部署到服务器上

记录时间: 2026-03-20