# 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。