[!info] related notes

• 上层 MOC: 云原生 MOC, BodySense 项目 MOC
• 理论: cloud-native-development, twelve-factor-app
• 参考: Docker MOC, CI/CD MOC

BodySense 云原生实践 MOC

知识总览

filters:
  and:
    - 'file.ext == "md"'
    - 'file.inFolder("z")'
    - 'this.file.links.contains(file)'
    - 'file.path != this.file.path'
formulas:
  knowledge: 'file.asLink(title)'
properties:
  formula.knowledge:
    displayName: 知识
  note.description:
    displayName: Description
  note.mastery:
    displayName: Mastery
views:
  - type: table
    name: 知识总览
    order:
      - formula.knowledge
      - note.description
      - note.mastery
    columnSize:
      formula.knowledge: 280
      note.description: 760
      note.mastery: 56

BodySense（体悟）是一个 AI 体态健康助手，采用 React + Go + Python 三服务架构。本 MOC 记录项目的云原生实践现状与演进方向。

从这里开始

1. BodySense 项目概览 — 项目全貌
2. 多服务架构 — 三服务为什么这样拆
3. 下面按”已落地 → 待改进”的顺序阅读

---

基础设施规划

• bodysense-cloud-native-infrastructure — DigitalOcean 基础设施方案：Droplet + Object Storage + Managed DB + Registry
• bodysense-environment-configuration — 环境变量配置方案：分层策略、服务级拆分、本地 vs 生产、VPC 地址

已落地实践

容器化

• Docker 多阶段构建 — Go / Python / Node 三个服务的镜像构建策略
• Docker Compose 开发环境 — 本地多容器编排（PostgreSQL + Redis + API + AI + Web）
• Docker 镜像配置 — 镜像配置与优化

反向代理

• Caddy 反向代理 — 自动 HTTPS、安全头、域名路由（body.bakersean.top）
• Caddy — Caddy Web Server 基础

CI/CD 流水线

• GitHub Actions CI — 多服务并行 CI（lint + typecheck + test）
• release-please 自动版本 — Conventional Commits 自动版本管理
• GitHub Actions — GitHub Actions 基础

自动部署

• Watchtower 自动部署 — 镜像更新自动滚动重启

健康检查

• 健康检查端点 — Go API 的 /healthz 端点与 Docker HEALTHCHECK

---

项目部署架构

[Browser]
    ↓ HTTPS
[Caddy :80/:443]  ← 自动 HTTPS + 安全头
    ├─ /           → [nginx :80 (web)]     → SPA 静态文件
    └─ /api/       → [Go API :8080]        → PostgreSQL + Redis
                        ↓ 内部调用
                    [Python AI :8100]       → PostgreSQL (pgvector)

镜像仓库： 阿里云 ACR 生产服务器： 115.29.x.x（body.bakersean.top） 自动更新： Watchtower 轮询 prod-latest 标签

---

待改进清单

环境与配置（12-Factor App）

• 所有服务配置完全环境变量化，不依赖 .env 文件硬编码
• 开发/生产环境使用相同的 Docker Compose 基础设施定义
• .env.production 中的敏感值迁移到密钥管理方案

健康检查标准化

• 每个服务统一 /healthz（存活）和 /readyz（就绪）端点
• Python AI Service 添加健康检查端点
• 前端 nginx 容器添加健康检查
• docker-compose.prod.yml 中所有服务配置 HEALTHCHECK

日志与可观测性

• 所有服务输出结构化日志（JSON 格式到 stdout）
• 请求链路 request_id 贯穿三服务（Go API → Python AI）
• Agent Run 的 run_id 贯穿全链路
• 接入 Prometheus metrics（Go API、Python AI）
• Grafana 看板搭建
• 接入 OpenTelemetry tracing

弹性设计

• Go API → Python AI 的调用设置超时
• Python AI → LLM API 的调用设置超时 + 重试
• 关键外部调用添加熔断
• API 限流（已有 Redis，可基于 Redis 实现）
• 所有服务实现优雅退出（SIGTERM 处理）

安全

• 敏感配置不写入 Docker 镜像（检查 .dockerignore 和构建层）
• 容器以非 root 用户运行
• 数据库定期自动备份
• 依赖漏洞扫描（CI 中集成 Trivy / Snyk）

部署进阶

• 灰度发布能力（Canary / Blue-Green）
• 数据库迁移自动化（CI/CD 中集成 golang-migrate）
• 回滚流程文档化
• 监控告警（服务宕机、错误率飙升、延迟异常）

---

最小实践路线（建议顺序）

1. ✅ Docker Compose 跑起来（已完成）
2. ✅ 多阶段构建镜像（已完成）
3. ✅ CI 自动测试（已完成）
4. ✅ 自动部署（已完成）
5. ✅ Caddy 反向代理 + 自动 HTTPS（已完成）
6. → 所有服务加 /healthz + /readyz
7. → 结构化日志（JSON stdout）
8. → request_id / run_id 贯穿链路
9. → Go → AI 调用加超时 + 重试
10. → Prometheus metrics
11. → OpenTelemetry tracing
12. → 灰度发布

---

相关 MOC

• 云原生 MOC
• BodySense 项目 MOC
• Docker MOC
• CI/CD MOC