docs: 整理文档目录结构 — 清理过时文档、归集功能子目录、统一命名规范
清理: - 删除 34 份过时文档(gap reports/QA临时报告/验收报告/阶段性文档) - 删除 docs/.hermes/skills 第三方 skills 副本(16 文件) - 删除 skills-lock.json 目录归集: - 根目录仅保留 README.md 索引 - product/ — 产品与架构设计(PRD + ARCHITECTURE + P2设计文档 + AI/企业路线图) - tracking/ — Chatwoot parity 开发跟踪 - requirements/ — M01-M12 模块需求 - plans/ — 历史实现计划 - parity/ — 路由 parity 与前端契约 - qa/ — QA 报告与测试计划 - ops/ — 运维部署 命名规范: - 全小写 kebab-case,禁止全大写文件名 - product/tracking/ops 用 NN- 序号前缀 - requirements 用 MNN- 两位零填充模块号 - plans/qa 用 YYYY-MM-DD- 日期前缀 - requirements M1-M9 零填充为 M01-M09(修复字典序) 同步更新: - backend/cmd/route_parity/main.go 路径默认值 - backend/scripts/parity_frontend_smoke.sh 报告路径 - 所有 docs 内部交叉引用 - .gitignore 排除编译产物 (backend/gochat, backend/route_parity) - 新增迁移 000052/000053 - 前端 WS 相关修改
This commit is contained in:
@@ -0,0 +1,81 @@
|
||||
# GoChat Rolling Upgrade Strategy
|
||||
# Reference: Chatwoot deployment uses zero-downtime upgrade pattern
|
||||
|
||||
## Overview
|
||||
|
||||
GoChat follows a blue-green deployment strategy for production upgrades,
|
||||
ensuring zero downtime during version transitions.
|
||||
|
||||
## Upgrade Process
|
||||
|
||||
### Step 1: Pre-flight Checks
|
||||
1. Verify new Docker image is built and pushed: `docker pull gochat/gochat:${NEW_VERSION}`
|
||||
2. Run database migrations on a staging environment first
|
||||
3. Verify backward compatibility of migrations (new code must work with old schema)
|
||||
4. Check feature flags — new features should be disabled by default
|
||||
|
||||
### Step 2: Database Migration
|
||||
```bash
|
||||
# Run migrations BEFORE deploying new code
|
||||
# Migrations must be backward-compatible
|
||||
docker compose -f docker-compose.prod.yml exec gochat /app/gochat migrate up
|
||||
```
|
||||
|
||||
### Step 3: Blue-Green Deployment (Docker Compose)
|
||||
```bash
|
||||
# 1. Deploy new version as "green" alongside "blue" (current)
|
||||
docker compose -f docker-compose.prod.yml up -d --no-deps gochat-green
|
||||
|
||||
# 2. Wait for health check to pass
|
||||
curl -f http://gochat-green:3000/health
|
||||
|
||||
# 3. Switch traffic (update nginx/upstream config)
|
||||
# nginx: switch upstream from blue to green
|
||||
|
||||
# 4. Drain old connections on blue
|
||||
# Wait 30s for in-flight requests to complete
|
||||
|
||||
# 5. Stop blue
|
||||
docker compose -f docker-compose.prod.yml stop gochat
|
||||
```
|
||||
|
||||
### Step 4: K8s Rolling Update
|
||||
```bash
|
||||
# Kubernetes handles rolling updates automatically via Deployment strategy
|
||||
kubectl set image deployment/gochat gochat=gochat/gochat:${NEW_VERSION}
|
||||
kubectl rollout status deployment/gochat
|
||||
```
|
||||
|
||||
K8s config (in Helm chart):
|
||||
- maxSurge: 1 (one extra pod during rollout)
|
||||
- maxUnavailable: 0 (no pods allowed to be unavailable)
|
||||
- readinessProbe: /ready endpoint
|
||||
- livenessProbe: /live endpoint
|
||||
|
||||
### Step 5: Verification
|
||||
1. Smoke test: hit /health, /ready endpoints
|
||||
2. Check logs for errors: `docker compose logs gochat --since 5m`
|
||||
3. Verify metrics: Prometheus dashboard should show normal traffic
|
||||
4. Monitor for 15 minutes before finalizing
|
||||
|
||||
### Step 6: Rollback (if needed)
|
||||
```bash
|
||||
# Docker Compose rollback
|
||||
docker compose -f docker-compose.prod.yml exec gochat /app/gochat migrate down ${N}
|
||||
docker compose -f docker-compose.prod.yml up -d --no-deps gochat-${OLD_VERSION}
|
||||
|
||||
# K8s rollback
|
||||
kubectl rollout undo deployment/gochat
|
||||
```
|
||||
|
||||
## Migration Compatibility Rules
|
||||
|
||||
- Migrations MUST be additive only in production (add columns, never remove)
|
||||
- Column removals require a 2-phase migration: soft-remove then hard-remove
|
||||
- New columns should have defaults or be nullable
|
||||
- Renames require a 3-phase migration: add new → copy data → remove old
|
||||
|
||||
## Worker Upgrade
|
||||
|
||||
Workers drain naturally: set a shutdown deadline, let in-flight jobs finish,
|
||||
then stop. New workers pick up queued jobs from Redis.
|
||||
Reference in New Issue
Block a user