部署概览¶

KanjiIQ使用全自动CI/CD流水线，在每次推送到main分支时构建Docker镜像、推送到Forgejo Container Registry并部署到k3s集群。

流水线流程¶

graph LR
    A[git push main] --> B[Forgejo Actions<br/>Triggered]
    B --> C[Docker Build<br/>Multi-stage]
    C --> D[Push to Registry<br/><registry>]
    D --> E[kubectl set image<br/>Rolling update]
    E --> F[Rollout Status<br/>Health check]

基于路径的触发¶

每个组件有自己的工作流，仅在相关文件变更时触发：

工作流	触发路径	镜像
`deploy-frontend.yml`	`frontend/**`, `Dockerfile.frontend`, `nginx.frontend.conf`	`jlpt-kanji-frontend`
`deploy-backend.yml`	`backend/**`, `Dockerfile.backend`	`jlpt-kanji-backend`
`deploy-docs.yml`	`docs/**`, `mkdocs.yml`, `Dockerfile.docs`	`jlpt-kanji-docs`

这意味着修改文档页面不会触发前端或后端的重新构建。

部署策略¶

KanjiIQ使用Kubernetes滚动更新：

使用更新后的镜像创建新Pod
就绪探针必须通过后，旧Pod才会被终止
如果新版本健康检查失败，滚动更新会自动停止
2个副本实现零停机部署

环境¶

环境	用途	URL
生产	线上应用	`kanjiiq.com`
预发布	发布前测试	本地k8s命名空间
开发	本地开发	`localhost:8080` / `localhost:3000`

预发布环境在单独的Kubernetes命名空间（jlpt-kanji-staging）中使用与生产相同的清单，并拥有独立的PostgreSQL实例。

镜像标签¶

每次构建产生两个标签：

:latest — 始终指向最新构建
:COMMIT_SHA — 不可变标签，用于可追溯性

部署使用commit SHA标签以确保确定性的滚动更新：

kubectl set image deployment/jlpt-kanji \
  frontend=<registry>/jlpt-kanji-frontend:abc1234 \
  -n jlpt-kanji