完整环境搭建
云驰智运 · 完整环境搭建文档（v1.0 / Sprint 24 截稿）
适用范围：开发环境（本地）/ 测试环境（小型云）/ 生产环境（K8s 多集群）三档。 版本基线见 versions.txt，请严格对齐避免"在我电脑上能跑"问题。
0. 三档环境一览
| 维度 | DEV（本地） | UAT（云单机） | PROD（K8s 多集群） |
|---|---|---|---|
| 节点 | 1 台 16C32G | 1 台 32C64G | ≥6 台 32C64G + GPU 可选 |
| 编排 | Docker Compose | Docker Compose | K8s 1.28+ + Istio Ambient |
| 数据库 | MySQL 单点 | MySQL 主从 | MySQL InnoDB Cluster |
| 缓存 | Redis 单点 | Redis 哨兵 | Redis Cluster 6 节点 |
| 存储 | MinIO 单点 | MinIO 4 节点 | OSS / S3 / 私有 Ceph |
| 监控 | Prom 单点 | Prom + Grafana | Prom + VM + Tempo + Loki + Pyroscope + Pixie |
| 必启项 | server + admin-pc | + 监控 | + Istio + KBS + ArgoCD + Kyverno |
1. 前置依赖（所有档次通用）
# JDK 17 (Temurin)
curl -L https://api.adoptium.net/v3/binary/latest/17/ga/linux/x64/jdk/hotspot/normal/eclipse \
-o jdk17.tar.gz && tar xzf jdk17.tar.gz
# Maven 3.9.6 / Node 20 / pnpm 8 / Docker 24+
sudo apt install -y maven nodejs npm docker.io docker-compose-plugin
npm i -g pnpm@8 @vue/cli @dcloudio/uvm
# 校验
java -version # ≥17.0.10
mvn -v # ≥3.9
node -v # ≥20.11
docker compose version # ≥v2.24
2. DEV 本地一键起步
2.1 起依赖（MySQL/Redis/MinIO/RabbitMQ）
cd logistics-platform/deploy
docker compose -f docker-compose.dev.yml up -d
# 默认账号密码 见 .env.prod.example（开发环境用默认 root/123456）
2.2 初始化数据库
# 进入 mysql 容器
docker exec -i logistics-mysql mysql -uroot -p123456 < sql/init.sql
docker exec -i logistics-mysql mysql -uroot -p123456 < sql/seed.sql
# 国产化 DM8 用：sql/init-dm.sql
2.3 启动后端
cd ../server
./mvnw -pl logistics-app -am spring-boot:run
# 默认 8080，Swagger: http://localhost:8080/swagger-ui/index.html
2.4 启动 PC 后台
cd ../admin-pc
pnpm i && pnpm dev
# 默认 5173，登录 admin/admin123
2.5 启动移动端 H5
cd ../client-app
pnpm i && pnpm dev:h5
# 默认 5174
3. 可观测三件套（DEV 可选）
cd deploy
docker compose -f docker-compose.observability.yml up -d
# Grafana: http://localhost:3000 admin/admin
# Tempo: http://localhost:3200
# Loki: http://localhost:3100
# Pyroscope: http://localhost:4040
后端只需在 application.yml 加：
otel:
enabled: true
exporter:
otlp:
endpoint: http://localhost:4317
spring:
application:
name: logistics-app
4. UAT 云单机部署
# 1. 克隆 + 配置 .env
cd /opt && git clone <repo> logistics-platform && cd $_/deploy
cp .env.prod.example .env.prod
vim .env.prod # 填真实数据库 / OSS / 短信 / 支付密钥
# 2. 一键起栈（应用 + 监控 + 审计）
docker compose --env-file .env.prod \
-f docker-compose.prod.yml \
-f docker-compose.monitor.yml \
-f docker-compose.audit.yml \
up -d
# 3. 冒烟测试
bash scripts/smoke-test.sh https://api.your-domain.com
域名 + HTTPS（Nginx + acme.sh）：
# Let's Encrypt 自动续期
acme.sh --issue --nginx -d api.your-domain.com -d admin.your-domain.com
5. PROD 生产 K8s 部署
5.1 集群准备
- K8s 1.28+ × 3 集群（沪 / 穗 / 海外） — 见 docs/29-Istio多集群联邦.md
- 节点 OS：Ubuntu 22.04 / 麒麟 V10（信创）
- CNI：Cilium 1.15（启用 Hubble）
- Kernel：≥ 5.8（eBPF CO-RE 必需）
- 证书：cert-manager + Let's Encrypt 或私有 CA
5.2 基础组件 Helm 部署顺序
| 顺序 | 组件 | 命名空间 | 备注 |
|---|---|---|---|
| 1 | cert-manager | cert-manager | TLS 证书自动签发 |
| 2 | Istio Ambient | istio-system | 见 ambient-mode.yaml |
| 3 | ArgoCD | argocd | GitOps 控制面 |
| 4 | Kyverno | kyverno | 准入策略 |
| 5 | Prometheus + VM + Tempo + Loki | observability | 见 docker-compose.observability.yml 转 Helm |
| 6 | Pyroscope | observability | 见 pyroscope.yaml |
| 7 | Pixie | px-operator | 见 ebpf-pixie-falco.yaml |
| 8 | Knative + KEDA | knative-serving | 见 knative-service.yaml |
| 9 | Ollama（LLM 告警摘要） | ai | qwen2.5:7b 本地推理 |
| 10 | logistics-app 业务 | logistics | ArgoCD Application 同步 |
5.3 SLSA L3 镜像签名（CI 侧）
# .github/workflows/slsa-l3-release.yml 已就绪
# 触发：git tag v1.0.0 && git push origin v1.0.0
5.4 KBS（Confidential Containers）
仅敏感业务（OCR / 跨境清算）启用：
helm install kbs ./deploy/security/kbs --namespace coco-tenant --create-namespace
kubectl label nodes <tdx-node> confidential-computing=tdx
6. 配置项一览（关键摘录）
6.1 后端 application.yml（按模块加）
# 数据库
spring.datasource.url: jdbc:mysql://mysql:3306/logistics?...
spring.redis.host: redis
spring.rabbitmq.host: rabbitmq
# 多租户
tenant:
enabled: true
default-id: 1
# OTel
otel.enabled: true
otel.exporter.otlp.endpoint: http://otel-collector:4317
# VM 时序写入
vm.write.url: http://victoria-metrics:8428/write
# LLM 告警摘要
ai.llm.url: http://ollama:11434/v1/chat/completions
ai.llm.model: qwen2.5:7b
# SSO
sso.callback-base: https://api.your-domain.com
sso.oidc.wework.client-id: ww...
6.2 前端 .env.production
VITE_API_BASE=https://api.your-domain.com
VITE_WS_BASE=wss://api.your-domain.com/ws
VITE_GAODE_KEY=xxx
VITE_OSS_HOST=https://oss.your-domain.com
7. 端口与防火墙
| 端口 | 用途 | 内/外 |
|---|---|---|
| 80/443 | Nginx HTTP/HTTPS | 外 |
| 8080 | 后端业务 | 内 |
| 8848 | OpenAPI | 外（沙箱） |
| 4317/4318 | OTel gRPC/HTTP | 内 |
| 4040 | Pyroscope | 内 |
| 8428 | VictoriaMetrics 写 | 内 |
| 4000 | Apollo Router GraphQL | 外 |
| 15008 | Istio HBONE | 内 |
| 9090 | Prometheus | 内 |
| 3000 | Grafana | 内 |
| 3306 | MySQL | 内 |
| 6379 | Redis | 内 |
| 5672/15672 | RabbitMQ | 内 |
| 9000/9001 | MinIO API/Console | 内 |
8. 数据库备份策略
- 主：xtrabackup 每日全量 + binlog 每 5 分钟增量
- 异地：跨区域 oss sync
s3://logistics-backup/<date>/ - 演练：每月恢复一次到隔离环境，跑 smoke-test.sh
9. 安全 Checklist（生产前）
- [ ] 替换所有 Mock：docs/41-功能差距与待完善清单.md G1-G9
- [ ] 数据库密码 / OSS AK / 微信支付证书 入 K8s Secret（不入代码）
- [ ] HTTPS 全站 + HSTS
- [ ] WAF / 限流（Nginx + Sentinel）
- [ ] 审计日志开（docs/18-审计日志ES索引.md）
- [ ] 数据脱敏注解打满 PII 字段
- [ ] cosign 签名 + Kyverno 拒绝未签名镜像
- [ ] 灾备每月演练
10. 常见问题
| 问题 | 排查 |
|---|---|
| Pod 启动慢 | OTel 接 unreachable collector → 关 otel.enabled=false 临时观察 |
| MySQL 连接池满 | HikariCP maximum-pool-size 改 50；查 slow query |
| Redis OOM | maxmemory + allkeys-lru 策略 |
| Kafka lag 飙高 | KEDA ScaledObject 自动扩，检查 bootstrapServers |
| WebXR 在 iOS 不工作 | 已知，回退 2D 画笔标记，见 docs/36 |
| LLM 摘要超时 | Ollama 模型未拉取：ollama pull qwen2.5:7b |
| Istio Ambient 升级后 502 | 检查 ztunnel DaemonSet 是否就绪：kubectl -n istio-system get pods -l app=ztunnel |
11. 升级与回滚
# 升级（蓝绿）
argocd app sync logistics-app --revision v1.1.0
# 回滚（一键）
argocd app rollback logistics-app
WASM 业务规则回滚（毫秒级）：
curl -F file=@freight_v1.wasm "https://api.your-domain.com/rule/wasm/freight/upload?version=v1"