docs: add Minikube PostgreSQL manifests and clean deploy markdown

- add split PostgreSQL K8s manifests for ConfigMap, Service, PVC, and StatefulSet - expose PostgreSQL through NodePort for local Minikube access - replace deploy.md LaTeX text syntax with Markdown inline code formatting - keep deployment documentation rendering stable in Wiki.js and Markdown viewers
2026-05-27 16:51:00 +08:00 · 2026-05-27 16:51:00 +08:00 · 57371fbf1f
parent 4a2666aa3b
commit 57371fbf1f
5 changed files with 129 additions and 35 deletions
--- a/deploy/deploy.md
+++ b/deploy/deploy.md
@ -1,12 +1,12 @@
 # 项目依赖服务部署指南

-本项目依赖于 $\text{PostgreSQL}$ 数据库和 $\text{Redis Stack Server}$（包含 $\text{Redisearch}$ 等模块）部署文档将使用 $\text{Docker}$ 容器化技术部署这两个依赖服务
+本项目依赖于 `PostgreSQL` 数据库和 `Redis Stack Server`（包含 `Redisearch` 等模块）部署文档将使用 `Docker` 容器化技术部署这两个依赖服务

 ## 前提条件

-1. 已安装 $\text{Docker}$
+1. 已安装 `Docker`
 2. 下载相关容器镜像
-3. 确保主机的 $\text{5432}$ 端口（$\text{Postgres}$）和 $\text{6379}$ 端口（$\text{Redis}$）未被占用
+3. 确保主机的 `5432` 端口（`Postgres`）和 `6379` 端口（`Redis`）未被占用

 ### 1\. 部署 PostgreSQL 数据库

@ -14,7 +14,7 @@

 #### 1.1 部署命令

-运行以下命令启动 $\text{PostgreSQL}$ 容器
+运行以下命令启动 `PostgreSQL` 容器

 ```bash
 docker run --name postgres \
@ -47,7 +47,7 @@ docker logs postgres

 #### 1.4 初始化异步任务表

-$\text{PostgreSQL}$ 启动后执行以下建表语句，创建异步任务系统所需的两张表：
+`PostgreSQL` 启动后执行以下建表语句，创建异步任务系统所需的两张表：

 ```sql
 -- ==========================================
@ -109,11 +109,11 @@ COMMENT ON TABLE async_task_result IS '异步任务执行结果表';

 ### 2\. 部署 Redis Stack Server

-我们将使用 `redis/redis-stack-server:latest` 镜像该镜像内置了 $\text{Redisearch}$ 模块，用于 $\text{ModelRT}$ 项目中补全功能
+我们将使用 `redis/redis-stack-server:latest` 镜像该镜像内置了 `Redisearch` 模块，用于 `ModelRT` 项目中补全功能

 #### 2.1 部署命令

