部署指南

前提条件

• Docker Engine 24+ 及 Docker Compose v2
• 域名的 TLS 证书（测试可使用自签名证书）
• 容器可用内存至少 4 GB

快速开始

# 1. 复制并配置环境变量
cp deployments/docker/.env.prod.example deployments/docker/.env.prod

# 2. 编辑 .env.prod — 修改所有 "CHANGE_ME_*" 值
#    POSTGRES_PASSWORD、REDIS_PASSWORD、NATS_AUTH_TOKEN 必须使用强随机字符串

# 3. 放置 TLS 证书
mkdir -p deployments/docker/nginx/certs
cp /path/to/tls.crt deployments/docker/nginx/certs/tls.crt
cp /path/to/tls.key deployments/docker/nginx/certs/tls.key

# 4. 构建并启动
make prod-up

# 5. 验证
make prod-logs
curl -k https://localhost/healthz

架构

                    ┌──────────┐
                    │  nginx   │ :80（重定向）/ :443（TLS）
                    └────┬─────┘
                         │
              ┌──────────┼──────────┐
              │          │          │
         /api/*     /ws/*      /grpc/*
              │          │          │
              ▼          ▼          ▼
         ┌─────────────────────────────┐
         │       umoo 后端          │ :8080（HTTP）/ :9090（gRPC）
         └──────┬──────┬──────┬────────┘
                │      │      │
           ┌────┘      │      └────┐
           ▼           ▼           ▼
      ┌─────────┐ ┌─────────┐ ┌───────────────────┐
      │ postgres │ │  redis  │ │ nats 集群（3+1）  │
      └─────────┘ └─────────┘ └───────────────────┘

服务说明

服务	端口	用途
nginx	80, 443	TLS 终止、反向代理、限流
umoo	8080, 9090	后端 HTTP API 及 gRPC 总线
postgres	5432	主数据存储，启用 RLS
redis	6379	设备注册、缓存、限流计数器
nats（×3 + seed）	4222	跨实例消息路由

环境变量

完整列表请参见 deployments/docker/.env.prod.example。

必须修改的关键变量：

变量	说明
POSTGRES_PASSWORD	PostgreSQL 超级用户密码
REDIS_PASSWORD	Redis 认证密码
NATS_AUTH_TOKEN	NATS 集群认证 Token

TLS 证书

Nginx 期望证书位于以下路径：

deployments/docker/nginx/certs/tls.crt
deployments/docker/nginx/certs/tls.key

生成自签名测试证书：

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout deployments/docker/nginx/certs/tls.key \
  -out deployments/docker/nginx/certs/tls.crt \
  -subj "/CN=umoo.local"

扩容

NATS 集群默认运行 3 个节点 + 1 个 seed 节点。如需扩展后端实例，可在 nginx 后运行多个 umoo 容器，各实例通过 NATS 自动发现彼此。

docker-compose.prod.yml 定义了资源限制：

服务	内存限制
postgres	1 GB
redis	512 MB
nats（每个）	256 MB

数据库迁移

迁移在后端启动时自动执行。初始化脚本（init-db.sql）创建数据库并启用所需扩展。

更新

git pull
make prod-down
make prod-up

数据卷在重启后持久保留。若需完全重置：

make prod-down
docker volume rm $(docker volume ls -q | grep umoo)
make prod-up