CI/CD 与生产部署

Phase 08 — Deployment · 知识点 09–10：CI/CD · Production Deployment

1. 学习目标

完成本知识点后，你应该能够：

理解 CI/CD 流水线：检查 → 测试 → 构建 → 部署
使用 GitHub Actions 实现 Go 项目自动测试与 Linux 二进制构建
设计 Production Deployment 流程：版本追踪、回滚、密钥管理
编写生产运行手册（Runbook），使他人可独立部署 Project 03
完成数字孪生后端从代码到上线的完整闭环
明确本路线部署边界（不含 Kubernetes）

2. 为什么需要

手动 scp 二进制容易出错、不可追溯、难以回滚。CI/CD 在每次 push 时自动跑 go test、go vet，构建可复现产物，部署脚本标准化——这是团队交付与生产稳定的基础。

Production Deployment 不仅是「把服务跑起来」，还包括监控、日志、备份、回滚、密钥轮换——Project 03 验收要求公网 HTTPS/WSS、进程恢复、版本可追踪。

3. 核心概念

3.1 CI/CD

阶段	典型任务
CI（持续集成）	lint、test、vet、race、build 镜像
CD（持续部署）	SSH 部署、Compose pull、systemd restart
触发	push main、tag v*、manual workflow

3.2 Production Deployment 要素

要素	说明
版本追踪	Git tag、镜像 tag `v1.2.3`
配置外置	环境变量 / secrets，不进仓库
健康检查	`/health`、systemd、Compose healthcheck
回滚	保留上一版二进制或镜像，一键切换
日志	journalctl / 集中日志，含 requestId、deviceId
备份	PostgreSQL 定期备份
Runbook	部署、重启、排障步骤文档

3.3 部署架构（本路线）

GitHub → Actions (test/build) → Artifact / Registry
                                      ↓
                              SSH → Linux server
                              systemd + Nginx + Docker(DB)

不包含：Kubernetes、Helm、Service Mesh。

4. 基础语法

4.1 GitHub Actions 示例

.github/workflows/ci.yml：

yaml

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      - name: Vet
        run: go vet ./...
      - name: Test
        run: go test -race ./...
      - name: Build
        run: CGO_ENABLED=0 go build -o server ./cmd/server

4.2 部署 Workflow（简化 SSH）

yaml

name: Deploy

on:
  push:
    tags: ['v*']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      - run: CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o server ./cmd/server
      - name: Upload to server
        env:
          SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
          HOST: ${{ secrets.DEPLOY_HOST }}
        run: |
          echo "$SSH_KEY" > key && chmod 600 key
          scp -i key -o StrictHostKeyChecking=no server deploy@$HOST:/opt/twin-server/bin/server.new
          ssh -i key deploy@$HOST 'sudo systemctl stop twin-server && mv /opt/twin-server/bin/server.new /opt/twin-server/bin/server && sudo systemctl start twin-server'

4.3 版本与回滚

bash

# 部署前备份
cp /opt/twin-server/bin/server /opt/twin-server/bin/server.bak

# 回滚
sudo systemctl stop twin-server
mv /opt/twin-server/bin/server.bak /opt/twin-server/bin/server
sudo systemctl start twin-server

4.4 Runbook 大纲

markdown

# Digital Twin Server 运行手册

## 前置条件
- Ubuntu 22.04、Docker、Nginx、域名 DNS

## 首次部署
1. 创建 deploy 用户
2. 安装 PostgreSQL/Redis（Docker Compose）
3. 配置 systemd + Nginx + certbot
4. 注入 secrets 到 /etc/twin-server/env

## 日常运维
- 查看状态：systemctl status twin-server
- 日志：journalctl -u twin-server -f
- 重启：sudo systemctl restart twin-server

## 回滚
...

## 故障排查
- WSS 失败 → 检查 Nginx Upgrade 头
- 502 → Go 进程是否运行

5. 代码解析

go test -race：CI 必跑，防止 WebSocket Hub 竞态上线。

Tag 触发部署：仅 v* tag 部署生产，避免每次 push 自动上线。

server.new + 原子替换：减少部署中途二进制不完整风险。

Secrets：DEPLOY_SSH_KEY、DATABASE_URL 存 GitHub Secrets，不写进 YAML 明文。

6. JavaScript / TypeScript 对比

概念	前端 CI	Go 后端 CI
检查	ESLint	go vet
测试	Vitest	go test
构建	vite build	go build / docker build
部署	Vercel / OSS	SSH + systemd
环境	静态托管	服务器进程