-运行以下命令启动 $\text{Redis Stack Server}$ 容器
+运行以下命令启动 `Redis Stack Server` 容器

 ```bash
 docker run --name redis -p 6379:6379 \
@ -130,7 +130,7 @@ docker run --name redis -p 6379:6379 \
 | **地址** | `localhost:6379` | |
 | **密码** | **无** | 默认未设置密码 |

-> **注意:** 生产环境中建议使用 `-e REDIS_PASSWORD=<your_secure_password>` 参数来设置 $\text{Redis}$ 访问密码
+> **注意:** 生产环境中建议使用 `-e REDIS_PASSWORD=<your_secure_password>` 参数来设置 `Redis` 访问密码

 #### 2.3 状态检查

@ -403,46 +403,46 @@ go run deploy/redis-test-data/measurments-recommend/measurement_injection.go

 | 类别 | 参数名 | 作用描述 | 示例值 |
 | :--- | :--- | :--- | :--- |
-| **Postgres** | `host` | PostgreSQL 数据库服务器的 $\text{IP}$ 地址或域名。 | `"192.168.1.101"` |
+| **Postgres** | `host` | PostgreSQL 数据库服务器的 `IP` 地址或域名。 | `"192.168.1.101"` |
 | | `port` | PostgreSQL 数据库服务器的端口号。 | `5432` |
 | | `database` | 连接的数据库名称。 | `"demo"` |
 | | `user` | 连接数据库所使用的用户名。 | `"postgres"` |
 | | `password` | 连接数据库所使用的密码。 | `"coslight"` |
-| **Kafka** | `servers` | Kafka 集群的 $\text{Bootstrap Server}$ 地址列表（通常是 $\text{host:port}$ 形式，多个地址用逗号分隔）。 | `"localhost:9092"` |
+| **Kafka** | `servers` | Kafka 集群的 `Bootstrap Server` 地址列表（通常是 `host:port` 形式，多个地址用逗号分隔）。 | `"localhost:9092"` |
 | | `port` | Kafka 服务器的端口号。 | `9092` |
-| | `group_id` | 消费者组 $\text{ID}$，用于标识和管理一组相关的消费者。 | `"modelRT"` |
+| | `group_id` | 消费者组 `ID`，用于标识和管理一组相关的消费者。 | `"modelRT"` |
 | | `topic` | Kafka 消息的主题名称。 | `""` |
-| | `auto_offset_reset` | 消费者首次启动或 $\text{Offset}$ 无效时，从哪个位置开始消费（如 `earliest` 或 `latest`）。 | `"earliest"` |
-| | `enable_auto_commit` | 是否自动提交 $\text{Offset}$。设为 $\text{false}$ 通常用于手动控制 $\text{Offset}$ 提交。 | `"false"` |
+| | `auto_offset_reset` | 消费者首次启动或 `Offset` 无效时，从哪个位置开始消费（如 `earliest` 或 `latest`）。 | `"earliest"` |
+| | `enable_auto_commit` | 是否自动提交 `Offset`。设为 `false` 通常用于手动控制 `Offset` 提交。 | `"false"` |
 | | `read_message_time_duration` | 读取消息时的超时或等待时间。 | `”0.5s"` |
 | **Logger (Zap)** | `mode` | 日志模式，通常为 `development`（开发）或 `production`（生产）。影响日志格式。 | `"development"` |
-| | `level` | 最低日志级别（如 $\text{debug, info, warn, error}$）。 | `"debug"` |
+| | `level` | 最低日志级别（如 `debug`, `info`, `warn`, `error`）。 | `"debug"` |
 | | `filepath` | 日志文件的输出路径和名称格式（`%s` 会被替换为日期等）。 | `"/Users/douxu/Workspace/coslight/modelRT/modelRT-%s.log"` |
-| | `maxsize` | 单个日志文件最大大小（单位：$\text{MB}$）。 | `1` |
+| | `maxsize` | 单个日志文件最大大小（单位：`MB`）。 | `1` |
 | | `maxbackups` | 保留旧日志文件的最大个数。 | `5` |
 | | `maxage` | 保留旧日志文件的最大天数。 | `30` |
 | | `compress` | 是否压缩备份的日志文件。 | `false` |
 | **Ants Pool** | `parse_concurrent_quantity` | 用于解析任务的协程池最大并发数量。 | `10` |
 | | `rtd_receive_concurrent_quantity` | 用于实时数据接收任务的协程池最大并发数量。 | `10` |
