82c0cae4e2
- Update tagline to emphasize cloud-native, vendor-neutral architecture - 🇨🇳 Chinese: 云原生 · 去平台绑定 · 可自由迁移 - 🇺🇸 English: Cloud-native · Vendor-neutral · Freely portable - Replace tech stack logos: Next.js, Go, Vercel, Cloud Run, PostgreSQL - Remove outdated stack references (Vue, Svelte, Node, Django, Laravel)
231 lines
5.7 KiB
Markdown
231 lines
5.7 KiB
Markdown
# RAG Server 数据库连接修复 Runbook
|
||
|
||
## 📋 概述
|
||
|
||
**问题**: RAG Server 无法连接到 PostgreSQL 数据库，导致 `/api/rag/query` 返回 404
|
||
**影响范围**: RAG 检索功能、向量搜索、知识库同步
|
||
**修复时间**: ~5 分钟
|
||
**风险等级**: 🟡 中等（前端已实现降级，用户体验影响有限）
|
||
|
||
---
|
||
|
||
## 🔍 问题诊断
|
||
|
||
### 错误症状
|
||
|
||
```
|
||
ERROR: cannot parse `admin_password`: failed to parse as keyword/value (invalid keyword/value)
|
||
WARN: postgres cache disabled; no database connection
|
||
```
|
||
|
||
### 根本原因
|
||
|
||
1. ❌ `DATABASE_URL` 环境变量指向 Secret Manager 引用 `admin_password`，而不是实际的数据库连接字符串
|
||
2. ❌ RAG 服务器无法连接到 PostgreSQL 数据库
|
||
3. ❌ 导致 `/api/rag/query` 返回 404
|
||
|
||
### 架构图
|
||
|
||
```
|
||
┌─────────────────────┐
|
||
│ Cloud Run │
|
||
│ (RAG Server) │
|
||
└──────────┬──────────┘
|
||
│
|
||
↓
|
||
┌─────────────────────┐
|
||
│ Stunnel │
|
||
│ 127.0.0.1:5432 │
|
||
└──────────┬──────────┘
|
||
│ TLS Tunnel
|
||
↓
|
||
┌─────────────────────┐
|
||
│ postgresql │
|
||
│ .onwalk.net:443 │
|
||
└──────────┬──────────┘
|
||
│
|
||
↓
|
||
┌─────────────────────┐
|
||
│ PostgreSQL │
|
||
│ Database │
|
||
└─────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 修复方案
|
||
|
||
### 方案 1: 使用 Stunnel (推荐) ⭐
|
||
|
||
#### 优势
|
||
- ✅ 安全性更好（TLS 加密）
|
||
- ✅ 不需要暴露数据库公网 IP
|
||
- ✅ 符合现有架构设计
|
||
- ✅ entrypoint.sh 已经支持 Stunnel
|
||
|
||
#### 步骤 1: 更新 Cloud Run 环境变量
|
||
|
||
```bash
|
||
gcloud run services update rag-server-svc-plus \
|
||
--region asia-northeast1 \
|
||
--project xzerolab-480008 \
|
||
--update-env-vars="\
|
||
DB_TLS_HOST=postgresql.onwalk.net,\
|
||
DB_TLS_PORT=443,\
|
||
POSTGRES_USER=postgres,\
|
||
POSTGRES_PASSWORD=otdcRLTJamszk3AE,\
|
||
POSTGRES_DB=knowledge_db,\
|
||
NVIDIA_API_KEY=NVAPI_KEY_PLACEHOLDER" \
|
||
--clear-env-vars=DATABASE_URL
|
||
```
|
||
|
||
**关键参数说明**:
|
||
- `DB_TLS_HOST` 和 `DB_TLS_PORT`: 触发 entrypoint.sh 启动 Stunnel
|
||
- Stunnel 会在 `127.0.0.1:5432` 监听
|
||
- `config/rag-server.yaml` 中的 `pgurl` 会自动使用 `127.0.0.1:5432`
|
||
- `--clear-env-vars=DATABASE_URL`: 移除错误的环境变量
|
||
|
||
#### 步骤 2: 验证部署
|
||
|
||
**检查日志**:
|
||
```bash
|
||
gcloud logging read \
|
||
"resource.type=cloud_run_revision AND resource.labels.service_name=rag-server-svc-plus" \
|
||
--limit 20 \
|
||
--project xzerolab-480008 \
|
||
--format="table(timestamp,textPayload)"
|
||
```
|
||
|
||
**期望输出**:
|
||
```
|
||
Starting Stunnel...
|
||
Stunnel is up!
|
||
INFO: Connected to PostgreSQL at 127.0.0.1:5432
|
||
```
|
||
|
||
#### 步骤 3: 功能测试
|
||
|
||
**测试 RAG 查询**:
|
||
```bash
|
||
curl -X POST https://rag-server-svc-plus-HASH-an.a.run.app/api/rag/query \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"query": "test query", "top_k": 5}'
|
||
```
|
||
|
||
**期望响应**: HTTP 200，包含检索结果
|
||
|
||
---
|
||
|
||
### 方案 2: 直接数据库连接 (不推荐)
|
||
|
||
⚠️ **仅在 PostgreSQL 有公网 IP 且无法使用 Stunnel 时使用**
|
||
|
||
```bash
|
||
# 更新 Secret Manager
|
||
echo "postgres://postgres:otdcRLTJamszk3AE@<PUBLIC_IP>:5432/knowledge_db?sslmode=require" | \
|
||
gcloud secrets versions add DATABASE_URL --data-file=- --project xzerolab-480008
|
||
|
||
# 更新 Cloud Run 使用 Secret
|
||
gcloud run services update rag-server-svc-plus \
|
||
--region asia-northeast1 \
|
||
--project xzerolab-480008 \
|
||
--update-secrets=DATABASE_URL=DATABASE_URL:latest
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 当前状态
|
||
|
||
### ✅ 工作的功能
|
||
- `/api/askai` - 直接 AI 回答（不依赖数据库）
|
||
- CORS 配置
|
||
- NVIDIA API 集成
|
||
|
||
### ❌ 待修复的功能
|
||
- `/api/rag/query` - RAG 检索（需要数据库连接）
|
||
- 向量搜索
|
||
- 知识库同步
|
||
|
||
---
|
||
|
||
## 🎯 前端降级策略
|
||
|
||
前端已经实现了优雅降级：
|
||
|
||
1. **首选**: 尝试 `/api/rag/query` (RAG 检索)
|
||
2. **降级**: 如果失败，回退到 `/api/askai` (直接 AI)
|
||
3. **结果**: 用户仍然可以获得答案，只是没有知识库上下文
|
||
|
||
---
|
||
|
||
## 🔄 回滚计划
|
||
|
||
如果修复后出现问题，执行以下回滚：
|
||
|
||
```bash
|
||
# 恢复原有 DATABASE_URL
|
||
gcloud run services update rag-server-svc-plus \
|
||
--region asia-northeast1 \
|
||
--project xzerolab-480008 \
|
||
--update-secrets=DATABASE_URL=admin_password:latest \
|
||
--remove-env-vars=DB_TLS_HOST,DB_TLS_PORT,POSTGRES_USER,POSTGRES_PASSWORD,POSTGRES_DB
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 验证清单
|
||
|
||
- [ ] Cloud Run 环境变量已更新
|
||
- [ ] `DATABASE_URL` 已清除
|
||
- [ ] 日志显示 "Stunnel is up!"
|
||
- [ ] `/api/rag/query` 返回 200
|
||
- [ ] 前端 RAG 功能正常
|
||
- [ ] 向量搜索可用
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
- [Stunnel 配置文档](../docs/stunnel-setup.md)
|
||
- [PostgreSQL 连接指南](../docs/postgres-connection.md)
|
||
- [Cloud Run 环境变量管理](https://cloud.google.com/run/docs/configuring/environment-variables)
|
||
|
||
---
|
||
|
||
## 🆘 故障排查
|
||
|
||
### 问题: Stunnel 无法启动
|
||
|
||
**检查**:
|
||
```bash
|
||
# 查看 Stunnel 日志
|
||
gcloud logging read "textPayload=~\"stunnel\"" --limit 50 --project xzerolab-480008
|
||
```
|
||
|
||
**可能原因**:
|
||
- DNS 解析失败
|
||
- 防火墙阻止 443 端口
|
||
- 证书验证失败
|
||
|
||
### 问题: 数据库连接超时
|
||
|
||
**检查**:
|
||
```bash
|
||
# 测试网络连通性
|
||
gcloud run services describe rag-server-svc-plus \
|
||
--region asia-northeast1 \
|
||
--project xzerolab-480008 \
|
||
--format="value(status.url)"
|
||
```
|
||
|
||
**可能原因**:
|
||
- PostgreSQL 服务未运行
|
||
- 密码错误
|
||
- 数据库名称错误
|
||
|
||
---
|
||
|
||
**最后更新**: 2026-01-26
|
||
**负责人**: DevOps Team
|
||
**审核人**: Tech Lead
|