15 KiB

Raw Blame History

项目部署指南

本项目依赖 MongoDB（事件持久化存储）与 RabbitMQ（mTLS 消息队列），并通过 OpenTelemetry + Jaeger 完成链路追踪。

前提条件

已安装 Docker 与 kubectl
Minikube 集群已启动并可访问
确保以下端口在宿主机上未被占用：27017（MongoDB）、5671（RabbitMQ AMQP）

1. 部署 MongoDB 数据库（Docker）

使用官方 mongo:7.0 镜像，在 Ubuntu 宿主机（192.168.1.101）上以 Docker 容器运行。

1.1 部署命令

docker run --name mongodb \
  -e MONGO_INITDB_ROOT_USERNAME=coslight \
  -e MONGO_INITDB_ROOT_PASSWORD=coslight@tj \
  -p 27017:27017 \
  -d mongo:7.0

1.2 连接信息

参数	值	说明
容器名称	`mongodb`	容器名
镜像版本	`mongo:7.0`	MongoDB 7.0
主机端口	`27017`	外部应用连接端口
用户名	`coslight`	Root 管理员
密码	`coslight@tj`	启动时通过 `MONGO_INITDB_ROOT_USERNAME` 设置
鉴权数据库	`admin`	`auth_db`
业务数据库	`eventdb`	EventRT 事件存储库

1.3 状态检查

# 检查容器启动状态
docker ps -a | grep mongodb
# 检查启动日志
docker logs mongodb

1.4 初始化 eventdb 数据库

MongoDB 启动后进入容器，为 eventdb 库授权：

docker exec -it mongodb mongosh \
  -u coslight -p coslight@tj --authenticationDatabase admin

在 mongosh 中执行：

// 切换到 eventdb，若不存在则自动创建
use eventdb

// 授予 coslight 用户对 eventdb 的读写权限（根用户已有全库权限，此步可选）
db.createUser({
  user: "coslight",
  pwd:  "coslight@tj",
  roles: [{ role: "readWrite", db: "eventdb" }]
})

2. 部署 RabbitMQ（Kubernetes）

RabbitMQ 配置为仅允许 TLS 连接（listeners.tcp = none），所有客户端须持有由同一 CA 签发的证书。YAML 文件位于 deploy/mq/。

2.1 TLS 证书生成

2.1.1 生成根 CA

git clone https://github.com/rabbitmq/tls-gen.git
cd tls-gen/basic

# 生成根 CA，结果输出至 result/
make CN=rabbitmq-server
# ca_certificate.pem 与 ca_key.pem（即 cakey.pem）生成于 result/

2.1.2 生成服务端证书

服务端证书需包含 SAN，使其同时匹配集群内 DNS 和 Minikube IP。使用 deploy/mq/server.conf（已预置正确配置）：

# 将 ca_certificate.pem 和 cakey.pem 放在当前目录
openssl genrsa -out server_key.pem 2048

openssl req -new -key server_key.pem \
    -out server_cert.csr -config deploy/mq/server.conf

openssl x509 -req -in server_cert.csr \
    -CA ca_certificate.pem -CAkey cakey.pem -CAcreateserial \
    -out server_certificate.pem -days 730 -sha256 \
    -extfile deploy/mq/server.conf -extensions v3_server

rm server_cert.csr

2.1.3 生成 EventRT 客户端证书

CN 必须与 RabbitMQ 中注册的用户名一致（eventrt-client）。使用 deploy/mq/eventrt.conf：

openssl genrsa -out eventrt_client_key.pem 2048

openssl req -new -key eventrt_client_key.pem \
    -out eventrt_client.csr -config deploy/mq/eventrt.conf

openssl x509 -req -in eventrt_client.csr \
    -CA ca_certificate.pem -CAkey cakey.pem -CAcreateserial \
    -out eventrt_client_cert.pem -days 365 \
    -extensions v3_client -extfile deploy/mq/eventrt.conf

rm eventrt_client.csr

2.1.4 生成 ModelRT 客户端证书

使用 deploy/mq/modelrt.conf（CN 为 modelrt-client）：

openssl genrsa -out modelrt_client_key.pem 2048

openssl req -new -key modelrt_client_key.pem \
    -out modelrt_client.csr -config deploy/mq/modelrt.conf