-| **Locker Redis** | `addr` | 分布式锁服务所使用的 $\text{Redis}$ 地址。 | `"127.0.0.1:6379"` |
-| | `password` | $\text{Locker Redis}$ 的密码。 | `""` |
-| | `db` | $\text{Locker Redis}$ 使用的数据库编号。 | `1` |
-| | `poolsize` | $\text{Locker Redis}$ 连接池的最大连接数。 | `50` |
-| | `timeout` | $\text{Locker Redis}$ 连接操作的超时时间（单位：毫秒）。 | `10` |
-| **Storage Redis** | `addr` | 数据存储服务所使用的 $\text{Redis}$ 地址（例如 $\text{Redisearch}$）。 | `"127.0.0.1:6379"` |
-| | `password` | $\text{Storage Redis}$ 的密码。 | `""` |
-| | `db` | $\text{Storage Redis}$ 使用的数据库编号。 | `0` |
-| | `poolsize` | $\text{Storage Redis}$ 连接池的最大连接数。 | `50` |
-| | `timeout` | $\text{Storage Redis}$ 连接操作的超时时间（单位：毫秒）。 | `10` |
-| **Base Config** | `grid_id` | 项目所操作的默认电网 $\text{ID}$。 | `1` |
-| | `zone_id` | 项目所操作的默认区域 $\text{ID}$。 | `1` |
-| | `station_id` | 项目所操作的默认变电站 $\text{ID}$。 | `1` |
+| **Locker Redis** | `addr` | 分布式锁服务所使用的 `Redis` 地址。 | `"127.0.0.1:6379"` |
+| | `password` | `Locker Redis` 的密码。 | `""` |
+| | `db` | `Locker Redis` 使用的数据库编号。 | `1` |
+| | `poolsize` | `Locker Redis` 连接池的最大连接数。 | `50` |
+| | `timeout` | `Locker Redis` 连接操作的超时时间（单位：毫秒）。 | `10` |
+| **Storage Redis** | `addr` | 数据存储服务所使用的 `Redis` 地址（例如 `Redisearch`）。 | `"127.0.0.1:6379"` |
+| | `password` | `Storage Redis` 的密码。 | `""` |
+| | `db` | `Storage Redis` 使用的数据库编号。 | `0` |
+| | `poolsize` | `Storage Redis` 连接池的最大连接数。 | `50` |
+| | `timeout` | `Storage Redis` 连接操作的超时时间（单位：毫秒）。 | `10` |
+| **Base Config** | `grid_id` | 项目所操作的默认电网 `ID`。 | `1` |
+| | `zone_id` | 项目所操作的默认区域 `ID`。 | `1` |
+| | `station_id` | 项目所操作的默认变电站 `ID`。 | `1` |
 | **Service Config** | `service_name` | 服务名称，用于日志、监控等标识。 | `"modelRT"` |
 | | `secret_key` | 服务内部使用的秘钥，用于签名或认证。 | `"modelrt_key"` |
-| **DataRT API** | `host` | 外部 $\text{DataRT}$ 服务的主机地址。 | `"http://127.0.0.1"` |
-| | `port` | $\text{DataRT}$ 服务的端口号。 | `8888` |
-| | `polling_api` | 轮询数据的 $\text{API}$ 路径。 | `"datart/getPointData"` |
-| | `polling_api_method` | 调用该 $\text{API}$ 使用的 $\text{HTTP}$ 方法。 | `"GET"` |
+| **DataRT API** | `host` | 外部 `DataRT` 服务的主机地址。 | `"http://127.0.0.1"` |
+| | `port` | `DataRT` 服务的端口号。 | `8888` |
+| | `polling_api` | 轮询数据的 `API` 路径。 | `"datart/getPointData"` |
+| | `polling_api_method` | 调用该 `API` 使用的 `HTTP` 方法。 | `"GET"` |

 #### 3.2 编译 ModelRT 服务

@ -762,7 +762,7 @@ kubectl delete secret modelrt-certs

 ### 6\. 部署可观测性栈（Kubernetes）

-在 $\text{Kubernetes}$ 集群中部署 $\text{Jaeger}$（链路追踪）+ $\text{Loki + Promtail + Grafana}$（日志可视化）。所有资源部署在 `default` 命名空间，$\text{YAML}$ 文件位于 `deploy/k8s/`。
+在 `Kubernetes` 集群中部署 `Jaeger`（链路追踪）+ `Loki + Promtail + Grafana`（日志可视化）。所有资源部署在 `default` 命名空间，`YAML` 文件位于 `deploy/k8s/`。

 #### 6.1 部署 Jaeger

@ -841,7 +841,7 @@ kubectl delete -f deploy/k8s/

 ### 7\. Mac 本地访问（SSH 隧道）

