planet/docs/plans/production-delivery-cicd-stabilization-plan.md

Planet 正式交付与 CI/CD 稳定化计划

Summary

• CI/CD 平台采用 Gitea Actions，由自托管 act_runner 执行。
• 正式交付目标采用 Kubernetes，端口、健康检查、重启和滚动发布交给 Service、Ingress、readiness/liveness probe。
• Vite 继续保留，但只作为开发服务器和生产构建工具；生产运行 nginx 托管 vite build 产物。
• 不新增 Webpack 双构建链。Electron 仅在离线桌面交付成为明确目标后再评估。

Key Changes

• 生产镜像：
  • frontend 多阶段构建，bun install + bun run build，最终 nginx 托管 dist。
  • backend/aiprovider 移除 --reload，加入容器健康检查。
  • 镜像标签使用 <registry>/<namespace>/<service>:<git-sha>，发布 tag 额外推 vX.Y.Z。
• Kubernetes：
  • 新增 Helm chart：deploy/helm/planet。
  • frontend 暴露 Ingress；backend/aiprovider 默认 ClusterIP。
  • PostgreSQL/Redis 默认外部依赖，values.single-node.yaml 提供演示/测试内置依赖。
• Gitea Actions：
  • ci.yaml：后端测试、前端构建、Docker build smoke、Helm render。
  • release.yaml：构建并推送三类镜像。
  • deploy-staging.yaml：部署 staging、等待 rollout、执行 smoke tests。
• 开发脚本边界：
  • planet.sh 保留为本地开发便利脚本。
  • CI/CD 与正式部署不调用 planet.sh start。

Vite / Webpack / Electron Decision

中肯结论：不要因为“企业生产环境”这件事去做 Webpack 版本；继续用 Vite，但把“开发服务器”和“生产构建/部署”分清楚。Electron 也不要现在做，除非正式版目标明确是离线桌面软件。

Vite 可以用于生产构建。生产环境运行的是 vite build 产出的静态资源，不是 Vite dev server。当前项目已经使用 React + Vite + Bun、import.meta.env、public/earth 静态资产路径和大量 Three.js/ES module 资源引用。维护 Webpack 双构建链会显著增加路径、资源、环境变量和回归测试成本。

如果未来客户环境确实要求更接近 Webpack 生态，优先做 Rsbuild/Rspack 技术 spike，而不是直接维护 Webpack 并行构建。Electron 适合离线运行、本地硬件/文件访问、系统托盘、自动更新和安装包分发；但 Planet 目前还包含 backend、database、Redis、AI Provider、Motion Agent 等服务编排，桌面壳不能解决正式交付的核心问题。

Test Plan

• CI gates：
  • uv sync --group dev
  • uv run pytest backend/tests/test_api.py backend/tests/test_realtime_sources.py -q
  • cd frontend && bun install --frozen-lockfile && bun run build
  • Docker build frontend/backend/aiprovider
  • helm lint deploy/helm/planet
  • helm template planet-staging deploy/helm/planet -f deploy/helm/planet/values.single-node.yaml
• Staging deployment:
  • helm upgrade --install planet-staging deploy/helm/planet --namespace planet-staging
  • 等待 frontend/backend/aiprovider rollout。
  • smoke test frontend /、frontend /health、backend /health、aiprovider /health。

Acceptance Criteria

• main/dev 提交能通过 CI。
• 发布 workflow 能生成可追踪镜像。
• staging 可从零部署并完成滚动升级。
• 正式部署不依赖本机端口清理，也不运行 Vite dev server。