openssl x509 -req -in modelrt_client.csr \
    -CA ca_certificate.pem -CAkey cakey.pem -CAcreateserial \
    -out modelrt_client_cert.pem -days 365 \
    -extensions v3_client -extfile deploy/mq/modelrt.conf

rm modelrt_client.csr

2.1.5 验证证书

# 验证服务端证书
openssl verify -CAfile ca_certificate.pem server_certificate.pem

# 验证客户端证书
openssl verify -CAfile ca_certificate.pem eventrt_client_cert.pem
openssl verify -CAfile ca_certificate.pem modelrt_client_cert.pem

# 确认 CN 和扩展（clientAuth / serverAuth）
openssl x509 -in server_certificate.pem -noout -subject -ext subjectAltName
openssl x509 -in eventrt_client_cert.pem -noout -subject -text | grep -A1 "Extended Key Usage"
openssl x509 -in modelrt_client_cert.pem -noout -subject

2.2 部署 RabbitMQ

2.2.1 创建证书 Secret

在证书文件所在目录执行：

sh deploy/mq/secert.sh

该脚本等价于：

kubectl create secret generic rabbitmq-certs \
  --from-file=ca_certificate.pem=./certs/ca_certificate.pem \
  --from-file=server_certificate.pem=./certs/server_certificate.pem \
  --from-file=server_key.pem=./certs/server_key.pem

2.2.2 部署

kubectl apply -f deploy/mq/rabbitmq-secret.yaml
kubectl apply -f deploy/mq/rabbitmq-users-config.yaml
kubectl apply -f deploy/mq/rabbitmq-config.yaml
kubectl apply -f deploy/mq/rabbitmq-deployment.yaml
kubectl apply -f deploy/mq/rabbitmq-service.yaml

2.2.3 端口汇总

端口	NodePort	说明
`5671`	`30671`	AMQP over TLS（客户端连接）
`5672`	`30672`	AMQP 明文（内部备用，生产禁用）
`15671`	`31671`	Management UI over TLS
`15672`	`31672`	Management UI 明文（内部备用）

2.2.4 用户与权限说明

用户定义在 rabbitmq-users-config.yaml 的 definitions.json 中，启动时通过 load_definitions 自动加载：

用户	认证方式	权限	说明
`coslight`	密码	administrator	管理员，密码在 `rabbitmq-secret.yaml`
`eventrt-client`	X.509 证书（CN）	configure/read/write	EventRT 服务专用
`modelrt-client`	X.509 证书（CN）	configure/read/write	ModelRT 服务专用
`web-client`	X.509 证书（CN）	read/write	Web 客户端

注意： 证书认证用户的 password_hash 留空；RabbitMQ 通过 ssl_cert_login_from = common_name 将证书 CN 映射为用户名。

3. 部署 EventRT（Kubernetes）

所有资源部署在 default 命名空间，YAML 文件位于 deploy/k8s/。

3.1 构建并推送镜像

镜像采用三阶段构建，最终基于 scratch：

阶段	基础镜像	作用
builder	`golang:1.26-alpine`	编译 Go 二进制（`CGO_ENABLED=0`，`-trimpath -ldflags="-s -w"`）
certs	`alpine:3.21`	提取 CA 证书、时区数据及非 root 用户定义（UID 默认 `1000`）
runtime	`scratch`	仅含可执行文件与运行时依赖，无 shell、无包管理器

方式一：从源码构建并加载

# 在项目根目录执行（默认运行用户 UID=1000）
docker build -f deploy/dockerfile/eventrt.Dockerfile -t coslight/eventrt:latest .

# 自定义运行用户 UID
docker build -f deploy/dockerfile/eventrt.Dockerfile \
  --build-arg USER_ID=2000 \
  -t coslight/eventrt:latest .

# 加载到 Minikube（无需私有仓库）
minikube image load coslight/eventrt:latest

方式二：直接加载已有本地镜像

Ubuntu 宿主机上已存在构建好的镜像（如 eventrt:v1）时，无需重新构建，直接导入 Minikube：

# 确认本地镜像存在
docker images eventrt:v1

# 加载到 Minikube
minikube image load eventrt:v1

# 验证镜像已进入 Minikube 缓存
minikube image ls | grep eventrt

