jackyu66gitandCursor
0f320e040b
Add host-first environment contracts (Local vs CI vs Prod), deps-only compose, and the Profile → Portrait → deep-access mock payment slice with device identity and auto-migrate on API startup. Co-authored-by: Cursor <cursoragent@cursor.com>
87 lines
2.4 KiB
Markdown
87 lines
2.4 KiB
Markdown
# Production & CI Deployment — AI Contract
|
||
|
||
本文件只约束 **CI** 与 **Production**。
|
||
本地编码见 [development.md](development.md)；Docker 角色见 [docker.md](docker.md)。
|
||
|
||
---
|
||
|
||
## Production Rules
|
||
|
||
Production **MUST** use immutable images.
|
||
|
||
### MUST NOT（生产）
|
||
|
||
- 服务器上 `git pull` 后直接编译运行当主发布路径
|
||
- 手工在机器上 `npm install` / `go mod download` 当发布步骤
|
||
- 登录容器改代码或改依赖冒充发布
|
||
- 使用镜像 tag `latest`
|
||
- 把本地 `.env` / 开发密钥打进镜像
|
||
|
||
### Happy path
|
||
|
||
```
|
||
Git Push → CI → Test → Build Image → Registry → Deploy → Health Check
|
||
```
|
||
|
||
### Health
|
||
|
||
- Liveness: `GET /api/v1/healthz`（必须）
|
||
- Readiness（有 DB 流量时）: `GET /api/v1/readyz`（检查 DB；可后补）
|
||
- Canonical paths 写入 OpenAPI
|
||
|
||
### Config
|
||
|
||
- Secrets **仅**环境变量 / 密钥管理系统
|
||
- 提交 `deploy/.env.example`，永不提交 `.env`
|
||
- 生产必备示例：`APP_ENV=prod` `HTTP_ADDR` `DATABASE_URL`（及日后支付/JWT 密钥）
|
||
|
||
### Containers
|
||
|
||
- 可运行的生产服务最终应有 Dockerfile（`deploy/Dockerfile.*`）
|
||
- Tag：`v0.x.y` 或 git SHA
|
||
|
||
### Deployment Target（预留，勿提前复杂化）
|
||
|
||
| Phase | Target | When |
|
||
|---|---|---|
|
||
| **1** | Docker Compose on a VPS | 首版上线默认 |
|
||
| **2** | Managed containers（云厂商容器服务） | 运维成本上去时 |
|
||
| **3** | Kubernetes | 明确有多服务/扩缩容需求时 |
|
||
|
||
P1 **不要**引入 K8s。缺的 Dockerfile / prod compose **按发布任务再加**，不为本地写代码先造全套镜像工作流。
|
||
|
||
### Topology（Phase 1 目标）
|
||
|
||
```
|
||
Docker Compose (VPS)
|
||
├── Go API container
|
||
├── Nginx（user-h5 静态或反代）
|
||
├── PostgreSQL
|
||
├── Redis（需要时）
|
||
└── Object storage（需要时）
|
||
```
|
||
|
||
---
|
||
|
||
## CI Rules
|
||
|
||
CI 优先 **一致性**：
|
||
|
||
- `go test ./...`（`apps/api`）
|
||
- `npm run build:h5`
|
||
- （有 Dockerfile 后）build 镜像 smoke
|
||
- 不在 CI 里要求开发者本机 Docker Desktop 才能合并文档/纯前端 PR（按 job 需要）
|
||
|
||
---
|
||
|
||
## Local vs Prod（对照）
|
||
|
||
| Topic | Local | Production |
|
||
|---|---|---|
|
||
| Go / Vue | 本机热更 | 镜像 |
|
||
| Postgres | `docker-compose.dev.yml` | 托管或 compose/k8s |
|
||
| 反馈 | 分钟级 | 发布质量与回滚 |
|
||
| 配置 | `.env.local` / dev | 密钥系统 / prod env |
|
||
|
||
禁止把右栏流程套到左栏日常开发。
|