-$\text{ModelRT / EventRT}$ 在 $\text{Mac}$ 本地运行时，依赖的 $\text{RabbitMQ}$、$\text{Redis}$、$\text{Jaeger}$、$\text{Loki}$、$\text{Grafana}$ 均部署在 $\text{Ubuntu}$ 宿主机（`192.168.1.101`）上的 $\text{Minikube}$（`192.168.49.2`）中。由于 $\text{Minikube}$ 网络不直接对外暴露，需通过 $\text{SSH}$ 本地端口转发建立访问隧道。
+`ModelRT / EventRT` 在 `Mac` 本地运行时，依赖的 `RabbitMQ`、`Redis`、`Jaeger`、`Loki`、`Grafana` 均部署在 `Ubuntu` 宿主机（`192.168.1.101`）上的 `Minikube`（`192.168.49.2`）中。由于 `Minikube` 网络不直接对外暴露，需通过 `SSH` 本地端口转发建立访问隧道。

 #### 7.1 网络拓扑

@ -888,7 +888,7 @@ ssh -fN \
 | `3100` | `31100` | Loki | 日志查询 API |
 | `3000` | `31000` | Grafana | 可视化界面 `http://localhost:3000` |

-> **注意：** 隧道建立后，本地配置文件中所有服务地址均填 `localhost:<本地端口>`，无需修改即可在 $\text{Mac}$ 上直接运行服务。
+> **注意：** 隧道建立后，本地配置文件中所有服务地址均填 `localhost:<本地端口>`，无需修改即可在 `Mac` 上直接运行服务。

 #### 7.4 关闭隧道

--- a/deploy/k8s/pg-configmap.yaml
+++ b/deploy/k8s/pg-configmap.yaml
@ -0,0 +1,8 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: postgres-config
+data:
+  POSTGRES_DB: demo
+  POSTGRES_USER: postgres
+  POSTGRES_PASSWORD: coslight
--- a/deploy/k8s/pg-pvc.yaml
+++ b/deploy/k8s/pg-pvc.yaml
@ -0,0 +1,10 @@
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: postgres-data
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 2Gi
--- a/deploy/k8s/pg-service.yaml
+++ b/deploy/k8s/pg-service.yaml
@ -0,0 +1,15 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: postgres
+  labels:
+    app: postgres
+spec:
+  type: NodePort
+  selector:
+    app: postgres
+  ports:
+    - name: postgres
+      port: 5432
+      targetPort: 5432
+      nodePort: 30432
--- a/deploy/k8s/pg-statefulset.yaml
+++ b/deploy/k8s/pg-statefulset.yaml
@ -0,0 +1,61 @@
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: postgres
+  labels:
+    app: postgres
+spec:
+  serviceName: postgres
+  replicas: 1
+  selector:
+    matchLabels:
+      app: postgres
+  template:
+    metadata:
+      labels:
+        app: postgres
+    spec:
+      containers:
+        - name: postgres
+          image: postgres:13.16
+          imagePullPolicy: IfNotPresent
+          ports:
+            - name: postgres
+              containerPort: 5432
+          envFrom:
+            - configMapRef:
+                name: postgres-config
+          volumeMounts:
+            - name: postgres-data
+              mountPath: /var/lib/postgresql/data
+          readinessProbe:
+            exec:
+              command:
+                - sh
+                - -c
+                - pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB"
+            initialDelaySeconds: 8
+            periodSeconds: 5
+            timeoutSeconds: 3
+            failureThreshold: 12
+          livenessProbe:
+            exec:
+              command:
+                - sh
+                - -c
+                - pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB"
+            initialDelaySeconds: 30
+            periodSeconds: 20
+            timeoutSeconds: 3
+            failureThreshold: 3
+          resources:
+            requests:
+              cpu: 100m
+              memory: 256Mi
+            limits:
+              cpu: 500m
+              memory: 512Mi
+      volumes:
+        - name: postgres-data
+          persistentVolumeClaim:
+            claimName: postgres-data