注意： deploy/k8s/eventrt-deployment.yaml 中的 image 字段需与加载的镜像名称一致，并将 imagePullPolicy 设为 Never，防止 Minikube 尝试从远端拉取。

3.1.1 镜像冒烟测试

# 查看镜像大小（scratch 镜像预期 ≤ 25 MB）
docker images coslight/eventrt:latest

# 检查镜像元信息（确认 User、Cmd、架构）
docker inspect coslight/eventrt:latest

# 验证二进制可执行（无 config 时程序报错退出属预期行为，说明镜像构建正常）
docker run --rm coslight/eventrt:latest

# 挂载示例配置做完整启动验证（Ctrl+C 退出）
docker run --rm \
  -v "$(pwd)/configs/config.example.yaml:/app/configs/config.yaml" \
  -p 8081:8081 \
  coslight/eventrt:latest

注意： scratch 镜像不含 shell，无法使用 docker exec 进入容器调试；如需排查问题，可临时将最终阶段改为 alpine 进行本地调试，确认后再切回 scratch。

3.2 创建客户端证书 Secret

在 RabbitMQ TLS 证书生成完成后（见 2.1），进入证书文件所在目录执行：

kubectl create secret generic eventrt-certs \
  --from-file=ca_certificate.pem=./ca_certificate.pem \
  --from-file=eventrt_client_cert.pem=./eventrt_client_cert.pem \
  --from-file=eventrt_client_key.pem=./eventrt_client_key.pem

3.3 部署

kubectl apply -f deploy/k8s/eventrt-secret.yaml
kubectl apply -f deploy/k8s/eventrt-configmap.yaml
kubectl apply -f deploy/k8s/eventrt-deployment.yaml
kubectl apply -f deploy/k8s/eventrt-service.yaml

3.4 配置说明

配置项	方式	说明
`mongodb.password`	Secret `eventrt-secret`	不写入 ConfigMap，通过环境变量 `MONGODB_PASSWORD` 注入
`service.secret_key`	Secret `eventrt-secret`	不写入 ConfigMap，通过环境变量 `SERVICE_SECRET_KEY` 注入
RabbitMQ 客户端证书	Secret `eventrt-certs`	挂载至 `/app/configs/certs/`
`config.yaml` 其余配置	ConfigMap `eventrt-config`	`rabbitmq.host` 已设为 K8s Service 名 `rabbitmq-service`
`K8S_NAMESPACE` / `K8S_NODE_NAME`	Downward API	注入至日志全局字段

3.5 状态检查

# 查看 Pod 状态
kubectl get pods -l app=eventrt

# 查看启动日志
kubectl logs -l app=eventrt --tail=50

# 查看 Service
kubectl get svc eventrt-service

3.6 端口汇总

NodePort	说明
`30081`	EventRT HTTP API

3.7 清理

kubectl delete -f deploy/k8s/eventrt-service.yaml \
               -f deploy/k8s/eventrt-deployment.yaml \
               -f deploy/k8s/eventrt-configmap.yaml \
               -f deploy/k8s/eventrt-secret.yaml
kubectl delete secret eventrt-certs

4. Mac 本地访问（SSH 隧道）

EventRT 在 Mac 本地运行时，RabbitMQ 部署在 Ubuntu 宿主机（192.168.1.101）的 Minikube 中，MongoDB 直接运行在宿主机上。需通过 SSH 本地端口转发建立访问隧道。

4.1 网络拓扑

Mac 本地端口  ──SSH隧道──▶  Ubuntu 宿主机 (192.168.1.101)  ──▶  Minikube NodePort (192.168.49.2)
                                       └──▶  MongoDB Docker (宿主机 27017)

4.2 建立隧道

ssh -L 27017:127.0.0.1:27017 \
    -L 5671:192.168.49.2:30671 \
    -L 15671:192.168.49.2:31671 \
    -L 4318:192.168.49.2:31318 \
    -L 16686:192.168.49.2:31686 \
    douxu@192.168.1.101

如需后台静默运行（不占用终端）：

ssh -fN \
    -L 27017:127.0.0.1:27017 \
    -L 5671:192.168.49.2:30671 \
    -L 15671:192.168.49.2:31671 \
    -L 4318:192.168.49.2:31318 \
    -L 16686:192.168.49.2:31686 \
    douxu@192.168.1.101

