56 lines
3.3 KiB
Markdown
56 lines
3.3 KiB
Markdown
# 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。
|