From c7dec53ded03b9c64338554ee0d50ddcc6d7392b Mon Sep 17 00:00:00 2001 From: douxu Date: Fri, 29 May 2026 14:20:02 +0800 Subject: [PATCH] docs: expand deploy guide to cover full project setup - add MongoDB Docker deployment steps with init and auth setup - restructure RabbitMQ section with step-by-step cert generation and K8s deploy - add EventRT Kubernetes deployment section (build, secrets, configmap, checks) - document SSH tunnel setup for Mac local dev (MongoDB, RabbitMQ, OTel, Jaeger) - add config.yaml parameter reference table for local development - add troubleshooting section for cert checks, TLS handshake, and MongoDB connectivity --- deploy/deploy.md | 480 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 378 insertions(+), 102 deletions(-) diff --git a/deploy/deploy.md b/deploy/deploy.md index a776273..936f8f8 100644 --- a/deploy/deploy.md +++ b/deploy/deploy.md @@ -1,154 +1,430 @@ -# RabbitMQ 部署与 mTLS 证书签发指南 +# 项目部署指南 -## 一、 证书签发 (PKI) +本项目依赖 `MongoDB`（事件持久化存储）与 `RabbitMQ`（mTLS 消息队列），并通过 `OpenTelemetry + Jaeger` 完成链路追踪。 -### 1. 准备工作 +## 前提条件 -确保本地拥有根 CA 文件:`ca_certificate.pem` 和 `cakey.pem` +1. 已安装 `Docker` 与 `kubectl` +2. `Minikube` 集群已启动并可访问 +3. 确保以下端口在宿主机上未被占用：`27017`（MongoDB）、`5671`（RabbitMQ AMQP） -### 2. 生成 RabbitMQ 服务端证书 +--- -服务端证书必须包含 `serverAuth` 权限，并涵盖所有访问域名和 IP +### 1\. 部署 MongoDB 数据库（Docker） -**配置文件 `server.conf` 关键点:** +使用官方 `mongo:7.0` 镜像，在 Ubuntu 宿主机（`192.168.1.101`）上以 Docker 容器运行。 -* **CN**: `rabbitmq-server` -* **SAN (alt_names)**: 必须包含 `localhost` 和 `127.0.0.1` 以适配 SSH 隧道 +#### 1.1 部署命令 ```bash -# 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 状态检查 + +```bash +# 检查容器启动状态 +docker ps -a | grep mongodb +# 检查启动日志 +docker logs mongodb +``` + +#### 1.4 初始化 eventdb 数据库 + +MongoDB 启动后进入容器，为 `eventdb` 库授权： + +```bash +docker exec -it mongodb mongosh \ + -u coslight -p coslight@tj --authenticationDatabase admin +``` + +在 `mongosh` 中执行： + +```javascript +// 切换到 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 + +```bash +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`（已预置正确配置）： + +```bash +# 将 ca_certificate.pem 和 cakey.pem 放在当前目录 openssl genrsa -out server_key.pem 2048 -# 2. 生成签名请求 (CSR) -openssl req -new -key server_key.pem -out server_cert.csr -config server.conf +openssl req -new -key server_key.pem \ + -out server_cert.csr -config deploy/mq/server.conf -# 3. 使用 v3_server 扩展签发 -openssl x509 -req -in server_cert.csr -CA ca_certificate.pem -CAkey cakey.pem -CAcreateserial \ +openssl x509 -req -in server_cert.csr \ + -CA ca_certificate.pem -CAkey cakey.pem -CAcreateserial \ -out server_certificate.pem -days 730 -sha256 \ - -extfile server.conf -extensions v3_server + -extfile deploy/mq/server.conf -extensions v3_server +rm server_cert.csr ``` -### 3. 生成客户端证书 (modelRT / eventRT) +##### 2.1.3 生成 EventRT 客户端证书 -**注意**:客户端证书必须包含 `clientAuth` 扩展，否则会导致 403 错误 - -#### 签发 modelRT 证书 +CN 必须与 RabbitMQ 中注册的用户名一致（`eventrt-client`）。使用 `deploy/mq/eventrt.conf`： + +```bash +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`）： ```bash -# 1. 生成私钥 openssl genrsa -out modelrt_client_key.pem 2048 -# 2. 生成 CSR (CN 必须匹配 rabbitmq 里的用户名: modelrt-client) -openssl req -new -key modelrt_client_key.pem -out modelrt_client_cert.csr -config modelrt.conf +openssl req -new -key modelrt_client_key.pem \ + -out modelrt_client.csr -config deploy/mq/modelrt.conf -# 3. 关键:使用 v3_client 扩展签发 -openssl x509 -req -in modelrt_client_cert.csr -CA ca_certificate.pem -CAkey cakey.pem -CAcreateserial \ - -out modelrt_client_cert.pem -days 730 -sha256 \ - -extfile modelrt.conf -extensions v3_client +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 ``` -*(eventRT 证书签发流程同上，只需更换 `eventrt.conf` 配置文件)* - ---- - -## 二、 RabbitMQ 服务端部署 (K8s) - -### 1. 配置用户与权限 - -修改 `rabbitmq-users-config.yaml`，确保用户标签为 `management` 或 `administrator`，并赋予 `/` 的权限 - -```yaml -# 关键部分:definitions.json -{ - "name": "modelrt-client", - "password_hash": "", - "tags": ["management"] -} - -``` - -### 2. 应用 Kubernetes 配置 +##### 2.1.5 验证证书 ```bash -# 1. 应用用户定义 -kubectl apply -f rabbitmq-users-config.yaml +# 验证服务端证书 +openssl verify -CAfile ca_certificate.pem server_certificate.pem -# 2. 创建插件 ConfigMap -kubectl create configmap rabbit-plugins-conf - --from-literal=enabled_plugins="[rabbitmq_auth_mechanism_ssl, \ - rabbitmq_management, rabbitmq_management_agent, \ - rabbitmq_prometheus, rabbitmq_web_dispatch]." +# 验证客户端证书 +openssl verify -CAfile ca_certificate.pem eventrt_client_cert.pem +openssl verify -CAfile ca_certificate.pem modelrt_client_cert.pem -# 3. 创建证书 Secret +# 确认 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 + +在证书文件所在目录执行： + +```bash +sh deploy/mq/secert.sh +``` + +该脚本等价于： + +```bash kubectl create secret generic rabbitmq-certs \ - --from-file=ca.pem=ca_certificate.pem \ - --from-file=server.pem=server_certificate.pem \ - --from-file=server_key.pem=server_key.pem - -# 4. 应用部署文件 -kubectl apply -f rabbitmq-config.yaml -kubectl apply -f rabbitmq-deployment.yaml -kubectl apply -f rabbitmq-service.yaml - + --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 ``` ---- - -## 三、 开发环境网络配置 (SSH 隧道) - -如果你在 Mac 上开发，RabbitMQ 在远程 Linux 的 Minikube 中，请执行以下命令建立加密隧道: +##### 2.2.2 部署 ```bash -# 将远程 Minikube 中 rabbitMQ service 的 NodePort (30671) 映射到 Mac 本地的 5671 -ssh -L 5671::30671 @host-ip - +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 映射为用户名。 + --- -## 四、 Go 程序配置 (config.yaml) +### 3\. 部署 EventRT（Kubernetes） -确保客户端配置指向隧道入口，并开启 TLS: +所有资源部署在 `default` 命名空间，YAML 文件位于 `deploy/k8s/`。 -```yaml -rabbitmq: - host: "localhost" - port: 5671 - server_name: "rabbitmq-server" - ca_cert_path: "./configs/certs/ca_certificate.pem" - client_cert_path: "./configs/certs/modelrt_client_cert.pem" - client_key_path: "./configs/certs/modelrt_client_key.pem" - -``` - ---- - -## 五、 验证与排查 - -### 1. 证书权限检查 - -运行以下命令，确信输出中有 `TLS Web Client Authentication`: +#### 3.1 构建并推送镜像 ```bash -openssl x509 -in modelrt_client_cert.pem -noout -text | grep -A 1 "Extended Key Usage" +# 在项目根目录执行 +docker build -f deploy/dockerfile/eventrt.Dockerfile -t coslight/eventrt:latest . +# 加载至 Minikube（无需私有仓库时） +minikube image load coslight/eventrt:latest ``` -### 2. 握手连通性验证 +#### 3.2 创建客户端证书 Secret + +在 RabbitMQ TLS 证书生成完成后（见 2.1），进入证书文件所在目录执行： + +```bash +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 部署 + +```bash +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 状态检查 + +```bash +# 查看 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 清理 + +```bash +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 网络拓扑 + +```text +Mac 本地端口 ──SSH隧道──▶ Ubuntu 宿主机 (192.168.1.101) ──▶ Minikube NodePort (192.168.49.2) + └──▶ MongoDB Docker (宿主机 27017) +``` + +#### 4.2 建立隧道 + +```bash +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 +``` + +如需后台静默运行（不占用终端）： + +```bash +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`；后台运行时查找并终止进程： + +```bash +# 找到 ssh 隧道进程 +ps aux | grep "ssh -fN" +# 终止（替换为实际 PID） +kill +``` + +--- + +### 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`： + +```bash +openssl x509 -in configs/certs/eventrt_client_cert.pem -noout -text \ + | grep -A1 "Extended Key Usage" +``` + +预期输出包含 `TLS Web Client Authentication`。 + +#### 6.2 握手连通性验证 ```bash openssl s_client -connect localhost:5671 \ - -cert modelrt_client_cert.pem \ - -key modelrt_client_key.pem \ - -CAfile ca_certificate.pem - + -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)` +预期结果：看到 `Verify return code: 0 (ok)`。 -### 3. 日志检查 +#### 6.3 RabbitMQ 日志检查 -如果连接成功，RabbitMQ 日志应显示: -`connection : user 'modelrt-client' authenticated and granted access to vhost '/'` +连接成功后，RabbitMQ 日志应出现： + +``` +connection : user 'eventrt-client' authenticated and granted access to vhost '/' +``` + +查看 Pod 日志： + +```bash +kubectl logs -l app=rabbitmq --tail=50 | grep eventrt-client +``` + +#### 6.4 MongoDB 连通性验证 + +```bash +mongosh "mongodb://coslight:coslight@tj@localhost:27017/eventdb?authSource=admin" +``` + +预期进入 `mongosh` 提示符，执行 `show collections` 无报错。