4.3 端口映射说明

Mac 本地端口	目标	服务	说明
`27017`	宿主机 `127.0.0.1:27017`	MongoDB	EventRT 事件数据库
`5671`	Minikube `192.168.49.2:30671`	RabbitMQ AMQP	消息队列 mTLS 连接
`15671`	Minikube `192.168.49.2:31671`	RabbitMQ Management	管理界面 `http://localhost:15671`
`4318`	Minikube `192.168.49.2:31318`	OTLP HTTP	OTel Trace 上报（Jaeger Collector）
`16686`	Minikube `192.168.49.2:31686`	Jaeger UI	链路追踪查询 `http://localhost:16686`

注意： 隧道建立后，本地 config.yaml 中所有服务地址填 localhost:<本地端口> 即可直接运行服务。

4.4 关闭隧道

前台运行时直接 Ctrl+C；后台运行时查找并终止进程：

# 找到 ssh 隧道进程
ps aux | grep "ssh -fN"
# 终止（替换为实际 PID）
kill <PID>

5. 本地开发配置（config.yaml）

将 configs/config.example.yaml 复制为 configs/config.yaml 并按以下说明调整：

5.1 配置参数说明

类别	参数名	作用描述	示例值
MongoDB	`host`	MongoDB 服务器地址	`"localhost"`
	`port`	MongoDB 端口	`27017`
	`user`	连接用户名	`"coslight"`
	`password`	连接密码	`"coslight@tj"`
	`database`	业务数据库名	`"eventdb"`
	`auth_db`	鉴权数据库	`"admin"`
	`timeout`	连接超时（秒）	`10`
RabbitMQ	`host`	RabbitMQ 服务器地址	`"localhost"`
	`port`	AMQP over TLS 端口	`5671`
	`server_name`	TLS SNI / 证书 CN	`"rabbitmq-server"`
	`ca_cert_path`	CA 证书路径	`"./configs/certs/ca_certificate.pem"`
	`client_cert_path`	客户端证书路径	`"./configs/certs/eventrt_client_cert.pem"`
	`client_key_path`	客户端私钥路径	`"./configs/certs/eventrt_client_key.pem"`
	`insecure_skip_verify`	是否跳过证书校验（开发临时用）	`false`
Logger (Zap)	`mode`	日志模式 `development` / `production`	`"development"`
	`level`	最低日志级别	`"debug"`
	`filepath`	日志文件路径（空字符串输出到 stdout）	`""`
	`maxsize`	单文件最大大小（MB）	`1`
	`maxbackups`	保留旧文件最大个数	`5`
	`maxage`	保留旧文件最大天数	`30`
	`compress`	是否压缩备份文件	`false`
Service	`service_addr`	HTTP 监听地址	`":8081"`
	`service_name`	服务名（日志/监控标识）	`"eventRT"`
	`secret_key`	内部签名密钥	`"eventrt_key"`
	`deploy_env`	部署环境 `development` / `production`	`"development"`
OTel	`endpoint`	OTLP HTTP 上报地址（不含协议前缀）	`"localhost:4318"`
	`insecure`	是否不启用 TLS	`true`

6. 排查手册

6.1 证书权限检查

确认客户端证书包含 TLS Web Client Authentication：

openssl x509 -in configs/certs/eventrt_client_cert.pem -noout -text \
  | grep -A1 "Extended Key Usage"

预期输出包含 TLS Web Client Authentication。

6.2 握手连通性验证

openssl s_client -connect localhost:5671 \
    -cert configs/certs/eventrt_client_cert.pem \
    -key  configs/certs/eventrt_client_key.pem \
    -CAfile configs/certs/ca_certificate.pem

预期结果：看到 Verify return code: 0 (ok)。

6.3 RabbitMQ 日志检查

连接成功后，RabbitMQ 日志应出现：

connection <xxx>: user 'eventrt-client' authenticated and granted access to vhost '/'

查看 Pod 日志：

kubectl logs -l app=rabbitmq --tail=50 | grep eventrt-client

6.4 MongoDB 连通性验证

mongosh "mongodb://coslight:coslight@tj@localhost:27017/eventdb?authSource=admin"

预期进入 mongosh 提示符，执行 show collections 无报错。

15 KiB Raw Blame History Unescape Escape