Use Case
项目目前只有 CI（lint + test）和 Release（自动打 tag），没有 CD 流程。部署依赖手动 just compose-deploy 本地构建。需要自动化：release 发布后自动构建镜像、推送到 GHCR、部署到 VPS。
Proposed Solution
Release tag 触发 CD workflow，分两个 job：
- build-and-push: 构建 Docker 镜像，推送到
ghcr.io/singularitylab-swufe/fastapi-template-agent，tag 为 semver + latest
- deploy: SSH 到 VPS，
git pull --ff-only 同步 compose 文件，从 GitHub Secrets 生成 .env，docker compose pull app && up -d app
文件变更：
docker/docker-compose.yml — 删 build: 块，image: 改为 GHCR 地址.github/workflows/cd.yml — 新建 CD workflowjustfile — compose-deploy 改 pull 模式，新增 compose-dev
.env 管理：ENV_CONFIG secret 存非敏感配置块，敏感值（DB_PASSWORD、JWT_SECRET 等）逐个 secret 存储，deploy 时拼接生成。便于后续迁移 K8s ConfigMap/Secret。
Alternatives Considered
- GitLab CI/CD：需要自部署 runner 配置，复杂度高，暂不考虑
- 合入 main 即触发（而非 release）：镜像 tag 无法对应 semver，回滚不清晰
.env 整块存为单个 secret：迁移 K8s 时需要拆分，不如一开始就分离- Docker Swarm / K8s：当前单机 VPS 场景过重
Implementation Notes
- 依赖 GitHub Secrets：
VPS_HOST, VPS_USER, VPS_SSH_KEY, VPS_DEPLOY_PATH, ENV_CONFIG, DB_PASSWORD, JWT_SECRET, CACHE_PASSWORD, OAUTH_GOOGLE_SECRET, OAUTH_GITHUB_SECRET
- VPS 前置：Docker + Compose 已装，仓库已 clone，SSH key 已授权，用户在 docker 组
- GHCR package 建议设为 public，省去 VPS 端 docker login
docker-compose.dev.yml 无需改动，已有 build: 段- deploy job 设
environment: production 支持 GitHub 环境保护规则
concurrency: cancel-in-progress: false 避免取消进行中的部署
Use Case
项目目前只有 CI（lint + test）和 Release（自动打 tag），没有 CD 流程。部署依赖手动
just compose-deploy本地构建。需要自动化：release 发布后自动构建镜像、推送到 GHCR、部署到 VPS。Proposed Solution
Release tag 触发 CD workflow，分两个 job：
ghcr.io/singularitylab-swufe/fastapi-template-agent，tag 为 semver + latestgit pull --ff-only同步 compose 文件，从 GitHub Secrets 生成.env，docker compose pull app && up -d app文件变更：
docker/docker-compose.yml— 删build:块，image:改为 GHCR 地址.github/workflows/cd.yml— 新建 CD workflowjustfile—compose-deploy改 pull 模式，新增compose-dev.env管理：ENV_CONFIGsecret 存非敏感配置块，敏感值（DB_PASSWORD、JWT_SECRET 等）逐个 secret 存储，deploy 时拼接生成。便于后续迁移 K8s ConfigMap/Secret。Alternatives Considered
.env整块存为单个 secret：迁移 K8s 时需要拆分，不如一开始就分离Implementation Notes
VPS_HOST,VPS_USER,VPS_SSH_KEY,VPS_DEPLOY_PATH,ENV_CONFIG,DB_PASSWORD,JWT_SECRET,CACHE_PASSWORD,OAUTH_GOOGLE_SECRET,OAUTH_GITHUB_SECRETdocker-compose.dev.yml无需改动，已有build:段environment: production支持 GitHub 环境保护规则concurrency: cancel-in-progress: false避免取消进行中的部署