Monorepo 时可并行 frontend + backend jobs。

7. 常见错误

错误 1：Secrets 提交到 Git

立即轮换密钥，用 git filter-repo 清理历史（慎用）。

错误 2：CI 不跑 race / 集成测试

生产偶发 panic 难以定位。

错误 3：无回滚预案

新版本故障时 downtime 延长。

错误 4：部署不迁移数据库

schema 变更需 migration 步骤纳入 Runbook。

错误 5：过度自动化

未通过 CI 的 tag 也部署——应加 manual approval 或环境保护规则。

8. 实际应用

Project 03 Phase 08 验收

项	标准
公网访问	HTTPS + WSS 正常
进程恢复	kill 后 systemd 自动重启
版本	镜像或二进制可对应 Git tag
密钥	不在仓库
Runbook	他人可按文档独立部署
CI	push PR 跑 test+vet

数字孪生端到端：

Git push tag v1.0.0
  → Actions build & deploy
  → Go server 重启
  → Three.js 连接 wss://api.example.com/ws
  → AGV 实时动画

9. 深入理解

9.1 Blue-Green / Canary

本路线不要求，了解概念即可：两版并存、逐步切流量。

9.2 数据库迁移

使用 golang-migrate 或 goose，部署脚本中 migrate up 在 restart 前执行。

9.3 监控告警

最小方案：Uptime 检查 /health + 磁盘空间 cron；进阶 Prometheus/Grafana 不在本路线范围。

10. 练习

详细练习见 exercises/phase-08-deployment/03-cicd-production.md。

Level 1 — 基础

练习 1.1：创建 GitHub Actions CI：vet + test + build。

练习 1.2：编写 Runbook 初稿（首次部署章节）。

Level 2 — 应用

练习 2.1：tag 触发构建 Linux 二进制 artifact。

练习 2.2：模拟回滚：备份与恢复二进制步骤。

Level 3 — 综合

练习 3.1：SSH 部署脚本（可手动执行，不必真实 secrets）。

练习 3.2：Runbook 故障排查：WSS 502 案例。

Level 4 — 项目实践

练习 4.1：Project 03 完整上线 — CI/CD + HTTPS/WSS + Runbook + Three.js 联调演示。

11. 学习检查

CI 与 CD 分别解决什么问题？
为什么生产部署用 tag 而非每次 push？
回滚至少需要保留什么？
Runbook 应包含哪些章节？
本路线 deliberately 不包含哪些部署技术？

12. 下一步

已完成	下一知识点	关系
CI/CD · Production Deployment	路线完成 — 进阶自选	数字孪生后端上线

恭喜完成 Phase 01–08 全部路线。Project 03 数字孪生 Server 应具备 REST + WebSocket + Docker + 生产部署能力。

可选进阶（路线外）：Kubernetes、Prometheus、Kafka、微服务拆分——待你巩固当前成果后再探索。

建议回顾 progress.md，标记 Phase 06–08 各知识点掌握程度，并归档 Runbook 与部署脚本到项目仓库的 docs/operations/（若你自行维护）。

学习导航

上一篇：Nginx、HTTPS 与 DNS · 对应练习

CI/CD 与生产部署 ​

1. 学习目标 ​

2. 为什么需要 ​

3. 核心概念 ​

3.1 CI/CD ​

3.2 Production Deployment 要素 ​

3.3 部署架构（本路线） ​

4. 基础语法 ​

4.1 GitHub Actions 示例 ​

4.2 部署 Workflow（简化 SSH） ​

4.3 版本与回滚 ​

4.4 Runbook 大纲 ​

5. 代码解析 ​

6. JavaScript / TypeScript 对比 ​

7. 常见错误 ​

错误 1：Secrets 提交到 Git ​

错误 2：CI 不跑 race / 集成测试 ​

错误 3：无回滚预案 ​

错误 4：部署不迁移数据库 ​

错误 5：过度自动化 ​

8. 实际应用 ​

Project 03 Phase 08 验收 ​

9. 深入理解 ​

9.1 Blue-Green / Canary ​

9.2 数据库迁移 ​

9.3 监控告警 ​

10. 练习 ​

Level 1 — 基础 ​

Level 2 — 应用 ​

Level 3 — 综合 ​

Level 4 — 项目实践 ​

11. 学习检查 ​

12. 下一步 ​

学习导航 ​